@opengsd/gsd-core 1.10.0 → 1.11.0

package/gsd-core/bin/lib/markdown-table.cjs

@@ -11,7 +11,7 @@
  * {ok,data|kind}; the two never mix (different modules).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TABLE_SCHEMAS = void 0;
+exports.QUICK_TASKS_SECTION_ABSENT = exports.TABLE_SCHEMAS = void 0;
 exports.matchTableSchema = matchTableSchema;
 exports.splitTableRow = splitTableRow;
 exports.isDelimiterRow = isDelimiterRow;
@@ -23,6 +23,7 @@ exports.findTableBySchema = findTableBySchema;
 exports.findTableWithColumns = findTableWithColumns;
 exports.escapeCell = escapeCell;
 exports.appendQuickTaskRow = appendQuickTaskRow;
+exports.resetQuickTaskRows = resetQuickTaskRows;
 const markdown_sectionizer_cjs_1 = require("./markdown-sectionizer.cjs");
 // ─── Schema registry ──────────────────────────────────────────────────────────
 /**
@@ -280,32 +281,54 @@ function unescapeCellText(raw) {
  */
 function updateTableCell(tableText, match, column, newValue) {
     const lines = splitLinesWithOffsets(tableText);
+    // #3255: pick the first VALID table whose columns include `column`. The prior
+    // code bound to the FIRST table of any shape and returned 'unknown column' if
+    // that one lacked the column — so a section holding a summary table above the
+    // target (e.g. ## Traceability: a phase-summary table, then the requirement
+    // rows) never reached the target table. Scan for the first valid table that
+    // carries the column; if none does but a valid table exists, still return
+    // 'unknown column' (single-table behaviour unchanged). Track the first
+    // malformation reason so a lone malformed table keeps its specific error.
     let headerIdx = -1;
+    let columns = [];
+    let firstValidIdx = -1;
+    let firstMalformedReason = null;
+    const recordMalformed = (reason) => {
+        if (firstMalformedReason === null && firstValidIdx === -1)
+            firstMalformedReason = reason;
+    };
     for (let i = 0; i < lines.length; i++) {
         const trimmed = lines[i].line.trim();
-        if (trimmed.startsWith('|') && trimmed.indexOf('|', 1) !== -1) {
+        if (!trimmed.startsWith('|') || trimmed.indexOf('|', 1) === -1)
+            continue;
+        const delimiterLine = lines[i + 1]?.line;
+        if (delimiterLine === undefined || !delimiterLine.trim().startsWith('|')) {
+            recordMalformed('missing delimiter row');
+            continue;
+        }
+        const candidateRanges = splitTableRowRanges(lines[i].line, lines[i].start);
+        const candidateColumns = candidateRanges.map((r) => unescapeCellText(tableText.slice(r.start, r.end)));
+        const delimiterCells = splitTableRow(delimiterLine);
+        if (!isDelimiterRow(delimiterCells)) {
+            recordMalformed('missing delimiter row');
+            continue;
+        }
+        if (delimiterCells.length !== candidateColumns.length) {
+            recordMalformed('delimiter/header column count mismatch');
+            continue;
+        }
+        if (firstValidIdx === -1)
+            firstValidIdx = i;
+        if (candidateColumns.includes(column)) {
             headerIdx = i;
+            columns = candidateColumns;
             break;
         }
     }
     if (headerIdx === -1) {
-        return { ok: false, reason: 'no table found' };
-    }
-    const delimiterLine = lines[headerIdx + 1]?.line;
-    if (delimiterLine === undefined || !delimiterLine.trim().startsWith('|')) {
-        return { ok: false, reason: 'missing delimiter row' };
-    }
-    const headerRanges = splitTableRowRanges(lines[headerIdx].line, lines[headerIdx].start);
-    const columns = headerRanges.map((r) => unescapeCellText(tableText.slice(r.start, r.end)));
-    const delimiterCells = splitTableRow(delimiterLine);
-    if (!isDelimiterRow(delimiterCells)) {
-        return { ok: false, reason: 'missing delimiter row' };
-    }
-    if (delimiterCells.length !== columns.length) {
-        return { ok: false, reason: 'delimiter/header column count mismatch' };
-    }
-    if (!columns.includes(column)) {
-        return { ok: false, reason: `unknown column: ${column}` };
+        if (firstValidIdx !== -1)
+            return { ok: false, reason: `unknown column: ${column}` };
+        return { ok: false, reason: firstMalformedReason ?? 'no table found' };
     }
     const targetColIdx = columns.indexOf(column);
     let selectedRange;
@@ -623,6 +646,17 @@ function escapeCell(value) {
         .replace(/\|/g, '\\|')
         .trim();
 }
+/**
+ * Shared sentinel `reason` returned by both `appendQuickTaskRow` and
+ * `resetQuickTaskRows` when the "Quick Tasks Completed" heading is absent
+ * from `stateContent` (#2142). The section is created lazily by
+ * `gsd-core/workflows/quick.md` Step 7b and is absent from
+ * `gsd-core/templates/state.md`, so an absent section is the common case,
+ * not an anomaly — callers compare against this constant rather than
+ * matching on the free-form reason string (CONTRIBUTING.md "Prohibited:
+ * Raw Text Matching").
+ */
+exports.QUICK_TASKS_SECTION_ABSENT = 'no Quick Tasks Completed section';
 /**
  * Append one row to STATE.md's "Quick Tasks Completed" table.
  *
@@ -645,7 +679,7 @@ function escapeCell(value) {
 function appendQuickTaskRow(stateContent, fields) {
     const section = (0, markdown_sectionizer_cjs_1.collectSection)(stateContent, (h) => /^quick tasks completed$/i.test(h.text.trim()));
     if (!section) {
-        return { ok: false, reason: 'no Quick Tasks Completed section' };
+        return { ok: false, reason: exports.QUICK_TASKS_SECTION_ABSENT };
     }
     const parsed = parseMarkdownTable(section.body);
     if (!parsed.ok) {
@@ -694,5 +728,84 @@ function appendQuickTaskRow(stateContent, fields) {
     const content = (0, markdown_sectionizer_cjs_1.replaceSection)(stateContent, section, newBody);
     return { ok: true, value: { content, row, variant: match.label } };
 }
+// ─── resetQuickTaskRows (#2142) ────────────────────────────────────────────
+/**
+ * Clear every DATA row from STATE.md's "Quick Tasks Completed" table, leaving
+ * the header + delimiter lines byte-identical, for use at milestone close when
+ * `--archive-quick` has actually moved the underlying `.planning/quick/*`
+ * directories out from under the table (see `src/milestone.cts`'s
+ * `archiveQuickTaskDirectories` / `cmdMilestoneComplete` wiring).
+ *
+ * Mirrors `appendQuickTaskRow`'s exact contract (same `collectSection` ->
+ * `parseMarkdownTable` -> `matchTableSchema` pipeline, same fail-loud posture,
+ * same EOL-detect-before-split handling) rather than inventing a second one:
+ *   - no "Quick Tasks Completed" heading -> `{ok:false, reason:
+ *     QUICK_TASKS_SECTION_ABSENT}` (no-op; a STATE.md without the section has
+ *     nothing to reset — per #2142 design doc §40, behavior table row 5, the
+ *     section is created lazily by quick.md Step 7b and is absent from
+ *     templates/state.md, so absence is the common path, not an anomaly.
+ *     Callers MUST treat this sentinel as silent — never surface it as a
+ *     `preservation_warnings` entry).
+ *   - the section body doesn't parse as a GFM table -> `{ok:false, reason}`.
+ *   - the table's header doesn't match a known `TABLE_SCHEMAS.QuickTasks`
+ *     variant -> `{ok:false, reason}` and — CRITICAL — no modification at
+ *     all. A user-added column means the data can't be safely addressed by
+ *     name, so clearing it would destroy rows under a schema we don't
+ *     understand (Postel's Law: liberal in accepting known shapes,
+ *     conservative about destroying what we don't).
+ */
+function resetQuickTaskRows(stateContent) {
+    if (typeof stateContent !== 'string' || stateContent.trim() === '') {
+        return { ok: false, reason: 'empty or non-string input' };
+    }
+    const section = (0, markdown_sectionizer_cjs_1.collectSection)(stateContent, (h) => /^quick tasks completed$/i.test(h.text.trim()));
+    if (!section) {
+        return { ok: false, reason: exports.QUICK_TASKS_SECTION_ABSENT };
+    }
+    const parsed = parseMarkdownTable(section.body);
+    if (!parsed.ok) {
+        return { ok: false, reason: `quick-tasks table: ${parsed.reason}` };
+    }
+    const match = matchTableSchema(parsed.value.columns);
+    if (!match || match.id !== 'QuickTasks') {
+        // Refuse the reset — keep every row, caller-owned content is untouched.
+        return {
+            ok: false,
+            reason: `unrecognized Quick Tasks schema (columns: ${parsed.value.columns.join(' | ')})`,
+        };
+    }
+    const cleared = parsed.value.rows.length;
+    // Detect the section's EOL BEFORE splitting on /\r?\n/ (which discards it) —
+    // exactly `appendQuickTaskRow`'s convention — so a CRLF document is not
+    // downgraded to mixed EOL by the rejoin below.
+    const eol = /\r\n/.test(section.body) ? '\r\n' : '\n';
+    const lines = section.body.split(/\r?\n/);
+    let headerIdx = -1;
+    for (let i = 0; i < lines.length; i++) {
+        if (lines[i].trim().startsWith('|')) {
+            headerIdx = i;
+            break;
+        }
+    }
+    // headerIdx is always found here — parseMarkdownTable already confirmed a
+    // header + delimiter row exist in this same `section.body`.
+    let lastTableLineIdx = headerIdx + 1; // delimiter row, when there are zero data rows
+    for (let i = headerIdx + 2; i < lines.length; i++) {
+        if (!lines[i].trim().startsWith('|'))
+            break;
+        lastTableLineIdx = i;
+    }
+    // Keep the header + delimiter lines [0 .. headerIdx+1] plus everything
+    // after the contiguous run of `|`-prefixed data rows — dropping only the
+    // data rows themselves. Non-table content before/after the table inside
+    // the section is preserved untouched.
+    const newLines = [
+        ...lines.slice(0, headerIdx + 2),
+        ...lines.slice(lastTableLineIdx + 1),
+    ];
+    const newBody = newLines.join(eol);
+    const content = (0, markdown_sectionizer_cjs_1.replaceSection)(stateContent, section, newBody);
+    return { ok: true, value: { content, cleared, variant: match.label } };
+}
 // Consumers: require('../gsd-core/bin/lib/markdown-table.cjs')
 // Named CJS exports are the canonical surface (ADR-457 .cts → .cjs build-at-publish).

package/gsd-core/bin/lib/milestone-lock.cjs

@@ -0,0 +1,248 @@
+"use strict";
+/**
+ * Milestone Lock — advisory (phase, session) claim over the single Current
+ * Position slot in STATE.md (#3311).
+ *
+ * Problem it solves: two sessions running DIFFERENT phases in the same working
+ * tree both read-modify-write `## Current Position`. The byte-level STATE.md
+ * lock (#464) already serializes those writes, so no write is lost — but the
+ * SEMANTIC clobber is silent: `state.advance-plan` takes no phase argument and
+ * advances whatever plan the (possibly just clobbered) Current Position names,
+ * and nothing ever surfaces that two sessions claimed two different phases
+ * against the one single-slot field.
+ *
+ * This module is the maintainer-chosen fix (issue #3311 comment): a milestone
+ * lock keyed by phase + session id, with a second session WARNED instead of
+ * silently overwriting. It is an advisory claim file, not a mutex:
+ *
+ * - `.planning/milestone.lock` (workstream-scoped via planningDir) holds
+ *   `{ phase, session, pid, updated_at }`.
+ * - Session identity reuses `getWorkstreamSessionKey()`
+ *   (active-workstream-store.cjs): env-first (GSD_SESSION_KEY,
+ *   CLAUDE_SESSION_ID, CODEX_THREAD_ID, …), then the controlling TTY. Two
+ *   agent sessions in different terminals/runtimes resolve different keys;
+ *   headless runs resolve to null.
+ * - Liveness is age-based only: a claim is live while
+ *   `now - updated_at < MILESTONE_LOCK_TTL_MS`. There is deliberately NO
+ *   pid-liveness gate — CLI invocations are short-lived, so the recorded pid
+ *   is dead by the next invocation regardless of whether the agent SESSION is
+ *   still active; pid-death would make every claim instantly stale. Active
+ *   sessions heartbeat their claim (advance-plan on a matching position
+ *   refreshes updated_at); an abandoned claim self-expires after the TTL.
+ * - Conflict rule: a live claim for a DIFFERENT phase held by a DIFFERENT
+ *   session. Same phase never conflicts (the lock is keyed by phase — two
+ *   sessions on one phase are doing the same work). A non-null session key
+ *   equal to the caller's never conflicts (one orchestrating session may
+ *   re-target its own claim). A null session key never counts as "same" as
+ *   anything, so headless parallel phases are still detected. The one
+ *   exception is advance-plan (checkMilestonePosition), which reports ANY
+ *   live claim/position phase mismatch regardless of session — a session's
+ *   own legitimate re-targeting goes through begin-phase, which keeps the
+ *   claim in sync, so a same-session mismatch is just as anomalous.
+ * - On conflict the existing claim is LEFT INTACT (not stolen): as long as two
+ *   phases are concurrently active, every Current Position mutation keeps
+ *   reporting the conflict. The conflicting command still proceeds (warn, not
+ *   block — a stale-but-live claim must not brick later sessions).
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MILESTONE_LOCK_TTL_MS = exports.MILESTONE_LOCK_FILENAME = void 0;
+exports.warnMilestoneConflict = warnMilestoneConflict;
+exports.claimMilestonePhase = claimMilestonePhase;
+exports.checkMilestonePosition = checkMilestonePosition;
+exports.checkMilestoneConflictForPhase = checkMilestoneConflictForPhase;
+exports.releaseMilestonePhase = releaseMilestonePhase;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const clock_cjs_1 = require("./clock.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- planning-workspace.cjs is an export= CommonJS module
+const planningWorkspace = require("./planning-workspace.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- active-workstream-store.cjs is an export= CommonJS module
+const activeWorkstreamStore = require("./active-workstream-store.cjs");
+exports.MILESTONE_LOCK_FILENAME = 'milestone.lock';
+/**
+ * How long a claim stays live without a heartbeat. Active sessions heartbeat
+ * on every advance-plan against their claimed phase; a phase's planning stage
+ * (begin-phase → first completed plan) can legitimately run for hours, so the
+ * floor must comfortably exceed the longest expected gap between heartbeats
+ * while still expiring an abandoned claim within a working day.
+ */
+exports.MILESTONE_LOCK_TTL_MS = 4 * 60 * 60 * 1000;
+function milestoneLockPath(cwd) {
+    return node_path_1.default.join(planningWorkspace.planningDir(cwd), exports.MILESTONE_LOCK_FILENAME);
+}
+/**
+ * Normalize a phase token for claim comparison: trim, and collapse an integer
+ * spelling to its canonical form so "01", "1" and " 1 " compare equal while
+ * decimals ("2.5") compare by their trimmed text.
+ */
+function normalizePhaseToken(value) {
+    const trimmed = String(value).trim();
+    if (/^\d+$/.test(trimmed))
+        return String(parseInt(trimmed, 10));
+    return trimmed;
+}
+function sameSession(a, b) {
+    // A null key is "unknown", not "equal" — two headless sessions must still
+    // conflict across phases (the CI/cron shape of #3311).
+    if (a === null || b === null)
+        return false;
+    return a === b;
+}
+function parseClaim(raw) {
+    if (!raw)
+        return null;
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.phase !== 'string' || !parsed.phase.trim())
+            return null;
+        return {
+            phase: parsed.phase,
+            session: typeof parsed.session === 'string' ? parsed.session : null,
+            pid: typeof parsed.pid === 'number' ? parsed.pid : 0,
+            updated_at: typeof parsed.updated_at === 'number' ? parsed.updated_at : 0,
+        };
+    }
+    catch {
+        // Corrupt body (concurrent partial write, hand edit) — treat as no claim.
+        // The next writer replaces the file; never crash a state command over an
+        // advisory sidecar.
+        return null;
+    }
+}
+function readClaim(cwd) {
+    try {
+        return parseClaim(node_fs_1.default.readFileSync(milestoneLockPath(cwd), 'utf-8'));
+    }
+    catch {
+        return null; // absent or unreadable — same posture as parseClaim
+    }
+}
+function writeClaim(cwd, claim) {
+    ensureClaimDir(cwd);
+    node_fs_1.default.writeFileSync(milestoneLockPath(cwd), JSON.stringify(claim, null, 2) + '\n');
+}
+// planningWorkspace.planningDir targets .planning (or the workstream-scoped
+// variant); the parent is created by every GSD command that gets this far, but
+// the claim write must not throw if it is somehow missing.
+function ensureClaimDir(cwd) {
+    try {
+        node_fs_1.default.mkdirSync(node_path_1.default.dirname(milestoneLockPath(cwd)), { recursive: true });
+    }
+    catch {
+        /* best-effort — see writeClaim callers' advisory posture */
+    }
+}
+function isClaimLive(claim, nowMs) {
+    return nowMs - claim.updated_at < exports.MILESTONE_LOCK_TTL_MS;
+}
+function currentSessionKey() {
+    return activeWorkstreamStore.getWorkstreamSessionKey();
+}
+function toConflict(claim, phase, session) {
+    return {
+        locked_phase: claim.phase,
+        locked_session: claim.session,
+        phase,
+        session,
+    };
+}
+/**
+ * Human-visible warning for a conflict. Emitted on stderr unconditionally —
+ * visibility is the entire point of this lock (#3311's "silent last-write-wins").
+ */
+function warnMilestoneConflict(conflict, action) {
+    const holder = conflict.locked_session ?? 'an unknown (headless) session';
+    const actor = conflict.session ?? 'an unknown (headless) session';
+    process.stderr.write(`[gsd-tools] WARNING: milestone lock conflict (#3311): ${holder} holds the milestone claim for phase ` +
+        `${conflict.locked_phase}, but ${actor} is running ${action} for phase ${conflict.phase}. ` +
+        `STATE.md's ## Current Position is a single slot — concurrent phases overwrite each other's ` +
+        `position. Verify Current Position before trusting it.\n`);
+}
+/**
+ * begin-phase entry point: claim `phase` for this session.
+ *
+ * Returns a conflict descriptor (and leaves the existing claim intact) when a
+ * live claim for a DIFFERENT phase is held by a DIFFERENT session; otherwise
+ * takes/refreshes the claim and returns null.
+ */
+function claimMilestonePhase(cwd, phase, nowMs) {
+    const now = nowMs ?? clock_cjs_1.realClock.now();
+    const session = currentSessionKey();
+    const existing = readClaim(cwd);
+    if (existing !== null &&
+        isClaimLive(existing, now) &&
+        normalizePhaseToken(existing.phase) !== normalizePhaseToken(phase) &&
+        !sameSession(existing.session, session)) {
+        return toConflict(existing, phase, session);
+    }
+    writeClaim(cwd, { phase: String(phase).trim(), session, pid: process.pid, updated_at: now });
+    return null;
+}
+/**
+ * advance-plan entry point: `positionPhase` is the phase STATE.md's Current
+ * Position currently names.
+ *
+ * A live claim naming a DIFFERENT phase means the position was moved away from
+ * the claimed phase without a matching begin-phase — the #3311 flip — and is
+ * returned as a conflict REGARDLESS of session: this session's own legitimate
+ * re-targeting goes through begin-phase, which keeps the claim in sync, so a
+ * same-session mismatch is exactly as anomalous as a cross-session one. A live
+ * claim matching the position phase is heartbeat-refreshed (this session is
+ * actively working that phase, so the claim stays live). No claim is ever
+ * created here: advance-plan has no phase argument of its own, so it can only
+ * corroborate or contradict an existing claim, not originate one.
+ */
+function checkMilestonePosition(cwd, positionPhase, nowMs) {
+    const now = nowMs ?? clock_cjs_1.realClock.now();
+    const existing = readClaim(cwd);
+    if (existing === null || !isClaimLive(existing, now))
+        return null;
+    const session = currentSessionKey();
+    if (normalizePhaseToken(existing.phase) === normalizePhaseToken(positionPhase)) {
+        // Heartbeat — keep the claim's liveness anchored to actual activity.
+        writeClaim(cwd, { phase: existing.phase, session: existing.session, pid: process.pid, updated_at: now });
+        return null;
+    }
+    return toConflict(existing, positionPhase, session);
+}
+/**
+ * phase.complete entry point (read-only check): a live claim for a DIFFERENT
+ * phase held by a DIFFERENT session is a conflict. phase.complete never claims
+ * — it ends work on a phase rather than starting it.
+ */
+function checkMilestoneConflictForPhase(cwd, phase, nowMs) {
+    const now = nowMs ?? clock_cjs_1.realClock.now();
+    const existing = readClaim(cwd);
+    if (existing === null || !isClaimLive(existing, now))
+        return null;
+    if (normalizePhaseToken(existing.phase) === normalizePhaseToken(phase))
+        return null;
+    const session = currentSessionKey();
+    if (!sameSession(existing.session, session)) {
+        return toConflict(existing, phase, session);
+    }
+    return null;
+}
+/**
+ * Release the claim when the phase it names completes — regardless of which
+ * session completes it (an orchestrator cleaning up after a dead session must
+ * not be blocked by the dead session's own claim). Returns whether a matching
+ * claim was removed.
+ */
+function releaseMilestonePhase(cwd, phase) {
+    const existing = readClaim(cwd);
+    if (existing === null)
+        return false;
+    if (normalizePhaseToken(existing.phase) !== normalizePhaseToken(phase))
+        return false;
+    try {
+        node_fs_1.default.unlinkSync(milestoneLockPath(cwd));
+        return true;
+    }
+    catch {
+        return false; // already gone — same outcome for the caller
+    }
+}