@opengsd/gsd-core 1.7.0-rc.4 → 1.7.0-rc.5

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

@@ -0,0 +1,234 @@
+/**
+ * Cline SDK binding — AgentPlugin + createAgentModel adapters
+ * (ADR-1239 Phase D / #2090).
+ *
+ * Two Context7-verified UPGRADES the file-convention projection ignored, now
+ * delivered through the negotiated `hookBus: host` + `modelMode: active`
+ * interface points:
+ *
+ *   UPGRADE 1 — `AgentPlugin.hooks.beforeTool` planning-artifact guard.
+ *     Re-implements the `.clinerules/hooks/PreToolUse` file-convention hook
+ *     (issue #787) as a real Cline SDK AgentPlugin. Guard semantics are
+ *     preserved EXACTLY: fail-open, cancel (skip) write-class calls targeting
+ *     `.planning/`, pass through everything else. The SDK maps the file hook's
+ *     `{cancel:true, errorMessage}` to `{skip:true, reason}` (beforeTool
+ *     contract).
+ *     Cite: https://github.com/cline/cline/blob/main/docs/sdk/plugins.mdx
+ *           https://github.com/cline/cline/blob/main/sdk/packages/agents/README.md
+ *
+ *   UPGRADE 2 — `DefaultGateway.createAgentModel({providerId, modelId})`.
+ *     Resolves GSD's per-subagent `model_overrides` / `model_profile_overrides`
+ *     (already used for OpenCode/Codex passive hosts) into the createAgentModel
+ *     call params for cline's active model mode. The host gateway owns the
+ *     actual model instantiation; this binding resolves WHICH model an
+ *     overridden subagent should use.
+ *     Cite: https://github.com/cline/cline/blob/main/docs/sdk/reference/gateway.mdx
+ *           https://github.com/cline/cline/blob/main/sdk/packages/llms/README.md
+ *
+ * This module is PURE (no I/O, no SDK import): the real `@cline/sdk` is a
+ * fast-moving package set not linked at build/test time, so the binding exposes
+ * the decision functions a host plugin/gateway would call. Tests drive payloads
+ * through them directly (same mock-the-SDK pattern as the VS Code reference
+ * binding, tests/fixtures/vscode-host-binding.cjs).
+ */
+'use strict';
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_CLINE_PROVIDER_ID = exports.clineGsdPlugin = exports.PLANNING_GUARD_REASON = exports.PLANNING_PATH_PATTERN = exports.WRITE_TOOL_PATTERN = void 0;
+exports.evaluateBeforeTool = evaluateBeforeTool;
+exports.inferProviderId = inferProviderId;
+exports.resolveClineAgentModelParams = resolveClineAgentModelParams;
+// ---------------------------------------------------------------------------
+// UPGRADE 1 — beforeTool planning-artifact guard
+// ---------------------------------------------------------------------------
+/**
+ * Write-class tool-verb detector. Matches the SAME regex as the #787
+ * PreToolUse file-convention hook so the guard behaves identically.
+ * Case-insensitive (the SDK delivers tool names in varying case).
+ */
+exports.WRITE_TOOL_PATTERN = /write|edit|replace|create|delete|remove|append|apply|patch|insert|mkdir/i;
+/**
+ * `.planning/` path detector. Matches `.planning` preceded by start-of-string
+ * or a path separator (posix `/` or windows `\`) and followed by a separator or
+ * end-of-string — so `.planning-readme.txt` is NOT falsely matched. Mirrors the
+ * PreToolUse hook's `(^|[\\/])\.planning([\\/]|$)` exactly.
+ */
+exports.PLANNING_PATH_PATTERN = /(^|[\\/])\.planning([\\/]|$)/;
+/**
+ * The user-visible reason returned when a `.planning/` write is blocked.
+ * Preserves the PreToolUse hook's errorMessage text so the guard behaves
+ * identically to the user (cancel→skip, errorMessage→reason).
+ */
+exports.PLANNING_GUARD_REASON = Object.freeze('GSD: .planning/ artifacts are managed by GSD workflows. Edit them only through a /gsd-* command, not directly.');
+/**
+ * Path-bearing field-name detector. Only PATH-keyed field values are inspected,
+ * so a document that merely mentions ".planning/" in its body content is never
+ * falsely blocked. Mirrors the PreToolUse hook's PATH_KEY regex exactly.
+ */
+const PATH_KEY_PATTERN = /^(path|file|file_?path|filepath|target_?path|target|dir|directory|uri|filename)$/i;
+/**
+ * Collect PATH-bearing string field values from an object tree, mirroring the
+ * PreToolUse hook's bounded walk. Pure; never throws.
+ */
+function collectPathValues(root) {
+    const paths = [];
+    const walk = (v, depth) => {
+        if (depth > 5 || paths.length > 64)
+            return;
+        if (Array.isArray(v)) {
+            for (const x of v)
+                walk(x, depth + 1);
+            return;
+        }
+        if (v && typeof v === 'object') {
+            const obj = v;
+            for (const k of Object.keys(obj)) {
+                const val = obj[k];
+                if (typeof val === 'string' && PATH_KEY_PATTERN.test(k)) {
+                    paths.push(val);
+                }
+                else {
+                    walk(val, depth + 1);
+                }
+            }
+        }
+    };
+    walk(root, 0);
+    return paths;
+}
+/**
+ * Resolve a tool name from a beforeTool payload's `tool` field, which may be a
+ * string or an object with a `name` property. Returns '' when absent (treated
+ * as non-write-class → allow, fail-open).
+ */
+function resolveToolName(tool) {
+    if (!tool)
+        return '';
+    if (typeof tool === 'string')
+        return tool;
+    const name = tool.name;
+    return typeof name === 'string' ? name : '';
+}
+/**
+ * The pure guard decision: given a beforeTool payload, decide skip (cancel) or
+ * allow. Fail-OPEN — any malformed input, missing tool, or thrown error returns
+ * 'allow' (the guard never blocks on a defect, mirroring the PreToolUse hook).
+ *
+ * @returns `{decision:'skip', reason}` for a write-class call targeting
+ *          `.planning/`; `{decision:'allow'}` for everything else.
+ */
+function evaluateBeforeTool(payload) {
+    try {
+        if (!payload)
+            return { decision: 'allow' };
+        const toolName = resolveToolName(payload.tool);
+        if (!toolName)
+            return { decision: 'allow' };
+        const isWrite = exports.WRITE_TOOL_PATTERN.test(toolName);
+        if (!isWrite)
+            return { decision: 'allow' };
+        const paths = collectPathValues(payload.input);
+        const isPlanningPath = (s) => exports.PLANNING_PATH_PATTERN.test(s);
+        if (paths.some(isPlanningPath)) {
+            return { decision: 'skip', reason: exports.PLANNING_GUARD_REASON };
+        }
+        return { decision: 'allow' };
+    }
+    catch {
+        // Fail-open: a defect in the guard never blocks the user's operation.
+        return { decision: 'allow' };
+    }
+}
+/**
+ * The Cline `AgentPlugin` shape (Context7 /cline/cline). A plugin implements
+ * `setup({agentId})` returning `{hooks, tools}`. The `beforeTool` hook returns
+ * `{skip:true, reason}` to block or `undefined` to allow.
+ *
+ * This object is the portable plugin a host loads from `~/.cline/plugins/`
+ * (analogous to `.opencode/plugins/gsd-core.js`). Its `beforeTool` delegates to
+ * the pure `evaluateBeforeTool` so the decision logic is testable without the
+ * SDK linked.
+ */
+exports.clineGsdPlugin = Object.freeze({
+    name: 'gsd-planning-guard',
+    setup(_ctx) {
+        return {
+            hooks: {
+                beforeTool(payload) {
+                    const decision = evaluateBeforeTool(payload);
+                    return decision.decision === 'skip' ? { skip: true, reason: decision.reason } : undefined;
+                },
+            },
+        };
+    },
+});
+// ---------------------------------------------------------------------------
+// UPGRADE 2 — createAgentModel model-override resolution
+// ---------------------------------------------------------------------------
+/**
+ * The fallback provider id when a model id does not match a known provider
+ * family. Anthropic is cline's most common default; the host gateway retains
+ * the final say over provider resolution.
+ */
+exports.DEFAULT_CLINE_PROVIDER_ID = 'anthropic';
+/**
+ * Infer a `providerId` (the createAgentModel first arg) from a model id by
+ * matching known provider families. Returns DEFAULT_CLINE_PROVIDER_ID for an
+ * unrecognized or empty id (fail-safe — the gateway applies its own default).
+ *
+ * Pure string-prefix classification; does not validate the id is a real model.
+ */
+function inferProviderId(modelId) {
+    if (typeof modelId !== 'string' || modelId.length === 0)
+        return exports.DEFAULT_CLINE_PROVIDER_ID;
+    const lower = modelId.toLowerCase();
+    if (lower.startsWith('claude'))
+        return 'anthropic';
+    if (lower.startsWith('gpt') || lower.startsWith('o1') || lower.startsWith('o3') || lower.startsWith('o4'))
+        return 'openai';
+    if (lower.startsWith('gemini'))
+        return 'google';
+    if (lower.startsWith('deepseek'))
+        return 'deepseek';
+    return exports.DEFAULT_CLINE_PROVIDER_ID;
+}
+/**
+ * Resolve the createAgentModel call params for a cline subagent from GSD's model
+ * override config. Mirrors the precedence OpenCode/Codex use (passive hosts
+ * embed the resolved model into agent frontmatter); for cline's active model
+ * mode the same resolution flows to `gateway.createAgentModel(params)`.
+ *
+ * Precedence (matches GSD's model_overrides > model_profile_overrides contract):
+ *   1. `modelOverrides[agentType]` — direct per-agent override
+ *   2. `modelProfileOverrides[profile][agentType]` — profile-scoped override
+ *   3. null — no override; the host gateway applies its own default
+ *
+ * Pure; never throws. Non-string / empty override values are ignored (fail-safe).
+ *
+ * @returns the `{providerId, modelId}` for createAgentModel, or null when no
+ *          override is configured (the gateway default applies — GSD does NOT
+ *          call createAgentModel in that case).
+ */
+function resolveClineAgentModelParams(args) {
+    const { agentType, modelOverrides, modelProfileOverrides, profile } = args;
+    if (!agentType || typeof agentType !== 'string')
+        return null;
+    // 1. Direct per-agent override wins.
+    if (modelOverrides && typeof modelOverrides === 'object') {
+        const direct = modelOverrides[agentType];
+        if (typeof direct === 'string' && direct.length > 0) {
+            return { providerId: inferProviderId(direct), modelId: direct };
+        }
+    }
+    // 2. Profile-scoped override.
+    if (modelProfileOverrides && typeof modelProfileOverrides === 'object' && profile) {
+        const profileEntry = modelProfileOverrides[profile];
+        if (profileEntry && typeof profileEntry === 'object') {
+            const profileModel = profileEntry[agentType];
+            if (typeof profileModel === 'string' && profileModel.length > 0) {
+                return { providerId: inferProviderId(profileModel), modelId: profileModel };
+            }
+        }
+    }
+    // 3. No override — gateway default applies.
+    return null;
+}

