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

package/gsd-core/bin/lib/handshake-serialized.cjs

@@ -0,0 +1,70 @@
+/**
+ * Serialized (out-of-process) capability-exchange handshake (ADR-1239 Phase E / #1683).
+ *
+ * Phase 1's `negotiateHostCapabilities` is IN-PROCESS (a host descriptor merged
+ * directly into the engine). Out-of-process SDK hosts (pi, VS Code) cannot share
+ * object references with the engine — they exchange a SERIALIZED capability set
+ * over a wire boundary (an MCP-style `initialize`). This module is the wire form
+ * of that handshake, kept CONSISTENT with the in-process negotiation: a request
+ * built + serialized here MUST yield the same NegotiationResult the in-process
+ * call produces for the same axes (asserted in tests/handshake-serialized.test.cjs).
+ *
+ * Wire shape (JSON — no object refs, safe across a process/IPC boundary):
+ *
+ *   request  = { protocolVersion: number, axes: Partial<HostIntegrationAxes> }
+ *   response = NegotiationResult = { protocolVersion, effective, points, warnings }
+ *
+ * The engine side delegates to negotiateHostCapabilities; the host side builds
+ * the request from a descriptor. Both round-trip through JSON so the exchange is
+ * strictly serializable (a non-JSON-safe value would break the wire contract).
+ *
+ * Pure + additive: no I/O, no global state. The companion MCP server (Phase 4)
+ * or an SDK host binds this to a real transport.
+ */
+'use strict';
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const hostIntegration = require("./host-integration.cjs");
+/** The wire method name for the initialize-style exchange. */
+const HANDSHAKE_METHOD = 'gsd/host-initialize';
+/**
+ * Host side: build a JSON-serializable handshake request from a host descriptor.
+ * Accepts either `{ protocolVersion?, axes }` or a bare axes object.
+ * Defaults protocolVersion to the engine's current PROTOCOL_VERSION.
+ */
+function buildHandshakeRequest(hostDescriptor) {
+    if (!hostDescriptor || typeof hostDescriptor !== 'object') {
+        throw new TypeError('buildHandshakeRequest: host descriptor (object) is required');
+    }
+    const desc = hostDescriptor;
+    const hasAxes = Object.prototype.hasOwnProperty.call(desc, 'axes');
+    const axes = (hasAxes ? desc.axes : desc);
+    if (!axes || typeof axes !== 'object') {
+        throw new TypeError('buildHandshakeRequest: descriptor.axes (object) is required');
+    }
+    const protocolVersion = typeof desc.protocolVersion === 'number' && Number.isFinite(desc.protocolVersion)
+        ? desc.protocolVersion
+        : hostIntegration.PROTOCOL_VERSION;
+    // Force a wire round-trip so a non-JSON-safe descriptor fails HERE, not later.
+    return JSON.parse(JSON.stringify({ protocolVersion, axes }));
+}
+/**
+ * Engine side: handle a serialized handshake request → a JSON-serializable
+ * NegotiationResult. Delegates to negotiateHostCapabilities, so the result is
+ * identical to the in-process negotiation for the same axes.
+ */
+function handleHandshakeRequest(request, engine = hostIntegration.DEFAULT_ENGINE) {
+    if (!request || typeof request !== 'object') {
+        throw new TypeError('handleHandshakeRequest: request (object) is required');
+    }
+    const req = request;
+    const axes = (req.axes && typeof req.axes === 'object' ? req.axes : {});
+    const protocolVersion = req.protocolVersion;
+    const result = hostIntegration.negotiateHostCapabilities({ ...axes, ...(typeof protocolVersion === 'number' && Number.isFinite(protocolVersion) ? { protocolVersion } : {}) }, engine);
+    // Force a wire round-trip: the response must be strictly JSON-serializable.
+    return JSON.parse(JSON.stringify(result));
+}
+module.exports = {
+    HANDSHAKE_METHOD,
+    buildHandshakeRequest,
+    handleHandshakeRequest,
+};

package/gsd-core/bin/lib/host-integration-sdk.cjs

