* refactor(#3187): give state field extraction one canonical owner stateFieldValue in state-document.cts becomes the single owner of the #1760 frontmatter-then-body fallback chain. The new whole-repo guard found 14 independent re-derivations where the epic scoped 5, all now routed through it: cmdStateSnapshot (11), cmdStatePrune (2) and smart-entry fmScalar (1). state validate was a gate that could not fail. Every warning it could emit sat behind a phase resolved without the frontmatter tier, so a STATE.md whose phase lives only in frontmatter skipped the drift scan entirely and returned valid:true. It also read unstripped content, letting a frontmatter status: key shadow the body field (#1255 class). Both fixed; output gains a scope field so could-not-look stops being output-identical to looked-and-clean. Verified on the remote runner. * docs(#3187): document the state validate scope field and its reason codes Adds docs/how-to/interpret-state-validate-results.md so a reader can tell nothing-to-report from could-not-look, updates the COMMANDS.md and USER-GUIDE.md entries, corrects the CONTEXT.md glossary overstatement about Current Position sole ownership, and drops the changeset fragment. * fix(#3187): close three drift-guard evasion shapes and test the refuse path The isolated adversarial review found the ladder detector was evadable by ordinary reformatting, not just deliberately: a member or computed operand (fm.key / fm[key]) missed the bare-identifier backreference, a swapped tier order missed a hardcoded number-then-boolean sequence, and a ladder wrapped across lines missed single-line detection. All three now caught, each with its own test plus a proven boundary control. The frontmatter-parse refuse path on the destructive complete-phase route was unreachable and therefore untested. It is now driven by an injected parse failure and asserts STATE.md is byte-identical after the refusal, rather than shipping untested defensive code on a path that rewrites user state. Verified on the remote runner. * fix(#3187): widen the drift guard to the prompt layer and disclose tier-2 changes The code-review spec axis found the guard's scan surface was src/ only, which is Decision 4(d)'s forbidden allowlist one directory wide - and it had a live miss: gsd-core/workflows/smart-entry.md tells an agent to read status from frontmatter or the body, a prose expression of this same chain. The surface now covers the prompt layer. That one site carries a permanent written exemption rather than a ratchet: it is the gsd-tools-is-down fallback, so it cannot call the owner by construction, and a ratchet would imply removable debt that does not exist. Two tier-2 output changes shipped undisclosed and are now named in the changeset and docs: complete-phase's idempotency guard consulting frontmatter, and the workstream inventory resolving frontmatter-only fields. docs/COMMANDS.md gains a state complete-phase entry, which it never had. Also records Amendment 5 on ADR-3180, extracts the duplicated frontmatter-parse block the epic's own thesis forbids, and re-points two assertions from free-form warning prose onto the structured drift object. Verified on the remote runner. * chore(#3187): backfill changeset PR number pr:0 placeholder replaced with the real PR number now that #3283 exists. --------- Co-authored-by: sim <sim@local>
This commit is contained in:
@@ -47,7 +47,7 @@ import phaseLifecycle = require('./phase-lifecycle.cjs');
|
||||
const { deriveProgressFromRoadmap } = phaseLifecycle;
|
||||
// eslint-disable-next-line @typescript-eslint/no-require-imports
|
||||
import stateDocument = require('./state-document.cjs');
|
||||
const { stateExtractField } = stateDocument;
|
||||
const { stateFieldValue } = stateDocument;
|
||||
// eslint-disable-next-line @typescript-eslint/no-require-imports
|
||||
import phaseId = require('./phase-id.cjs');
|
||||
const { comparePhaseNum, extractPhaseToken, normalizePhaseName, phaseTokenMatches } = phaseId;
|
||||
@@ -140,14 +140,6 @@ export const SITUATIONS: readonly Situation[] = Object.freeze([
|
||||
|
||||
// ─── Detection ─────────────────────────────────────────────────────────────────
|
||||
|
||||
/** Frontmatter scalar helper: prefer YAML frontmatter, fall back to body field. */
|
||||
function fmScalar(fm: Record<string, unknown>, body: string, key: string, bodyField: string): string | null {
|
||||
const v = fm[key];
|
||||
if (typeof v === 'string' && v.trim()) return v.trim();
|
||||
if (typeof v === 'number' || typeof v === 'boolean') return String(v);
|
||||
return stateExtractField(body, bodyField);
|
||||
}
|
||||
|
||||
/** Read a scalar value from a nested frontmatter object (e.g. progress.total_phases). */
|
||||
function fmScalarKey(obj: unknown, key: string): string | null {
|
||||
if (!obj || typeof obj !== 'object') return null;
|
||||
@@ -324,26 +316,34 @@ export function detectSignals(cwd: string, now: () => number = Date.now): SmartE
|
||||
// - body prose: `Phase: 3`, `**Status:** verifying`, `Total Phases: 5`
|
||||
// Read each field across every form, scalar-first then nested then body, so
|
||||
// the classifier works on real STATE.md files written by current GSD.
|
||||
const statusRaw = fmScalar(fm, body, 'status', 'Status');
|
||||
const pausedAtRaw = fmScalar(fm, body, 'paused_at', 'Paused At');
|
||||
const lastActivityRaw = fmScalar(fm, body, 'last_activity', 'Last Activity');
|
||||
const statusRaw = stateFieldValue(fm, body, 'status', 'Status').value;
|
||||
const pausedAtRaw = stateFieldValue(fm, body, 'paused_at', 'Paused At').value;
|
||||
const lastActivityRaw = stateFieldValue(fm, body, 'last_activity', 'Last Activity').value;
|
||||
|
||||
// current_phase: scalar fm → nested (none) → body "Current Phase" → body "Phase".
|
||||
// The body `Phase:` field is the canonical location in prose-form STATE.md
|
||||
// (e.g. "Phase: 3" or "Phase: 3 — ui-review"); parse the leading number.
|
||||
// #3187 / ADR-3180 Amendment 3 ("0.x split"): this read is DELIBERATELY
|
||||
// unscoped — smart-entry classifies `gsd next` routing over the whole body,
|
||||
// whereas state.cts's copies of this same field scope it to `## Current
|
||||
// Position` (#1776/#2956). Those are two different questions sharing a
|
||||
// name; folding the scoped read in here would silently change smart-entry's
|
||||
// routing, an undisclosed Tier-2 change (design's Rejected #3). Both owner
|
||||
// calls below intentionally pass the unscoped `body`, never a Current-
|
||||
// Position slice.
|
||||
const currentPhaseRaw =
|
||||
fmScalar(fm, body, 'current_phase', 'Current Phase') ??
|
||||
stateExtractField(body, 'Phase');
|
||||
stateFieldValue(fm, body, 'current_phase', 'Current Phase').value ??
|
||||
stateFieldValue(fm, body, null, 'Phase').value;
|
||||
|
||||
// total_phases & percent: nested `progress:` object takes precedence in the
|
||||
// nested schema; scalar fm / body fields cover the flat schema.
|
||||
const progressFm = typeof fm.progress === 'object' ? fm.progress : null;
|
||||
const totalPhasesRaw: string | null =
|
||||
fmScalarKey(progressFm, 'total_phases') ??
|
||||
fmScalar(fm, body, 'total_phases', 'Total Phases');
|
||||
stateFieldValue(fm, body, 'total_phases', 'Total Phases').value;
|
||||
const progressRaw: string | null =
|
||||
fmScalarKey(progressFm, 'percent') ??
|
||||
fmScalar(fm, body, 'progress', 'Progress');
|
||||
stateFieldValue(fm, body, 'progress', 'Progress').value;
|
||||
|
||||
// Blockers list: `- <text>` items under a `## Blockers` heading.
|
||||
const blockers: string[] = [];
|
||||
|
||||
Reference in New Issue
Block a user