This commit is contained in:
@@ -1835,7 +1835,7 @@ Presence and posture are separate verdicts: a missing agent is reported in `miss
|
||||
Detect drift between STATE.md and the actual filesystem.
|
||||
|
||||
**Prerequisites:** `.planning/STATE.md` exists
|
||||
**Produces:** Validation report showing any drift between STATE.md fields and filesystem reality
|
||||
**Produces:** Validation report showing any drift between STATE.md fields and filesystem reality, as coded diagnostics
|
||||
|
||||
```bash
|
||||
node gsd-tools.cjs state validate
|
||||
@@ -1845,12 +1845,24 @@ The report also carries a `scope` field reporting whether the drift derivation c
|
||||
|
||||
| `scope` | Meaning |
|
||||
|---|---|
|
||||
| `complete` | The derivation ran over usable input — a resolvable phase, a readable disk scan. `valid`/`warnings`/`drift` are a real answer. |
|
||||
| `complete` | The derivation ran over usable input — a resolvable phase, a readable disk scan. `valid`/`warnings` are a real answer. |
|
||||
| `truncated` | Part of the input was cut short (e.g. the phase's plan/summary scan hit its cap) — the answer may be incomplete. |
|
||||
| `unscoped` | `Current Phase` could not be resolved from either frontmatter or body — there was nothing to scope the disk lookup to, so the derivation never ran. |
|
||||
| `unreadable` | The frontmatter parse or a filesystem read (the phases directory scan) failed — the derivation could not consult its input. |
|
||||
|
||||
`valid` is **not** routed from `scope`: `valid` still means "no drift warnings were found," and `scope` says whether the scan could actually run. A freshly-initialized project reports `{valid:true, warnings:[], drift:{}, scope:'unscoped'}` — nothing was wrong, and the phase could not be checked. See [Interpret `state validate` results](how-to/interpret-state-validate-results.md) for how to act on each `scope` value.
|
||||
`valid` is **not** routed from `scope`: `valid` still means "no warnings were found," and `scope` says whether the scan could actually run. A freshly-initialized project reports `{valid:true, warnings:[], scope:'unscoped'}` — nothing was wrong, and the phase could not be checked. See [Interpret `state validate` results](how-to/interpret-state-validate-results.md) for how to act on each `scope` value.
|
||||
|
||||
Each `warnings` entry is a coded diagnostic object (`{code, severity, message, remedy}`), not a bare string. Every remedy is an `ADVISE` action naming the command or edit to make — none is auto-applied. `S001` is `severity: ERROR` (STATE.md could not be read at all); every other code is `severity: WARNING`:
|
||||
|
||||
| Code | Severity | Meaning |
|
||||
|---|---|---|
|
||||
| `S001` | error | STATE.md is unreadable/corrupt (embedded NUL or binary content) — reported with `valid:false` and no other checks run |
|
||||
| `S002` | warning | No usable `current_phase`/`Current Phase`/`Current Position Phase` value anywhere in STATE.md |
|
||||
| `S003` | warning | STATE.md's phase sources (frontmatter vs. body) disagree on the current phase |
|
||||
| `S004` | warning | The phases directory, or a directory matching the current phase, is missing or unreadable |
|
||||
| `S005` | warning | STATE.md's plan count disagrees with the plan count on disk |
|
||||
| `S006` | warning | STATE.md still says "executing" but a `*-VERIFICATION.md` in the phase shows verification passed |
|
||||
| `S007` | warning | Every plan in the phase has a summary, but STATE.md still says "executing" |
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user