@opengsd/gsd-core 1.10.0 → 1.12.0

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

@@ -9,9 +9,17 @@
  */
 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;
 exports.stateReplaceField = stateReplaceField;
 exports.stateReplaceFieldWithFallback = stateReplaceFieldWithFallback;
+exports.stateReplaceFieldInSession = stateReplaceFieldInSession;
 exports.normalizeStateStatus = normalizeStateStatus;
 exports.computeProgressPercent = computeProgressPercent;
 exports.shouldPreserveExistingProgress = shouldPreserveExistingProgress;
@@ -19,10 +27,21 @@ exports.normalizeProgressNumbers = normalizeProgressNumbers;
 exports.isStateTemplateDefault = isStateTemplateDefault;
 exports.stateReplaceFieldIfTemplate = stateReplaceFieldIfTemplate;
 const markdown_table_cjs_1 = require("./markdown-table.cjs");
-// Internal helpers
-function escapeRegex(str) {
-    return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}
+const phase_lifecycle_cjs_1 = require("./phase-lifecycle.cjs");
+const markdown_sectionizer_cjs_1 = require("./markdown-sectionizer.cjs");
+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;
@@ -203,8 +222,180 @@ 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 = escapeRegex(fieldName);
+    const escaped = (0, pattern_cjs_1.escapeRegex)(fieldName);
     // Bold inline format: **FieldName:** value
     const boldPattern = new RegExp(`\\*\\*${escaped}:\\*\\*[ \\t]*(.+)`, 'i');
     const boldMatch = content.match(boldPattern);
@@ -222,8 +413,107 @@ function stateExtractField(content, fieldName) {
         return hit.rawValue.trim();
     return null;
 }