package/gsd-core/bin/lib/host-integration-adapters/imperative-hook-bus.cjs

@@ -0,0 +1,145 @@
+/**
+ * Imperative hook-bus adapter — descriptor-driven hooks.json binding
+ * (ADR-1239 Phase D / #2089).
+ *
+ * Generalizes the Cursor-specific `writeCursorHooksJson`/`removeCursorHooksJson`
+ * into a descriptor-driven hook-bus binding that reads the negotiated `hookBus`
+ * axis + the host's documented hook-event list (from
+ * `runtime.hostBehaviors.managedHookEvents`), NOT a hardcoded
+ * `sessionStart`/`postToolUse` pair.
+ *
+ * This module is PURE (no I/O): it resolves the event→script mapping and builds
+ * the hooks.json entry manifest. The actual file I/O (copying scripts, writing
+ * hooks.json) stays in `runtime-hooks-surface.cts`, which calls into the pure
+ * functions exported here. This separation makes the binding testable without a
+ * filesystem.
+ *
+ * Cursor hook-event universe (closed vocabulary per ADR-1239,
+ * https://cursor.com/docs/hooks):
+ *   sessionStart, sessionEnd, preToolUse, postToolUse, subagentStart,
+ *   subagentStop, beforeShellExecution, afterShellExecution,
+ *   afterMCPExecution, afterFileEdit, preCompact, stop,
+ *   beforeTabFileRead, afterTabFileEdit, workspaceOpen
+ *
+ * GSD registers for the 6 events in the portable floor + subagent lifecycle
+ * (AC4a upgrade, #2089):
+ *   sessionStart, postToolUse, preToolUse, stop, subagentStart, subagentStop
+ */
+'use strict';
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GSD_HOOK_MARKER = exports.CURSOR_EVENT_SCRIPT_MAP = exports.CURSOR_HOOK_EVENTS = void 0;
+exports.resolveManagedHookEvents = resolveManagedHookEvents;
+exports.resolveHookScripts = resolveHookScripts;
+exports.buildHookBusEntries = buildHookBusEntries;
+/**
+ * The full set of Cursor hook events GSD can register for.
+ * Frozen closed vocabulary — adding an event requires updating both this set
+ * and the event→script mapping below.
+ */
+exports.CURSOR_HOOK_EVENTS = Object.freeze([
+    'sessionStart',
+    'postToolUse',
+    'preToolUse',
+    'stop',
+    'subagentStart',
+    'subagentStop',
+]);
+/**
+ * Event → hook-script mapping. Each event maps to a standalone `.js` script
+ * under `hooks/` that Cursor invokes via `hooks.json`.
+ *
+ * Convention: `gsd-cursor-<kebab-event>.js`. The script files are authored in
+ * `hooks/` and copied to `<configDir>/hooks/` during install by
+ * `runtime-hooks-surface.cts`.
+ */
+exports.CURSOR_EVENT_SCRIPT_MAP = Object.freeze({
+    sessionStart: 'gsd-cursor-session-start.js',
+    postToolUse: 'gsd-cursor-post-tool.js',
+    preToolUse: 'gsd-cursor-pre-tool.js',
+    stop: 'gsd-cursor-stop.js',
+    subagentStart: 'gsd-cursor-subagent-start.js',
+    subagentStop: 'gsd-cursor-subagent-stop.js',
+});
+/**
+ * The GSD-managed marker written into each hooks.json entry so the
+ * reconcile pass can distinguish GSD-owned entries from user-owned ones.
+ */
+exports.GSD_HOOK_MARKER = 'gsd-managed';
+/**
+ * Resolve the managed hook events from a runtime descriptor's
+ * `hostBehaviors.managedHookEvents` list. Falls back to the full
+ * `CURSOR_HOOK_EVENTS` set when the descriptor does not declare the list
+ * (backward-compat for descriptors predating #2089).
+ *
+ * Pure: no I/O, never throws. Unknown event names are silently filtered
+ * (fail-closed — an unrecognized event is never registered). Falls back to
+ * the full CURSOR_HOOK_EVENTS set when the descriptor is absent or all entries
+ * are unrecognized (ensures the portable-event floor is always covered).
+ *
+ * @param managedHookEvents - the descriptor's `hostBehaviors.managedHookEvents` array
+ * @returns a deduplicated, validated array of event names
+ */
+function resolveManagedHookEvents(managedHookEvents) {
+    if (!Array.isArray(managedHookEvents) || managedHookEvents.length === 0) {
+        return exports.CURSOR_HOOK_EVENTS;
+    }
+    const valid = new Set(exports.CURSOR_HOOK_EVENTS);
+    const seen = new Set();
+    const result = [];
+    for (const ev of managedHookEvents) {
+        if (typeof ev === 'string' && valid.has(ev) && !seen.has(ev)) {
+            seen.add(ev);
+            result.push(ev);
+        }
+    }
+    return result.length > 0 ? result : exports.CURSOR_HOOK_EVENTS;
+}
+/**
+ * Build the list of hook script files that need to be copied for the given
+ * managed events. Each event maps to a script via `CURSOR_EVENT_SCRIPT_MAP`.
+ *
+ * Pure: returns a deduplicated array of script filenames.
+ *
+ * @param events - the managed event names (validated by `resolveManagedHookEvents`)
+ * @returns array of script filenames (e.g. `['gsd-cursor-session-start.js', ...]`)
+ */
+function resolveHookScripts(events) {
+    const scripts = [];
+    const seen = new Set();
+    for (const ev of events) {
+        const script = exports.CURSOR_EVENT_SCRIPT_MAP[ev];
+        if (script && !seen.has(script)) {
+            seen.add(script);
+            scripts.push(script);
+        }
+    }
+    return scripts;
+}
+/**
+ * Build the hooks.json managed-entry manifest for the given events.
+ * Each entry is `{ type: 'command', command: <cmd>, [GSD_HOOK_MARKER]: true }`.
+ *
+ * The `command` string is built by the caller (it requires platform-specific
+ * node-runner resolution from `runtime-hooks-surface.cts`). This function
+ * receives a pre-built `event → command` map and attaches the marker.
+ *
+ * Pure: no I/O.
+ *
+ * @param events - the managed event names
+ * @param commands - a map of event → command string (built by the caller)
+ * @returns a map of event → managed entry, ready for hooks.json reconciliation
+ */
+function buildHookBusEntries(events, commands) {
+    const entries = {};
+    for (const ev of events) {
+        const cmd = commands[ev];
+        if (cmd) {
+            entries[ev] = {
+                type: 'command',
+                command: cmd,
+                [exports.GSD_HOOK_MARKER]: true,
+            };
+        }
+    }
+    return entries;
+}

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

