@opengsd/gsd-core 1.11.0 → 1.12.0

package/gsd-core/bin/lib/state-document.cjs

@@ -9,6 +9,11 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.KNOWN_STATUS_PATTERNS = exports.KNOWN_TEMPLATE_DEFAULTS = void 0;
+exports.toFiniteNumber = toFiniteNumber;
+exports.isUnfilledFieldValue = isUnfilledFieldValue;
+exports.leadingCalendarDate = leadingCalendarDate;
+exports.isRealCalendarDate = isRealCalendarDate;
+exports.stateFieldContinuation = stateFieldContinuation;
 exports.stateExtractField = stateExtractField;
 exports.stateFieldValue = stateFieldValue;
 exports.stateCurrentPositionSlice = stateCurrentPositionSlice;
@@ -28,6 +33,15 @@ const pattern_cjs_1 = require("./pattern.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- planning-scope.cjs is an export= CommonJS module
 const planningScopeMod = require("./planning-scope.cjs");
 const { SCOPE } = planningScopeMod;
+/**
+ * Coerce an arbitrary frontmatter scalar to a finite number, or `null` if it
+ * is not one. Exported per ADR-3473 §8.6: `state-transition.cts`'s
+ * progress-ratchet unmeasured-scan check ("is this derived total a real
+ * measurement?") must ask through the SAME coercion this module already uses
+ * for `existingProgressExceedsDerived`, rather than growing a second private
+ * copy. This matters because frontmatter scalars arrive as STRINGS
+ * (`"0"`, not `0`) — a raw `=== 0` test is wrong at both call sites.
+ */
 function toFiniteNumber(value) {
     const number = Number(value);
     return Number.isFinite(number) ? number : null;
@@ -208,6 +222,178 @@ function locateFieldRow(content, fieldName) {
     }
     return null;
 }
+/**
+ * True only when y/m/d name a date that actually exists on the calendar.
+ *
+ * `Date.parse` validates shape but not value: it rolls an out-of-range day
+ * FORWARD rather than rejecting it (`2026-02-30` -> `2026-03-02`,
+ * `2026-04-31` -> `2026-05-01`). Shape-only validation would therefore
+ * propagate a different, wrong instant instead of failing safe — precisely
+ * what ADR-227 ("validate shape AND value; on failure of either layer coerce
+ * to the contract's safe default, never propagate") exists to prevent. A
+ * round-trip through Date.UTC detects the rollover: any component the
+ * constructor normalised comes back changed.
+ *
+ * #3696: this predicate previously lived privately inside `smart-entry.cts`,
+ * where it gated `parseActivityTimestamp`. `state validate` needed the same
+ * answer to assert the `last_activity` invariant (S008), and a second copy is
+ * the "generative fix divergence" class outright — two surfaces that disagree
+ * about whether a STATE.md is usable is the defect #3696 opens with, so a
+ * parity test over two copies would be codifying the bug rather than fixing
+ * it. It moves here because this module is already the designated owner of
+ * STATE.md field semantics (ADR-3180 §7.7) and `smart-entry.cts` imports no
+ * peer that would make the reverse direction a cycle.
+ */
+/**
+ * True when a field carries no value a writer ever supplied: absent, blank, or
+ * still holding the shipped template's bracket placeholder.
+ *
+ * `templates/state.md:35` ships `Last activity: [YYYY-MM-DD] — [What happened]`,
+ * so EVERY freshly-initialized project has this exact string until something
+ * records activity. #3696's first cut only spared the ABSENT form, which made
+ * S008 fire on the shipped template itself — caught by the pre-existing
+ * "template-equivalent phase identities remain clean without disk drift" test,
+ * which is precisely what it is there for.
+ *
+ * The placeholder test is anchored at the START rather than "contains a bracket
+ * anywhere", so a real description that happens to cite one — `2026-08-19 — fixed
+ * [#123] parsing` — is still a filled-in value. That keeps the rule from
+ * silently swallowing genuine drift.
+ *
+ * Distinct from `isStateTemplateDefault`, which answers a different question
+ * ("may a later handler overwrite this?") and deliberately returns true for a
+ * bare ISO date — a perfectly valid value here.
+ */
+function isUnfilledFieldValue(value) {
+    if (value === null || value === undefined)
+        return true;
+    const trimmed = value.trim();
+    return trimmed === '' || trimmed.startsWith('[');
+}
+/**
+ * The `YYYY-MM-DD` prefix of `value`, but only when it names a date that
+ * actually exists. `null` for anything else — no leading date token at all, or
+ * a token that is shape-valid and calendar-impossible.
+ *
+ * #3696 review: this is deliberately a LEADING-TOKEN test, not the fully
+ * anchored prose grammar `parseProseLastActivityField` uses. That function
+ * requires the whole value to be `date` or `date <separator> description`, and
+ * returns `{date: <the entire raw string>}` when it does not match — a shape
+ * that reads like success. Asserting the S008 invariant through it therefore
+ * rejected values the real reader accepts: `smart-entry`'s
+ * `parseActivityTimestamp` needs only a leading date and reconstructs the
+ * instant even when the suffix carries no dash, so
+ * `Last activity: 2026-08-24 Shipped feature X` parses fine there while S008
+ * called it unreadable. That is the same two-surfaces-disagree defect #3696
+ * exists to close, merely pointing the other way.
+ *
+ * So the invariant asserted is the one the readers actually share: a leading
+ * ISO date token that is a real calendar date.
+ */
+function leadingCalendarDate(value) {
+    if (!value)
+        return null;
+    const match = /^(\d{4})-(\d{2})-(\d{2})(?![\d-])/.exec(value.trim());
+    if (!match)
+        return null;
+    return isRealCalendarDate(Number(match[1]), Number(match[2]), Number(match[3]))
+        ? `${match[1]}-${match[2]}-${match[3]}`
+        : null;
+}
+function isRealCalendarDate(year, month, day) {
+    if (month < 1 || month > 12 || day < 1 || day > 31)
+        return false;
+    const probe = new Date(Date.UTC(year, month - 1, day));
+    return (probe.getUTCFullYear() === year &&
+        probe.getUTCMonth() === month - 1 &&
+        probe.getUTCDate() === day);
+}
+/**
+ * Markdown structure that can legitimately follow a single-line field. A line
+ * matching any of these is the NEXT construct, never a continuation of the
+ * field above it.
+ *
+ * BREADTH IS THE POINT, and the failure direction is deliberate: a missed
+ * truncation costs a diagnostic nobody sees, while a false S009 reports drift on
+ * a well-formed STATE.md — a gate that fires on valid documents is worse than no
+ * gate. When a shape is ambiguous, it belongs here.
+ *
+ * #3696 review round 2 added the last three arms after all three were shown to
+ * produce false S009 fires on well-formed content: an indented code block, an
+ * HTML block, and a setext underline (`===`, which the `[-*_]{3,}` rule does not
+ * cover — it only knows `-`, `*` and `_`).
+ */
+const MD_STRUCTURE_LINE_RE = /^(?:#{1,6}\s|\||>|```|~~~|[-*_]{3,}\s*$|=+\s*$|[-*+]\s|\d+[.)]\s|\[[^\]]+\]:|<|(?: {4}|\t))/;
+/**
+ * A setext heading's underline — `===` or `---` on its own line. The line ABOVE
+ * one of these is a heading TITLE, which is indistinguishable from prose on its
+ * own, so the scan must look ahead by one line rather than consume it. Without
+ * this, `Last activity: …\nMy Heading\n===` reported "My Heading ===" as dropped
+ * continuation text (#3696 review round 2).
+ */
+const SETEXT_UNDERLINE_RE = /^(?:=+|-+)\s*$/;
+const STATE_SIBLING_FIELD_LINE_RE = /^\*{0,2}[A-Za-z][A-Za-z0-9 _-]*\*{0,2}:{1,2}\*{0,2}(?:\s|$)/;
+/**
+ * Return the prose that FOLLOWS a single-line field but plainly belongs to it —
+ * i.e. the remainder `stateExtractField` silently drops when a writer emits a
+ * value long enough to wrap.
+ *
+ * `stateExtractField`'s `(.+)` is newline-excluding, so
+ *
+ *     Last activity: 2026-08-19 — Project initialized from ingest; PROJECT.md,
+ *     REQUIREMENTS.md, ROADMAP.md written
+ *
+ * yields only the first line and the rest is lost with no diagnostic (#3696).
+ * `templates/state.md` prescribes a single-line field, so the DOCUMENT is what
+ * is wrong here, not the reader — this function exists so `state validate` can
+ * SAY so, not so the reader can start guessing at a multi-line grammar the
+ * template does not sanction.
+ *
+ * That is also why the fix is not in `stateExtractField` itself: it has 20
+ * direct callers and a CRITICAL blast radius (ADR-3180 §7.7, Rejected #1), and
+ * joining continuations there would apply to every field — `Status:` would
+ * swallow the line beneath it.
+ *
+ * Returns `null` when the field is absent, is a pipe-table row (a table cell
+ * cannot wrap), or is followed by end-of-file, a blank line, Markdown
+ * structure, or a sibling field.
+ */
+function stateFieldContinuation(content, fieldName) {
+    const escaped = (0, pattern_cjs_1.escapeRegex)(fieldName);
+    // Same two single-line grammars stateExtractField uses, in the same order, so
+    // this locates exactly the line whose value it returned. The pipe-table rung
+    // is deliberately absent: a `| Field | value |` row is bounded by its closing
+    // pipe and cannot wrap.
+    const match = new RegExp(`\\*\\*${escaped}:\\*\\*[ \\t]*(.+)`, 'i').exec(content) ??
+        new RegExp(`^${escaped}:[ \\t]*(.+)`, 'im').exec(content);
+    if (!match)
+        return null;
+    // `(.+)` stops at the line terminator, so the field's line ends where the
+    // match does. JS `.` excludes \r as well as \n, so on a CRLF document the \r
+    // sits just AFTER the match rather than inside it — hence the strip below
+    // before testing for the newline.
+    const afterValue = match.index + match[0].length;
+    const rest = content.slice(afterValue).replace(/^\r/, '');
+    if (!rest.startsWith('\n'))
+        return null; // end of file: nothing follows
+    const lines = rest.slice(1).split('\n').map((line) => line.replace(/\r$/, ''));
+    const continuation = [];
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (!line.trim())
+            break;
+        if (MD_STRUCTURE_LINE_RE.test(line))
+            break;
+        if (STATE_SIBLING_FIELD_LINE_RE.test(line))
+            break;
+        // Look ahead one line: a setext underline below makes THIS line a heading
+        // title, so stop before consuming it rather than after.
+        if (i + 1 < lines.length && SETEXT_UNDERLINE_RE.test(lines[i + 1]))
+            break;
+        continuation.push(line.trim());
+    }
+    return continuation.length ? continuation.join(' ') : null;
+}
 function stateExtractField(content, fieldName) {
     const escaped = (0, pattern_cjs_1.escapeRegex)(fieldName);
     // Bold inline format: **FieldName:** value

package/gsd-core/bin/lib/state-md-schema.cjs

@@ -0,0 +1,221 @@
+"use strict";
+/**
+ * STATE.md Field Schema — the one declaration (ADR-3473 §8.8, issue #3873).
+ *
+ * Phase 3 substrate. Before this module, "which STATE.md keys exist and what
+ * they carry" was declared in THREE hand-maintained places that were already
+ * observed to disagree (see the `last_activity` docstring below):
+ *
+ *   - `FIELD_CLASSIFICATION` (`src/state-transition.cts`) — source/preservation/
+ *     guard/mergeStrategy per frontmatter key (ADR-1769 §4 / ADR-3408).
+ *   - `FRONTMATTER_BODY_SOURCE` (`src/state-transition.cts`) — which BODY field
+ *     a frontmatter key derives from.
+ *   - `FRONTMATTER_KEY_TO_BODY_LABEL` (`src/state.cts`) — the Title-Case label
+ *     a report speaks a preserved field in (ADR-3408 §8.4/§8.5).
+ *
+ * This module is the single row-per-key declaration those three now PROJECT
+ * from at load time (`state-transition.cts` / `state.cts`), rather than
+ * hand-maintaining a fourth copy of the same knowledge. Every exported shape
+ * of the three original tables is unchanged — same keys, same key ORDER, same
+ * frozen/null-prototype-ness — so every existing consumer (the preservation
+ * dispatch loop, `getFieldClassification`, `getPreserveWhenUnchangedFields`,
+ * `bodyLabelFor`, and issue #3872's `declaredLeavesOf`) keeps working without
+ * an edit. See `.gsd/phase/feat-3873-state-md-schema/40-design.md`.
+ *
+ * LEAF MODULE, DELIBERATELY. This file imports from neither `state-transition.cts`
+ * nor `state.cts` — both of those import THIS module, and either importing
+ * back would be the exact CJS require-cycle `src/health-diagnostic-types.cts`'s
+ * own docstring describes breaking for the health-diagnostic rule tables
+ * (`module.exports` read before it is assigned, so a destructured value comes
+ * back `undefined`). `FieldSource` / `FieldPreservation` / `FieldGuard` /
+ * `FieldMergeStrategy` therefore live HERE now and are re-exported (by the same
+ * name, so no importer of `state-transition.cts` needs to change) from
+ * `state-transition.cts`.
+ *
+ * ADR-457 build-at-publish: source in `src/state-md-schema.cts`, compiled to
+ * `gsd-core/bin/lib/state-md-schema.cjs` (gitignored).
+ *
+ * Design: .gsd/phase/feat-3873-state-md-schema/40-design.md
+ * Test matrix: .gsd/phase/feat-3873-state-md-schema/50-test-matrix.md
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.STATE_FIELD_SCHEMA = exports.STATUS_LIFECYCLE_ENUM = void 0;
+/**
+ * The seven CANONICAL values `normalizeStateStatus` (`src/state-document.cts`)
+ * maps recognized raw status prose TO — the function's default fallback plus
+ * each branch's literal output, in the order the function tests them. This is
+ * NOT the raw body prose vocabulary `CONTEXT.md`'s "STATE.md Status Lifecycle
+ * (ADR-2207)" entry documents (`Ready to plan` → `All phases complete` →
+ * `<version> milestone complete` → `Awaiting next milestone`, plus the
+ * handler-authored strings in `KNOWN_TEMPLATE_DEFAULTS['Status']`) — that is
+ * free-form prose `normalizeStateStatus` READS.
+ *
+ * CORRECTED (#3873 phase-3 test-matrix row 26 — verified by executing
+ * `normalizeStateStatus`, not by reading this docstring's prior claim):
+ * this is NOT a closed set the `status` frontmatter key is restricted to at
+ * runtime. `normalizeStateStatus` is deliberately LENIENT: its fallback is
+ * `normalizedStatus = status || 'unknown'`, and when none of its
+ * substring-match branches recognize the raw input, that fallback — the
+ * caller's raw, UNRECOGNIZED prose — is returned unchanged. A status value
+ * outside this seven-member set is not rejected, coerced, or normalized; it
+ * passes straight through into the frontmatter. `STATUS_LIFECYCLE_ENUM` is
+ * therefore the set of values the normalizer maps recognized input ONTO, not
+ * a runtime-enforced closed vocabulary for the field.
+ */
+exports.STATUS_LIFECYCLE_ENUM = Object.freeze([
+    'unknown',
+    'paused',
+    'executing',
+    'planning',
+    'discussing',
+    'verifying',
+    'completed',
+]);
+// ─── The one declaration ────────────────────────────────────────────────────
+//
+// Row order below is `FIELD_CLASSIFICATION`'s (`src/state-transition.cts`,
+// pre-#3873) ORIGINAL literal order, verified by direct read and preserved
+// deliberately: the `FIELD_CLASSIFICATION` projection built from this table
+// (`state-transition.cts`) walks `Object.keys(STATE_FIELD_SCHEMA)` directly,
+// so this row order IS that projection's key order, and key order is
+// observable (the preservation dispatch loop iterates it). The two other
+// projections (`FRONTMATTER_BODY_SOURCE`, `FRONTMATTER_KEY_TO_BODY_LABEL`) do
+// NOT reuse this same order — their pre-#3873 literals were independently
+// hand-written and already disagreed with each other and with this order (see
+// each projection's own ordering constant in its home module) — so each
+// projection module declares its OWN explicit key-order list rather than
+// re-deriving order from this table's iteration, which would silently change
+// two of the three tables' observable order out from under every consumer.
+exports.STATE_FIELD_SCHEMA = Object.freeze(Object.assign(Object.create(null), {
+    // Schema
+    gsd_state_version: {
+        type: 'string', cardinality: 'one', source: 'free', preservation: 'derive', emitted: 'always',
+    },
+    // Milestone (external — from ROADMAP.md)
+    milestone: {
+        type: 'string', cardinality: 'optional', source: 'external', preservation: 'preserve-if-placeholder', emitted: 'when-present',
+    },
+    milestone_name: {
+        type: 'string', cardinality: 'optional', source: 'external', preservation: 'preserve-if-placeholder', emitted: 'when-present',
+    },
+    // Phase / plan position (body-derived)
+    current_phase: {
+        type: 'string', cardinality: 'optional', source: 'body', preservation: 'preserve-when-unchanged',
+        bodySource: Object.freeze(['Current Phase']), bodyLabel: 'Current Phase', emitted: 'when-present',
+    },
+    current_phase_name: {
+        type: 'string', cardinality: 'optional', source: 'curated', preservation: 'preserve-when-unchanged',
+        bodySource: Object.freeze(['Current Phase Name']), bodyLabel: 'Current Phase Name', emitted: 'when-present',
+    },
+    current_plan: {
+        type: 'string', cardinality: 'optional', source: 'body', preservation: 'preserve-when-unchanged',
+        bodySource: Object.freeze(['Current Plan']), bodyLabel: 'Current Plan',
+        // #3873 phase-3 test-matrix row 25 (verified by executing
+        // `advancePlanCore`, `src/state-transition.cts:1306`, not by reading
+        // its docstring): TODAY the `Current Plan` body field parses in
+        // exactly ONE shape — a bare number `N`, paired with a separate
+        // `Total Plans in Phase` field. The hybrid compound `N of M` written
+        // directly into `Current Plan` (no `Total Plans in Phase` sibling)
+        // does NOT parse: `legacyTotal` is absent, `planField` reads the
+        // DIFFERENT `Plan` field (also absent), so the function falls to its
+        // NaN/NaN error branch. Feeding `Current Plan: 2 of 5` WITH a
+        // `Total Plans in Phase` sibling present does not change this — it
+        // "succeeds" only because `parseInt("2 of 5", 10)` truncates to `2`
+        // and the sibling supplies the total; the `of 5` half is silently
+        // discarded, which is `parseInt` coincidence, not shape recognition.
+        // `Plan: N of M` (a DIFFERENT field name) DOES parse the hybrid shape,
+        // but `buildStateFrontmatter` never reads `Plan` into `current_plan`
+        // (verified: it calls `stateExtractField(bodyContent, 'Current Plan')`
+        // only), so that shape is out of scope for this row regardless.
+        //
+        // #3784 is the open issue for teaching `Current Plan` to read the
+        // hybrid shape; **PR #3791** ("fix(#3784): read the hybrid
+        // `Current Plan: N of M` shape, keep zero-padding, and name the
+        // accepted shapes on failure") is the in-flight fix. Do NOT widen
+        // this row speculatively — that would assert a shape the shipped
+        // parser does not accept, which is the exact defect class §8.8
+        // exists to make impossible. When #3791 merges, `acceptedShapes`
+        // MUST widen to `['N', 'N of M']` — until then, the row 23/24/25
+        // parser-shape tests (`tests/state-transition.test.cjs`) will go RED
+        // the moment the parser changes underneath it. That failure is the
+        // forcing function working as designed, not a broken test: it is
+        // what stops the schema and the parser from drifting apart silently.
+        acceptedShapes: Object.freeze(['N']),
+        emitted: 'when-present',
+    },
+    // Status / lifecycle (body-derived; #1230 delta heuristic applies)
+    // guard: the 'unknown' sentinel is the ONLY true executor-side guard in
+    // this table (stopped_at's `## Session` scoping is caller-side delta
+    // extraction, not an executor condition) — ADR-3408 Decision 1.
+    status: {
+        type: 'string', enum: exports.STATUS_LIFECYCLE_ENUM, cardinality: 'one', source: 'body', preservation: 'preserve-when-unchanged',
+        guard: 'non-sentinel-unknown', bodySource: Object.freeze(['Status']), bodyLabel: 'Status', emitted: 'always',
+    },
+    stopped_at: {
+        type: 'string', cardinality: 'optional', source: 'body', preservation: 'preserve-when-unchanged',
+        bodySource: Object.freeze(['Stopped At', 'Stopped at']), bodyLabel: 'Stopped At', emitted: 'when-present',
+    },
+    paused_at: {
+        type: 'string', cardinality: 'optional', source: 'body', preservation: 'preserve-when-unchanged',
+        bodySource: Object.freeze(['Paused At']), bodyLabel: 'Paused At', emitted: 'when-present',
+    },
+    // Activity log
+    last_updated: {
+        type: 'string', cardinality: 'one', source: 'free', preservation: 'derive', emitted: 'always',
+    }, // realClock.nowIso()
+    // #3873: THE LIVE DISAGREEMENT. Pre-schema, `FRONTMATTER_BODY_SOURCE`
+    // carried this key (`last_activity: ['Last Activity', 'Last activity']`)
+    // while `FRONTMATTER_KEY_TO_BODY_LABEL` did NOT — same field, two
+    // tables, two different answers to "does this key have a reportable
+    // body label". Resolved by DECLARATION, not by picking whichever table
+    // "looks right": `bodySource` is present below (this key IS derived from
+    // a body field and `buildStateFrontmatter` — `src/state.cts` — reads it
+    // via that exact two-case-variant fallback), and `bodyLabel` is
+    // deliberately ABSENT, because that is what ships TODAY —
+    // `last_activity`'s `preservation` is `'derive'`, never
+    // `'preserve-when-unchanged'`, so it can never reach `bodyLabelFor`'s
+    // (`src/state.cts`) `STATE_BODY_LABEL_UNWIRED_ROW` throw in the first
+    // place; the absent label is inert, not a latent bug. Pinned by
+    // `tests/state.test.cjs`'s pre-existing
+    // `lastActivityLabelResolutionMatchesShippedBehavior`. Do NOT "tidy"
+    // this by adding a label — that would be shipping a policy change
+    // disguised as a consolidation, exactly the #3427 failure this epic is
+    // named after.
+    last_activity: {
+        type: 'string', cardinality: 'optional', source: 'body', preservation: 'derive',
+        bodySource: Object.freeze(['Last Activity', 'Last activity']), emitted: 'when-present',
+    }, // always refresh on transition
+    last_activity_desc: {
+        type: 'string', cardinality: 'optional', source: 'body', preservation: 'preserve-when-unchanged',
+        bodySource: Object.freeze(['Last Activity Description']), bodyLabel: 'Last Activity Description', emitted: 'when-present',
+    },
+    // Commit provenance (#2573) — ambient git read, recomputed on every write,
+    // exactly like last_updated. Never preserved: a stale stamp would claim
+    // STATE.md was written against a commit it wasn't.
+    state_head: {
+        type: 'string', cardinality: 'optional', source: 'free', preservation: 'derive', emitted: 'when-present',
+    }, // #2573
+    // Progress block (disk-derived, except the curated progress ratchet)
+    // mergeStrategy: 'progress-ratchet' — completed_plans/completed_phases
+    // only ever ratchet UP toward the derived value (#2969); everything
+    // else in the merge is either always-derived (#2440) or always-curated.
+    progress: {
+        type: 'object', cardinality: 'optional', source: 'curated', preservation: 'preserve-always',
+        mergeStrategy: 'progress-ratchet', emitted: 'when-present',
+    }, // #3242, #1446
+    'progress.total_phases': {
+        type: 'number', cardinality: 'optional', source: 'disk', preservation: 'derive', emitted: 'when-present',
+    },
+    'progress.completed_phases': {
+        type: 'number', cardinality: 'optional', source: 'disk', preservation: 'derive', emitted: 'when-present',
+    },
+    'progress.total_plans': {
+        type: 'number', cardinality: 'optional', source: 'disk', preservation: 'derive', emitted: 'when-present',
+    },
+    'progress.completed_plans': {
+        type: 'number', cardinality: 'optional', source: 'disk', preservation: 'derive', emitted: 'when-present',
+    },
+    'progress.percent': {
+        type: 'number', cardinality: 'optional', source: 'disk', preservation: 'derive', emitted: 'when-present',
+    },
+}));