next

var NextCmd = &cobra.Command{
	Use:   "next [flags]",
	Short: "Identify and implement next highest priority requirement",
	Long: `Identify the next highest priority unimplemented requirement and generate
comprehensive implementation guidance.

This command automatically:
- Uses the token index when it still describes this tree, and scans the tree
  itself when it does not
- Identifies highest priority STUB or IMPL requirement
- Excludes hidden requirements (test files, templates, examples)
- Requires every dependency to be proven complete -- passing evidence at the
  current commit for a local one, a satisfied external/peer state otherwise
- Generates comprehensive implementation prompt with:
  - Specification details
  - Constitutional principles
  - Test-first guidance
  - Token placement examples

Priority determination factors:
1. PRIORITY field (1=highest, 10=lowest); a token that declares none is
   ranked -- and reported -- at the neutral default 5
2. STATUS (STUB before IMPL)
3. DEPENDS_ON (every dependency must be proven complete by evidence, or
   satisfied as an external/peer requirement)

The answer names its own source: "database" when the index is present and
still describes this tree, "filesystem" when the tree had to be scanned
directly. Completion is only ever claimed from a current index.`,
	RunE: func(cmd *cobra.Command, args []string) error {
		format, err := resolveFormat(cmd)
		if err != nil {
			return err
		}
		dbPath, _ := cmd.Flags().GetString("db")
		promptFlag, _ := cmd.Flags().GetBool("prompt")
		dryRun, _ := cmd.Flags().GetBool("dry-run")
		filterStatus, _ := cmd.Flags().GetString("status")
		filterAspect, _ := cmd.Flags().GetString("aspect")
		allowUnknownExternal, _ := cmd.Flags().GetBool("allow-unknown-external")
		root, _ := cmd.Flags().GetString("root")
		if root == "" {
			root = "."
		}

		dbPath = resolveDBPath(root, dbPath)

		filters := make(map[string]string)
		if filterStatus != "" {
			filters["status"] = filterStatus
		}
		if filterAspect != "" {
			filters["aspect"] = filterAspect
		}

		projectID := utils.ReadProjectID(cmd)

		sel, err := selectNext(selection{
			DBPath:               dbPath,
			Root:                 root,
			ProjectID:            projectID,
			Filters:              filters,
			AllowUnknownExternal: allowUnknownExternal,
			Stderr:               cmd.ErrOrStderr(),
		})
		if err != nil {

			if guarded := utils.GuardContract(cmd, err); errors.Is(guarded, utils.ErrContractFailed) {
				return guarded
			}
			return fmt.Errorf("select next priority: %w", err)
		}

		out := cmd.OutOrStdout()

		if format == FormatJSON {
			return emitJSON(out, sel)
		}

		if sel.Token == nil {
			printNoWork(out, sel.Source, sel.Blocked)
			return nil
		}

		if dryRun {
			fmt.Fprintf(out, "Next priority (dry run): %s - %s\n", sel.Token.ReqID, sel.Token.Feature)
			fmt.Fprintf(out, "Priority: %d | Status: %s | Aspect: %s\n", sel.Token.Priority, sel.Token.Status, sel.Token.Aspect)
			fmt.Fprintf(out, "Location: %s\n", sel.Token.FilePath)
			fmt.Fprintf(out, "Source: %s\n", sel.Source)
			return nil
		}

		promptArg, _ := cmd.Flags().GetString("prompt-arg")
		output, err := renderPrompt(root, sel.Token, projectID, dbPath, promptFlag, promptArg)
		if err != nil {
			return fmt.Errorf("render prompt: %w", err)
		}

		fmt.Fprintln(out, output)
		return nil
	},
}