@@ -434,6 +434,22 @@ const EXTENSION_EVENT_SURFACES = Object.freeze({
     opencode: Object.freeze([
         'session.created', 'session.idle', 'experimental.session.compacting',
         'tool.execute.before', 'tool.execute.after', 'file.edited',
+        // #2087 — additional documented plugin events GSD binds (opencode.ai/docs/plugins):
+        // permission decisions + session error surface.
+        'permission.asked', 'permission.replied', 'session.error',
+    ]),
+    // #2091 — Hermes Agent real plugin hook vocabulary (13 events).
+    // Cite: https://github.com/nousresearch/hermes-agent/blob/main/website/docs/user-guide/features/hooks.md
+    // Replaces the borrowed `hookEvents: "claude"` 6-event surface that silently
+    // never fired on Hermes.
+    hermes: Object.freeze([
+        'pre_tool_call', 'post_tool_call',
+        'pre_llm_call', 'post_llm_call',
+        'on_session_start', 'on_session_end',
+        'on_session_finalize', 'on_session_reset',
+        'subagent_start', 'subagent_stop',
+        'pre_gateway_dispatch', 'pre_approval_request',
+        'transform_tool_result',
     ]),
     pi: Object.freeze(['tool_call']),
     none: Object.freeze([]),

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

@@ -63,9 +63,9 @@ const { resolveModelInternal, resolveGranularityInternal, assertValidGranularity
 const { findPhaseInternal } = phaseLocator;
 const { getRoadmapPhaseInternal, getMilestoneInfo, getMilestonePhaseFilter, stripShippedMilestones, extractCurrentMilestone, } = roadmapParser;
 const { pathExistsInternal, generateSlugInternal, toPosixPath } = coreUtils;
-const { normalizePhaseName, phaseTokenMatches, stripProjectCodePrefix } = phaseId;
+const { escapeRegex, normalizePhaseName, phaseTokenMatches, stripProjectCodePrefix, PHASE_NUMBER_TOKEN_SOURCE } = phaseId;
 const { pruneOrphanedWorktrees } = worktreeSafety;
-const { planningPaths, planningDir, planningRoot, getActiveWorkstream, findContextMdIn, } = planningWorkspace;
+const { planningPaths, planningDir, planningRoot, listAvailableWorkstreams, getActiveWorkstream, findContextMdIn, } = planningWorkspace;
 const { determinePhaseStatus } = commandsMod;
 const { extractFrontmatter } = frontmatterMod;
 const { readVerificationStatus } = verificationMod;
@@ -74,6 +74,35 @@ const { evaluateUatPassed } = uatPredicateMod;
 void stripShippedMilestones;
 // Accept all bold/colon variants of the Requirements header (#2769)
 const REQUIREMENTS_HEADER_RE = /^\*\*Requirements:?\*\*[^\S\n]*:?[^\S\n]*([^\n]*)$/m;
+// #2056: normalizePhaseName() strips ANY [A-Z][A-Z0-9_]*- prefix as a project
+// code (e.g. 'MEM-01' → '01'), so a foreign-prefixed workstream/task id would
+// collapse to its numeric suffix and resolve to an unrelated numeric phase via
+// the dir/roadmap fallback. init plan-phase must require EXACT prefixed
+// evidence — a phase dir whose token literally IS the prefixed query, or a
+// roadmap entry literally headed with it — before accepting such a match. The
+// configured project_code's own prefix (e.g. LKML-01 under project_code: LKML)
+// is never foreign and always passes through.
+function parsePhasePrefix(phase) {
+    const match = String(phase).match(/^([A-Z][A-Z0-9_]*)-(?=\d)/i);
+    return match ? match[1] : null;
+}
+function isForeignPrefixedPhaseQuery(phase, projectCode) {
+    const prefix = parsePhasePrefix(phase);
+    if (!prefix)
+        return false;
+    const configured = typeof projectCode === 'string' ? projectCode.trim() : '';
+    return !configured || prefix.toUpperCase() !== configured.toUpperCase();
+}
+function phaseInfoMatchesExactPrefix(phaseInfo, phase) {
+    const num = phaseInfo?.['phase_number'];
+    const numStr = typeof num === 'string' ? num : (typeof num === 'number' ? String(num) : '');
+    return numStr.toUpperCase() === phase.toUpperCase();
+}
+function roadmapPhaseMatchesExactPrefix(roadmapPhase, phase) {
+    const sectionRaw = roadmapPhase?.['section'];
+    const section = typeof sectionRaw === 'string' ? sectionRaw : '';
+    return new RegExp(`^#{2,4}\\s*Phase\\s+${escapeRegex(phase)}(?:\\b|\\s|:)`, 'i').test(section);
+}
 function listPhaseSummaryFiles(phaseDir) {
     return scanPhasePlans(phaseDir)['summaryFiles'];
 }
@@ -332,8 +361,18 @@ function cmdInitPlanPhase(cwd, phase, raw, options = {}) {
         error('phase required for init plan-phase');
     }
     const config = loadConfig(cwd);
+    const foreignPrefixedPhase = isForeignPrefixedPhaseQuery(phase, config.project_code);
     let phaseInfo = findPhaseInternal(cwd, phase);
-    const roadmapPhase = getRoadmapPhaseInternal(cwd, phase);
+    // #2056: a foreign-prefixed query must only match a phase whose token literally
+    // IS the prefixed query (e.g. a real 'MEM-01-*' dir); otherwise the numeric
+    // fallback ('MEM-01' → '01') would resolve to the unrelated numeric phase.
+    if (foreignPrefixedPhase && !phaseInfoMatchesExactPrefix(phaseInfo, phase)) {
+        phaseInfo = null;
+    }
+    let roadmapPhase = getRoadmapPhaseInternal(cwd, phase);
+    if (foreignPrefixedPhase && !roadmapPhaseMatchesExactPrefix(roadmapPhase, phase)) {
+        roadmapPhase = null;
+    }
     if (phaseInfo?.['archived'] && roadmapPhase?.['found']) {
         phaseInfo = null;
     }
@@ -573,6 +612,9 @@ function cmdInitQuick(cwd, description, raw) {
         executor_model: resolveModelInternal(cwd, 'gsd-executor'),
         checker_model: resolveModelInternal(cwd, 'gsd-plan-checker'),
         verifier_model: resolveModelInternal(cwd, 'gsd-verifier'),
+        // #2072: the quick review step spawns gsd-code-reviewer; resolve its own model
+        // so model_overrides / models.verification apply (was reusing executor_model).
+        reviewer_model: resolveModelInternal(cwd, 'gsd-code-reviewer'),
         commit_docs: config.commit_docs,
         branch_name: quickBranchName,
         quick_id: quickId,
@@ -874,8 +916,8 @@ 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);
-        // #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;
+        // #1729: `(?:\s*\([^)\n]{0,200}\))?` tolerates a pre-colon ( ) tag (literal mirror of OPTIONAL_PHASE_TAG_SOURCE).
+        const phasePattern = new RegExp(`#{2,4}\\s*Phase\\s+(${PHASE_NUMBER_TOKEN_SOURCE})(?:\\s*\\([^)\\n]{0,200}\\))?\\s*:`, 'gi');
         let m;
         while ((m = phasePattern.exec(currentSection)) !== null) {
             if (/^999(?:\.|$)/.test(m[1]))
@@ -896,7 +938,7 @@ function cmdInitMilestoneOp(cwd, raw) {
         for (const e of entries) {
             if (!e.isDirectory())
                 continue;
-            const m = stripProjectCodePrefix(e.name).match(/^(\d+[A-Z]?(?:\.\d+)*)/);
+            const m = stripProjectCodePrefix(e.name).match(new RegExp(`^(${PHASE_NUMBER_TOKEN_SOURCE})`));
             if (!m)
                 continue;
             diskPhaseDirs.set(canonicalizePhase(m[1]), e.name);
@@ -1024,13 +1066,13 @@ function cmdInitManager(cwd, raw) {
         }
     })();
     const _checkboxStates = new Map();
-    const _cbPattern = /-\s*\[(x| )\]\s*.*Phase\s+(\d+[A-Z]?(?:\.\d+)*)[:\s]/gi;
+    const _cbPattern = new RegExp(`-\\s*\\[(x| )\\]\\s*.*Phase\\s+(${PHASE_NUMBER_TOKEN_SOURCE})[:\\s]`, 'gi');
     let _cbMatch;
     while ((_cbMatch = _cbPattern.exec(content)) !== null) {
         _checkboxStates.set(_cbMatch[2], _cbMatch[1].toLowerCase() === 'x');
     }
-    // #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;
+    // #1729: `(?:\s*\([^)\n]{0,200}\))?` tolerates a pre-colon ( ) tag (literal mirror of OPTIONAL_PHASE_TAG_SOURCE).
+    const phasePattern = new RegExp(`#{2,4}\\s*Phase\\s+(${PHASE_NUMBER_TOKEN_SOURCE})(?:\\s*\\([^)\\n]{0,200}\\))?\\s*:\\s*([^\\n]+)`, 'gi');
     const phases = [];
     let match;
     while ((match = phasePattern.exec(content)) !== null) {
@@ -1148,7 +1190,7 @@ function cmdInitManager(cwd, raw) {
         .filter((p) => p['phase_complete'] === true)
         .map((p) => normalizePhaseNumber(p['number'])));
     const phaseMap = new Map(phases.map((p) => [normalizePhaseNumber(p['number']), p]));
-    const _allCompletedPattern = /-\s*\[x\]\s*.*Phase\s+(\d+[A-Z]?(?:\.\d+)*)[:\s]/gi;
+    const _allCompletedPattern = new RegExp(`-\\s*\\[x\\]\\s*.*Phase\\s+(${PHASE_NUMBER_TOKEN_SOURCE})[:\\s]`, 'gi');
     let _allMatch;
     while ((_allMatch = _allCompletedPattern.exec(rawContent)) !== null) {
         const phaseNum = normalizePhaseNumber(_allMatch[1]);
@@ -1180,7 +1222,7 @@ function cmdInitManager(cwd, raw) {
             phase['deps_satisfied'] = true;
         }
         else {
-            const depNums = phase['depends_on'].match(/\d+[A-Z]?(?:\.\d+)*/gi) || [];
+            const depNums = phase['depends_on'].match(new RegExp(`${PHASE_NUMBER_TOKEN_SOURCE}`, 'gi')) || [];
             phase['deps_satisfied'] = depNums.every((n) => completedNums.has(normalizePhaseNumber(n)));
             phase['dep_phases'] = depNums;
         }
@@ -1319,18 +1361,7 @@ function cmdInitProgress(cwd, raw) {
     // 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 _availableWorkstreams = listAvailableWorkstreams(cwd);
     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. ` +
@@ -1346,14 +1377,14 @@ 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);
-        // #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;
+        // #1729: `(?:\s*\([^)\n]{0,200}\))?` tolerates a pre-colon ( ) tag (literal mirror of OPTIONAL_PHASE_TAG_SOURCE).
+        const headingPattern = new RegExp(`#{2,4}\\s*Phase\\s+(${PHASE_NUMBER_TOKEN_SOURCE})(?:\\s*\\([^)\\n]{0,200}\\))?\\s*:\\s*([^\\n]+)`, 'gi');
         let hm;
         while ((hm = headingPattern.exec(roadmapContent)) !== null) {
             roadmapPhaseNums.add(hm[1]);
             roadmapPhaseNames.set(hm[1], hm[2].replace(/\(INSERTED\)/i, '').trim());
         }
-        const cbPattern = /-\s*\[(x| )\]\s*.*Phase\s+(\d+[A-Z]?(?:\.\d+)*)[:\s]/gi;
+        const cbPattern = new RegExp(`-\\s*\\[(x| )\\]\\s*.*Phase\\s+(${PHASE_NUMBER_TOKEN_SOURCE})[:\\s]`, 'gi');
         let cbm;
         while ((cbm = cbPattern.exec(roadmapContent)) !== null) {
             roadmapCheckboxStates.set(cbm[2], cbm[1].toLowerCase() === 'x');
@@ -1371,14 +1402,14 @@ function cmdInitProgress(cwd, raw) {
             .map((e) => e.name)
             .filter(isDirInMilestone)
             .sort((a, b) => {
-            const pa = a.match(/^(\d+[A-Z]?(?:\.\d+)*)/i);
-            const pb = b.match(/^(\d+[A-Z]?(?:\.\d+)*)/i);
+            const pa = a.match(new RegExp(`^(${PHASE_NUMBER_TOKEN_SOURCE})`, 'i'));
+            const pb = b.match(new RegExp(`^(${PHASE_NUMBER_TOKEN_SOURCE})`, 'i'));
             if (!pa || !pb)
                 return a.localeCompare(b);
             return parseInt(pa[1], 10) - parseInt(pb[1], 10);
         });
         for (const dir of dirs) {
-            const dirMatch = dir.match(/^(\d+[A-Z]?(?:\.\d+)*)-?(.*)/i);
+            const dirMatch = dir.match(new RegExp(`^(${PHASE_NUMBER_TOKEN_SOURCE})-?(.*)`, 'i'));
             const phaseNumber = dirMatch ? dirMatch[1] : dir;
             const phaseName = dirMatch && dirMatch[2] ? dirMatch[2] : null;
             seenPhaseNums.add(phaseNumber.replace(/^0+/, '') || '0');
@@ -1870,11 +1901,24 @@ function buildSkillManifest(cwd, skillsDir = null) {
                 kind: 'skills',
             },
             {
-                root: '~/.codex/skills',
+                // ADR-1239 upgrade 3 (#2088): Codex's canonical skill root is
+                // $HOME/.agents/skills (per codex core-skills loader.rs), resolved via
+                // the skills-kind `home` override in getGlobalSkillsBase.
+                root: '~/.agents/skills',
                 path: (0, runtime_homes_cjs_1.getGlobalSkillsBase)('codex'),
                 scope: 'global',
                 kind: 'skills',
             },
+            {
+                // Codex's deprecated fallback skill root ($CODEX_HOME/skills). Kept as a
+                // discovery-only legacy root so pre-move installs remain inventoried;
+                // GSD no longer installs here (#2088).
+                root: '~/.codex/skills',
+                path: node_path_1.default.join((0, runtime_homes_cjs_1.getGlobalConfigDir)('codex'), 'skills'),
+                scope: 'global',
+                kind: 'skills',
+                deprecated: true,
+            },
             {
                 root: '.claude/gsd-core/skills',
                 path: node_path_1.default.join(node_os_1.default.homedir(), '.claude', 'gsd-core', 'skills'),