fix(walkthrough): honesty + discoverability fixes across CLI surfaces

Auto interactive-walkthrough of the Atlas CLI surfaces (5 reviewed, no P0/P1).
Four evidence-backed fixes under TDD + Second-Check:
- validate-prd Check 6: fail-closed on an ABSENT requirements section instead of
  vacuously passing + claiming 'all requirements are specific' (P2 honesty).
- watcher permit reason: surface a cheating-winner discrepancy instead of masking
  it behind 'no to-be-slashed' (P2 legibility; the permit boolean is unchanged).
- set-status --status: enumerate the valid status vocabulary in -h (P2).
- engine-preflight/next-task/economy-report: add missing flag help (P3 consistency).

RAG-ready runlogs under .i-walkthroughs/entries/. Offline suite 886 passed / 5 skipped.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: claude

.i-walkthroughs/README.md

@@ -0,0 +1,6 @@
+# Interactive-walkthrough runlogs
+
+RAG-ingestion-ready learning units from `/interactive-walkthrough` runs on this repo.
+One file per (surface, issue) under `entries/`; `index.jsonl` is the append-only machine index;
+`schema.md` is the single source of truth. Headless repo: "route" = a CLI/MCP surface
+(e.g. `cli:validate-prd`), evidence = live CLI/test runs.

.i-walkthroughs/entries/2026-06-17-cli-undocumented-flags.md

