work-on-task: --non-interactive mode for headless callers

[bborbe]

Why

Fixes the root cause of the Vault UI "Start" hang (claude session start timed out after 5m). vault-cli work-on bootstraps a session with claude --print -p '/vault-cli:work-on-task "<file>"' — a headless turn that cannot answer AskUserQuestion. Today work-on-task asks in Phase 4 (create missing task) and Phase 5 (plan-task sharpening), so the headless turn blocks until the timeout.

What

• /vault-cli:work-on-task parses --non-interactive (deprecated alias --tool), strips it from the task identifier, and:
  • Phase 4 (not_found): prints the report + "no task created" note and STOPs — no AskUserQuestion.
  • Phase 5 (sharpen/gate): skipped entirely — no plan-task/execute-task (both interactive). Orient-and-stop; interactive sharpening resumes on terminal resume.
• Assistant unchanged — it already forbids AskUserQuestion by design.
• CHANGELOG under ## Unreleased.

Sequencing

Depends on the flag-name convention from #45 (rename --tool→--non-interactive). Must merge before the Go change that makes vault-cli work-on pass --non-interactive (dark-factory prompt drafted, held pending these two merges).

[ben-s-pull-request-reviewer]

Based on my review, let me compile the findings.

Diff Summary: Only 2 files changed — CHANGELOG.md (unreleased changelog entry) and commands/work-on-task.md (slash command documentation). No Go code changes.

Review Findings:

Should Fix (Important):

1. --tool alias dependency on PR #45 unverifiable — The Plan notes the deprecated --tool alias "depends on flag-rename from PR #45." I cannot verify whether PR #45 was merged into this branch. The current diff correctly references --tool as deprecated in the parsing logic, but if PR #45's flag-rename was not merged, the alias may not actually work. Recommendation: confirm PR #45 is merged into feature/work-on-task-non-interactive.

2. No scenario coverage for non-interactive paths — scenarios/002-task-lifecycle.md tests task work-on "Simple Task" (interactive path) but does not test --non-interactive. Per CLAUDE.md: "After completing a spec or major refactor, walk the relevant scenarios/*.md to verify end-to-end behavior." The new non-interactive MODE branches (Phase 4 not_found gate and Phase 5 skip) have no corresponding scenario steps.

