@opengsd/gsd-core 1.5.0 → 1.6.0-rc.2

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

@@ -33,7 +33,6 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
-const node_os_1 = __importDefault(require("node:os"));
 const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const installProfiles = require("./install-profiles.cjs");
@@ -41,7 +40,9 @@ const { readActiveProfile, resolveProfile, loadSkillsManifest, } = installProfil
 const clusters_cjs_1 = require("./clusters.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const runtimeArtifactLayout = require("./runtime-artifact-layout.cjs");
-const { findInstallSourceRoot, getInstallExports } = runtimeArtifactLayout;
+const { findInstallSourceRoot } = runtimeArtifactLayout;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const runtimeArtifactConversion = require("./runtime-artifact-conversion.cjs");
 const SURFACE_FILE_NAME = '.gsd-surface.json';
 /**
  * Read the surface state from a runtime config directory.
@@ -265,26 +266,18 @@ function applySurface(runtimeConfigDir, layout, manifest, clusterMap, registry)
     const resolved = resolveSurface(layout.configDir, skillManifest, clusterMap, registry);
     // Mirror installRuntimeArtifacts: skills kinds get per-runtime path rewrites
     // so SKILL.md bodies reference the install target (pathPrefix), not the
-    // converter's default ~/.claude paths (#813). Computed lazily so command-only
-    // runtimes do not trigger the install.js require.
-    let pathPrefix = null;
+    // converter's default ~/.claude paths (#813). Delegated to the conversion
+    // module's deep seam (ADR-1508 / #1511 Phase 2) — no attribution resolver
+    // needed here (proven: Co-Authored-By never appears in staged content; see
+    // brief PROVEN KEY FACT). No getInstallExports() call required.
     for (const kind of layout.kinds) {
         const staged = kind.stage(resolved);
         if (kind.kind === 'skills') {
-            const installExports = getInstallExports();
-            if (pathPrefix === null) {
-                const scope = layout.scope ?? 'global';
-                const resolvedTarget = node_path_1.default.resolve(layout.configDir).replace(/\\/g, '/');
-                const homeDir = node_os_1.default.homedir().replace(/\\/g, '/');
-                pathPrefix = installExports.computePathPrefix({
-                    isGlobal: scope === 'global',
-                    isOpencode: layout.runtime === 'opencode',
-                    isWindowsHost: process.platform === 'win32',
-                    resolvedTarget,
-                    homeDir,
-                });
-            }
-            installExports.applyRuntimeContentRewritesInPlace(staged, layout.runtime, pathPrefix);
+            runtimeArtifactConversion.rewriteStagedSkillBodies(staged, {
+                runtime: layout.runtime,
+                configDir: layout.configDir,
+                scope: layout.scope ?? 'global',
+            });
         }
         const dest = node_path_1.default.join(layout.configDir, kind.destSubpath);
         _syncGsdDir(staged, dest, kind, skillManifest);

package/gsd-core/bin/lib/uat-predicate.cjs

@@ -19,6 +19,9 @@ const node_path_1 = __importDefault(require("node:path"));
 // 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 markdownSectionizer = require("./markdown-sectionizer.cjs");
+const { stripFencedCode } = markdownSectionizer;
 // ─── Blocking state sets (documented for maintainability) ─────────────────────
 // UAT file frontmatter `status` values that indicate the file is not fully done
 const BLOCKING_UAT_FM_STATUSES = new Set([
@@ -53,8 +56,8 @@ function stripFalsePositiveContexts(content) {
     let stripped = content.replace(/^---\r?\n[\s\S]*?\r?\n---[ \t]*(\r?\n|$)/, '');
     // Step (b): remove HTML comments anywhere; unterminated comment swallows to EOF
     stripped = stripped.replace(/<!--[\s\S]*?(?:-->|$)/g, '');
-    // Step (c): remove fenced code blocks via CommonMark-style state machine (handles CRLF + indented fences)
-    stripped = _stripFencedBlocks(stripped).text;
+    // Step (c): remove fenced code blocks via the canonical seam (ADR-1372 T5)
+    stripped = stripFencedCode(stripped).text;
     // Step (d): remove blockquote lines
     stripped = stripped
         .split('\n')
@@ -62,49 +65,6 @@ function stripFalsePositiveContexts(content) {
         .join('\n');
     return stripped;
 }
-/**
- * CommonMark-style fenced-code-block stripper.
- * Tracks the opening delimiter char and length so that a ~~~ line inside a
- * ``` fence is correctly treated as fence content, not a closing delimiter.
- *
- * Opening rule: first delimiter line with char+len sets openFence.
- * Closing rule: delimiter line with SAME char, run length >= openFence.len,
- *   and NO trailing non-whitespace text closes the fence.
- * All delimiter and content lines are dropped; non-fence lines are kept.
- * Returns the kept text plus unterminatedFence:true if EOF inside a fence.
- */
-function _stripFencedBlocks(content) {
-    const lines = content.split('\n');
-    const kept = [];
-    let openFence = null;
-    const delimRe = /^(\s*)(`{3,}|~{3,})(.*)$/;
-    for (const rawLine of lines) {
-        // Tolerate CRLF: strip trailing \r for matching, but we work on split-by-\n lines
-        // (the outer caller joined by \n already; we just handle a stray \r in the last char)
-        const line = rawLine.replace(/\r$/, '');
-        const m = delimRe.exec(line);
-        if (m) {
-            const char = m[2][0];
-            const len = m[2].length;
-            const trailing = m[3];
-            if (openFence === null) {
-                // Opening delimiter — drop this line and record the fence
-                openFence = { char, len };
-            }
-            else if (char === openFence.char && len >= openFence.len && /^\s*$/.test(trailing)) {
-                // Closing delimiter (same char, sufficient length, no trailing text) — drop and close
-                openFence = null;
-            }
-            // else: mismatched delimiter inside fence (e.g. ~~~ inside ```) — drop as content
-            continue; // delimiter lines are always dropped
-        }
-        if (openFence === null) {
-            kept.push(rawLine);
-        }
-        // Lines inside fence are dropped
-    }
-    return { text: kept.join('\n'), unterminatedFence: openFence !== null };
-}
 /**
  * Analyse raw markdown for structural anomalies (unterminated fence / comment).
  * Exported for unit-testability and used by evaluateUatPassed for per-file malformed detection.
@@ -129,8 +89,8 @@ function analyzeMarkdown(raw) {
         }
         i = close + 3;
     }
-    // Fence state machine gives the accurate unterminated-fence signal.
-    const { unterminatedFence } = _stripFencedBlocks(raw);
+    // Fence state machine gives the accurate unterminated-fence signal (seam, ADR-1372 T5).
+    const { unterminatedFence } = stripFencedCode(raw);
     return { unterminatedFence, unterminatedComment };
 }
 // ─── parseUatResultItems ──────────────────────────────────────────────────────

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

@@ -18,6 +18,9 @@ const node_path_1 = __importDefault(require("node:path"));
 const io = require("./io.cjs");
 const { output, error } = io;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
+const markdownSectionizer = require("./markdown-sectionizer.cjs");
+const { collectSection, tokenizeHeadings } = markdownSectionizer;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
 const roadmapParser = require("./roadmap-parser.cjs");
 const { getMilestonePhaseFilter } = roadmapParser;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
@@ -128,11 +131,16 @@ function cmdRenderCheckpoint(cwd, options = {}, raw) {
 }
 // ─── parseCurrentTest ─────────────────────────────────────────────────────────
 function parseCurrentTest(content) {
-    const currentTestMatch = content.match(/##\s*Current Test\s*(?:\n<!--[\s\S]*?-->)?\n([\s\S]*?)(?=\n##\s|$)/i);
-    if (!currentTestMatch) {
+    // Use the seam to locate the ## Current Test section (ADR-1372 T5).
+    // HTML-comment stripping within the section body is UAT-specific, so we keep
+    // the comment removal caller-side after extracting the body.
+    const currentTestSection = collectSection(content, (h) => /^current\s+test$/i.test(h.text) && h.level === 2, { levelBounded: true });
+    if (!currentTestSection) {
         error('UAT file is missing a Current Test section');
     }
-    const section = currentTestMatch[1].trimEnd();
+    // Remove any leading HTML comment block (UAT-specific document structure)
+    const rawBody = currentTestSection.body.replace(/^<!--[\s\S]*?-->\s*\n?/, '');
+    const section = rawBody.trimEnd();
     if (!section.trim()) {
         error('Current Test section is empty');
     }
@@ -173,36 +181,41 @@ function parseCurrentTest(content) {
     };
 }
 function parseFirstPendingTest(content) {
-    const testsMatch = content.match(/##\s*Tests\s*\n([\s\S]*?)(?=\n##\s|$)/i);
-    if (!testsMatch) {
+    // Use the seam to locate the ## Tests section (ADR-1372 T5).
+    const testsSection = collectSection(content, (h) => /^tests$/i.test(h.text) && h.level === 2, { levelBounded: true });
+    if (!testsSection) {
         return null;
     }
-    const testsSection = testsMatch[1];
-    const headingPattern = /^###\s*(\d+)\.\s*([^\n]+)\s*$/gm;
-    const headings = [];
-    let headingMatch;
-    while ((headingMatch = headingPattern.exec(testsSection)) !== null) {
-        headings.push({
-            index: headingMatch.index,
-            number: parseInt(headingMatch[1], 10),
-            name: headingMatch[2].trim(),
-        });
-    }
-    for (let i = 0; i < headings.length; i += 1) {
-        const current = headings[i];
-        const next = headings[i + 1];
-        const block = testsSection.slice(current.index, next ? next.index : undefined);
+    const sectionBody = testsSection.body;
+    // Within the Tests section body, find ### N. Name sub-headings.
+    // tokenizeHeadings operates on the section body as a standalone document,
+    // filtering to level-3 headings matching the UAT-specific "N. Name" pattern.
+    // The UAT-specific item parsing (number extraction, result parsing) stays caller-side.
+    const subHeadings = tokenizeHeadings(sectionBody).filter((h) => h.level === 3 && /^\d+\.\s+/.test(h.text));
+    for (let i = 0; i < subHeadings.length; i += 1) {
+        const current = subHeadings[i];
+        const next = subHeadings[i + 1];
+        // Slice the block for this sub-test from the section body text
+        const block = next
+            ? sectionBody.slice(current.offset, next.offset)
+            : sectionBody.slice(current.offset);
         if (!/^result:\s*\[?pending\]?\s*$/im.test(block)) {
             continue;
         }
+        // Extract the UAT-specific number and name from the heading text
+        const headingParts = current.text.match(/^(\d+)\.\s+(.+)$/);
+        if (!headingParts)
+            continue;
+        const testNumber = parseInt(headingParts[1], 10);
+        const testName = headingParts[2].trim();
         const expected = parseExpectedFromTestBlock(block);
         if (!expected) {
-            error(`Pending UAT test ${current.number} is missing an expected field`);
+            error(`Pending UAT test ${testNumber} is missing an expected field`);
         }
         return {
             complete: false,
-            number: current.number,
-            name: (0, security_cjs_1.sanitizeForDisplay)(current.name),
+            number: testNumber,
+            name: (0, security_cjs_1.sanitizeForDisplay)(testName),
             expected: (0, security_cjs_1.sanitizeForDisplay)(expected),
         };
     }
@@ -273,10 +286,10 @@ function parseUatItems(content) {
 function parseVerificationItems(content, status) {
     const items = [];
     if (status === 'human_needed') {
-        // Extract from human_verification section — look for numbered items or table rows
-        const hvSection = content.match(/##\s*Human Verification.*?\n([\s\S]*?)(?=\n##\s|\n---\s|$)/i);
+        // Use the seam to locate the ## Human Verification section (ADR-1372 T5).
+        const hvSection = collectSection(content, (h) => /^human\s+verification/i.test(h.text) && h.level === 2, { levelBounded: true });
         if (hvSection) {
-            const lines = hvSection[1].split('\n');
+            const lines = hvSection.body.split('\n');
             for (const line of lines) {
                 // Match table rows: | N | description | ... |
                 const tableMatch = line.match(/\|\s*(\d+)\s*\|\s*([^|]+)/);

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

@@ -37,14 +37,17 @@ exports.canonicalPlanStem = canonicalPlanStem;
 exports.phaseVariants = phaseVariants;
 exports.buildRoadmapPhaseVariants = buildRoadmapPhaseVariants;
 exports.buildNotStartedPhaseVariants = buildNotStartedPhaseVariants;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const phaseIdMod = require("./phase-id.cjs");
+const { OPTIONAL_PROJECT_CODE_PREFIX_SOURCE } = phaseIdMod;
 // ── Issue #26: regex constants (W005, W006-archived) ────────────────────────
 // Matches legacy numeric dirs (01-setup), milestone-prefixed dirs (02-01-setup),
 // deep dirs (02-04-01-deep), and project-code-prefixed variants (GSD-02-01-setup).
-exports.phaseDirNameRe = /^(?:[A-Z]{1,6}-)?\d{2,}(?:-\d+)*(?:\.\d+)*-[\w-]+$/i;
+exports.phaseDirNameRe = new RegExp(`^${OPTIONAL_PROJECT_CODE_PREFIX_SOURCE}\\d{2,}(?:-\\d+)*(?:\\.\\d+)*-[\\w-]+$`, 'i');
 // Extracts the full phase token from a directory name, including milestone-prefixed
 // multi-segment tokens like "02-01" from "02-01-setup" or "GSD-02-01-setup".
 // Greedily captures all leading all-digit segments before the first letter-start segment.
-exports.PHASE_TOKEN_FROM_DIR_RE = /^(?:[A-Z]{1,6}-)?(\d+(?:-\d+)*[A-Z]?(?:\.\d+)*)(?:-[a-z]|$)/i;
+exports.PHASE_TOKEN_FROM_DIR_RE = new RegExp(`^${OPTIONAL_PROJECT_CODE_PREFIX_SOURCE}(\\d+(?:-\\d+)*[A-Z]?(?:\\.\\d+)*)(?:-[a-z]|$)`, 'i');
 exports.MILESTONE_ARCHIVE_DIR_RE = /^v\d+.*-phases$/i;
 // ── Issue #26: I001 canonicalization ────────────────────────────────────────
 function canonicalPlanStem(stem) {

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

@@ -50,7 +50,7 @@ const { getMilestoneInfo, stripShippedMilestones, extractCurrentMilestone } = ro
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const worktreeSafetyMod = require("./worktree-safety.cjs");
 const { inspectWorktreeHealth } = worktreeSafetyMod;
-const { planningDir } = planningWorkspace;
+const { planningDir, planningRoot } = planningWorkspace;
 const { extractFrontmatter, parseMustHavesBlock } = frontmatterMod;
 const { writeStateMd } = stateMod;
 const { MODEL_PROFILES } = modelProfilesMod;
@@ -1112,12 +1112,18 @@ function cmdValidateHealth(cwd, options, raw) {
         }, raw);
         return;
     }
-    const planBase = planningDir(cwd);
-    const projectPath = node_path_1.default.join(planBase, 'PROJECT.md');
-    const roadmapPath = node_path_1.default.join(planBase, 'ROADMAP.md');
-    const statePath = node_path_1.default.join(planBase, 'STATE.md');
-    const configPath = node_path_1.default.join(planBase, 'config.json');
-    const phasesDir = node_path_1.default.join(planBase, 'phases');
+    // rootBase always resolves to .planning/ (shared root — PROJECT.md, config.json live here)
+    // wsBase resolves to .planning/workstreams/<ws>/ when GSD_WORKSTREAM is set (STATE.md, ROADMAP.md, phases/)
+    const rootBase = planningRoot(cwd);
+    const wsBase = planningDir(cwd);
+    // planBase is kept as an alias for wsBase for all the internal helpers (collectDiskPhases, etc.)
+    // that are already parameterised on the workstream-aware path.
+    const planBase = wsBase;
+    const projectPath = node_path_1.default.join(rootBase, 'PROJECT.md');
+    const roadmapPath = node_path_1.default.join(wsBase, 'ROADMAP.md');
+    const statePath = node_path_1.default.join(wsBase, 'STATE.md');
+    const configPath = node_path_1.default.join(rootBase, 'config.json');
+    const phasesDir = node_path_1.default.join(wsBase, 'phases');
     const _slashRuntime = (0, runtime_slash_cjs_1.resolveRuntime)(cwd);
     const slash = (name) => (0, runtime_slash_cjs_1.formatGsdSlash)(name, _slashRuntime);
     const errors = [];
@@ -1133,7 +1139,7 @@ function cmdValidateHealth(cwd, options, raw) {
         else
             info.push(issue);
     };
-    if (!node_fs_1.default.existsSync(planBase)) {
+    if (!node_fs_1.default.existsSync(rootBase)) {
         addIssue('error', 'E001', '.planning/ directory not found', `Run ${slash('new-project')} to initialize`);
         output({ status: 'broken', errors, warnings, info, repairable_count: 0 }, raw);
         return;
@@ -1404,7 +1410,17 @@ function cmdValidateHealth(cwd, options, raw) {
                     continue;
                 }
                 if (finding['kind'] === 'stale') {
-                    addIssue('warning', 'W017', `Stale git worktree: ${finding['path']} (last modified ${finding['ageMinutes']} minutes ago)`, `Run: git worktree remove ${finding['path']} --force`);
+                    // Do not flag the active session's worktree — removing it would be harmful.
+                    const worktreePath = finding['path'];
+                    const activeCwd = process.cwd();
+                    const normalizedWorktree = node_path_1.default.resolve(worktreePath);
+                    const normalizedCwd = node_path_1.default.resolve(activeCwd);
+                    // Skip if the worktree IS the cwd or is an ancestor of it.
+                    const isActiveWorktree = normalizedCwd === normalizedWorktree ||
+                        normalizedCwd.startsWith(normalizedWorktree + node_path_1.default.sep);
+                    if (isActiveWorktree)
+                        continue;
+                    addIssue('warning', 'W017', `Stale git worktree: ${worktreePath} (last modified ${finding['ageMinutes']} minutes ago)`, `Run: git worktree remove ${worktreePath} --force`);
                 }
             }
         }
@@ -1440,8 +1456,8 @@ function cmdValidateHealth(cwd, options, raw) {
     catch {
         /* W021 check is advisory — skip on error */
     }