@@ -0,0 +1,57 @@
+---
+id: 2026-06-17-cli-undocumented-flags
+schema_version: 1
+repo: anombyte93/prd-taskmaster
+branch: walkthrough/atlas-cli-surfaces
+commit: pending
+date: 2026-06-17
+route: "cli:set-status"
+screen_purpose: "Expose the engine's CLI flags clearly enough that a cold user can discover what each does — and what values it accepts — from -h alone."
+mode: auto
+viewport: cli
+device_class: desktop
+severity: P2
+category: interaction
+root_cause: "Several argparse flags were added with no help= string; most damaging, set-status --status is a REQUIRED flag whose valid vocabulary (pending/in-progress/done/review/deferred/cancelled/blocked) appeared nowhere in help, SKILL.md, or the MCP tool."
+assumption_trap: "the flag name is self-documenting (a required enum flag is not — the accepted values must be shown)."
+reusable_rule: "Every CLI flag gets help text; a required enum flag must enumerate its accepted values in that help."
+evidence_method: [code]
+files_changed: ["prd_taskmaster/cli.py", "tests/core/test_cli.py"]
+first_check: {result: fail, metric: "build_parser(): set-status --status, engine-preflight --no-configure, next-task --tag, economy-report --input all have help==None", evidence_ref: "pytest test_cli_flags_have_discoverable_help (pre-fix RED) + live set-status -h showing bare '--status STATUS'"}
+second_check: {result: pass, metric: "all four flags have non-empty help; set-status --status help contains 'in-progress'", evidence_ref: "pytest (GREEN) + live: set-status -h now prints 'Task status; one of: pending, in-progress, done, review, deferred, cancelled, blocked'", regression_scan: pass}
+regression_checks: ["set-status invalid-status error path unchanged (help-only, no argparse choices added → still returns FR-28 dict, not an argparse usage error)", "all existing CLI subprocess tests", "full offline suite"]
+verdict: resolved
+status: verified
+approval: pending
+evidence_dir: evidence/2026-06-17-cli-undocumented-flags
+tags: [cli, discoverability, help-text, consistency, set-status]
+related: []
+title: "Undocumented CLI flags — esp. set-status --status whose valid vocabulary was undiscoverable"
+---
+
+## Lesson (TL;DR)
+Four CLI flags carried no help text; the worst was `set-status --status`, a REQUIRED flag whose accepted values were findable nowhere a user looks (`-h`, SKILL.md, or the MCP tool). A cold user had to read source to learn the status vocabulary. Every flag gets help; a required enum flag enumerates its values.
+
+## Screen & Purpose
+Surfaces `cli:set-status`, `cli:engine-preflight`, `cli:next-task`, `cli:economy-report`. Soul purpose: a self-describing CLI a cold user can drive from `-h`.
+
+## Issue (first check)
+`build_parser()` introspection: `set-status --status`, `engine-preflight --no-configure`, `next-task --tag`, `economy-report --input` all had `help is None`. Live `set-status -h` printed `--status STATUS` with no value list — the vocabulary (pending/in-progress/done/review/deferred/cancelled/blocked) was invisible.
+
+## Root Cause
+Flags were added via `add_argument(...)` without `help=`. Inconsistent with sibling flags (e.g. `parse-prd --input`) that do carry help.
+
+## Fix
+`cli.py`: add help strings to the four flags. For `set-status --status`, the help enumerates the valid status vocabulary. Help-only (NOT argparse `choices=`) so the engine's existing FR-28-safe status validation + error dict is preserved rather than replaced by an argparse usage error.
+
+## Second Check (re-verification, MANDATORY)
+Post-fix: introspection shows all four flags with non-empty help; `set-status --status` help contains "in-progress"; live `set-status -h` prints the full status list. Regression scan: the invalid-status path still returns the engine's FR-28 error dict (no `choices=` added, so no behavior change to error handling); all existing CLI subprocess tests pass; full offline suite green. `regression_scan=pass`, `verdict=resolved`.
+
+## Reusable Rule
+Every CLI flag gets help text; a required enum flag must enumerate its accepted values in that help.
+
+## Decision Trail
+Owner: walkthrough auto-mode; real owner approves via PR. Rejected: adding argparse `choices=` for `--status` (would move validation to the parse layer and emit an argparse usage error instead of the engine's structured FR-28 dict — a contract change). Deferred: also documenting the status vocabulary in SKILL.md + the MCP tool description (follow-up; this entry fixes the CLI surface).
+
+## Revisions
+- 2026-06-17: initial fix; second check passed on first attempt.

.i-walkthroughs/entries/2026-06-17-cli-validate-prd-check6-false-pass.md

@@ -0,0 +1,58 @@
+---
+id: 2026-06-17-cli-validate-prd-check6-false-pass
+schema_version: 1
+repo: anombyte93/prd-taskmaster
+branch: walkthrough/atlas-cli-surfaces
+commit: pending
+date: 2026-06-17
+route: "cli:validate-prd"
+screen_purpose: "Give a user a fast, honest, point-scored verdict on whether a PRD is complete enough to parse into a trustworthy task graph."
+mode: auto
+viewport: cli
+device_class: desktop
+severity: P2
+category: trust
+root_cause: "Check 6 ran VAGUE_PATTERN.findall over an empty string when no requirements section existed; an empty match list read as 'no vague terms' → passed:true + 'All requirements are specific'."
+assumption_trap: "no-vague-terms == requirements-are-testable (true only when requirements actually exist)."
+reusable_rule: "A presence/quality check over an ABSENT section must fail-closed, never pass-and-assert-quality on emptiness."
+evidence_method: [code]
+files_changed: ["prd_taskmaster/validation.py", "tests/core/test_validation.py"]
+first_check: {result: fail, metric: "empty PRD → check6.passed=true, detail='All requirements are specific', checks_passed=3, score=13", evidence_ref: "live: python3 script.py validate-prd --input /tmp/wt_empty.md (pre-fix)"}
+second_check: {result: pass, metric: "empty PRD → check6.passed=false, detail='No requirements section found', checks_passed=2, score=8, grade=NEEDS_WORK", evidence_ref: "live post-fix run + pytest -k 'validate_empty_prd or check6_fails_closed'", regression_scan: pass}
+regression_checks: ["sample_prd (real requirements) still passes check6", "thorough PRD still 57/57 EXCELLENT exit 0", "grade boundary tests", "full offline suite tests/core+tests/plugin"]
+verdict: resolved
+status: verified
+approval: pending
+evidence_dir: evidence/2026-06-17-cli-validate-prd-check6-false-pass
+tags: [validate-prd, honesty, fail-closed, vacuous-pass]
+related: []
+title: "validate-prd Check 6 falsely passed + claimed specificity on a PRD with zero requirements"
+---
+
+## Lesson (TL;DR)
+`validate-prd` Check 6 ("Functional requirements are testable") passed AND printed "All requirements are specific" on a PRD that had no requirements section at all — a positively false claim about content that does not exist. Root cause: a vague-term scan over an empty string returns no matches, which the code read as success. A presence/quality check over an absent section must fail-closed.
+
+## Screen & Purpose
+Surface `cli:validate-prd` (13-check PRD quality gate, `validation.py:run_validate_prd`). Soul purpose: an honest, point-scored verdict on PRD completeness. Headless/CLI; evidence = live runs + unit tests.
+
+## Issue (first check)
+Live, pre-fix, on a PRD containing only a title + Overview (zero requirements):
+`check 6 → passed:true, detail:"All requirements are specific"`; `checks_passed:3, score:13`. The detail makes an affirmative specificity claim about requirements that are absent. (The final grade NEEDS_WORK was already correct; the defect is the per-check honesty + an inflated checks_passed.)
+
+## Root Cause
+`reqs_section` was empty; `VAGUE_PATTERN.findall("")==[]` → `passed = len([])==0 = True` and the else-branch detail "All requirements are specific" fired. The check never distinguished "present and specific" from "absent".
+
+## Fix
+`validation.py`: when `reqs_section.strip()` is empty, emit `passed:false, detail:"No requirements section found"` (fail-closed); otherwise the original vague-term logic. Smallest coherent change; checks 5 & 10 (user-stories / NFRs are genuinely OPTIONAL sections) left intentionally untouched.
+
+## Second Check (re-verification, MANDATORY)
+Same empty PRD, post-fix: `check 6 → passed:false, detail:"No requirements section found"`, `checks_passed:2, score:8, grade:NEEDS_WORK`. Same-metric assertion now passes. Regression scan: `sample_prd` (real requirements) still passes check 6; a thorough PRD still scores 57/57 EXCELLENT (exit 0); grade-boundary tests green; full offline suite green. `regression_scan=pass`, `verdict=resolved`.
+
+## Reusable Rule
+A presence/quality check over an ABSENT section must fail-closed — never pass-and-assert-quality on emptiness.
+
+## Decision Trail
+Owner: walkthrough auto-mode (Hayden stand-in); real owner approves via the PR. Rejected: only rewording the detail while keeping `passed:true` (would leave the vacuous pass + inflated count). Deferred: checks 5 & 10 pass-on-absent (P3; those sections are legitimately optional) — recorded for a future decision.
+
+## Revisions
+- 2026-06-17: initial fix; second check passed on first attempt.

.i-walkthroughs/entries/2026-06-17-cli-watcher-permit-reason-mask.md

@@ -0,0 +1,57 @@
+---
+id: 2026-06-17-cli-watcher-permit-reason-mask
+schema_version: 1
+repo: anombyte93/prd-taskmaster
+branch: walkthrough/atlas-cli-surfaces
+commit: pending
+date: 2026-06-17
+route: "cli:watcher-run"
+screen_purpose: "Let an operator see the fail-closed real-slash permit for a job and understand WHY it is or isn't permitted."
+mode: auto
+viewport: cli
+device_class: desktop
+severity: P2
+category: trust
+root_cause: "The permit reason ladder tested `not to_slash` before `discrepancies`, so a job with no to-be-slashed submissions but a cheating-winner DISCREPANCY reported the benign 'no to-be-slashed' message instead of the discrepancy."
+assumption_trap: "empty to-be-slashed set == nothing interesting happened (ignores discrepancies/abstains on the winners)."
+reusable_rule: "Order a fail-closed reason ladder most-serious-finding first; never let a benign branch shadow a security-relevant one."
+evidence_method: [code]
+files_changed: ["prd_taskmaster/tournament/watcher.py", "tests/core/test_tournament_watcher.py"]
+first_check: {result: fail, metric: "permit_enforce_slash(record with empty to_slash + cheating-winner DISCREPANCY).reason == 'blocked: no to-be-slashed submissions to confirm' (discrepancy masked)", evidence_ref: "pytest test_permit_reason_surfaces_winner_discrepancy_over_empty_slash (pre-fix RED)"}
+second_check: {result: pass, metric: "same record → reason contains 'discrepancy' and NOT 'no to-be-slashed'; permitted still False; ex-win in discrepancies", evidence_ref: "pytest (post-fix GREEN)", regression_scan: pass}
+regression_checks: ["existing permit reason tests (discrepancy-among-slashes, abstained-winner, empty-to_slash, mixed-batch) unchanged", "permitted boolean decision unchanged across all permit tests", "full offline suite"]
+verdict: resolved
+status: verified
+approval: pending
+evidence_dir: evidence/2026-06-17-cli-watcher-permit-reason-mask
+tags: [watcher, slash-gate, fail-closed, legibility, self-review]
+related: [atlas-watcher-built]
+title: "watcher permit reason masked a caught cheating-winner discrepancy with a benign 'no to-be-slashed' message"
+---
+
+## Lesson (TL;DR)
+The watcher's real-slash permit correctly BLOCKED a job where a winner was an independent discrepancy, but its human-readable `reason` said "no to-be-slashed submissions to confirm" — hiding the very thing the operator most needs to see. The boolean was right; the explanation lied by omission. Order the reason ladder most-serious-first.
+
+## Screen & Purpose
+Surface `cli:watcher-run` → `watcher.permit_enforce_slash` (the fail-closed gate that decides whether real `--enforce-slash` forfeiture may proceed). Soul purpose: an operator-legible, honest permit verdict.
+
+## Issue (first check)
+A record with zero to-be-slashed submissions but a cheating winner (recorded PASS, watcher DISCREPANCY) returned `permitted:false` (correct) with `reason:"blocked: no to-be-slashed submissions to confirm"` (wrong — the discrepancy was in `out["discrepancies"]` but never surfaced in the headline reason). `to_slash` is empty because the winner recorded PASS, so the `elif not to_slash` branch fired before `elif discrepancies`.
+
+## Root Cause
+Reason-ladder ordering: `permitted → not to_slash → discrepancies → abstained → track_record`. The benign empty-set branch shadowed the security-relevant discrepancy branch.
+
+## Fix
+`watcher.py`: reorder the ladder to `permitted → discrepancies → abstained → not to_slash → track_record`. The `permitted` boolean is unchanged (already `not discrepancies and not abstained and ...`); only the explanatory string ordering changed.
+
+## Second Check (re-verification, MANDATORY)
+Post-fix, same record: `reason` contains "discrepancy", does NOT contain "no to-be-slashed", `permitted` still False, `ex-win` in `discrepancies`. Regression scan: all prior permit tests (discrepancy-among-slashes, abstained-winner, empty-to_slash, mixed-batch, concordance boundary) unchanged; every `permitted` boolean identical to before. Full offline suite green. `regression_scan=pass`, `verdict=resolved`.
+
+## Reusable Rule
+Order a fail-closed reason ladder most-serious-finding first; a benign branch must never shadow a security-relevant one.
+
+## Decision Trail
+Owner: walkthrough auto-mode; real owner approves via PR. This fix touches code authored earlier this same session — a good reminder that the adversarial surface review caught a legibility gap the build-time tests didn't assert. No alternatives rejected; the reorder is the minimal correct change.
+
+## Revisions
+- 2026-06-17: initial fix; second check passed on first attempt.

.i-walkthroughs/index.jsonl

@@ -0,0 +1,3 @@
+{"id":"2026-06-17-cli-validate-prd-check6-false-pass","repo":"anombyte93/prd-taskmaster","branch":"walkthrough/atlas-cli-surfaces","route":"cli:validate-prd","date":"2026-06-17","severity":"P2","category":"trust","verdict":"resolved","status":"verified","title":"validate-prd Check 6 falsely passed + claimed specificity on a PRD with zero requirements","file":"entries/2026-06-17-cli-validate-prd-check6-false-pass.md"}
+{"id":"2026-06-17-cli-watcher-permit-reason-mask","repo":"anombyte93/prd-taskmaster","branch":"walkthrough/atlas-cli-surfaces","route":"cli:watcher-run","date":"2026-06-17","severity":"P2","category":"trust","verdict":"resolved","status":"verified","title":"watcher permit reason masked a caught cheating-winner discrepancy","file":"entries/2026-06-17-cli-watcher-permit-reason-mask.md"}
+{"id":"2026-06-17-cli-undocumented-flags","repo":"anombyte93/prd-taskmaster","branch":"walkthrough/atlas-cli-surfaces","route":"cli:set-status","date":"2026-06-17","severity":"P2","category":"interaction","verdict":"resolved","status":"verified","title":"Undocumented CLI flags incl. set-status --status vocabulary","file":"entries/2026-06-17-cli-undocumented-flags.md"}