Optional:
3. CHANGELOG entry is thin — lists what is skipped but not what IS done (orient = assistant's status + daily note + guides). Could be clearer.

Correctness verification (documentary code review):

• Phase 4 non-interactive gate: ✅ Correctly skips all 7 create-gate steps and all AskUserQuestion calls
• Phase 5 non-interactive gate: ✅ Correctly skips plan-task and execute-task, prints orient-complete message
• Stripping logic: ✅ Both --non-interactive and deprecated --tool are stripped before assistant prompt
• argument-hint updated: ✅ Shows [--non-interactive]
• Stripped args used in assistant prompt: ✅ Uses {stripped arguments}

---

{
  "verdict": "request-changes",
  "summary": "The non-interactive MODE gates in both Phase 4 and Phase 5 are correctly implemented in the command documentation. However, the deprecated `--tool` alias depends on a flag-rename from PR #45 that could not be verified, and the non-interactive branches have no scenario coverage — the existing `scenarios/002-task-lifecycle.md` only tests the interactive path.",
  "comments": [
    {
      "file": "commands/work-on-task.md",
      "line": 20,
      "severity": "major",
      "message": "Should Fix (Important): The deprecated `--tool` alias is listed in the parsing logic but the Plan notes it 'depends on flag-rename from PR #45'. Verify PR #45 is merged into this branch — if the flag-rename was not merged, `--tool` will not be recognized and headless callers using the deprecated alias will fall through to interactive mode unexpectedly."
    },
    {
      "file": "commands/work-on-task.md",
      "line": 86,
      "severity": "major",
      "message": "Should Fix (Important): No scenario coverage for the non-interactive MODE branches. `scenarios/002-task-lifecycle.md` only tests `task work-on \"Simple Task\"` (interactive path). Add a scenario or scenario variant that tests `--non-interactive` to cover the Phase 4 not_found gate and Phase 5 orient-and-stop path. Per CLAUDE.md, all changed behavior should be verifiable via scenarios."
    }
  ],
  "concerns_addressed": [
    "correctness: MODE=non_interactive gate in Phase 4 — CONFIRMED: correctly skips all AskUserQuestion calls and create-gate steps 1-7",
    "correctness: MODE=non_interactive gate in Phase 5 — CONFIRMED: correctly skips plan-task and execute-task entirely",
    "correctness: Stripping logic — CONFIRMED: both --non-interactive and deprecated --tool are parsed and removed before passing to assistant prompt",
    "correctness: deprecated --tool alias depends on PR #45 — UNVERIFIED: cannot confirm PR #45 flag-rename was merged; flagged as Should Fix",
    "tests: No test coverage visible in diff — CONFIRMED: only interactive path tested in scenarios; non-interactive paths have no scenario coverage"
  ]
}

[bborbe]

Addressed the review:

Finding 1 (--tool / #45 dependency): Resolved by removing the --tool alias here. work-on-task never had --tool, and the Go caller (vault-cli work-on) will pass --non-interactive, so the alias was dead weight. Parsing of --non-interactive is self-contained in this command and has no dependency on #45 (which only renames --tool→--non-interactive in the create/complete/defer family). Clarified inline.

Finding 2 (scenario coverage): Not applicable to this change. scenarios/*.md are executable acceptance tests against the built binary ($VAULT_CLI ... task work-on). This PR changes only the Claude-interpreted /vault-cli:work-on-task slash-command markdown — there is no binary flag or CLI surface for a scenario to drive. The binary-level piece (vault-cli work-on appending --non-interactive to the claude --print bootstrap) is a separate change, and even there the bootstrap shells out to claude, which is non-deterministic/unavailable in a scenario run. No scenario added by design; documenting the rationale per the guardrail override process.

superseded by new automated review

[ben-s-pull-request-reviewer]

Based on my review of the diff against master, here is my analysis:

Diff Summary

• CHANGELOG.md: Added ## Unreleased section describing --non-interactive feature
• commands/work-on-task.md: Added --non-interactive flag with gates in Phases 4 and 5

Concern Verification

Concern	Verdict
Phase 4 gate order — non-interactive checked FIRST before interactive steps	✅ VERIFIED. Gate at line 1 of Phase 4, before steps 1–7
Strip flag from $ARGUMENTS before passing to assistant prompt	✅ VERIFIED. Step 1 strips --non-interactive, Step 2 explicitly uses "stripped arguments"
Phase 4 not_found security — no sensitive data in report	✅ VERIFIED. Report only contains Searched sources block and task-not-found message
Assistant path safety — assistant itself doesn't emit AskUserQuestion	✅ VERIFIED. Assistant Phase 2 only orients (status, daily note, guides). AskUserQuestion lives in Phases 4/5 which are skipped
Test coverage — none visible in diff	✅ ACCEPTABLE. Changed files are markdown only (CHANGELOG + command file). No Go code affected

Findings

None. The implementation correctly:

• Checks non-interactive mode FIRST in both Phase 4 and Phase 5 gates
• Strips the flag token before passing to assistant (self-contained parsing as documented)
• Suppresses AskUserQuestion calls in non-interactive mode
• Prints appropriate informational messages for headless callers
• Documents the feature properly in CHANGELOG.md under ## Unreleased

{
  "verdict": "approve",
  "summary": "The --non-interactive feature is correctly implemented with gates placed FIRST in Phases 4 and 5, proper argument stripping before assistant invocation, and no AskUserQuestion leakage. No test coverage needed — this is a command-file change, not Go code.",
  "comments": [],
  "concerns_addressed": [
    "correctness: Phase 4 gate order verified — non-interactive check is first",
    "correctness: $ARGUMENTS stripped before assistant prompt — verified",
    "security: Phase 4 not_found report contains only source list, no sensitive data",
    "correctness: assistant path does not emit AskUserQuestion — verified",
    "tests: no test coverage expected for markdown command file change"
  ]
}

superseded by new automated review

[ben-s-pull-request-reviewer]

Review Complete

Files changed: CHANGELOG.md, commands/work-on-task.md

Analysis

Concern 1 (Flag parsing): The --non-interactive flag is parsed self-contained in Step 1. It sets MODE=non_interactive and strips the flag token. The stripped arguments are used consistently in the Step 2 assistant prompt ({stripped arguments}) and the Phase 4/5 gates check MODE=non_interactive. ✓

Concern 2 (Phase 4 gate): The non-interactive gate is checked first, skips AskUserQuestion and task creation, prints the not_found report + info message, and stops before steps 1-7. ✓

Concern 3 (Phase 5 gate): The non-interactive gate skips Phase 5 entirely (no plan-task or execute-task), prints the orient message, and stops. ✓

Concern 4 (Tests): No test coverage added. Since the changed files are markdown command definitions (not Go code), traditional test suites don't apply. This is Nice to Have.

Toolchain: ast-grep-runner was blocked by permission system — mechanical funnel unavailable, but no code issues found from manual review.

{
  "verdict": "approve",
  "summary": "The `--non-interactive` flag implementation in work-on-task.md is correct: flag parsing strips the token before use, Phase 4 gate skips AskUserQuestion and task creation in non-interactive mode, and Phase 5 gate skips the plan-task/execute-task sharpening chain entirely. All three concerns from the plan are addressed. LICENSE file exists. No Must/Should fixes identified.",
  "comments": [],
  "concerns_addressed": [
    "correctness: Flag parsing correctly strips `--non-interactive` token and uses stripped args in Step 2 prompt (commands/work-on-task.md:20-21,29)",
    "correctness: Phase 4 non-interactive gate skips AskUserQuestion and task creation (commands/work-on-task.md:51)",
    "correctness: Phase 5 non-interactive gate skips plan-task and execute-task entirely (commands/work-on-task.md:86)",
    "tests: No test coverage for non-interactive paths — Nice to Have (markdown command files don't have traditional tests)"
  ]
}