+/**
+ * Single owner of the #1760 STATE.md field-extraction fallback chain: "read
+ * field F, preferring the YAML frontmatter scalar, falling back to the body
+ * field." Added for #3187 (epic #3180, ADR-3180 §7.7) to collapse three
+ * independent re-derivations of this chain — `src/smart-entry.cts`'s
+ * `fmScalar` closure, and `src/state.cts`'s `cmdStateSnapshot` and
+ * `cmdStatePrune` — onto one function, per ADR-3180 Decision 1 ("keep N
+ * copies with a parity test" is rejected: a parity test proves today's
+ * agreement, not that copy N+1 won't happen).
+ *
+ * Takes ALREADY-PARSED `fm` and `body` rather than raw STATE.md content: the
+ * heaviest caller, `cmdStateSnapshot`, reads roughly ten fields off one parse
+ * and must not re-parse frontmatter per field.
+ *
+ * `stateExtractField` (above) is deliberately left untouched — it has 20
+ * direct callers and a CRITICAL blast radius (ADR-3180 §7.7's Rejected #1) —
+ * so this function is additive: it calls `stateExtractField` rather than
+ * replacing it or changing its signature.
+ *
+ * Fallback ladder (unchanged from every prior copy this replaces):
+ *   1. `fm[fmKey]` is a non-empty (post-`.trim()`) string → that trimmed
+ *      string.
+ *   2. `fm[fmKey]` is a `number` or `boolean` → `String(fm[fmKey])`, so `0`
+ *      and `false` are VALUES, not absence.
+ *   3. Anything else (`null`, `undefined`, an object, an array, or an
+ *      empty/whitespace-only string) → fall through to
+ *      `stateExtractField(body, bodyField)`.
+ *
+ * `fmKey === null` skips steps 1–2 outright: for a caller whose chain has no
+ * frontmatter side for this particular field (e.g. `state.cts`'s body-only
+ * `Last Activity` / `Last activity` case-variant pair, which sits inside a
+ * function that DOES own a ladder for its other fields, so per this phase's
+ * function-scoped guard it must still route through this owner).
+ * `bodyField === null` skips step 3: for a caller whose "no frontmatter
+ * value" case falls through to an already-computed value instead of a fresh
+ * extractor call (e.g. `cmdStateSnapshot`'s `last_activity`, which falls to
+ * its already-parsed prose date rather than re-extracting the body).
+ *
+ * `scope` reports whether the chain ran over inputs it could actually
+ * consult (ADR-3180 Decision 2/§7.7 — mirrors `scanPhasePlans`'s
+ * scope-carrying result in `plan-scan.cts`; see `planning-scope.cjs`). This
+ * function's own ladder always runs to completion on whatever `fm`/`body` it
+ * is given, INCLUDING when the answer is `null` — a genuinely absent field is
+ * a real answer, not a failure to look (§7.7 behavior table row 4). So
+ * `scope` defaults to `SCOPE.COMPLETE` and is only ever something else when
+ * the CALLER passes `opts.scope`, because only the caller knows whether an
+ * input it handed in was itself degraded — e.g. `fm` came back `{}` from an
+ * unterminated frontmatter fence (`extractFrontmatter` swallows that parse
+ * failure), or `body` is an unscoped whole-document fallback because a
+ * required `## Current Position` section was not found (#2956). This
+ * function never invents a new `SCOPE` member — the enum is frozen at
+ * COMPLETE/TRUNCATED/UNSCOPED/UNREADABLE (`planning-scope.cjs`).
+ *
+ * #1760 is the fallback chain's origin.
+ */
+function stateFieldValue(fm, body, fmKey, bodyField, opts) {
+    const v = fmKey === null ? undefined : fm[fmKey];
+    let value;
+    if (typeof v === 'string' && v.trim()) {
+        value = v.trim();
+    }
+    else if (typeof v === 'number' || typeof v === 'boolean') {
+        value = String(v);
+    }
+    else {
+        value = bodyField === null ? null : stateExtractField(body, bodyField);
+    }
+    return { value, scope: opts?.scope ?? SCOPE.COMPLETE };
+}
+/**
+ * Match the "Current Position" section body from a STATE.md body. #2956: this
+ * is the Phase analogue of state.cts's matchSessionSection. `Phase` canonically
+ * lives under `## Current Position` (gsd-core/templates/state.md), so — like
+ * Stopped At / Paused At under `## Session` — it must be extracted from THAT
+ * section, not from the first `Phase:` / `**Phase:**` line anywhere in the
+ * body. Without the scope, a historical `Phase:` line in an archive section
+ * silently shadows the real one on every read/write, and because callers use
+ * this for routing (state.cts's current_phase) and for drift detection
+ * (gsd-tools.cjs's `drift-guard phase-status` CLI seam), a stale match either
+ * routes work to the wrong phase or fabricates a drift finding.
+ *
+ * Level-flexible: the canonical template uses an h2 `## Current Position`, the
+ * bootstrap template an h3 `### Current Position` (templates/state.md). Both
+ * must match — mirroring how matchSessionSection recognises `## Session` and
+ * `## Session Continuity`. Exact 'current position' text match (case-
+ * insensitive) excludes unrelated headings. Built on the `collectSection`
+ * seam, so it inherits that seam's CRLF tolerance (#2444 fix).
+ *
+ * This is the single owner of the scope — state.cts's private
+ * `matchCurrentPositionSection` delegates here rather than duplicating the
+ * logic, so the two consumers cannot drift apart.
+ *
+ * Returns the section body, or null (caller falls back to full-body search).
+ */
+function stateCurrentPositionSlice(body) {
+    const isCurrentPosition = (h) => (h.level === 2 || h.level === 3) && h.text.trim().toLowerCase() === 'current position';
+    const section = (0, markdown_sectionizer_cjs_1.collectSection)(body, isCurrentPosition, { levelBounded: true });
+    return section ? section.body : null;
+}
 function stateReplaceField(content, fieldName, newValue) {
-    const escaped = escapeRegex(fieldName);
+    const escaped = (0, pattern_cjs_1.escapeRegex)(fieldName);
     // Bold inline format: **FieldName:** value
     const boldPattern = new RegExp(`(\\*\\*${escaped}:\\*\\*\\s*)(.*)`, 'i');
     if (boldPattern.test(content)) {
@@ -253,6 +543,33 @@ function stateReplaceFieldWithFallback(content, primary, fallback, value) {
     }
     return content;
 }
+/**
+ * #3374: session-scoped variant of stateReplaceFieldWithFallback for the
+ * `## Session` continuity fields. The post-sync harvest (state.cts's
+ * matchSessionSection → buildStateFrontmatter) reads these fields ONLY from
+ * the session section, so a writer that refreshes one must target the same
+ * scope — a whole-body replace lets a decoy `**Stopped at:**` line in an
+ * unrelated (e.g. archive) section absorb the refresh while the harvested
+ * session value stays stale.
+ *
+ * Section preference mirrors the reader exactly: the normalized `## Session`
+ * block wins over the bootstrap `## Session Continuity` heading when both
+ * exist (legacy duplicate files); the continuity heading is only consulted
+ * when no canonical `## Session` section exists. `levelBounded` heading
+ * matching also excludes `## Session Continuity Archive` (the #2444 scoping).
+ *
+ * Replace-only (no insertion): returns `content` unchanged when no session
+ * section exists or the field is absent from it, so a STATE.md layout without
+ * the line keeps its shape and the post-sync preservation pass decides the
+ * frontmatter value (see #3374).
+ */
+function stateReplaceFieldInSession(content, primary, fallback, value) {
+    const isSession = (h) => h.level === 2 && h.text.trim().toLowerCase() === 'session';
+    const isSessionContinuity = (h) => h.level === 2 && h.text.trim().toLowerCase() === 'session continuity';
+    const hasCanonicalSession = (0, markdown_sectionizer_cjs_1.collectSection)(content, isSession, { levelBounded: true }) !== null;
+    const target = hasCanonicalSession ? isSession : isSessionContinuity;
+    return (0, markdown_sectionizer_cjs_1.withSection)(content, target, (sectionBody) => stateReplaceFieldWithFallback(sectionBody, primary, fallback, value));
+}
 function normalizeStateStatus(status, pausedAt) {
     let normalizedStatus = status || 'unknown';
     const statusLower = (status || '').toLowerCase();
@@ -279,7 +596,20 @@ function normalizeStateStatus(status, pausedAt) {
     }
     return normalizedStatus;
 }
-function computeProgressPercent(completedPlans, totalPlans, completedPhases, totalPhases) {
+/**
+ * ADR-3180 §7.6 rule 4 (#3217): `scope` is the `listMilestonePhaseDirs`-owner
+ * discriminator for the phase/plan set these four counts were derived from.
+ * A caller that cannot vouch for `scope === SCOPE.COMPLETE` must pass the
+ * scope it actually has — this function refuses to compose a percentage
+ * from counts whose scope says they are not a trustworthy answer, returning
+ * `null` (never `0`; see the module's already-existing "no data" `null`
+ * below, which this generalizes) exactly like its pre-existing "no data"
+ * case. `scope` is REQUIRED (no default) so a caller cannot silently opt out
+ * of rule 4 by omission.
+ */
+function computeProgressPercent(completedPlans, totalPlans, completedPhases, totalPhases, scope) {
+    if (scope !== SCOPE.COMPLETE)
+        return null;
     const hasPlanData = totalPlans !== null && totalPlans > 0 && completedPlans !== null;
     const hasPhaseData = totalPhases !== null && totalPhases > 0 && completedPhases !== null;
     if (!hasPlanData && !hasPhaseData)
@@ -288,7 +618,7 @@ function computeProgressPercent(completedPlans, totalPlans, completedPhases, tot
     // cannot track through intermediate boolean variables).
     const planFraction = hasPlanData ? (completedPlans ?? 0) / (totalPlans ?? 1) : 1;
     const phaseFraction = hasPhaseData ? (completedPhases ?? 0) / (totalPhases ?? 1) : 1;
-    return Math.min(100, Math.round(Math.min(planFraction, phaseFraction) * 100));
+    return (0, phase_lifecycle_cjs_1.clampPercentFromFraction)(Math.min(planFraction, phaseFraction));
 }
 function shouldPreserveExistingProgress(existingProgress, derivedProgress) {
     if (!existingProgress || typeof existingProgress !== 'object')

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',
+    },
+}));