-    const milestonesPath = node_path_1.default.join(planBase, 'MILESTONES.md');
-    const milestonesArchiveDir = node_path_1.default.join(planBase, 'milestones');
+    const milestonesPath = node_path_1.default.join(rootBase, 'MILESTONES.md');
+    const milestonesArchiveDir = node_path_1.default.join(rootBase, 'milestones');
     const missingFromRegistry = [];
     try {
         if (node_fs_1.default.existsSync(milestonesArchiveDir)) {
@@ -1470,7 +1486,7 @@ function cmdValidateHealth(cwd, options, raw) {
         /* intentionally empty — milestone sync check is advisory */
     }
     try {
-        const entries = node_fs_1.default.readdirSync(planBase, { withFileTypes: true });
+        const entries = node_fs_1.default.readdirSync(rootBase, { withFileTypes: true });
         for (const entry of entries) {
             if (!entry.isFile())
                 continue;
@@ -1566,7 +1582,7 @@ function cmdValidateHealth(cwd, options, raw) {
                         }
                         const milestone = getMilestoneInfo(cwd);
                         const projectRef = node_path_1.default
-                            .relative(cwd, node_path_1.default.join(planningDir(cwd), 'PROJECT.md'))
+                            .relative(cwd, node_path_1.default.join(rootBase, 'PROJECT.md'))
                             .split(node_path_1.default.sep)
                             .join('/');
                         let stateContent = `# Session State\n\n`;
@@ -1871,8 +1887,17 @@ function cmdVerifyCodebaseDrift(cwd, raw) {
             else if (status === 'D')
                 deleted.push(file);
         }
-        const config = loadConfig(cwd);
-        const wf = config?.workflow;
+        // loadConfig() returns a flattened object — there is no nested `workflow`
+        // key. Read the raw config.json directly to access workflow-scoped keys,
+        // matching the pattern used in check-command-router.cts:readWorkflowConfig.
+        let wf;
+        try {
+            const rawCfg = JSON.parse(node_fs_1.default.readFileSync(node_path_1.default.join(planningDir(cwd), 'config.json'), 'utf-8'));
+            wf = rawCfg['workflow'];
+        }
+        catch {
+            wf = undefined;
+        }
         const threshold = Number.isInteger(wf?.drift_threshold) && wf?.drift_threshold >= 1
             ? wf?.drift_threshold
             : 3;

package/gsd-core/bin/lib/worktree-safety.cjs

@@ -693,6 +693,206 @@ function cmdWorktreeCleanupWave(cwd, args = []) {
         process.exitCode = 1;
     }
 }
+/**
+ * Pure planner for the per-agent wave-manifest append.
+ *
+ * Validates the candidate entry at write time using the SAME rules the
+ * cleanup-wave reader enforces (via `normalizeCleanupManifestEntry`), so an
+ * entry that `record-agent` accepts is guaranteed to survive
+ * `normalizeCleanupManifest` on read — a field that would be silently dropped
+ * at cleanup time fails loudly here instead.
+ *
+ * `agent_id` is treated write-strict (required) even though the reader is
+ * lenient (nullable): the whole point of this verb is to catch an
+ * under-populated entry at write time, and an entry whose author cannot be
+ * identified defeats that. A duplicate `(worktree_path, branch)` is also
+ * rejected loudly — the reader dedups on that key, so a re-record would be
+ * silently dropped (the failure mode this verb exists to eliminate). The
+ * on-disk shape stays the existing 4-field entry (`agent_id`, `worktree_path`,
+ * `branch`, `expected_base`) — no schema change; the reader re-derives
+ * `allowed_bases`.
+ */
+function planWorktreeRecordAgent(manifestRaw, fields) {
+    // 1. Write-strict required-field check (loud, with which flag is missing).
+    //    Trim first so a whitespace-only value ("   ") is rejected here rather
+    //    than deferred to a guaranteed `git worktree remove` failure at cleanup.
+    const agentId = (fields.agentId || '').trim();
+    const worktreePath = (fields.worktreePath || '').trim();
+    const branch = (fields.branch || '').trim();
+    const base = (fields.base || '').trim();
+    const missing = [];
+    if (!agentId)
+        missing.push('--agent-id');
+    if (!worktreePath)
+        missing.push('--path');
+    if (!branch)
+        missing.push('--branch');
+    if (!base)
+        missing.push('--base');
+    if (missing.length > 0) {
+        return {
+            ok: false,
+            reason: 'missing_field',
+            hint: `record-agent requires ${missing.join(', ')}. Re-run with all of --agent-id, --path, --branch, --base set to non-empty (non-whitespace) values.`,
+            entry: null,
+            manifest: null,
+        };
+    }
+    // 2. Shared validation: run the candidate through the reader's normalizer.
+    //    If it returns null the reader would drop this entry on read — reject now.
+    const candidate = {
+        agent_id: agentId,
+        worktree_path: worktreePath,
+        branch,
+        expected_base: base,
+    };
+    const entry = normalizeCleanupManifestEntry(candidate);
+    if (!entry) {
+        return {
+            ok: false,
+            reason: 'invalid_entry',
+            hint: `Entry failed cleanup-manifest validation: --path/--branch/--base must be non-empty and --branch must match ^worktree-agent-[A-Za-z0-9._/-]+$ (got branch="${branch}"). Fix the field and re-run.`,
+            entry: null,
+            manifest: null,
+        };
+    }
+    // 3. Parse the existing manifest. The init shell ({orchestrator_root, worktrees: []})
+    //    is written inline by the orchestrator before any agent spawns; a missing or
+    //    malformed manifest is a loud failure here, not a silent under-populated write.
+    let parsed;
+    try {
+        parsed = JSON.parse(manifestRaw);
+    }
+    catch {
+        return {
+            ok: false,
+            reason: 'invalid_manifest_json',
+            hint: 'Manifest is not valid JSON. The orchestrator must initialize it as {"orchestrator_root": "...", "worktrees": []} before recording agents.',
+            entry: null,
+            manifest: null,
+        };
+    }
+    // Accept the canonical {worktrees: []} shell or a bare top-level array (both
+    // are read by normalizeCleanupManifest); preserve any other top-level keys.
+    let worktrees;
+    let writeBack;
+    if (Array.isArray(parsed)) {
+        worktrees = parsed;
+        writeBack = worktrees;
+    }
+    else if (parsed && typeof parsed === 'object') {
+        const container = parsed;
+        if (container.worktrees === undefined)
+            container.worktrees = [];
+        if (!Array.isArray(container.worktrees)) {
+            return {
+                ok: false,
+                reason: 'manifest_shape_invalid',
+                hint: 'Manifest "worktrees" must be an array. Re-initialize as {"orchestrator_root": "...", "worktrees": []}.',
+                entry: null,
+                manifest: null,
+            };
+        }
+        worktrees = container.worktrees;
+        writeBack = container;
+    }
+    else {
+        return {
+            ok: false,
+            reason: 'manifest_shape_invalid',
+            hint: 'Manifest must be a JSON object {"worktrees": []} or a top-level array.',
+            entry: null,
+            manifest: null,
+        };
+    }
+    // 4. Reject a duplicate (worktree_path, branch). The reader dedups on this
+    //    exact key, but only over entries that NORMALIZE successfully — so an
+    //    existing malformed same-key entry (which the reader would drop) must NOT
+    //    block recording a valid one. Run each existing entry through the reader's
+    //    own normalizer and compare only the entries the reader would keep; this
+    //    matches its dedup behavior exactly. A real duplicate signals an upstream
+    //    double-spawn — surface it loudly instead of silently dropping it.
+    const dupKey = `${entry.worktree_path}\0${entry.branch}`;
+    const isDuplicate = worktrees.some((existing) => {
+        const normalized = normalizeCleanupManifestEntry(existing);
+        return normalized !== null && `${normalized.worktree_path}\0${normalized.branch}` === dupKey;
+    });
+    if (isDuplicate) {
+        return {
+            ok: false,
+            reason: 'duplicate_entry',
+            hint: `The manifest already records worktree_path="${entry.worktree_path}" branch="${entry.branch}". The cleanup reader dedups on (worktree_path, branch), so re-recording would be silently dropped — this usually signals an upstream double-spawn. Investigate rather than re-record.`,
+            entry: null,
+            manifest: null,
+        };
+    }
+    // 5. Append the minimal 4-field entry, matching the existing on-disk format.
+    const recorded = {
+        agent_id: entry.agent_id,
+        worktree_path: entry.worktree_path,
+        branch: entry.branch,
+        expected_base: entry.expected_base,
+    };
+    worktrees.push(recorded);
+    return {
+        ok: true,
+        reason: 'ok',
+        entry: recorded,
+        manifest: `${JSON.stringify(writeBack, null, 2)}\n`,
+    };
+}
+/**
+ * CLI command: append a validated per-agent entry to a wave cleanup manifest.
+ *
+ * Usage: worktree record-agent --manifest <path> --agent-id <id> --path <worktree> --branch <branch> --base <sha>
+ *
+ * Fails loudly (non-zero exit + recovery hint on stderr) when a field is
+ * missing/garbled or the manifest is absent/malformed, rather than appending an
+ * under-populated entry that the cleanup reader would silently drop.
+ */
+function cmdWorktreeRecordAgent(cwd, args = [], deps = {}) {
+    const flag = (name) => {
+        const i = args.indexOf(name);
+        return i >= 0 && i + 1 < args.length ? args[i + 1] : '';
+    };
+    const write = deps.write || ((s) => process.stdout.write(s));
+    const writeErr = deps.writeErr || ((s) => process.stderr.write(s));
+    const manifestPath = flag('--manifest');
+    if (!manifestPath) {
+        writeErr('Usage: worktree record-agent --manifest <path> --agent-id <id> --path <worktree> --branch <branch> --base <sha>\n');
+        process.exitCode = 2;
+        return { ok: false, reason: 'usage', entry: null };
+    }
+    const resolved = node_path_1.default.resolve(cwd, manifestPath);
+    const readFile = deps.readFile || ((p) => node_fs_1.default.readFileSync(p, 'utf8'));
+    let manifestRaw;
+    try {
+        manifestRaw = readFile(resolved);
+    }
+    catch (err) {
+        const hint = `Manifest not found or unreadable at ${manifestPath}. The orchestrator must initialize it ({"orchestrator_root": "...", "worktrees": []}) before recording agents.`;
+        writeErr(`[gsd] worktree.record-agent: manifest_read_failed — ${hint}\n`);
+        write(`${JSON.stringify({ ok: false, reason: 'manifest_read_failed', hint, error: err.message }, null, 2)}\n`);
+        process.exitCode = 1;
+        return { ok: false, reason: 'manifest_read_failed', hint, entry: null };
+    }
+    const plan = planWorktreeRecordAgent(manifestRaw, {
+        agentId: flag('--agent-id'),
+        worktreePath: flag('--path'),
+        branch: flag('--branch'),
+        base: flag('--base'),
+    });
+    if (!plan.ok || plan.manifest === null) {
+        writeErr(`[gsd] worktree.record-agent: ${plan.reason} — ${plan.hint || ''}\n`);
+        write(`${JSON.stringify({ ok: false, reason: plan.reason, hint: plan.hint }, null, 2)}\n`);
+        process.exitCode = 1;
+        return { ok: false, reason: plan.reason, hint: plan.hint, entry: null };
+    }
+    const writeFile = deps.writeFile || ((p, content) => node_fs_1.default.writeFileSync(p, content, 'utf8'));
+    writeFile(resolved, plan.manifest);
+    write(`${JSON.stringify({ ok: true, reason: 'ok', entry: plan.entry, manifest_path: resolved }, null, 2)}\n`);
+    return { ok: true, reason: 'ok', entry: plan.entry, manifest_path: resolved };
+}
 /**
  * Reap orphaned linked worktrees whose lock owner process is dead, whose
  * branch tip is fully merged into the default branch, and whose lock file
@@ -978,6 +1178,8 @@ module.exports = {
     planWorktreeWaveCleanup,
     executeWorktreeWaveCleanupPlan,
     cmdWorktreeCleanupWave,
+    planWorktreeRecordAgent,
+    cmdWorktreeRecordAgent,
     reapOrphanWorktrees,
     cmdWorktreeReapOrphans,
     resolveWorktreeRoot,

package/gsd-core/bin/shared/config-defaults.manifest.json

@@ -53,7 +53,8 @@
     "post_planning_gaps": true,
     "security_enforcement": true,
     "security_asvs_level": 1,
-    "security_block_on": "high"
+    "security_block_on": "high",
+    "context_guard_mode": "warn"
   },
   "planning": {
     "commit_docs": true,
@@ -93,5 +94,9 @@
   "plan_review": {
     "source_grounding": true,
     "source_grounding_authority": "grep"
+  },
+  "capabilities": {
+    "strict_known_registries": null,
+    "auto_update": false
   }
 }

package/gsd-core/bin/shared/config-schema.manifest.json

@@ -55,6 +55,8 @@
     "workflow.subagent_timeout",
     "workflow.test_command",
     "workflow.build_command",
+    "workflow.mvp_mode",
+    "workflow.context_guard_mode",
     "executor.stall_detect_interval_minutes",
     "executor.stall_threshold_minutes",
     "workflow.inline_plan_threshold",
@@ -91,7 +93,9 @@
     "model_policy.high",
     "model_policy.medium",
     "model_policy.low",
-    "agent_skills_security.trusted_global_roots"
+    "agent_skills_security.trusted_global_roots",
+    "capabilities.strict_known_registries",
+    "capabilities.auto_update"
   ],
   "runtimeStateKeys": [
     "workflow._auto_chain_active"