@opengsd/gsd-core 1.7.0-rc.1 → 1.7.0-rc.3

package/gsd-core/bin/lib/smart-entry.cjs

@@ -0,0 +1,521 @@
+"use strict";
+/**
+ * Smart Entry — state-aware situation classifier for the /gsd front door.
+ *
+ * Reads project + workflow state (`.planning/STATE.md`, ROADMAP.md, git) and
+ * classifies the user's situation into one of a small set of enumerated values,
+ * each carrying a recommended next action and a menu of alternatives. Pure
+ * detection → classification; no side effects, no writes.
+ *
+ * Surfaced as `gsd-tools smart-entry [--json]`. The markdown `/gsd` command +
+ * workflow shells out to `smart-entry --json`, renders an AskUserQuestion menu
+ * (with a --text numbered-list fallback for non-Claude runtimes), and dispatches
+ * the chosen action to an existing slash command. See
+ * docs/superpowers/specs/2026-06-27-gsd-smart-entry-design.md and
+ * docs/adr/1787-gsd-next-smart-entry.md.
+ *
+ * Relationship to `/gsd:progress --next`: this classifier is a *menu* front door,
+ * not a second router. For in-project forward motion (planning → executing →
+ * verify-pending) the recommended action delegates to `/gsd:progress --next`
+ * (workflows/next.md) — the single, gated advancement engine (Route 0 resume-
+ * incomplete-phase invariant + Gates 1-3). smart-entry never re-derives forward
+ * routing itself; a standalone advancement command that bypassed those gates is
+ * exactly what got the old flat `/gsd-next` removed (#3054). Its distinct value is
+ * the states `--next` cannot reach: pre-project (no-project), remediation (paused,
+ * blocked, verify-failed), and lifecycle exits (idle-stranded, complete).
+ *
+ * Design note: this is the gsd-core analog of gsd-pi's `showSmartEntry` branch
+ * tree, redesigned for gsd-core's `.planning/` phase loop. gsd-pi's
+ * milestone/slice/task model does not exist here; the situation table is the
+ * translation, not a port.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SITUATIONS = void 0;
+exports.detectSignals = detectSignals;
+exports.classify = classify;
+exports.actionsFor = actionsFor;
+exports.classifyProject = classifyProject;
+exports.runSmartEntry = runSmartEntry;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_child_process_1 = require("node:child_process");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const ioMod = require("./io.cjs");
+const { output } = ioMod;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const planningWorkspace = require("./planning-workspace.cjs");
+const { planningPaths } = planningWorkspace;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const frontmatter = require("./frontmatter.cjs");
+const { extractFrontmatter } = frontmatter;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const stateDocument = require("./state-document.cjs");
+const { stateExtractField } = stateDocument;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const phaseId = require("./phase-id.cjs");
+const { comparePhaseNum, extractPhaseToken, normalizePhaseName, phaseTokenMatches } = phaseId;
+// ─── Constants ────────────────────────────────────────────────────────────────
+/**
+ * Staleness threshold for idle-stranded detection. A clean tree whose last
+ * activity is older than this (with non-complete status) is considered stranded
+ * committed-but-unshipped work. Hardcoded for v1; configurable later.
+ */
+const IDLE_STALE_MS = 72 * 60 * 60 * 1000; // 72h
+/** @internal a single source of truth so the structure test can assert coverage. */
+exports.SITUATIONS = Object.freeze([
+    'no-project',
+    'paused',
+    'blocked',
+    'verify-failed',
+    'needs-first-phase',
+    'planning',
+    'executing',
+    'verify-pending',
+    'idle-stranded',
+    'complete',
+    'unknown',
+]);
+// ─── Detection ─────────────────────────────────────────────────────────────────
+/** Frontmatter scalar helper: prefer YAML frontmatter, fall back to body field. */
+function fmScalar(fm, body, key, bodyField) {
+    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, key) {
+    if (!obj || typeof obj !== 'object')
+        return null;
+    const v = obj[key];
+    if (typeof v === 'string' && v.trim())
+        return v.trim();
+    if (typeof v === 'number' || typeof v === 'boolean')
+        return String(v);
+    return null;
+}
+function parseIntOrNull(s) {
+    if (s === null)
+        return null;
+    const cleaned = s.replace('%', '').trim();
+    const n = Number.parseInt(cleaned, 10);
+    return Number.isFinite(n) ? n : null;
+}
+function phaseTokenFromDirName(name) {
+    const token = extractPhaseToken(name);
+    return /^\d+(?:[A-Z])?(?:\.\d+)*(?:-|$)/i.test(token) ? token : null;
+}
+/**
+ * Parse a `last_activity` value that may be an ISO date or a free-form string
+ * into an epoch-ms timestamp. Returns null when unparseable.
+ */
+function parseActivityTimestamp(raw) {
+    if (!raw)
+        return null;
+    const ms = Date.parse(raw);
+    return Number.isNaN(ms) ? null : ms;
+}
+/** Read-only git signals. Any git error is swallowed → "no git signal". */
+function readGitSignals(cwd) {
+    const run = (args) => {
+        try {
+            return (0, node_child_process_1.execFileSync)('git', args, {
+                cwd,
+                encoding: 'utf-8',
+                maxBuffer: 4 * 1024 * 1024,
+                windowsHide: true,
+                stdio: ['pipe', 'pipe', 'pipe'],
+            });
+        }
+        catch {
+            return '';
+        }
+    };
+    // Cheap "is this a git repo" probe that also doubles as the dirty check.
+    const status = run(['status', '--porcelain']);
+    if (status === '' && !run(['rev-parse', '--is-inside-work-tree']).trim()) {
+        return { has_git: false, dirty: false, unpushed: false };
+    }
+    const dirty = status.trim().length > 0;
+    // `git log @{u}..HEAD` lists commits on this branch not on its upstream.
+    // Non-empty ⇒ unpushed. Errors (no upstream, detached HEAD) ⇒ not unpushed.
+    const unpushed = run(['log', '@{u}..HEAD', '--oneline']).trim().length > 0;
+    return { has_git: true, dirty, unpushed };
+}
+/** Leading numeric phase token from a STATE.md scalar or body `Phase:` value. */
+function phaseTokenFromState(raw) {
+    if (!raw?.trim())
+        return null;
+    const match = raw.trim().match(/^(\d+(?:[A-Z])?(?:\.\d+)*)/i);
+    return match ? match[1] : null;
+}
+/**
+ * Detect whether the current phase's verify report indicates failure. The
+ * canonical signal is a phase summary/verify artifact whose STATUS: marker reads
+ * blocked, failed, or fail. Scoped to STATE.md's current phase so a leftover or
+ * newer phase tree cannot skew routing. Returns true only on a clear positive signal.
+ */
+function detectVerifyFailed(cwd, currentPhaseRaw) {
+    const phasesDir = node_path_1.default.join(planningPaths(cwd).phases);
+    let entries = [];
+    try {
+        entries = node_fs_1.default.readdirSync(phasesDir)
+            .map((name) => ({ name, phaseToken: phaseTokenFromDirName(name) }))
+            .filter((entry) => entry.phaseToken !== null)
+            .sort((a, b) => comparePhaseNum(a.phaseToken, b.phaseToken) || a.name.localeCompare(b.name))
+            .map((entry) => entry.name);
+    }
+    catch {
+        return false;
+    }
+    if (entries.length === 0)
+        return false;
+    const phaseToken = phaseTokenFromState(currentPhaseRaw);
+    let targetDir;
+    if (phaseToken) {
+        const normalized = normalizePhaseName(phaseToken);
+        targetDir = entries.find((name) => phaseTokenMatches(name, normalized));
+        if (!targetDir)
+            return false;
+    }
+    else {
+        // No current phase in state — fall back to the highest-numbered phase dir.
+        targetDir = entries[entries.length - 1];
+    }
+    const latestDir = node_path_1.default.join(phasesDir, targetDir);
+    let files = [];
+    try {
+        files = node_fs_1.default.readdirSync(latestDir);
+    }
+    catch {
+        return false;
+    }
+    const candidates = files.filter((f) => /summary|verif(?:y|ication)|uat/i.test(f));
+    for (const name of candidates) {
+        let content = '';
+        try {
+            content = node_fs_1.default.readFileSync(node_path_1.default.join(latestDir, name), 'utf-8');
+        }
+        catch {
+            continue;
+        }
+        const statusMatch = content.match(/STATUS:\s*([A-Za-z_-]+)/i);
+        if (statusMatch && /\b(blocked|fail(ed)?)\b/i.test(statusMatch[1])) {
+            return true;
+        }
+    }
+    return false;
+}
+/** Parse `.planning/STATE.md` (frontmatter + body) into the raw signals we need. */
+function readStateFile(statePath) {
+    let content;
+    try {
+        content = node_fs_1.default.readFileSync(statePath, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+    const fm = extractFrontmatter(content);
+    const body = content.replace(/^---[\s\S]*?---\s*/, '');
+    return { fm, body };
+}
+/** Collect the full signal set from disk for `cwd`. Exported for unit tests. */
+function detectSignals(cwd, now = Date.now) {
+    const paths = planningPaths(cwd);
+    const hasPlanning = node_fs_1.default.existsSync(paths.planning);
+    const hasRoadmap = node_fs_1.default.existsSync(paths.roadmap);
+    const git = readGitSignals(cwd);
+    const empty = {
+        current_phase: null,
+        total_phases: null,
+        status: '',
+        progress: null,
+        has_planning: hasPlanning,
+        has_roadmap: hasRoadmap,
+        git_dirty: git.dirty,
+        git_unpushed: git.unpushed,
+        paused: false,
+        blockers: [],
+        has_git: git.has_git,
+        verify_failed: false,
+        stale_activity: false,
+    };
+    if (!hasPlanning)
+        return empty;
+    const parsed = readStateFile(paths.state);
+    if (!parsed)
+        return empty;
+    const { fm, body } = parsed;
+    // STATE.md has two lineages of schemas (see state.cjs parseProsePhaseField):
+    //   - scalar frontmatter: `current_phase: 3`, `total_phases: 5`
+    //   - nested frontmatter: `progress: { total_phases: 5, percent: 40 }`
+    //   - 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');
+    // 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.
+    const currentPhaseRaw = fmScalar(fm, body, 'current_phase', 'Current Phase') ??
+        stateExtractField(body, 'Phase');
+    // 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 = fmScalarKey(progressFm, 'total_phases') ??
+        fmScalar(fm, body, 'total_phases', 'Total Phases');
+    const progressRaw = fmScalarKey(progressFm, 'percent') ??
+        fmScalar(fm, body, 'progress', 'Progress');
+    // Blockers list: `- <text>` items under a `## Blockers` heading.
+    const blockers = [];
+    const blockersMatch = body.match(/##\s*Blockers\s*\n([\s\S]*?)(?=\n##|$)/i); // allow-adhoc-markdown: read-only blockers section-collect in smart-entry.cts; mirrors state.cts (#1372), pending collectSection migration
+    if (blockersMatch) {
+        const items = blockersMatch[1].match(/^-\s+(.+)$/gm) || [];
+        for (const item of items)
+            blockers.push(item.replace(/^-\s+/, '').trim());
+    }
+    const paused = Boolean(pausedAtRaw && pausedAtRaw.trim());
+    // Stale = no recorded activity for IDLE_STALE_MS. Used only by idle-stranded.
+    // Computed here (with the clock seam) so the pure classify() stays a function
+    // of (signals, staleActivity) and detectSignals owns all disk reads.
+    const lastActivityMs = parseActivityTimestamp(lastActivityRaw);
+    const staleActivity = lastActivityMs !== null && now() - lastActivityMs > IDLE_STALE_MS;
+    // Verify-failed may be signalled either by STATE.md status or by a failed
+    // STATUS: marker on the current phase's summary/verify artifact.
+    const verifyFailed = /\bverify-fail(ed)?|verification-fail|uat-fail\b/i.test(statusRaw || '') ||
+        detectVerifyFailed(cwd, currentPhaseRaw);
+    return {
+        current_phase: parseIntOrNull(currentPhaseRaw),
+        total_phases: parseIntOrNull(totalPhasesRaw),
+        status: (statusRaw || '').toLowerCase(),
+        progress: parseIntOrNull(progressRaw),
+        has_planning: hasPlanning,
+        has_roadmap: hasRoadmap,
+        git_dirty: git.dirty,
+        git_unpushed: git.unpushed,
+        paused,
+        blockers,
+        has_git: git.has_git,
+        verify_failed: verifyFailed,
+        stale_activity: staleActivity,
+    };
+}
+// ─── Situation classification ─────────────────────────────────────────────────
+/** True when the workflow has fully completed all phases. */
+function isComplete(s) {
+    if (s.total_phases === null || s.current_phase === null)
+        return false;
+    return s.current_phase >= s.total_phases && /\bcomplete(d)?|done|shipped\b/i.test(s.status);
+}
+/** Idle-stranded: clean tree, committed work not shipped, optionally stale. */
+function isIdleStranded(s) {
+    if (/\bcomplete(d)?|done|shipped|paused\b/i.test(s.status))
+        return false;
+    if (s.git_dirty)
+        return false;
+    // Unpushed commits are the strongest signal. Otherwise require staleness.
+    return s.git_unpushed || s.stale_activity;
+}
+/**
+ * Classify signals into a situation. Priority order matters — the first
+ * matching predicate wins (e.g. paused beats blocked). Exported for unit tests.
+ * Pure function of signals (staleness + verify-failed are precomputed on signals).
+ */
+function classify(s) {
+    if (!s.has_planning)
+        return 'no-project';
+    if (s.paused)
+        return 'paused';
+    if (s.blockers.length > 0)
+        return 'blocked';
+    if (s.verify_failed)
+        return 'verify-failed';
+    if (s.total_phases === null || s.total_phases <= 0 || !s.has_roadmap)
+        return 'needs-first-phase';
+    if (isComplete(s))
+        return 'complete';
+    if (/\bplanning|planned\b/i.test(s.status))
+        return 'planning';
+    if (/\bexecut(e|ing)|active|in.progress|building\b/i.test(s.status))
+        return 'executing';
+    if (/\bverify|review|needs.review|pending.review\b/i.test(s.status))
+        return 'verify-pending';
+    if (isIdleStranded(s))
+        return 'idle-stranded';
+    return 'unknown';
+}
+// ─── Action sets ──────────────────────────────────────────────────────────────
+const action = (id, label, command, recommended = false) => ({ id, label, command, recommended });
+function rec(id, label, command) {
+    return action(id, label, command, true);
+}
+/** Per-situation ordered action list; recommended action first. */
+function actionsFor(situation, s) {
+    const phaseN = s.current_phase ?? '';
+    const execLabel = phaseN === '' ? 'Continue executing' : `Continue executing phase ${phaseN}`;
+    switch (situation) {
+        case 'no-project':
+            return [
+                rec('new-project', 'Start a new project', '/gsd:new-project'),
+                action('map-codebase', 'Map an existing codebase', '/gsd:map-codebase'),
+                action('quick', 'Quick task', '/gsd:quick'),
+                action('help', 'Show help', '/gsd:help'),
+            ];
+        case 'paused':
+            return [
+                rec('resume-work', 'Resume work', '/gsd:resume-work'),
+                action('progress', 'Show progress', '/gsd:progress'),
+                action('quick', 'Quick task', '/gsd:quick'),
+                action('help', 'Show help', '/gsd:help'),
+            ];
+        case 'blocked':
+            return [
+                rec('debug', 'Debug the blocker', '/gsd:debug'),
+                action('verify-work', 'Verify current work', '/gsd:verify-work'),
+                action('capture', 'Capture a note', '/gsd:capture'),
+                action('progress', 'Show progress', '/gsd:progress'),
+            ];
+        case 'verify-failed':
+            return [
+                rec('verify-work', 'Re-verify work', '/gsd:verify-work'),
+                action('debug', 'Debug the failure', '/gsd:debug'),
+                action('code-review', 'Review recent work', '/gsd:code-review'),
+                action('progress', 'Show progress', '/gsd:progress'),
+            ];
+        case 'needs-first-phase':
+            return [
+                rec('discuss-phase', 'Discuss the first phase', '/gsd:discuss-phase'),
+                action('plan-phase', 'Plan phase 1', '/gsd:plan-phase'),
+                action('quick', 'Quick task', '/gsd:quick'),
+                action('progress', 'Show progress', '/gsd:progress'),
+            ];
+        case 'planning':
+            // Forward motion → delegate to the single gated engine (see 'executing').
+            return [
+                rec('progress-next', `Advance to the next step (plan phase ${phaseN || 1})`, '/gsd:progress --next'),
+                action('plan-phase', `Plan phase ${phaseN || 1}`, '/gsd:plan-phase'),
+                action('discuss-phase', 'Discuss before planning', '/gsd:discuss-phase'),
+                action('progress', 'Show progress', '/gsd:progress'),
+            ];
+        case 'executing':
+            // In-project forward motion delegates to the single gated engine
+            // (/gsd:progress --next → workflows/next.md). Its Route 0 resume-incomplete
+            // -phase invariant + Gates 1-3 must not be bypassed by dispatching a raw
+            // /gsd:execute-phase here — that divergence is why the old flat /gsd-next
+            // was removed (#3054). Direct execute stays as an explicit secondary choice.
+            return [
+                rec('progress-next', 'Advance to the next step', '/gsd:progress --next'),
+                action('execute-phase', execLabel, '/gsd:execute-phase'),
+                action('quick', 'Quick task', '/gsd:quick'),
+                action('code-review', 'Review recent work', '/gsd:code-review'),
+            ];
+        case 'verify-pending':
+            // Forward motion → delegate to the single gated engine (see 'executing').
+            return [
+                rec('progress-next', 'Advance to the next step (verify)', '/gsd:progress --next'),
+                action('verify-work', 'Verify work', '/gsd:verify-work'),
+                action('code-review', 'Review recent work', '/gsd:code-review'),
+                action('ship', 'Ship completed work', '/gsd:ship'),
+            ];
+        case 'idle-stranded':
+            return [
+                rec('ship', 'Ship committed work', '/gsd:ship'),
+                action('complete-milestone', 'Complete the milestone', '/gsd:complete-milestone'),
+                action('progress', 'Show progress', '/gsd:progress'),
+                action('capture', 'Capture a note', '/gsd:capture'),
+            ];
+        case 'complete':
+            return [
+                rec('new-milestone', 'Start a new milestone', '/gsd:new-milestone'),
+                action('extract-learnings', 'Extract learnings', '/gsd:extract-learnings'),
+                action('quick', 'Quick task', '/gsd:quick'),
+                action('progress', 'Show progress', '/gsd:progress'),
+            ];
+        case 'unknown':
+        default:
+            return [
+                rec('progress', 'Show progress', '/gsd:progress'),
+                action('progress-next', 'Advance to the next step', '/gsd:progress --next'),
+                action('quick', 'Quick task', '/gsd:quick'),
+                action('help', 'Show help', '/gsd:help'),
+            ];
+    }
+}
+// ─── Summary line ─────────────────────────────────────────────────────────────
+function buildSummary(situation, s) {
+    switch (situation) {
+        case 'no-project':
+            return 'No project yet — start fresh or map an existing codebase';
+        case 'paused':
+            return 'Work is paused — pick up where you left off';
+        case 'blocked':
+            return `Blocked${s.blockers.length ? ` · ${s.blockers.length} blocker(s)` : ''} — resolve before continuing`;
+        case 'verify-failed':
+            return 'Recent verification failed — re-verify or debug';
+        case 'needs-first-phase':
+            return 'Project initialized — plan your first phase';
+        case 'planning':
+            return `Phase ${s.current_phase ?? '?'} of ${s.total_phases ?? '?'} — needs a plan`;
+        case 'executing':
+            return progressLine('executing', s);
+        case 'verify-pending':
+            return progressLine('ready to verify', s);
+        case 'idle-stranded':
+            return 'Committed work not shipped — time to ship';
+        case 'complete':
+            return 'All phases complete — start a new milestone';
+        case 'unknown':
+        default:
+            return 'Unsure of state — showing progress';
+    }
+}
+function progressLine(tail, s) {
+    const parts = [];
+    if (s.current_phase !== null && s.total_phases !== null) {
+        parts.push(`Phase ${s.current_phase} of ${s.total_phases}`);
+    }
+    else if (s.current_phase !== null) {
+        parts.push(`Phase ${s.current_phase}`);
+    }
+    if (s.progress !== null)
+        parts.push(`${s.progress}%`);
+    parts.push(tail);
+    return parts.join(' · ');
+}
+// ─── Orchestration ─────────────────────────────────────────────────────────────
+/**
+ * Run the full detect → classify → assemble pipeline. Pure: no stdout, no
+ * writes. Exported for direct unit testing and reuse. The clock seam drives
+ * staleness detection inside detectSignals.
+ */
+function classifyProject(cwd, now = Date.now) {
+    const signals = detectSignals(cwd, now);
+    const situation = classify(signals);
+    const actions = actionsFor(situation, signals);
+    const recommended = actions.find((a) => a.recommended)?.id ?? 'progress';
+    const summary = buildSummary(situation, signals);
+    return { situation, recommended, summary, signals, actions };
+}
+/**
+ * `gsd-tools smart-entry` entry point. `--json` emits machine JSON; default
+ * emits a human-readable summary line. Never throws for a missing `.planning/`
+ * (returns `no-project`); other internal failures surface a typed error via
+ * `output()` so the workflow can fall back to `/gsd:progress`.
+ */
+function runSmartEntry(cwd, args, raw) {
+    const json = args.includes('--json');
+    const result = classifyProject(cwd);
+    if (json) {
+        output(result, raw, undefined);
+        return;
+    }
+    // Human mode: a compact one-liner plus the recommended action.
+    const human = `${result.summary}\nRecommended: ${result.recommended} → ${result.actions.find((a) => a.id === result.recommended)?.command ?? '/gsd:progress'}`;
+    output(null, true, human);
+}

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

@@ -19,6 +19,7 @@ exports.STATE_MD_SECTIONS = exports.FIELD_CLASSIFICATION = void 0;
 exports.getFieldClassification = getFieldClassification;
 exports.applyStatePreservation = applyStatePreservation;
 exports.transitionCore = transitionCore;
+exports.sliceCurrentPositionSection = sliceCurrentPositionSection;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const frontmatter = require("./frontmatter.cjs");
 const state_document_cjs_1 = require("./state-document.cjs");
@@ -319,6 +320,20 @@ function locateCurrentPosition(body) {
     }
     return { start, end };
 }
+/**
+ * Return the body text of the `## Current Position` section, or `null` when it
+ * is absent. Reuses the fence-aware `locateCurrentPosition` locator (ADR-1372).
+ *
+ * Exposed so callers that must read a position field (e.g. `cmdStatePrune`,
+ * #1776) can scope extraction to the canonical section instead of the whole
+ * document — where `stateExtractField`'s pipe-table fallback could otherwise
+ * latch onto an unrelated `| Phase | N |` row elsewhere in STATE.md. This
+ * scopes the *caller*; the shared extractor is left broad for every other use.
+ */
+function sliceCurrentPositionSection(body) {
+    const span = locateCurrentPosition(body);
+    return span === null ? null : body.slice(span.start, span.end);
+}
 /**
  * First-time ## Current Position mutation: update Phase / Plan / Status /
  * Last activity lines. Mirrors state.cts:2261-2324 byte-for-behaviour

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

@@ -35,7 +35,7 @@ const { extractFrontmatter, reconstructFrontmatter } = frontmatter;
 const scanPhasePlans = require("./plan-scan.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const stateTransitionMod = require("./state-transition.cjs");
-const { transitionCore, applyStatePreservation } = stateTransitionMod;
+const { transitionCore, applyStatePreservation, sliceCurrentPositionSection } = stateTransitionMod;
 const state_document_cjs_1 = require("./state-document.cjs");
 const markdown_sectionizer_cjs_1 = require("./markdown-sectionizer.cjs");
 const STATE_PROGRESS_RESYNC_FIELDS = new Set([
@@ -1293,7 +1293,8 @@ function buildStateFrontmatter(bodyContent, cwd) {
                     // truth for total_phases (#549).
                     let roadmapPhaseCount = 0;
                     if (roadmapScope !== null) {
-                        const phaseHeadingPattern = /#{2,4}\s*Phase\s+([\w][\w.-]*)\s*:/gi;
+                        // #1729: `(?:\s*\([^)\n]*\))?` tolerates a pre-colon ( ) tag (literal mirror of OPTIONAL_PHASE_TAG_SOURCE).
+                        const phaseHeadingPattern = /#{2,4}\s*Phase\s+([\w][\w.-]*)(?:\s*\([^)\n]*\))?\s*:/gi;
                         let m;
                         while ((m = phaseHeadingPattern.exec(roadmapScope)) !== null) {
                             // Only count tokens that contain at least one digit — excludes
@@ -2245,7 +2246,8 @@ function cmdStateSync(cwd, options, raw) {
     try {
         let roadmapPhaseCount = 0;
         if (syncRoadmapScope !== null) {
-            const phaseHeadingPattern = /#{2,4}\s*Phase\s+([\w][\w.-]*)\s*:/gi;
+            // #1729: `(?:\s*\([^)\n]*\))?` tolerates a pre-colon ( ) tag (literal mirror of OPTIONAL_PHASE_TAG_SOURCE).
+            const phaseHeadingPattern = /#{2,4}\s*Phase\s+([\w][\w.-]*)(?:\s*\([^)\n]*\))?\s*:/gi;
             let m;
             while ((m = phaseHeadingPattern.exec(syncRoadmapScope)) !== null) {
                 // Only count tokens that contain at least one digit — excludes
@@ -2321,12 +2323,29 @@ function cmdStatePrune(cwd, options, raw) {
     }
     const keepRecent = parseInt(String(options.keepRecent), 10) || 3;
     const dryRun = !!options.dryRun;
-    // #1760: the canonical STATE.md template emits `Phase: [X] of [Y]`, not
-    // `Current Phase:`. Read both (mirroring buildStateFrontmatter /
-    // resolvePhaseIdForCompletePhase) so prune engages on template-conformant
-    // STATE.md instead of bailing with "Only 0 phases — nothing to prune".
+    // Resolve the current phase via the same canonical chain buildStateFrontmatter
+    // uses (frontmatter `current_phase` → `Current Phase` field → prose `Phase: X
+    // of Y`), so prune engages on template-conformant STATE.md instead of bailing
+    // "Only 0 phases" (#1760).
+    // #1776: scope ONLY the prose `Phase:` term to the canonical `## Current
+    // Position` section. Over the whole body, `stateExtractField`'s pipe-table
+    // fallback matches any `| Phase | N |` row (e.g. a historical verification
+    // table), resolving a stale phase and computing a wrong cutoff. Frontmatter and
+    // the explicit `Current Phase` field are unambiguous, so they stay document-wide;
+    // the shared extractor is not narrowed for any other caller.
     const rawState = node_fs_1.default.readFileSync(statePath, 'utf-8');
-    const currentPhaseRaw = (0, state_document_cjs_1.stateExtractField)(rawState, 'Current Phase') || (0, state_document_cjs_1.stateExtractField)(rawState, 'Phase');
+    const fm = extractFrontmatter(rawState);
+    const body = stripFrontmatter(rawState);
+    // Mirror buildStateFrontmatter's fmScalar: only string/number/boolean
+    // frontmatter scalars are usable (an object/array `current_phase` is ignored,
+    // which also avoids a base-to-string on a non-primitive).
+    const fmRawPhase = fm.current_phase;
+    const fmCurrentPhase = typeof fmRawPhase === 'string' ? (fmRawPhase.trim() || null)
+        : typeof fmRawPhase === 'number' || typeof fmRawPhase === 'boolean' ? String(fmRawPhase)
+            : null;
+    const positionSection = sliceCurrentPositionSection(body);
+    const prosePhase = positionSection !== null ? parseProsePhaseField((0, state_document_cjs_1.stateExtractField)(positionSection, 'Phase')).phase : null;
+    const currentPhaseRaw = fmCurrentPhase ?? (0, state_document_cjs_1.stateExtractField)(body, 'Current Phase') ?? prosePhase;
     const currentPhase = parseInt(String(currentPhaseRaw), 10) || 0;
     const cutoff = currentPhase - keepRecent;
     if (cutoff <= 0) {

package/gsd-core/bin/lib/surface.cjs

@@ -466,16 +466,25 @@ function _syncGsdDir(stagedDir, destDir, kind, manifest) {
         //   - agents: only gsd-* are GSD-owned
         //   - flat command dirs: only `${kindPrefix}`-prefixed are GSD-owned
         //   - namespaced command dirs: the whole dir is GSD-owned
-        for (const file of node_fs_1.default.readdirSync(destDir).filter(f => f.endsWith('.md'))) {
-            if (kindName === 'agents' && !file.startsWith('gsd-'))
-                continue;
-            if (kindName === 'commands' && !namespacedByDir && kindPrefix && !file.startsWith(kindPrefix))
-                continue;
-            if (!stagedDestNames.has(file)) {
-                try {
-                    node_fs_1.default.unlinkSync(node_path_1.default.join(destDir, file));
+        //
+        // Manifest gate (#2018): when the manifest is empty/absent (e.g. an unresolvable
+        // install source root yields an empty staged dir), the staged set is untrustworthy.
+        // Skills are guarded by pruneSkillDirs' manifest-membership check; agents must be
+        // guarded here — skip the prune loop entirely so an empty manifest never deletes
+        // every gsd-* agent. Copying (above) still runs so genuinely new agents are added.
+        const shouldPruneAgents = !(kindName === 'agents' && (!manifest || manifest.size === 0));
+        if (shouldPruneAgents) {
+            for (const file of node_fs_1.default.readdirSync(destDir).filter(f => f.endsWith('.md'))) {
+                if (kindName === 'agents' && !file.startsWith('gsd-'))
+                    continue;
+                if (kindName === 'commands' && !namespacedByDir && kindPrefix && !file.startsWith(kindPrefix))
+                    continue;
+                if (!stagedDestNames.has(file)) {
+                    try {
+                        node_fs_1.default.unlinkSync(node_path_1.default.join(destDir, file));
+                    }
+                    catch { /* ignore */ }
                 }
-                catch { /* ignore */ }
             }
         }
     }