@@ -0,0 +1,53 @@
+/**
+ * Host-Integration SDK — the published public surface (ADR-1239 Phase E / #1683).
+ *
+ * External host-plugin authors import ONLY from this entry. It IS the contract:
+ * everything it re-exports is public + versioned (PROTOCOL_VERSION governs the
+ * set); everything else in gsd-core is internal. An SDK smoke test
+ * (tests/sdk-smoke.test.cjs) builds a new host-plugin against this surface only
+ * — proving an external author can wire a host without reading gsd-core internals.
+ *
+ * Surface: the negotiated schema + classification, the five adapters
+ * (declarative/imperative/model/hook/state), and the serialized handshake.
+ * Frozen so the public shape cannot be mutated by consumers.
+ */
+'use strict';
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const hostIntegration = require("./host-integration.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const adapterDeclarative = require("./adapter-declarative.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const adapterImperative = require("./adapter-imperative.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const modelAdapter = require("./model-adapter.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const hookBus = require("./hook-bus.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const stateIo = require("./state-io.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const handshake = require("./handshake-serialized.cjs");
+const SDK = Object.freeze({
+    // ── Schema + protocol version ────────────────────────────────────────────
+    PROTOCOL_VERSION: hostIntegration.PROTOCOL_VERSION,
+    HOST_INTEGRATION_AXES: hostIntegration.HOST_INTEGRATION_AXES,
+    INTERFACE_POINTS: hostIntegration.INTERFACE_POINTS,
+    PROFILE_BASELINES: hostIntegration.PROFILE_BASELINES,
+    // ── Negotiation + classification ─────────────────────────────────────────
+    negotiateHostCapabilities: hostIntegration.negotiateHostCapabilities,
+    profileOf: hostIntegration.profileOf,
+    degradationFor: hostIntegration.degradationFor,
+    hookEventSurfaceFor: hostIntegration.hookEventSurfaceFor,
+    extensionEventSurfaceFor: hostIntegration.extensionEventSurfaceFor,
+    shouldFlattenDispatch: hostIntegration.shouldFlattenDispatch,
+    // ── Embedding + engine adapters ──────────────────────────────────────────
+    createDeclarativeAdapter: adapterDeclarative.createDeclarativeAdapter,
+    createImperativeAdapter: adapterImperative.createImperativeAdapter,
+    createModelAdapter: modelAdapter.createModelAdapter,
+    createHookBus: hookBus.createHookBus,
+    createStateIO: stateIo.createStateIO,
+    // ── Serialized handshake (out-of-process SDK hosts: pi / VS Code) ─────────
+    HANDSHAKE_METHOD: handshake.HANDSHAKE_METHOD,
+    buildHandshakeRequest: handshake.buildHandshakeRequest,
+    handleHandshakeRequest: handshake.handleHandshakeRequest,
+});
+module.exports = SDK;

package/gsd-core/bin/lib/host-integration.cjs

@@ -394,6 +394,63 @@ function shouldFlattenDispatch(dispatch) {
     const canBackground = dispatch.background === true && dispatch.backgroundDispatch === true;
     return !canBackground;
 }
+// ---------------------------------------------------------------------------
+// Managed-hook event surface per hookEvents dialect (ADR-1239 / ADR-1016)
+// ---------------------------------------------------------------------------
+// Host-fireable MANAGED-hook events per `hookEvents` dialect. `hookEvents` is the
+// managed-hook dialect — the event names GSD writes into a DECLARATIVE host's
+// settings.json (claude = SessionStart/PreToolUse/…; gemini = BeforeTool/AfterTool).
+// This is DISTINCT from the extension-system event surface (below): a host's
+// plugin/extension API fires a different, plugin-owned event set. The two must
+// not be conflated (ADR-1239 amendment / #1943 — the former 'opencode-subset'
+// `hookEvents` value was this conflation; it is now `extensionEvents: opencode`).
+const HOOK_EVENT_SURFACES = Object.freeze({
+    claude: Object.freeze(['SessionStart', 'PreToolUse', 'PostToolUse', 'Stop', 'SessionEnd', 'PreCompact']),
+    gemini: Object.freeze(['SessionStart', 'BeforeTool', 'AfterTool', 'SessionEnd']),
+});
+/**
+ * Resolve the managed-hook event surface for a `hookEvents` dialect.
+ * Returns null for unknown/missing dialects (fail-closed). Pure, never throws.
+ */
+function hookEventSurfaceFor(hookEvents) {
+    if (typeof hookEvents !== 'string')
+        return null;
+    return HOOK_EVENT_SURFACES[hookEvents] || null;
+}
+// ---------------------------------------------------------------------------
+// Extension-system event surface (ADR-1239 amendment / #1943)
+// ---------------------------------------------------------------------------
+// The events a host's PLUGIN/EXTENSION API exposes — for imperative-embedding
+// hosts that load GSD as a plugin. This is a SEPARATE vocabulary + descriptor
+// field (`extensionEvents`) from `hookEvents`: hookEvents = the managed-hook
+// dialect (declarative hosts' settings.json); extensionEvents = the plugin-owned
+// event subset (imperative hosts' extension API). They are not the same thing.
+//
+// Values are documentation-sourced (ADR-1239 §research): OpenCode ~25 plugin
+// events (session/tool/file/permission); pi ~30 fine-grained extension events;
+// 'none' = the host exposes no extension surface and the engine owns the bus
+// (VS Code). Declarative hosts (no plugin API) do not set `extensionEvents`.
+const EXTENSION_EVENT_SURFACES = Object.freeze({
+    opencode: Object.freeze([
+        'session.created', 'session.idle', 'experimental.session.compacting',
+        'tool.execute.before', 'tool.execute.after', 'file.edited',
+    ]),
+    pi: Object.freeze(['tool_call']),
+    none: Object.freeze([]),
+});
+/**
+ * Resolve the extension-system event surface for an `extensionEvents` dialect.
+ * Returns null for unknown/missing dialects (fail-closed). Pure, never throws.
+ *
+ * A non-null result is what makes an `extensionEvents` value a CONSUMED value
+ * rather than reserved vocab. For 'opencode' it carries NO workflow-phase events
+ * — the engine owns phase sequencing internally on such hosts (ADR-1239 §OpenCode).
+ */
+function extensionEventSurfaceFor(extensionEvents) {
+    if (typeof extensionEvents !== 'string')
+        return null;
+    return EXTENSION_EVENT_SURFACES[extensionEvents] || null;
+}
 module.exports = {
     PROTOCOL_VERSION,
     UNDOCUMENTED,
@@ -401,8 +458,12 @@ module.exports = {
     INTERFACE_POINTS,
     PROFILE_BASELINES,
     DEFAULT_ENGINE,
+    HOOK_EVENT_SURFACES,
+    EXTENSION_EVENT_SURFACES,
     degradationFor,
     profileOf,
     negotiateHostCapabilities,
     shouldFlattenDispatch,
+    hookEventSurfaceFor,
+    extensionEventSurfaceFor,
 };

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

@@ -60,9 +60,9 @@ const { resolveModelInternal, resolveGranularityInternal, assertValidGranularity
 const { findPhaseInternal } = phaseLocator;
 const { getRoadmapPhaseInternal, getMilestoneInfo, getMilestonePhaseFilter, stripShippedMilestones, extractCurrentMilestone, } = roadmapParser;
 const { pathExistsInternal, generateSlugInternal, toPosixPath } = coreUtils;
-const { normalizePhaseName, phaseTokenMatches } = phaseId;
+const { normalizePhaseName, phaseTokenMatches, stripProjectCodePrefix } = phaseId;
 const { pruneOrphanedWorktrees } = worktreeSafety;
-const { planningPaths, planningDir, planningRoot, findContextMdIn, } = planningWorkspace;
+const { planningPaths, planningDir, planningRoot, getActiveWorkstream, findContextMdIn, } = planningWorkspace;
 const { determinePhaseStatus } = commandsMod;
 const { extractFrontmatter } = frontmatterMod;
 const { readVerificationStatus } = verificationMod;
@@ -919,9 +919,12 @@ function cmdInitMilestoneOp(cwd, raw) {
         const roadmapPath = node_path_1.default.join(planningDir(cwd), 'ROADMAP.md');
         const roadmapRaw = node_fs_1.default.readFileSync(roadmapPath, 'utf-8');
         const currentSection = extractCurrentMilestone(roadmapRaw, cwd);
-        const phasePattern = /#{2,4}\s*Phase\s+(\d+[A-Z]?(?:\.\d+)*)\s*:/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*:/gi;
         let m;
         while ((m = phasePattern.exec(currentSection)) !== null) {
+            if (/^999(?:\.|$)/.test(m[1]))
+                continue;
             roadmapPhaseNumbers.push(m[1]);
         }
     }
@@ -938,7 +941,7 @@ function cmdInitMilestoneOp(cwd, raw) {
         for (const e of entries) {
             if (!e.isDirectory())
                 continue;
-            const m = e.name.match(/^(\d+[A-Z]?(?:\.\d+)*)/);
+            const m = stripProjectCodePrefix(e.name).match(/^(\d+[A-Z]?(?:\.\d+)*)/);
             if (!m)
                 continue;
             diskPhaseDirs.set(canonicalizePhase(m[1]), e.name);
@@ -1071,7 +1074,8 @@ function cmdInitManager(cwd, raw) {
     while ((_cbMatch = _cbPattern.exec(content)) !== null) {
         _checkboxStates.set(_cbMatch[2], _cbMatch[1].toLowerCase() === 'x');
     }
-    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 phases = [];
     let match;
     while ((match = phasePattern.exec(content)) !== null) {
@@ -1355,6 +1359,29 @@ function cmdInitProgress(cwd, raw) {
     const config = loadConfig(cwd);
     const milestone = getMilestoneInfo(cwd);
     const _slashRuntime = (0, runtime_slash_cjs_1.resolveRuntime)(cwd);
+    // #1912: fail safe in workstream mode with no active workstream. With no active
+    // workstream and no --ws, planningDir(cwd) resolves to root .planning — silently
+    // reporting a stale root milestone. Require an explicit workstream instead.
+    // Mirror planningDir's resolution (GSD_WORKSTREAM env > stored active pointer) so
+    // an explicit --ws (which sets GSD_WORKSTREAM) satisfies the check.
+    const _wsRoot = node_path_1.default.join(planningRoot(cwd), 'workstreams');
+    let _availableWorkstreams = [];
+    try {
+        _availableWorkstreams = node_fs_1.default
+            .readdirSync(_wsRoot, { withFileTypes: true })
+            .filter((e) => e.isDirectory())
+            .map((e) => e.name)
+            .sort();
+    }
+    catch {
+        /* no workstreams dir → flat mode */
+    }
+    const _resolvedWorkstream = process.env['GSD_WORKSTREAM'] || getActiveWorkstream(cwd);
+    if (_availableWorkstreams.length > 0 && !_resolvedWorkstream) {
+        error(`init.progress requires a workstream in workstream mode — no active workstream is set, so root STATE.md (likely stale) would be reported. ` +
+            `Pass --ws <name> or run ${(0, runtime_slash_cjs_1.formatGsdSlash)('workstream set', _slashRuntime)} first. ` +
+            `Available workstreams: ${_availableWorkstreams.join(', ')}`);
+    }
     const phasesDir = node_path_1.default.join(planningDir(cwd), 'phases');
     const phases = [];
     let currentPhase = null;
@@ -1364,7 +1391,8 @@ function cmdInitProgress(cwd, raw) {
     const roadmapCheckboxStates = new Map();
     try {
         const roadmapContent = extractCurrentMilestone(node_fs_1.default.readFileSync(node_path_1.default.join(planningDir(cwd), 'ROADMAP.md'), 'utf-8'), cwd);
-        const headingPattern = /#{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 headingPattern = /#{2,4}\s*Phase\s+(\d+[A-Z]?(?:\.\d+)*)(?:\s*\([^)\n]*\))?\s*:\s*([^\n]+)/gi;
         let hm;
         while ((hm = headingPattern.exec(roadmapContent)) !== null) {
             roadmapPhaseNums.add(hm[1]);

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

@@ -29,7 +29,7 @@ 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;
@@ -112,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;
@@ -151,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 = (() => {
@@ -261,7 +267,7 @@ 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)) {
         (0, shell_command_projection_cjs_1.retryRenameSync)(auditFile, node_path_1.default.join(archiveDir, `${version}-MILESTONE-AUDIT.md`));
     }
@@ -309,7 +315,8 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
     }
     // 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);
@@ -398,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);
@@ -410,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/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,

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

@@ -32,7 +32,7 @@ const coreUtilsMod = require("./core-utils.cjs");
 const { toPosixPath, generateSlugInternal, readSubdirectories } = coreUtilsMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- phase-id.cjs is an export= CommonJS module
 const phaseIdMod = require("./phase-id.cjs");
-const { escapeRegex, normalizePhaseName, phaseMarkdownRegexSource, comparePhaseNum, phaseTokenMatches, OPTIONAL_PROJECT_CODE_PREFIX_SOURCE, } = phaseIdMod;
+const { escapeRegex, normalizePhaseName, phaseMarkdownRegexSource, comparePhaseNum, phaseTokenMatches, OPTIONAL_PROJECT_CODE_PREFIX_SOURCE, OPTIONAL_PHASE_TAG_SOURCE, } = phaseIdMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- phase-locator.cjs is an export= CommonJS module
 const phaseLocatorMod = require("./phase-locator.cjs");
 const { findPhaseInternal, getArchivedPhaseDirs } = phaseLocatorMod;
@@ -181,7 +181,7 @@ function cmdPhaseNextDecimal(cwd, basePhase, raw) {
         if (node_fs_1.default.existsSync(roadmapPath)) {
             try {
                 const roadmapContent = node_fs_1.default.readFileSync(roadmapPath, 'utf-8');
-                const phasePattern = new RegExp(`#{2,4}\\s*Phase\\s+${phaseMarkdownRegexSource(normalized)}\\.(\\d+)\\s*:`, 'gi');
+                const phasePattern = new RegExp(`#{2,4}\\s*Phase\\s+${phaseMarkdownRegexSource(normalized)}\\.(\\d+)${OPTIONAL_PHASE_TAG_SOURCE}\\s*:`, 'gi');
                 let pm;
                 while ((pm = phasePattern.exec(roadmapContent)) !== null) {
                     decimalSet.add(parseInt(pm[1], 10));
@@ -221,7 +221,7 @@ function getRoadmapModeForPhase(cwd, phaseNum) {
     const milestoneContent = extractCurrentMilestone(rawContent, cwd);
     const fullContent = stripShippedMilestones(rawContent);
     const escapedPhase = phaseMarkdownRegexSource(phaseNum);
-    const phaseHeader = new RegExp(`#{2,4}\\s*Phase\\s+${escapedPhase}\\s*:`, 'i');
+    const phaseHeader = new RegExp(`#{2,4}\\s*Phase\\s+${escapedPhase}${OPTIONAL_PHASE_TAG_SOURCE}\\s*:`, 'i');
     for (const content of [milestoneContent, fullContent]) {
         const headerMatch = content.match(phaseHeader);
         if (!headerMatch || headerMatch.index === undefined)
@@ -578,7 +578,8 @@ function cmdPhaseAdd(cwd, description, raw, customId) {
             // Three sources are scanned so that a phase in ANY representation
             // (section header, roadmap bullet, or on-disk directory) is counted:
             // 1) Section headers: ### Phase N: / ## Phase N: / #### Phase N:
-            const headerPattern = /#{2,4}\s*Phase\s+(\d+)[A-Z]?(?:\.\d+)*:/gi;
+            // #1729: `(?:\s*\([^)\n]*\))?` tolerates a pre-colon ( ) tag (literal mirror of OPTIONAL_PHASE_TAG_SOURCE).
+            const headerPattern = /#{2,4}\s*Phase\s+(\d+)[A-Z]?(?:\.\d+)*(?:\s*\([^)\n]*\))?:/gi;
             // 2) Roadmap bullet entries: - [ ] **Phase N: ...** (all checkbox variants)
             // The lookahead accepts colon, decimal-dot, whitespace, bold-close asterisk,
             // or end-of-line so titleless forms ("- [ ] **Phase 11**", "- [ ] Phase 11")
@@ -662,7 +663,8 @@ function cmdPhaseAddBatch(cwd, descriptions, raw) {
         const content = extractCurrentMilestone(rawContent, cwd);
         let maxPhase = 0;
         if (config.phase_naming !== 'custom') {
-            const phasePattern = /#{2,4}\s*Phase\s+(\d+)[A-Z]?(?:\.\d+)*:/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]*\))?:/gi;
             let m;
             while ((m = phasePattern.exec(content)) !== null) {
                 const num = parseInt(m[1], 10);
@@ -740,14 +742,14 @@ function cmdPhaseInsert(cwd, afterPhase, description, raw) {
         const content = extractCurrentMilestone(rawContent, cwd);
         const normalizedAfter = normalizePhaseName(afterPhase);
         const afterPhaseEscaped = phaseMarkdownRegexSource(normalizedAfter);
-        const targetPattern = new RegExp(`#{2,4}\\s*Phase\\s+${afterPhaseEscaped}:`, 'i');
+        const targetPattern = new RegExp(`#{2,4}\\s*Phase\\s+${afterPhaseEscaped}${OPTIONAL_PHASE_TAG_SOURCE}:`, 'i');
         const headingMatch = targetPattern.test(content);
-        const bulletPattern = new RegExp(`-\\s*\\[[ x]\\]\\s*(?:\\*\\*)?Phase\\s+${afterPhaseEscaped}[:\\s]`, 'i');
+        const bulletPattern = new RegExp(`-\\s*\\[[ x]\\]\\s*(?:\\*\\*)?Phase\\s+${afterPhaseEscaped}${OPTIONAL_PHASE_TAG_SOURCE}[:\\s]`, 'i');
         const anyHeadingPattern = /#{2,4}\s*Phase\s+\d/i;
         const roadmapHasHeadingPhases = anyHeadingPattern.test(content);
         const isBulletStyle = !headingMatch && bulletPattern.test(content) && !roadmapHasHeadingPhases;
         if (!headingMatch && !isBulletStyle) {
-            const checklistPattern = new RegExp(`-\\s*\\[[ x]\\]\\s*(?:\\*\\*)?Phase\\s+${afterPhaseEscaped}[:\\s]`, 'i');
+            const checklistPattern = new RegExp(`-\\s*\\[[ x]\\]\\s*(?:\\*\\*)?Phase\\s+${afterPhaseEscaped}${OPTIONAL_PHASE_TAG_SOURCE}[:\\s]`, 'i');
             if (checklistPattern.test(content)) {
                 error(`Phase ${afterPhase} exists in roadmap summary but is missing a detail section (### Phase ${afterPhase}: ...).`);
             }
@@ -769,7 +771,7 @@ function cmdPhaseInsert(cwd, afterPhase, description, raw) {
         catch {
             /* intentionally empty */
         }
-        const rmPhasePattern = new RegExp(`#{2,4}\\s*Phase\\s+${phaseMarkdownRegexSource(normalizedBase)}\\.(\\d+)\\s*:`, 'gi');
+        const rmPhasePattern = new RegExp(`#{2,4}\\s*Phase\\s+${phaseMarkdownRegexSource(normalizedBase)}\\.(\\d+)${OPTIONAL_PHASE_TAG_SOURCE}\\s*:`, 'gi');
         let rmMatch;
         while ((rmMatch = rmPhasePattern.exec(rawContent)) !== null) {
             decimalSet.add(parseInt(rmMatch[1], 10));
@@ -785,13 +787,13 @@ function cmdPhaseInsert(cwd, afterPhase, description, raw) {
         (0, shell_command_projection_cjs_1.platformWriteSync)(node_path_1.default.join(dirPath, '.gitkeep'), '');
         let updatedContent;
         if (isBulletStyle) {
-            const boldBulletPattern = new RegExp(`-\\s*\\[[ x]\\]\\s*\\*\\*Phase\\s+${afterPhaseEscaped}:`, 'i');
+            const boldBulletPattern = new RegExp(`-\\s*\\[[ x]\\]\\s*\\*\\*Phase\\s+${afterPhaseEscaped}${OPTIONAL_PHASE_TAG_SOURCE}:`, 'i');
             const useBold = boldBulletPattern.test(content);
             const phaseLabel = useBold
                 ? `**Phase ${_decimalPhase}: ${description}**`
                 : `Phase ${_decimalPhase}: ${description}`;
             const bulletEntry = `\n- [ ] ${phaseLabel}`;
-            const targetBulletPattern = new RegExp(`(-\\s*\\[[ x]\\]\\s*(?:\\*\\*)?Phase\\s+${afterPhaseEscaped}[:\\s][^\\n]*)`, 'i');
+            const targetBulletPattern = new RegExp(`(-\\s*\\[[ x]\\]\\s*(?:\\*\\*)?Phase\\s+${afterPhaseEscaped}${OPTIONAL_PHASE_TAG_SOURCE}[:\\s][^\\n]*)`, 'i');
             const bulletMatchResult = rawContent.match(targetBulletPattern);
             if (!bulletMatchResult) {
                 error(`Could not find Phase ${afterPhase} bullet line`);
@@ -811,7 +813,7 @@ function cmdPhaseInsert(cwd, afterPhase, description, raw) {
         }
         else {
             const phaseEntry = `\n### Phase ${_decimalPhase}: ${description} (INSERTED)\n\n**Goal:** [Urgent work - to be planned]\n**Requirements**: TBD\n**Depends on:** Phase ${afterPhase}\n**Plans:** 0 plans\n\nPlans:\n- [ ] TBD (run ${(0, runtime_slash_cjs_1.formatGsdSlash)('plan-phase', (0, runtime_slash_cjs_1.resolveRuntime)(cwd))} ${_decimalPhase} to break down)\n`;
-            const headerPattern = new RegExp(`(#{2,4}\\s*Phase\\s+${afterPhaseEscaped}:[^\\n]*\\n)`, 'i');
+            const headerPattern = new RegExp(`(#{2,4}\\s*Phase\\s+${afterPhaseEscaped}${OPTIONAL_PHASE_TAG_SOURCE}:[^\\n]*\\n)`, 'i');
             const headerMatch = rawContent.match(headerPattern);
             if (!headerMatch) {
                 error(`Could not find Phase ${afterPhase} header`);
@@ -940,11 +942,13 @@ function updateRoadmapAfterPhaseRemoval(roadmapPath, targetPhase, isDecimal, rem
     withPlanningLock(cwd, () => {
         let content = node_fs_1.default.readFileSync(roadmapPath, 'utf-8');
         const escaped = escapeRegex(targetPhase);
-        content = content.replace(new RegExp(`\\n?(?<h>#{2,4})\\s*Phase\\s+${escaped}\\s*:[\\s\\S]*?(?=\\n\\k<h>(?!#)\\s+Phase\\s+[^\\n:]+\\s*:|$)`, 'i'), '');
-        content = content.replace(new RegExp(`\\n?-\\s*\\[[ x]\\]\\s*.*Phase\\s+${escaped}[:\\s][^\\n]*`, 'gi'), '');
+        content = content.replace(new RegExp(`\\n?(?<h>#{2,4})\\s*Phase\\s+${escaped}${OPTIONAL_PHASE_TAG_SOURCE}\\s*:[\\s\\S]*?(?=\\n\\k<h>(?!#)\\s+Phase\\s+[^\\n:]+\\s*:|$)`, 'i'), '');
+        content = content.replace(new RegExp(`\\n?-\\s*\\[[ x]\\]\\s*.*Phase\\s+${escaped}${OPTIONAL_PHASE_TAG_SOURCE}[:\\s][^\\n]*`, 'gi'), '');
         content = content.replace(new RegExp(`\\n?\\|\\s*${escaped}\\.?\\s[^|]*\\|[^\\n]*`, 'gi'), '');
         if (!isDecimal) {
-            content = content.replace(/(#{2,4}\s*Phase\s+)(\d+(?:\.\d+)?)(\s*:)/gi, (_match, prefix, num, suffix) => `${prefix}${decrementRoadmapPhaseToken(num, removedInt)}${suffix}`);
+            // #1729: fold an optional pre-colon ( ) tag into the suffix capture so it
+            // is re-emitted verbatim — a tagged later phase still gets renumbered.
+            content = content.replace(/(#{2,4}\s*Phase\s+)(\d+(?:\.\d+)?)((?:\s*\([^)\n]*\))?\s*:)/gi, (_match, prefix, num, suffix) => `${prefix}${decrementRoadmapPhaseToken(num, removedInt)}${suffix}`);
             content = content.replace(/(-\s*\[[ x]\]\s*.*?Phase\s+)(\d+)(\s*:|\s+)/gi, (_match, prefix, num, suffix) => `${prefix}${decrementRoadmapPhaseNumber(num, removedInt)}${suffix}`);
             content = content.replace(/(\|\s*)(\d+)(\.\s)/g, (_match, prefix, num, suffix) => `${prefix}${decrementRoadmapPhaseNumber(num, removedInt)}${suffix}`);
             content = content.replace(/(?<![0-9-])(\d{2})-(\d{2})(?=(?:(?:-[A-Za-z][A-Za-z0-9-]*)?-(?:PLAN|SUMMARY)\.md)|(?![0-9-]))/g, (_match, phaseNum, planNum) => `${decrementRoadmapPaddedPhaseNumber(phaseNum, removedInt)}-${planNum}`);
@@ -1047,7 +1051,7 @@ function phaseDisplayNameFromRoadmap(roadmapContent, phaseNum) {
     if (!roadmapContent || !phaseNum)
         return null;
     const phaseEscaped = phaseMarkdownRegexSource(phaseNum);
-    const heading = roadmapContent.match(new RegExp(`^#{2,4}\\s*Phase\\s+${phaseEscaped}\\s*:\\s*([^\\n]+)`, 'im'));
+    const heading = roadmapContent.match(new RegExp(`^#{2,4}\\s*Phase\\s+${phaseEscaped}${OPTIONAL_PHASE_TAG_SOURCE}\\s*:\\s*([^\\n]+)`, 'im'));
     if (!heading)
         return null;
     const name = heading[1].replace(/\(INSERTED\)/i, '').trim();
@@ -1128,7 +1132,7 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
                 const originalRoadmapContent = node_fs_1.default.readFileSync(roadmapPath, 'utf-8');
                 roadmapContent = originalRoadmapContent;
                 const phaseEscaped = phaseMarkdownRegexSource(phaseNum);
-                const checkboxPattern = new RegExp(`(-\\s*\\[)[ ](\\]\\s*.*Phase\\s+${phaseEscaped}[:\\s][^\\n]*)`, 'i');
+                const checkboxPattern = new RegExp(`(-\\s*\\[)[ ](\\]\\s*.*Phase\\s+${phaseEscaped}${OPTIONAL_PHASE_TAG_SOURCE}[:\\s][^\\n]*)`, 'i');
                 roadmapContent = roadmapContent.replace(checkboxPattern, `$1x$2 (completed ${today})`);
                 const tableRowPattern = new RegExp(`^(\\|\\s*${phaseEscaped}\\.?\\s[^|]*(?:\\|[^\\n]*))$`, 'im');
                 roadmapContent = roadmapContent.replace(tableRowPattern, (fullRow) => {
@@ -1170,7 +1174,7 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
                 if (node_fs_1.default.existsSync(reqPath)) {
                     const phaseEsc = phaseMarkdownRegexSource(phaseNum);
                     const currentMilestoneRoadmap = extractCurrentMilestone(roadmapContent, cwd);
-                    const phaseSectionMatch = currentMilestoneRoadmap.match(new RegExp(`(#{2,4}\\s*Phase\\s+${phaseEsc}[:\\s][\\s\\S]*?)(?=#{2,4}\\s*Phase\\s+|$)`, 'i'));
+                    const phaseSectionMatch = currentMilestoneRoadmap.match(new RegExp(`(#{2,4}\\s*Phase\\s+${phaseEsc}${OPTIONAL_PHASE_TAG_SOURCE}[:\\s][\\s\\S]*?)(?=#{2,4}\\s*Phase\\s+|$)`, 'i'));
                     const sectionText = phaseSectionMatch ? phaseSectionMatch[1] : '';
                     const reqMatch = sectionText.match(/\*\*Requirements:?\*\*[^\S\n]*:?[^\S\n]*([^\n]+)/i);
                     const originalReqContent = node_fs_1.default.readFileSync(reqPath, 'utf-8');
@@ -1288,15 +1292,21 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
                 try {
                     const roadmapForPhases = extractCurrentMilestone(roadmapContent, cwd);
                     // #1591: match BOTH heading-style phases (`### Phase N:`) AND
-                    // checkbox-list items (`- [ ] Phase N:` / `- [x] Phase N:`). When
-                    // the active milestone's checklist is `- [ ]` items inside a
-                    // <details> block (and the next phase has no directory yet, so the
-                    // disk-based resolver finds nothing), this roadmap-enumeration
-                    // fallback is the only path that can find the next phase. The prior
-                    // heading-only pattern missed checkbox items → is_last_phase=true on
-                    // a mid-milestone phase. The marker alternation is the only change;
-                    // the number/name captures are unchanged.
-                    const phasePattern = /(?:#{2,4}|-\s*\[[ xX]\])\s*Phase\s+(\d+[A-Z]?(?:\.\d+)*)\s*:\s*([^\n]+)/gi;
+                    // checkbox-list items, INCLUDING the canonical bold form the roadmap
+                    // template emits (`- [ ] **Phase N: Name**`). When the active
+                    // milestone's checklist is `- [ ]` items inside a <details> block
+                    // (and the next phase has no directory yet, so the disk-based
+                    // resolver finds nothing), this roadmap-enumeration fallback is the
+                    // only path that can find the next phase. The prior heading-only
+                    // pattern missed checkbox items, and a checkbox-only broadening still
+                    // missed the bold template rows → is_last_phase=true on a mid-milestone
+                    // phase. Allow optional `**`/`__` emphasis after the marker and stop
+                    // the name capture at emphasis so bold names slug cleanly; the number
+                    // capture is unchanged.
+                    // #1729: `(?:\s*\([^)\n]*\))?` after the number tolerates a pre-colon
+                    // ( ) tag (literal mirror of OPTIONAL_PHASE_TAG_SOURCE) so
+                    // `### Phase N (Cluster B): X` resolves. Captures are unchanged.
+                    const phasePattern = /(?:#{2,4}|-\s*\[[ xX]\])\s*(?:\*\*|__)?\s*Phase\s+(\d+[A-Z]?(?:\.\d+)*)(?:\s*\([^)\n]*\))?\s*:\s*([^\n*]+)/gi;
                     let pm;
                     while ((pm = phasePattern.exec(roadmapForPhases)) !== null) {
                         if (comparePhaseNum(pm[1], phaseNum) > 0) {

package/gsd-core/bin/lib/phases-command-router.cjs

@@ -4,8 +4,8 @@
  * Keeps gsd-tools.cjs thin while preserving current CJS semantics.
  *
  * Unsupported in this router (treated as unknown):
- * - archive: `phases archive` is excluded from the subcommands list so it
- *   falls through to the unknown-subcommand error path.
+ * - archive: `phases archive` is excluded (#2684) — it is an internal
+ *   subcommand that milestone.complete forwards to, not a public surface.
  *
  * ADR-457 build-at-publish: the hand-written bin/lib/phases-command-router.cjs
  * collapsed to a TypeScript source of truth. Behaviour is preserved byte-for-behaviour
@@ -19,7 +19,8 @@ const { routeCjsCommandFamily } = cjsCommandRouterAdapter;
 function routePhasesCommand({ phase, milestone, args, cwd, raw, error }) {
     routeCjsCommandFamily({
         args,
-        // Exclude 'archive' so it hits the unknownMessage path.
+        // #2684: `phases archive` is deliberately excluded — it is an internal
+        // subcommand that milestone.complete forwards to, not a public surface.
         subcommands: command_aliases_cjs_1.PHASES_SUBCOMMANDS.filter((s) => s !== 'archive'),
         error,
         unknownMessage: (_subcommand, available) => `Unknown phases subcommand. Available: ${available.join(', ')}`,