@opengsd/gsd-core 1.6.1 → 1.7.0-rc.2

package/gsd-core/bin/lib/install-profiles.cjs

@@ -14,6 +14,9 @@ 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 conversionModule = require("./runtime-artifact-conversion.cjs");
+const { applyAgentPathRewrites: _applyAgentPathRewrites, processAttribution: _processAttribution, normalizeAgentBodyForRuntime: _normalizeAgentBodyForRuntime, readGsdCommandNames: _readGsdCommandNames, } = conversionModule;
 // ---------------------------------------------------------------------------
 // Profile definitions
 // ---------------------------------------------------------------------------
@@ -521,19 +524,33 @@ function stageSkillsForRuntimeAsSkills(srcCommandsDir, resolvedProfile, converte
  * For tiered profiles, only agents whose full stem is in `resolvedProfile.agents`
  * are staged (mirrors `stageAgentsForProfile` behaviour).
  *
+ * ADR-1235 §1: when `agentCtx` is provided, the per-file order matches the inline
+ * agent loop in bin/install.js exactly:
+ *   1. applyAgentPathRewrites   (4 base ~/.claude/ regexes; skipped for copilot/antigravity)
+ *   2. processAttribution       (Co-Authored-By policy)
+ *   3. converter                (runtime-specific frontmatter/body transform)
+ *   4. normalizeAgentBodyForRuntime (colon→hyphen refs; no-op for trivial group)
+ * When `agentCtx` is absent, only the converter is applied (backward-compat for
+ * the feat-1173 synthetic-descriptor tests and the copilot/antigravity paths
+ * that handle cross-cutting inside their converters).
+ *
  * @param srcAgentsDir    source agents directory (e.g. agents/)
  * @param resolvedProfile profile filter from resolveProfile()
  * @param converter       (content: string, isGlobal?: boolean) → string per-file
  *                        converter; scope-aware converters (copilot/antigravity)
  *                        read isGlobal, single-arg converters ignore it (#1173)
  * @param isGlobal        install scope passed through to the converter
+ * @param agentCtx        optional cross-cutting context (ADR-1235 §1); when absent,
+ *                        only the converter is applied (backward compat)
  */
-function stageAgentsForRuntimeWithConverter(srcAgentsDir, resolvedProfile, converter, isGlobal = false) {
+function stageAgentsForRuntimeWithConverter(srcAgentsDir, resolvedProfile, converter, isGlobal = false, agentCtx) {
     if (!node_fs_1.default.existsSync(srcAgentsDir))
         return srcAgentsDir;
     const stageDir = node_fs_1.default.mkdtempSync(node_path_1.default.join(node_os_1.default.tmpdir(), 'gsd-profile-runtime-agents-'));
     try {
         const entries = node_fs_1.default.readdirSync(srcAgentsDir, { withFileTypes: true });
+        // Resolve cmdNames once per staging call (not per file) for performance.
+        const cmdNames = agentCtx ? _readGsdCommandNames() : [];
         for (const entry of entries) {
             if (!entry.isFile())
                 continue;
@@ -546,9 +563,23 @@ function stageAgentsForRuntimeWithConverter(srcAgentsDir, resolvedProfile, conve
                     continue;
                 }
             }
-            const content = node_fs_1.default.readFileSync(node_path_1.default.join(srcAgentsDir, entry.name), 'utf8');
-            const converted = converter(content, isGlobal);
-            node_fs_1.default.writeFileSync(node_path_1.default.join(stageDir, entry.name), converted, 'utf8');
+            let content = node_fs_1.default.readFileSync(node_path_1.default.join(srcAgentsDir, entry.name), 'utf8');
+            if (agentCtx) {
+                // ADR-1235 §1: pre-converter cross-cutting (matches inline loop order exactly)
+                // Step 1: path rewrites (4 base ~/.claude/ regexes; skipped for copilot/antigravity)
+                content = _applyAgentPathRewrites(content, agentCtx.runtime, agentCtx.pathPrefix);
+                // Step 2: attribution
+                content = _processAttribution(content, agentCtx.attribution);
+                // Step 3: converter (runtime-specific frontmatter/body transform)
+                content = converter(content, isGlobal);
+                // Step 4: normalize colon→hyphen refs (no-op for trivial group)
+                content = _normalizeAgentBodyForRuntime(content, agentCtx.runtime, cmdNames);
+            }
+            else {
+                // Backward-compat: only apply the converter (no cross-cutting)
+                content = converter(content, isGlobal);
+            }
+            node_fs_1.default.writeFileSync(node_path_1.default.join(stageDir, entry.name), content, 'utf8');
         }
     }
     catch (err) {

package/gsd-core/bin/lib/installer-migrations.cjs

@@ -88,7 +88,7 @@ function atomicWriteInstallState(configDir, content) {
     const tmpPath = `${filePath}.tmp-${process.pid}-${Date.now()}`;
     try {
         node_fs_1.default.writeFileSync(tmpPath, content, 'utf8');
-        node_fs_1.default.renameSync(tmpPath, filePath);
+        (0, shell_command_projection_cjs_1.retryRenameSync)(tmpPath, filePath);
     }
     catch (error) {
         try {

package/gsd-core/bin/lib/mcp-server.cjs

@@ -0,0 +1,194 @@
+/**
+ * Companion MCP server (ADR-1239 Phase C-2, #1681 slice 3a).
+ *
+ * A minimal stdio JSON-RPC 2.0 server exposing two of the six interface points
+ * so any MCP-consuming host (Claude/Codex/OpenCode/VS Code/Gemini/Cursor/Cline/
+ * Hermes) can drive GSD with NO bespoke plugin:
+ *
+ *   - point 1 (command): tool `gsd_invoke_command` → the command-routing hub
+ *     (`createHub`/`dispatch`, src/command-routing-hub.cts).
+ *   - point 5 (state IO): tools `gsd_read_state` / `gsd_write_state` → the
+ *     Phase 3 `stateIO` seam (src/state-io.cts, filesystem default).
+ *
+ * No new runtime dependency — the JSON-RPC stdio loop is hand-rolled (the repo
+ * ships only claude-agent-sdk + ws; adding an MCP SDK is a separate packaging
+ * decision). The protocol logic (`handleMessage`) is PURE and fully testable;
+ * `runServer` is a thin line-delimited-JSON loop over injectable streams.
+ *
+ * Bin entry / packaging / manifest-version-sync is slice 3b — this module is
+ * the additive, importable server surface a host (or the bin shim) drives.
+ */
+'use strict';
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SERVER_NAME = exports.PROTOCOL_VERSION = void 0;
+exports.handleMessage = handleMessage;
+exports.runServer = runServer;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const commandRoutingHub = require("./command-routing-hub.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const stateIo = require("./state-io.cjs");
+exports.PROTOCOL_VERSION = '2024-11-05';
+exports.SERVER_NAME = 'gsd-core';
+const SERVER_VERSION = '1.7.0';
+// JSON-RPC 2.0 error codes.
+const PARSE_ERROR = -32700;
+const INVALID_REQUEST = -32600;
+const METHOD_NOT_FOUND = -32601;
+const INVALID_PARAMS = -32602;
+const INTERNAL_ERROR = -32603;
+const TOOLS = [
+    {
+        name: 'gsd_invoke_command',
+        description: 'Invoke a GSD command via the command-routing hub (interface point 1).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                family: { type: 'string', description: 'Command family (e.g. "query", "state", "phase").' },
+                subcommand: { type: 'string', description: 'Subcommand name.' },
+                args: { type: 'array', items: {}, description: 'Positional args.' },
+            },
+            required: ['family', 'subcommand'],
+        },
+    },
+    {
+        name: 'gsd_read_state',
+        description: 'Read a .planning state file (interface point 5).',
+        inputSchema: {
+            type: 'object',
+            properties: { path: { type: 'string', description: 'Absolute path under .planning/.' } },
+            required: ['path'],
+        },
+    },
+    {
+        name: 'gsd_write_state',
+        description: 'Write a .planning state file (interface point 5).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: 'Absolute path under .planning/.' },
+                content: { type: 'string', description: 'File content.' },
+            },
+            required: ['path', 'content'],
+        },
+    },
+];
+function errorResponse(id, code, message, data) {
+    const err = { code, message };
+    if (data !== undefined)
+        err.data = data;
+    return { jsonrpc: '2.0', id, error: err };
+}
+function okResponse(id, result) {
+    return { jsonrpc: '2.0', id, result };
+}
+function asString(v) {
+    return typeof v === 'string' ? v : null;
+}
+function callTool(name, args, ctx) {
+    const a = (args && typeof args === 'object' ? args : {});
+    const cwd = asString(ctx.cwd) || process.cwd();
+    try {
+        if (name === 'gsd_invoke_command') {
+            const family = asString(a.family);
+            const subcommand = asString(a.subcommand);
+            if (!family || !subcommand) {
+                return { isError: true, content: [{ type: 'text', text: 'gsd_invoke_command requires string "family" and "subcommand".' }] };
+            }
+            const hub = commandRoutingHub.createHub();
+            const res = hub.dispatch({ family, subcommand, args: Array.isArray(a.args) ? a.args : [], cwd, raw: undefined });
+            return { content: [{ type: 'text', text: JSON.stringify(res) }] };
+        }
+        if (name === 'gsd_read_state') {
+            const p = asString(a.path);
+            if (!p)
+                return { isError: true, content: [{ type: 'text', text: 'gsd_read_state requires string "path".' }] };
+            const io = stateIo.createStateIO({ io: 'filesystem' });
+            return { content: [{ type: 'text', text: io.read(p) }] };
+        }
+        if (name === 'gsd_write_state') {
+            const p = asString(a.path);
+            const content = asString(a.content);
+            if (!p || content === null)
+                return { isError: true, content: [{ type: 'text', text: 'gsd_write_state requires string "path" and "content".' }] };
+            const io = stateIo.createStateIO({ io: 'filesystem' });
+            io.write(p, content);
+            return { content: [{ type: 'text', text: JSON.stringify({ ok: true, path: p }) }] };
+        }
+        return { isError: true, content: [{ type: 'text', text: `Unknown tool: ${name}` }] };
+    }
+    catch (e) {
+        return { isError: true, content: [{ type: 'text', text: `Tool error: ${e instanceof Error ? e.message : String(e)}` }] };
+    }
+}
+/**
+ * Pure JSON-RPC handler. Takes a parsed request object + context, returns a
+ * JSON-RPC response object (or null for JSON-RPC notifications — no id).
+ */
+function handleMessage(request, ctx = {}) {
+    if (!request || typeof request !== 'object') {
+        return errorResponse(null, INVALID_REQUEST, 'Invalid Request: not an object.');
+    }
+    const id = request.id;
+    // Notification (no id) → no response per JSON-RPC.
+    const isNotification = id === undefined || id === null;
+    const method = typeof request.method === 'string' ? request.method : '';
+    let result;
+    switch (method) {
+        case 'initialize':
+            result = {
+                protocolVersion: exports.PROTOCOL_VERSION,
+                capabilities: { tools: {} },
+                serverInfo: { name: exports.SERVER_NAME, version: SERVER_VERSION },
+            };
+            break;
+        case 'tools/list':
+            result = { tools: TOOLS };
+            break;
+        case 'tools/call': {
+            const params = (request.params && typeof request.params === 'object' ? request.params : {});
+            const toolName = asString(params.name);
+            if (!toolName)
+                return errorResponse(id, INVALID_PARAMS, 'tools/call requires string "name".');
+            result = callTool(toolName, params.arguments, ctx);
+            break;
+        }
+        default:
+            if (isNotification)
+                return null;
+            return errorResponse(id, METHOD_NOT_FOUND, `Method not found: ${method || '(empty)'}.`);
+    }
+    if (isNotification)
+        return null;
+    return okResponse(id, result);
+}
+/**
+ * Thin stdio loop over injectable streams. Reads line-delimited JSON-RPC from
+ * `input`, writes responses (one JSON object + newline) to `output`. Stops when
+ * input ends. Errors in handleMessage are caught and emitted as JSON-RPC error
+ * responses (the loop never crashes).
+ */
+async function runServer({ input, output, ctx = {}, }) {
+    for await (const chunk of input) {
+        const lines = chunk.toString('utf-8').split(/\r?\n/);
+        for (const line of lines) {
+            if (!line.trim())
+                continue;
+            let parsed;
+            try {
+                parsed = JSON.parse(line);
+            }
+            catch {
+                output.write(JSON.stringify(errorResponse(null, PARSE_ERROR, 'Parse error.')) + '\n');
+                continue;
+            }
+            try {
+                const response = handleMessage(parsed, ctx);
+                if (response)
+                    output.write(JSON.stringify(response) + '\n');
+            }
+            catch (e) {
+                output.write(JSON.stringify(errorResponse(null, INTERNAL_ERROR, e instanceof Error ? e.message : 'Internal error.')) + '\n');
+            }
+        }
+    }
+}

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

@@ -19,6 +19,8 @@ const frontmatterMod = require("./frontmatter.cjs");
 const stateMod = require("./state.cjs");
 const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
 const runtime_slash_cjs_1 = require("./runtime-slash.cjs");
+const clock_cjs_1 = require("./clock.cjs");
+const state_transition_cjs_1 = require("./state-transition.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const ioMod = require("./io.cjs");
 const { output, error } = ioMod;
@@ -27,13 +29,13 @@ const phaseIdMod = require("./phase-id.cjs");
 const { escapeRegex, normalizePhaseName, phaseTokenMatches } = phaseIdMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const roadmapParserMod = require("./roadmap-parser.cjs");
-const { getMilestonePhaseFilter, extractCurrentMilestone } = roadmapParserMod;
+const { getMilestonePhaseFilter, extractCurrentMilestone, getMilestoneInfo } = roadmapParserMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const coreUtilsMod = require("./core-utils.cjs");
 const { extractOneLinerFromBody } = coreUtilsMod;
 const { planningPaths } = planningWorkspace;
 const { extractFrontmatter } = frontmatterMod;
-const { writeStateMd, stateReplaceFieldWithFallback } = stateMod;
+const { writeStateMd } = stateMod;
 function cmdRequirementsMarkComplete(cwd, reqIdsRaw, raw) {
     if (!reqIdsRaw || reqIdsRaw.length === 0) {
         error('requirement IDs required. Usage: requirements mark-complete REQ-01,REQ-02 or REQ-01 REQ-02');
@@ -110,8 +112,13 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
     const roadmapPath = planningPaths(cwd).roadmap;
     const reqPath = planningPaths(cwd).requirements;
     const statePath = planningPaths(cwd).state;
-    const milestonesPath = node_path_1.default.join(cwd, '.planning', 'MILESTONES.md');
-    const archiveDir = node_path_1.default.join(cwd, '.planning', 'milestones');
+    // #1911: derive the archive base from the workstream-aware planning root so
+    // `milestone complete --ws` archives into the workstream, not root. planningPaths(cwd).planning
+    // resolves to the workstream base when GSD_WORKSTREAM is set and to root .planning otherwise
+    // (flat mode is a no-op).
+    const planningBase = planningPaths(cwd).planning;
+    const milestonesPath = node_path_1.default.join(planningBase, 'MILESTONES.md');
+    const archiveDir = node_path_1.default.join(planningBase, 'milestones');
     const phasesDir = planningPaths(cwd).phases;
     const today = new Date().toISOString().split('T')[0];
     const milestoneName = options.name || version;
@@ -149,7 +156,8 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
             if (stateVersion && stateVersion === version) {
                 const roadmapContent = node_fs_1.default.readFileSync(roadmapPath, 'utf-8');
                 const scopedContent = extractCurrentMilestone(roadmapContent, cwd);
-                const phasePattern = /#{2,4}\s*Phase\s+(\d+[A-Z]?(?:\.\d+)*)\s*:\s*([^\n]+)/gi;
+                // #1729: `(?:\s*\([^)\n]*\))?` tolerates a pre-colon ( ) tag (literal mirror of OPTIONAL_PHASE_TAG_SOURCE).
+                const phasePattern = /#{2,4}\s*Phase\s+(\d+[A-Z]?(?:\.\d+)*)(?:\s*\([^)\n]*\))?\s*:\s*([^\n]+)/gi;
                 const noDirectoryPhases = [];
                 let pm;
                 const phaseDirEntries = (() => {
@@ -259,9 +267,9 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
         (0, shell_command_projection_cjs_1.platformWriteSync)(node_path_1.default.join(archiveDir, `${version}-REQUIREMENTS.md`), archiveHeader + reqContent);
     }
     // Archive audit file if exists
-    const auditFile = node_path_1.default.join(cwd, '.planning', `${version}-MILESTONE-AUDIT.md`);
+    const auditFile = node_path_1.default.join(planningBase, `${version}-MILESTONE-AUDIT.md`);
     if (node_fs_1.default.existsSync(auditFile)) {
-        node_fs_1.default.renameSync(auditFile, node_path_1.default.join(archiveDir, `${version}-MILESTONE-AUDIT.md`));
+        (0, shell_command_projection_cjs_1.retryRenameSync)(auditFile, node_path_1.default.join(archiveDir, `${version}-MILESTONE-AUDIT.md`));
     }
     // Create/append MILESTONES.md entry
     const accomplishmentsList = accomplishments.map((a) => `- ${a}`).join('\n');
@@ -289,38 +297,26 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
     else {
         (0, shell_command_projection_cjs_1.platformWriteSync)(milestonesPath, `# Milestones\n\n${milestoneEntry}`);
     }
-    // Update STATE.md — keep frontmatter/body semantically aligned after closure
+    // Update STATE.md — keep frontmatter/body semantically aligned after closure.
+    // ADR-1769 Phase 5: dispatches to the STATE.md Transition Module. The closure
+    // write (Status, Last Activity, Last Activity Description, Current Position
+    // reset, Operator Next Steps reset) is the pure `milestoneCompleteCore` in
+    // src/state-transition.cts, backed by the field-classification table. The
+    // runtime-specific next-milestone slash command is resolved here and injected
+    // via the intent so the core stays pure. writeStateMd still owns the lock and
+    // the steady-state syncStateFrontmatter post-sync.
     if (node_fs_1.default.existsSync(statePath)) {
-        let stateContent = node_fs_1.default.readFileSync(statePath, 'utf-8');
-        stateContent = stateReplaceFieldWithFallback(stateContent, 'Status', null, `${version} milestone complete`);
-        stateContent = stateReplaceFieldWithFallback(stateContent, 'Last Activity', 'Last activity', today);
-        stateContent = stateReplaceFieldWithFallback(stateContent, 'Last Activity Description', null, `${version} milestone completed and archived`);
-        // Reset Current Position narrative so resume/progress flows do not keep
-        // pointing at closed-phase execution instructions.
-        const positionPattern = /(##\s*Current Position\s*\n)([\s\S]*?)(?=\n##|$)/i; // allow-adhoc-markdown: pre-seam section write-modify in milestone.cts; pending collectSection migration #1372
-        const closedPositionBody = `\nPhase: Milestone ${version} complete\n` +
-            `Plan: —\n` +
-            `Status: Awaiting next milestone\n` +
-            `Last activity: ${today} — Milestone ${version} completed and archived\n\n`;
-        if (positionPattern.test(stateContent)) {
-            stateContent = stateContent.replace(positionPattern, (_m, header) => `${header}${closedPositionBody}`);
-        }
-        else {
-            stateContent = `${stateContent.trimEnd()}\n\n## Current Position\n${closedPositionBody}`;
-        }
-        // Normalize operator-next-step tails that can become stale after close.
-        const operatorPattern = /(##\s*Operator Next Steps\s*\n)([\s\S]*?)(?=\n##|$)/i; // allow-adhoc-markdown: pre-seam section write-modify in milestone.cts; pending collectSection migration #1372
-        if (operatorPattern.test(stateContent)) {
-            stateContent = stateContent.replace(operatorPattern, `$1\n- Start the next milestone with ${(0, runtime_slash_cjs_1.formatGsdSlash)('new-milestone', (0, runtime_slash_cjs_1.resolveRuntime)(cwd))}\n\n`);
-        }
-        else {
-            stateContent = `${stateContent.trimEnd()}\n\n## Operator Next Steps\n\n- Start the next milestone with ${(0, runtime_slash_cjs_1.formatGsdSlash)('new-milestone', (0, runtime_slash_cjs_1.resolveRuntime)(cwd))}\n`;
-        }
-        writeStateMd(statePath, stateContent, cwd);
+        const result = (0, state_transition_cjs_1.transitionCore)(node_fs_1.default.readFileSync(statePath, 'utf-8'), {
+            kind: 'milestoneComplete',
+            version,
+            nextMilestoneCommand: (0, runtime_slash_cjs_1.formatGsdSlash)('new-milestone', (0, runtime_slash_cjs_1.resolveRuntime)(cwd)),
+        }, { clock: clock_cjs_1.realClock, progressProvider: () => null });
+        writeStateMd(statePath, result.content, cwd);
     }
     // Archive phase directories if requested
     let phasesArchived = false;
-    if (options.archivePhases) {
+    // #1871: archive phase dirs by default on milestone complete (opt out via --no-archive-phases).
+    if (options.archivePhases !== false) {
         try {
             const phaseArchiveDir = node_path_1.default.join(archiveDir, `${version}-phases`);
             (0, shell_command_projection_cjs_1.platformEnsureDir)(phaseArchiveDir);
@@ -330,7 +326,7 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
             for (const dir of phaseDirNames) {
                 if (!isDirInMilestone(dir))
                     continue;
-                node_fs_1.default.renameSync(node_path_1.default.join(phasesDir, dir), node_path_1.default.join(phaseArchiveDir, dir));
+                (0, shell_command_projection_cjs_1.retryRenameSync)(node_path_1.default.join(phasesDir, dir), node_path_1.default.join(phaseArchiveDir, dir));
                 archivedCount++;
             }
             phasesArchived = archivedCount > 0;
@@ -409,10 +405,8 @@ function cmdPhasesClear(cwd, raw, args) {
             }
         }
         try {
-            for (const entry of dirs) {
-                node_fs_1.default.rmSync(node_path_1.default.join(phasesDir, entry.name), { recursive: true, force: true });
-                cleared++;
-            }
+            // #1871: archive phase directories instead of destroying them (shared helper).
+            cleared = archivePhaseDirectories(cwd, phasesDir, dirs).archived;
         }
         catch (e) {
             const message = e instanceof Error ? e.message : String(e);
@@ -421,6 +415,40 @@ function cmdPhasesClear(cwd, raw, args) {
     }
     output({ cleared }, raw, `${cleared} phase director${cleared === 1 ? 'y' : 'ies'} cleared`);
 }
+/**
+ * #1871: move each non-999 phase directory under `phasesDir` into
+ * `milestones/<version>-phases/` (collision-safe; version from getMilestoneInfo,
+ * timestamp fallback). Shared by `phases clear` (archive-then-remove) and the
+ * internal milestone.complete phase archival so phase history survives a
+ * milestone switch instead of being hard-deleted.
+ */
+function archivePhaseDirectories(cwd, phasesDir, dirs) {
+    let archiveVersion = null;
+    try {
+        archiveVersion = getMilestoneInfo(cwd).version ?? null;
+    }
+    catch {
+        /* ROADMAP/STATE unreadable — fall back to a dated label */
+    }
+    if (!archiveVersion) {
+        archiveVersion = `archived-${new Date().toISOString().replace(/[-:T]/g, '').slice(0, 8)}`;
+    }
+    const archivePhasesDir = node_path_1.default.join(planningPaths(cwd).planning, 'milestones', `${archiveVersion}-phases`);
+    (0, shell_command_projection_cjs_1.platformEnsureDir)(archivePhasesDir);
+    let archived = 0;
+    for (const entry of dirs) {
+        const src = node_path_1.default.join(phasesDir, entry.name);
+        // Collision-safe: if a same-named archive entry exists (re-run), suffix it.
+        let dest = node_path_1.default.join(archivePhasesDir, entry.name);
+        let n = 1;
+        while (node_fs_1.default.existsSync(dest)) {
+            dest = node_path_1.default.join(archivePhasesDir, `${entry.name}.${n++}`);
+        }
+        (0, shell_command_projection_cjs_1.retryRenameSync)(src, dest);
+        archived++;
+    }
+    return { archiveDir: archivePhasesDir, archived };
+}
 module.exports = {
     cmdRequirementsMarkComplete,
     cmdMilestoneComplete,

package/gsd-core/bin/lib/model-adapter.cjs

@@ -0,0 +1,50 @@
+/**
+ * Model adapter seam (ADR-1239 Phase C-1, AC3 / #1680).
+ *
+ * Two model-layer adapters selected by the negotiated `modelMode` axis
+ * (host-integration.cts):
+ *
+ *   - `passive` — GSD can only inject prompts / a per-agent `model` field (the
+ *     CLI runtimes: claude/gemini/codex/opencode/cursor/…). Formalizes today's
+ *     tier routing from src/model-resolver.cts: `resolveModel` delegates
+ *     straight to `resolveModelForTier`, so passive reproduces current behavior
+ *     byte-for-behavior.
+ *   - `active` — the host exposes a provider `sendRequest` (VS Code `vscode.lm`,
+ *     pi providers). GSD calls the model through the host. Ships here as a SEAM:
+ *     a host-supplied `sendRequest` slot, fail-closed until a real consumer
+ *     binds it (Phase 5 / #1682).
+ *
+ * Minimal (per ADR-1239 open wire-shape question): one factory, two shapes
+ * discriminated by `mode`. Concrete provider protocol (request/response shape)
+ * is fixed when a real active host lands in Phase 5.
+ */
+'use strict';
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createModelAdapter = createModelAdapter;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const modelResolver = require("./model-resolver.cjs");
+function createModelAdapter({ modelMode }, options = {}) {
+    if (modelMode !== 'passive' && modelMode !== 'active') {
+        throw new TypeError(`createModelAdapter: modelMode must be 'passive' | 'active' (got ${JSON.stringify(modelMode)})`);
+    }
+    if (modelMode === 'passive') {
+        return Object.freeze({
+            mode: 'passive',
+            resolveModel({ cwd, agentType, attempt }) {
+                return modelResolver.resolveModelForTier(cwd, agentType, attempt);
+            },
+        });
+    }
+    // active: bind the host's sendRequest, fail-closed if absent.
+    const sendRequest = options.sendRequest;
+    return Object.freeze({
+        mode: 'active',
+        sendRequest(req) {
+            if (typeof sendRequest !== 'function') {
+                throw new Error('ActiveModelAdapter.sendRequest: no host provider bound — the active model seam ' +
+                    'requires a sendRequest primitive from the host (Phase 5 wires a concrete provider).');
+            }
+            return sendRequest(req);
+        },
+    });
+}

package/gsd-core/bin/lib/phase-id.cjs

@@ -20,6 +20,23 @@ const PROJECT_CODE_PREFIX_STRIP_RE = /^[A-Z][A-Z0-9_]*-(?=\d)/;
 const PROJECT_CODE_PREFIX_STRIP_RE_I = /^[A-Z][A-Z0-9_]*-(?=\d)/i;
 const PROJECT_CODE_PREFIX_CAPTURE_RE_I = /^([A-Z][A-Z0-9_]*)-(\d.*)/i;
 const OPTIONAL_PROJECT_CODE_PREFIX_SOURCE = '(?:[A-Z][A-Z0-9_]*-)?';
+// #1729: phase headers may carry a parenthetical tag between the number and the
+// colon, e.g. `### Phase 26 (Cluster B): Title`. This optional, non-capturing
+// fragment is injected at every phase-header regex call site (immediately after
+// the phase-number token, before the colon/space delimiter) so the resolver
+// tolerates the tag — mirroring how `[...]` is already tolerated before `Phase`.
+// `[^)\n]*` keeps the match single-line (headers are one line) to avoid
+// over-consuming across a malformed multi-line document. Injected at the call
+// site (not baked into phaseMarkdownRegexSource) so it applies uniformly to
+// both the numeric and project-code-exact escaped sources, and so the decimal
+// sub-phase patterns can place it after the `.N` segment.
+//
+// Enumeration/parse call sites that read phase headers from a regex *literal*
+// (rather than a `new RegExp` built from an interpolated phase number) cannot
+// reference this constant; they inline its literal-regex mirror instead —
+// `(?:\s*\([^)\n]*\))?` — kept character-for-character equivalent to this
+// source. Both forms must change together; see the #1729 regression test.
+const OPTIONAL_PHASE_TAG_SOURCE = '(?:\\s*\\([^)\\n]*\\))?';
 function stripProjectCodePrefix(value, caseInsensitive = true) {
     const input = String(value);
     const re = caseInsensitive ? PROJECT_CODE_PREFIX_STRIP_RE_I : PROJECT_CODE_PREFIX_STRIP_RE;
@@ -215,6 +232,7 @@ function phaseTokenMatches(dirName, normalized) {
 module.exports = {
     escapeRegex,
     OPTIONAL_PROJECT_CODE_PREFIX_SOURCE,
+    OPTIONAL_PHASE_TAG_SOURCE,
     stripProjectCodePrefix,
     normalizePhaseName,
     getMilestoneFromPhaseId,