* feat(#2790): add read-only planning.inspect schema-v1 snapshot query Adds a read-only query emitting a schema-versioned JSON projection of .planning/ so downstream harness UIs can consume planning state without parsing GSD's Markdown a second time. Composed strictly from the ADR-3180 section 7 owners plus parsePlanDocument, parseRequirements and parseUatItems; markdown structure is read through the Markdown Sectionizer and Markdown Table Model seams. It declares its own flat external schema rather than serializing PlanningSnapshot, which is the diagnostic-rule subject and still growing. Extracts plan-document parsing out of cmdPhasePlanIndex into a shared leaf module so phase.plan-index and planning.inspect cannot drift, including the plan-id derivation both surfaces report. Also fixes parseRequirements dropping the separator delimiter used by the shipped requirements template, surfaced while wiring the requirement rows. * fix(#2790): close spec gaps and a raw-text test assertion found in review Review findings from the standards, spec and security passes: - phases[] rows carry goal and dependencies, the two per-phase elements the issue Summary names that had no corresponding field. Goal is bounded to the section's leading prose so the Depends-on line, the Plans checklist and the wave annotations are not duplicated into it. - requirement rows carry their own diagnostic codes, so a consumer no longer has to string-parse the global diagnostics subject to correlate. - roadmap_acceptance.checkbox is looked up through the phase-id key owners. It was compared raw against the on-disk directory name, so it read null for every real-world slugged phase directory and the evidence channel was inert. - the hostile-input test asserts the structured payload instead of matching the raw stdout string. The absence proof over raw stdout is kept deliberately. * fix(#2790): register planning in the runtime usage list and repair fixtures Remote runner reported 9 failures on 9b3f9aa. Two root causes, both fixed: - gsd-tools.cjs registered the planning family in HOST_COMMAND_ROUTERS but never added it to TOP_LEVEL_USAGE's Commands list. Those are two surfaces a parity test guards, and the top-of-file block comment is not the runtime help string. A real wiring gap that every local gate and three review passes missed. - the new suite's fixtures could not produce a resolvable phase set. STATE.md frontmatter omitted the milestone field, which ADR-3180 7.2 rule 1 makes the primary milestone selector, so the phase set scoped unscoped and every percentage was correctly withheld. Separately declarePhase returned a path without creating the directory, so a phase declared but never written to left phases empty. Both reproduced against the built module before fixing. No assertion was weakened. The withholding path is still exercised and still returns null when the roadmap is absent. * chore(#2790): backfill changeset pr number * test(#2790): cover every enumerated matrix row and contain a symlink escape Reverses a silent deferral. An earlier revision left 23 of the 78 enumerated matrix rows unimplemented and 7 more as one-off manual checks, with a paragraph in the artifact and the PR body describing the gap. CLAUDE.md is explicit that such a note is not a fix and is not surfacing. The rows are implemented instead and the manual-evidence bucket is gone: 49 test cases become 88, covering all 78. Writing the symlink row proved a real leak: a *-PLAN.md symlinked outside .planning/ had its content emitted into the payload, confirmed via a direct call and the spawned CLI. readDocument now resolves target and planning root with realpathSync and rejects an escape, returning the ordinary unreadable-document shape. Tested both ways, because a containment check that over-rejects is its own defect: an escaping symlink leaks nothing and degrades that plan alone, while a legitimately relocated .planning/ symlink stays fully readable. The three new modules are registered in the mutation COVERED registry, which had been reporting has_work false and skipping the Stryker gate entirely. Provisional non-binding floors so the shards run and report; raised to the measured value before merge, since the registry forbids calibrating from a local run. * fix(#2790): satisfy the mutation ratchet contract and scope the 1MB test Remote runner reported 16 failures on 8c451ed. Two causes. The COVERED registry has a paired contract the earlier commit violated: every module needs a matching RATCHET_BASELINE entry, and minScore must be between 50 and 100 with minScore === baseline. The provisional floor of 1 was illegal on both counts. All three modules now sit at 50 — the registry's own enforced minimum — with matching baselines. The score cannot be measured locally: the shard runs node --test, which this repo hard-blocks, so CI is the only source. Floors are raised to the measured value once this PR's shards report; a shard below 50 means the tests need strengthening, since the floor cannot go lower. The 1MB test was measuring the test harness rather than the product. The command handles the oversized payload correctly by spilling to a tmpfile and resolving it back, but the resolved stdout then exceeds runGsdTools' maxBuffer and the helper reports ENOBUFS. It now uses --pick so stdout stays one byte while the full 1MB document is still read and parsed end to end. * fix(#2790): wire containment across every document read this command drives An isolated security review of the containment control found the boundary logic sound but not comprehensively wired: two content reads reached the filesystem without it. An escaped phase DIRECTORY could enumerate external filenames into the file fields and diagnostic subjects. Both enumeration sites now containment-check the directory before reading. Worth recording that the leak was already prevented one layer earlier than the review claimed: Dirent#isDirectory() reports false for a directory symlink, so such a directory never becomes a phase row at all. The guard is defense-in-depth for a direct caller and for platforms where a reparse point reports as a directory. A *-VERIFICATION.md symlinked outside the root leaked one frontmatter value verbatim, because readVerificationStatus does its own read and copies an unrecognized status into the payload's next_action. Closed from the consumer side through that function's existing fs injection seam, so src/verification.cts keeps its signature and its other callers are untouched. The reviewer additionally rated a forged status: passed as an integrity bypass. It is not: anyone able to plant the symlink can plant a real VERIFICATION.md saying the same thing. The incremental risk is confidentiality, which is what these fixes close. src/plan-scan.cts is deliberately unchanged: isPlanSuperseded reads symlink-followed content but yields only a derived boolean, no document text. * test(#2790): give the mutation shards an in-process surface Two Stryker shards were CANCELLED at the 15-minute cap, not failed on score. CI log: 640 mutants instrumented, and the dry run reported 'Ran 1 tests in 20 seconds' because the shards pointed at the integration suite, where nearly every case spawns a gsd-tools subprocess and Stryker's command runner treats the whole test-runner invocation as a single test. 640 x 20s cannot finish in 15 minutes; at the kill it was 27/640 with an ETA over an hour. Every other COVERED module points at a property or unit file, and the workflow's own paths filter lists exactly those two patterns. In-process is the intended mutation surface; the shards were pointed at the wrong shape of test. Adds tests/planning-inspect.unit.test.cjs — 39 cases in 10 describes that spawn nothing and call the built modules directly. plan-document and the router need no filesystem at all, one being a pure content-to-object parser and the other taking an injected mock. The three shards now point here. The 91-case integration suite is untouched and still runs in the normal test job. * chore(#2790): ratchet mutation floors to the measured CI scores CI run 32392791843 measured all three shards, which is the only source the registry accepts — local runs count timeouts as kills and inflate badly. planning-command-router 95.65 -> floor 94 plan-document 76.58 -> floor 75 planning-inspect 57.03 -> floor 56 Applied the registry's own rule, floor(score) - 1, and updated RATCHET_BASELINE to match, since the ratchet test enforces equality. planning-inspect sits well below the file's target of 80 and is the obvious ratchet candidate as its tests improve. planning-command-router already exceeds the target. The placeholder comment about floors pending measurement is removed rather than left standing as a false statement. --------- Co-authored-by: sim <sim@local>
This commit is contained in:
Tom Boucher
@@ -578,6 +578,102 @@ Pass `--json` to receive the typed IR directly (useful in scripts and test asser
|
||||
|
||||
---
|
||||
|
||||
## Planning Snapshot Commands
|
||||
|
||||
### `planning inspect`
|
||||
|
||||
Emits a read-only, schema-versioned snapshot of everything `.planning/` knows,
|
||||
as one JSON document. It exists so a downstream tool — a harness UI, a
|
||||
mission-control view, a dashboard — can consume planning state without parsing
|
||||
`ROADMAP.md` / `REQUIREMENTS.md` / `*-PLAN.md` / `*-SUMMARY.md` a second time
|
||||
and drifting from gsd-core's own answers.
|
||||
|
||||
```bash
|
||||
gsd-tools query planning inspect
|
||||
gsd-tools query planning.inspect # dotted canonical form — identical output
|
||||
```
|
||||
|
||||
**Takes no arguments.** A stray positional or an unrecognized flag is a
|
||||
fail-loud usage error, not a silently-ignored one: a caller who believed
|
||||
`--phase 3` was scoping the query would otherwise receive a whole-project
|
||||
snapshot presented as a scoped one.
|
||||
|
||||
`planning inspect` writes nothing, anywhere. It is safe to run against a
|
||||
project mid-workflow.
|
||||
|
||||
#### The schema contract
|
||||
|
||||
```json
|
||||
{ "schema_version": 1, "...": "..." }
|
||||
```
|
||||
|
||||
`schema_version` is the contract. **A consumer must reject any value other than
|
||||
the one it was written against** rather than best-effort-parsing a shape it does
|
||||
not know. Every top-level key is always present; a key is never omitted to
|
||||
signal absence, because omission is itself something callers come to depend on.
|
||||
|
||||
| Key | What it carries |
|
||||
|-----|-----------------|
|
||||
| `schema_version` | Always `1` today |
|
||||
| `generated_from` | Resolved `cwd` and `.planning/` root (`null` when there is no planning root) |
|
||||
| `milestone` | `version`, `name`, and the `scope` of that answer |
|
||||
| `active` | `phase`, `plan`, and `status` — three distinct STATE.md facts, each scoped separately |
|
||||
| `phases[]` | Per phase: completion, verification, roadmap acceptance, UAT, plan and task rows |
|
||||
| `orphan_phase_dirs[]` | Directories under `phases/` that the current milestone window does not declare |
|
||||
| `requirements[]` | Requirement rows with mapped-phase traceability |
|
||||
| `progress` | `accepted_phases` and `completed_plans`, as independent fractions |
|
||||
| `diagnostics[]` | Coded reasons for every non-answer above |
|
||||
|
||||
#### Three kinds of evidence, never folded together
|
||||
|
||||
Each phase reports `verification`, `roadmap_acceptance`, and `uat` **side by
|
||||
side**. They are not combined into a single verdict, because they answer
|
||||
different questions and can legitimately disagree — a phase can pass
|
||||
verification while UAT items remain open.
|
||||
|
||||
`roadmap_acceptance.checkbox` is reported with `authoritative: false`. A ticked
|
||||
ROADMAP checkbox is a human annotation with no machine authority: completion is
|
||||
derived from disk state (a passing `*-VERIFICATION.md`), and a stale tick never
|
||||
overrides it. See [Milestone window scope](#milestone-window-scope-roadmap-analyze).
|
||||
|
||||
#### Unknown is a real answer; nothing is inferred
|
||||
|
||||
Where the evidence is absent, or where two sources disagree, the value is `null`
|
||||
or `"unknown"` and a coded entry in `diagnostics[]` says why. It is never
|
||||
reconciled, guessed, or filled from a plausible default.
|
||||
|
||||
The most common case is task-scoped file provenance. A `<task>` block declares
|
||||
the files it plans to touch, but `SUMMARY.md`'s `## Files Created/Modified`
|
||||
section describes the **whole plan**, not an individual task. Spreading that
|
||||
plan-level list across the plan's tasks would be inference, so instead:
|
||||
|
||||
| `provenance` | Meaning |
|
||||
|---|---|
|
||||
| `task_scoped` | The summary attributed files to this specific task (via a deviation block naming `Found during: Task N`) |
|
||||
| `plan_scoped` | A summary exists, but only carries a plan-level file list — this task's changed files are unknown |
|
||||
| `absent` | No summary exists yet |
|
||||
|
||||
When a task's planned and changed file sets both exist and disagree,
|
||||
`agreement` is `"conflicting"` and **both lists are emitted verbatim**.
|
||||
|
||||
#### Percentages are withheld rather than guessed
|
||||
|
||||
`progress.accepted_phases` and `progress.completed_plans` are independent
|
||||
fractions, each `{completed, total, percent, scope}`. `percent` is `null`
|
||||
whenever `scope` is anything other than `complete` — the same rule the roadmap
|
||||
and progress surfaces follow, for the same reason. See
|
||||
[A non-`COMPLETE` scope withholds the percentage entirely](#a-non-complete-scope-withholds-the-percentage-entirely-3217).
|
||||
|
||||
`0` is a real answer under a `complete` scope and is never withheld.
|
||||
|
||||
#### Large payloads
|
||||
|
||||
Output over ~50 KB is written to a temp file and returned as
|
||||
`@file:<path>`, which `gsd-tools` resolves transparently before writing to
|
||||
stdout — the same channel `init` uses. Callers see JSON either way.
|
||||
|
||||
---
|
||||
|
||||
## Template Commands
|
||||
|
||||
Template selection and filling.
|
||||
|
||||
Reference in New Issue
Block a user