CLI: machine-actionable error codes in `--agent` JSON output

[yamcodes]

This was generated by AI during triage.

Summary

When arkenv init refuses to proceed because a safety check tripped (unmet technical requirements, dirty git tree, non-empty directory), the --agent / --json output does not tell the calling agent which check failed or how to escalate. Agents are left pattern-matching on prose like "Use --force to bypass these checks."

Spun out of the discussion on #1111, where it was decided that --agent must never imply --force — meaning agents need a deliberate, machine-readable path to escalate instead.

Current behavior

• Safety-check refusals are reported via human-oriented error/info log lines (e.g. Technical requirements not met: … Use --force to bypass these checks.), and the command exits without a structured explanation.
• The JSON reporter's terminal status: "error" payload carries only free-text message/error fields — no stable identifier distinguishing "requirements not met" from "dirty git tree" from any other failure.

Desired behavior

Every deliberate refusal in the CLI's JSON output carries:

• a stable, documented error code (e.g. REQUIREMENTS_NOT_MET, GIT_TREE_DIRTY, NON_EMPTY_DIR) that is part of the CLI's public contract;
• a retryWith hint listing the flags that would bypass the check (e.g. ["--force"]), empty when the failure is not bypassable;
• enough structured detail for the agent to report the problem (e.g. the failed requirements with current/expected).

Unexpected/internal errors keep a generic code (e.g. INTERNAL) so consumers can distinguish "the CLI refused" from "the CLI broke".

Acceptance criteria

• Each safety-check refusal in init (requirements, git status, non-empty directory) emits a distinct stable code in JSON mode
• Bypassable refusals include a retryWith array naming the bypass flag(s)
• Codes are documented (CLI docs and/or agent skill guidance) as a stable contract
• The agent skill guidance explains the escalation pattern: run without --force, inspect code/retryWith, retry deliberately
• Human-readable (non-JSON) output is unchanged
• Tests cover the JSON shape for each refusal path

Out of scope

• Changing --agent, --yes, or --force semantics (settled in should we keep both --yes and --force ? #1110 / should --agent continue using --yes? should it use --force? #1111)
• Error codes for validation failures (ArkEnvError) — separate surface
• Retrofitting codes onto commands other than init (can follow once the pattern exists)

Related

• should --agent continue using --yes? should it use --force? #1111 — decision: --agent implies --yes, never --force
• should we keep both --yes and --force ? #1110 — decision: keep both --yes and --force

[pullfrog]

This run croaked 😵

The workflow encountered an error before any progress could be reported. Please check the link below for details.

  ^{｜ Rerun failed job ➔ ｜ View workflow run ｜ via Pullfrog ｜ 𝕏}

[yamcodes]

This was generated by AI during triage.

Agent Brief

Category: enhancement
Summary: Add stable error codes and retryWith hints to the CLI's JSON output for deliberate safety-check refusals in init.

Current behavior:
When arkenv init runs in --agent/--json mode and a safety check trips — unmet technical requirements, dirty git working tree, or scaffolding into a non-empty directory — the refusal surfaces only as human-oriented log lines (e.g. "Technical requirements not met:" followed by "Use --force to bypass these checks."). The JSON reporter's terminal error payload contains only free-text message/error fields. A calling agent cannot distinguish which check failed, whether it is bypassable, or how to escalate, without parsing prose.

Desired behavior:
Deliberate refusals emit a structured JSON payload containing:

• code: a stable string identifier unique per refusal reason (suggested: REQUIREMENTS_NOT_MET, GIT_TREE_DIRTY, NON_EMPTY_DIR; internal/unexpected failures use a generic code such as INTERNAL)
• retryWith: an array of flag strings that would bypass the check (e.g. ["--force"]), empty when the refusal is not bypassable
• structured details sufficient for the agent to report the problem, e.g. the list of failed requirements with their current and expected values

The codes are a public contract: documented, covered by tests, and never renamed casually. Non-JSON (human) output is byte-for-byte unchanged.

Key interfaces:

• The JSON reporter's terminal error method (currently fatal(message, error?) emitting { status: "error", details: {...} }) — needs to carry code and retryWith, or a sibling method for structured refusals should be added
• The init command's safety-check paths (requirements scan, git status check, non-empty-directory guard) — each currently logs and returns early; each must map to its distinct code
• The reporter port shared by text/JSON/memory reporters — whatever shape is chosen must keep text output unchanged and be testable via the memory reporter
• CLI documentation and the ArkEnv agent skill guidance — must list the codes and describe the escalation pattern (run without --force, inspect code/retryWith, retry deliberately)

Acceptance criteria:

• In JSON mode, failing technical requirements yields a payload with code: "REQUIREMENTS_NOT_MET", retryWith: ["--force"], and per-requirement details including current/expected values where available
• In JSON mode, a dirty git tree yields code: "GIT_TREE_DIRTY" with retryWith: ["--force"]
• In JSON mode, the non-empty-directory guard yields code: "NON_EMPTY_DIR" with retryWith: ["--force"]
• Unexpected errors carry a generic code distinct from all refusal codes
• Human-readable output for all these paths is unchanged (existing text-reporter tests still pass unmodified)
• Tests assert the exact JSON shape for each refusal path
• Codes and the escalation pattern are documented in the CLI docs and/or the arkenv agent skill

Out of scope:

• Any change to --agent, --yes, or --force semantics (settled in should we keep both --yes and --force ? #1110/should --agent continue using --yes? should it use --force? #1111)
• Error codes for schema validation failures (ArkEnvError)
• Commands other than init