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

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

@@ -111,7 +111,8 @@ function parseCallsAgents(content) {
  * `gsd-*` agent name references. Agent stems are stored under the special
  * key `_calls_agents_<stem>` so they don't conflict with skill stems.
  */
-function loadSkillsManifest(commandsDir) {
+const DEFAULT_COMMANDS_DIR = node_path_1.default.resolve(__dirname, '..', '..', '..', 'commands', 'gsd');
+function loadSkillsManifest(commandsDir = DEFAULT_COMMANDS_DIR) {
     const manifest = new Map();
     if (!node_fs_1.default.existsSync(commandsDir))
         return manifest;
@@ -504,6 +505,60 @@ function stageSkillsForRuntimeAsSkills(srcCommandsDir, resolvedProfile, converte
     ensureExitCleanup();
     return stageDir;
 }
+/**
+ * Stage a converted copy of the agents directory for a given runtime.
+ *
+ * Analogous to `stageCommandsForRuntimeFlat` but for agent `.md` files. Each
+ * source `.md` is passed through `converter` and written as a flat `${name}.md`
+ * file in the staging directory. Agent filenames are kept verbatim (no prefix
+ * added here — the prefix is already embedded in agent stems, e.g. `gsd-planner.md`).
+ *
+ * This is used by the descriptor-driven `dispatchKindEntry` when an `agents` kind
+ * entry carries a non-null converter (ADR-457 / #1173). When `converter` is null,
+ * `agentsKind` falls back to the existing raw-copy path (`stageAgentsForProfile`).
+ *
+ * For the `full` profile (`skills === '*'`), all `.md` files are staged.
+ * For tiered profiles, only agents whose full stem is in `resolvedProfile.agents`
+ * are staged (mirrors `stageAgentsForProfile` behaviour).
+ *
+ * @param srcAgentsDir    source agents directory (e.g. agents/)
+ * @param resolvedProfile profile filter from resolveProfile()
+ * @param converter       (content: string) → string  pure per-file converter
+ */
+function stageAgentsForRuntimeWithConverter(srcAgentsDir, resolvedProfile, converter) {
+    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 });
+        for (const entry of entries) {
+            if (!entry.isFile())
+                continue;
+            if (!entry.name.endsWith('.md'))
+                continue;
+            // For tiered profiles, gate by agent stem (full filename without extension).
+            if (resolvedProfile.skills !== '*') {
+                const stem = entry.name.slice(0, -3);
+                if (!(resolvedProfile.agents instanceof Set && resolvedProfile.agents.has(stem))) {
+                    continue;
+                }
+            }
+            const content = node_fs_1.default.readFileSync(node_path_1.default.join(srcAgentsDir, entry.name), 'utf8');
+            const converted = converter(content);
+            node_fs_1.default.writeFileSync(node_path_1.default.join(stageDir, entry.name), converted, 'utf8');
+        }
+    }
+    catch (err) {
+        try {
+            node_fs_1.default.rmSync(stageDir, { recursive: true, force: true });
+        }
+        catch { /* best-effort */ }
+        throw err;
+    }
+    STAGED_DIRS.add(stageDir);
+    ensureExitCleanup();
+    return stageDir;
+}
 /**
  * Stage converted command files as flat `.md` files.
  *
@@ -722,6 +777,7 @@ module.exports = {
     mostRestrictiveProfile,
     stageSkillsForProfile,
     stageAgentsForProfile,
+    stageAgentsForRuntimeWithConverter,
     stageSkillsForRuntimeAsSkills,
     stageCommandsForRuntimeFlat,
     STAGED_DIRS,

package/gsd-core/bin/lib/installer-migration-report.cjs

@@ -38,6 +38,7 @@ exports.BUNDLED_GSD_HOOK_FILES = Object.freeze(new Set([
     'hooks/gsd-context-monitor.js',
     'hooks/gsd-cursor-post-tool.js',
     'hooks/gsd-cursor-session-start.js',
+    'hooks/gsd-ensure-canonical-path.js',
     'hooks/gsd-graphify-update.sh',
     'hooks/gsd-phase-boundary.sh',
     'hooks/gsd-prompt-guard.js',

package/gsd-core/bin/lib/loop-resolver.cjs

@@ -6,7 +6,9 @@
  * filters the materialized Capability Registry by config activation and returns
  * the active hooks as a JSON envelope with a rendered-markdown field.
  *
- * REGISTRY-ONLY: no workflow calls this yet (phase-6 cutover is out of scope).
+ * Consumed live by the landed phase-6 loop-hook cutovers: plan-phase.md / autonomous.md
+ * at plan:pre (ui-phase) and autonomous.md at verify:post (ui-review). Further per-feature
+ * cutovers are ongoing.
  *
  * Command surface: gsd-tools loop render-hooks <point>
  *
@@ -38,6 +40,9 @@ const { output: coreOutput, error: coreError } = core;
 const configLoaderModule = require("./config-loader.cjs");
 const { loadConfig } = configLoaderModule;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
+const capabilityStateModule = require("./capability-state.cjs");
+const { resolveCapabilityRuntimeState } = capabilityStateModule;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
 const planningWorkspaceMod = require("./planning-workspace.cjs");
 const { planningDir, planningRoot } = planningWorkspaceMod;
 // ─── Canonical points (derived from LOOP_HOST_CONTRACT — authoritative 12) ───
@@ -213,7 +218,7 @@ function _resolveActivationValue(dotKey, config, cwd, registry) {
  * resolved against `config`; active iff truthy. Inactive hooks are filtered out.
  */
 function resolveLoopHooks(input) {
-    const { point, registry, config, cwd } = input;
+    const { point, registry, config, cwd, capabilityStatesById } = input;
     // Validate point
     const canonicalPoints = _getCanonicalPoints(registry);
     if (!canonicalPoints.includes(point)) {
@@ -243,31 +248,112 @@ function resolveLoopHooks(input) {
             return false;
         return _resolveActivationValue(when, config, cwd, registry);
     }
+    function isCapabilityEnabled(capId) {
+        if (!capabilityStatesById)
+            return true;
+        const state = capabilityStatesById instanceof Map
+            ? capabilityStatesById.get(capId)
+            : capabilityStatesById[capId];
+        if (!state)
+            return false;
+        return state.enabled !== false;
+    }
     // Helper: safe string array
     function toStringArray(v) {
         if (!Array.isArray(v))
             return [];
         return v.filter((x) => typeof x === 'string');
     }
+    function toFragment(v) {
+        if (!v || typeof v !== 'object' || Array.isArray(v))
+            return undefined;
+        const raw = v;
+        const fragment = {};
+        if (typeof raw.inline === 'string')
+            fragment.inline = raw.inline;
+        if (typeof raw.path === 'string')
+            fragment.path = raw.path;
+        return Object.keys(fragment).length > 0 ? fragment : undefined;
+    }
+    /**
+     * Resolve declared configValues for a contribution hook.
+     * The hook may carry `configValues: { alias: "dotted.key", ... }`.
+     * Each key is resolved using the same four-level precedence as activation resolution,
+     * but returning the raw value (not coerced to boolean) so numeric/string config values
+     * are preserved (e.g. security_asvs_level: 2, security_block_on: "medium").
+     */
+    function resolveConfigValues(hook) {
+        const raw = hook['configValues'];
+        if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+            return undefined;
+        const rawMap = raw;
+        const resolved = {};
+        for (const [alias, dotKey] of Object.entries(rawMap)) {
+            // Prototype-pollution guard (inline literal, CodeQL barrier)
+            if (alias === '__proto__' || alias === 'constructor' || alias === 'prototype')
+                continue;
+            if (typeof dotKey !== 'string')
+                continue;
+            // Level 1: loadConfig result
+            const fromConfig = _getNestedConfigValue(config, dotKey);
+            if (fromConfig.found) {
+                resolved[alias] = fromConfig.value;
+                continue;
+            }
+            // Level 2 + 3: raw config.json files
+            if (cwd) {
+                const wsConfigPath = node_path_1.default.join(planningDir(cwd), 'config.json');
+                const rootConfigPath = node_path_1.default.join(planningRoot(cwd), 'config.json');
+                const fromWs = _readRawConfigKey(wsConfigPath, dotKey);
+                if (fromWs.found) {
+                    resolved[alias] = fromWs.value;
+                    continue;
+                }
+                if (wsConfigPath !== rootConfigPath) {
+                    const fromRoot = _readRawConfigKey(rootConfigPath, dotKey);
+                    if (fromRoot.found) {
+                        resolved[alias] = fromRoot.value;
+                        continue;
+                    }
+                }
+            }
+            // Level 4: registry configSchema default
+            const schemaEntry = registry['configSchema']?.[dotKey];
+            if (schemaEntry && typeof schemaEntry === 'object' && schemaEntry !== null) {
+                const def = schemaEntry['default'];
+                if (def !== undefined) {
+                    resolved[alias] = def;
+                    continue;
+                }
+            }
+            // Level 5: absent → undefined (omit from resolved map)
+        }
+        return Object.keys(resolved).length > 0 ? resolved : undefined;
+    }
     // Process steps
     const stepsRaw = entryMap['steps'];
     const steps = Array.isArray(stepsRaw) ? stepsRaw : [];
     for (const hook of steps) {
         if (!hook || typeof hook !== 'object')
             continue;
+        const capId = typeof hook['capId'] === 'string' ? hook['capId'] : '';
+        if (!isCapabilityEnabled(capId))
+            continue;
         if (!isActive(hook))
             continue;
-        const capId = typeof hook['capId'] === 'string' ? hook['capId'] : '';
         const ref = (typeof hook['ref'] === 'object' && hook['ref'] !== null)
             ? hook['ref']
             : undefined;
         const when = typeof hook['when'] === 'string' ? hook['when'] : undefined;
+        const fragment = toFragment(hook['fragment']);
         const produces = toStringArray(hook['produces']);
         const consumes = toStringArray(hook['consumes']);
         const onError = typeof hook['onError'] === 'string' ? hook['onError'] : undefined;
         const active = { capId, kind: 'step' };
         if (ref !== undefined)
             active.ref = ref;
+        if (fragment !== undefined)
+            active.fragment = fragment;
         if (when !== undefined)
             active.when = when;
         if (produces.length > 0)
@@ -284,17 +370,23 @@ function resolveLoopHooks(input) {
     for (const hook of contributions) {
         if (!hook || typeof hook !== 'object')
             continue;
+        const capId = typeof hook['capId'] === 'string' ? hook['capId'] : '';
+        if (!isCapabilityEnabled(capId))
+            continue;
         if (!isActive(hook))
             continue;
-        const capId = typeof hook['capId'] === 'string' ? hook['capId'] : '';
         const into = typeof hook['into'] === 'string' ? hook['into'] : undefined;
+        const fragment = toFragment(hook['fragment']);
         const when = typeof hook['when'] === 'string' ? hook['when'] : undefined;
         const produces = toStringArray(hook['produces']);
         const consumes = toStringArray(hook['consumes']);
         const onError = typeof hook['onError'] === 'string' ? hook['onError'] : undefined;
+        const configValuesResolved = resolveConfigValues(hook);
         const active = { capId, kind: 'contribution' };
         if (into !== undefined)
             active.into = into;
+        if (fragment !== undefined)
+            active.fragment = fragment;
         if (when !== undefined)
             active.when = when;
         if (produces.length > 0)
@@ -303,6 +395,8 @@ function resolveLoopHooks(input) {
             active.consumes = consumes;
         if (onError !== undefined)
             active.onError = onError;
+        if (configValuesResolved !== undefined)
+            active.configValues = configValuesResolved;
         activeHooks.push(active);
     }
     // Process gates
@@ -311,9 +405,11 @@ function resolveLoopHooks(input) {
     for (const hook of gates) {
         if (!hook || typeof hook !== 'object')
             continue;
+        const capId = typeof hook['capId'] === 'string' ? hook['capId'] : '';
+        if (!isCapabilityEnabled(capId))
+            continue;
         if (!isActive(hook))
             continue;
-        const capId = typeof hook['capId'] === 'string' ? hook['capId'] : '';
         const when = typeof hook['when'] === 'string' ? hook['when'] : undefined;
         const check = hook['check'] !== undefined ? hook['check'] : undefined;
         const blocking = typeof hook['blocking'] === 'boolean' ? hook['blocking'] : undefined;
@@ -352,7 +448,9 @@ function renderLoopHooks(resolved) {
             stepOrdinal += 1;
             const refStr = hook.ref?.skill
                 ? `skill:${hook.ref.skill}`
-                : JSON.stringify(hook.ref ?? {});
+                : hook.ref?.agent
+                    ? `agent:${hook.ref.agent}`
+                    : JSON.stringify(hook.ref ?? {});
             lines.push(`### Step ${stepOrdinal}: ${refStr} (${hook.capId})`);
             if (hook.produces && hook.produces.length > 0) {
                 lines.push(`- produces: ${hook.produces.join(', ')}`);
@@ -366,10 +464,24 @@ function renderLoopHooks(resolved) {
             if (hook.onError) {
                 lines.push(`- onError: ${hook.onError}`);
             }
+            if (hook.fragment?.inline) {
+                lines.push('');
+                lines.push(hook.fragment.inline);
+            }
+            else if (hook.fragment?.path) {
+                lines.push('');
+                lines.push(`_Step fragment path is declared but not rendered by loop-resolver: ${hook.fragment.path}_`);
+            }
             lines.push('');
         }
         else if (hook.kind === 'contribution') {
-            lines.push(`<contribution from="${hook.capId}" into="${hook.into ?? '(unset)'}"/>`);
+            lines.push(`<contribution from="${hook.capId}" into="${hook.into ?? '(unset)'}">`);
+            if (hook.fragment?.inline) {
+                lines.push(hook.fragment.inline);
+            }
+            else if (hook.fragment?.path) {
+                lines.push(`_Contribution fragment path is declared but not rendered by loop-resolver: ${hook.fragment.path}_`);
+            }
             if (hook.produces && hook.produces.length > 0) {
                 lines.push(`- produces: ${hook.produces.join(', ')}`);
             }
@@ -379,6 +491,10 @@ function renderLoopHooks(resolved) {
             if (hook.when) {
                 lines.push(`- when: \`${hook.when}\``);
             }
+            if (hook.onError) {
+                lines.push(`- onError: ${hook.onError}`);
+            }
+            lines.push('</contribution>');
             lines.push('');
         }
         else if (hook.kind === 'gate') {
@@ -417,34 +533,59 @@ function renderLoopHooks(resolved) {
  * merged-object-from-untrusted-keys security concern and correctly handles
  * pre-cutover keys like `workflow.ui_phase` that live in config.json but are not
  * yet exposed through loadConfig's whitelist.
+ *
+ * --active-cap <capId>: when present, resolves hooks for <point> exactly as the
+ * normal path does, then prints exactly `true` (if any resolved activeHook has
+ * capId === <capId>) or `false` followed by a single newline, and exits 0.
+ * No JSON envelope is emitted — output is clean for shell $(…) capture.
+ * Missing <capId> value → coreError + non-zero exit.
+ * Unknown/inactive capId → `false` (not an error).
  */
-function cmdLoopRenderHooks(cwd, point, raw, _options = {}) {
+function cmdLoopRenderHooks(cwd, point, raw, options = {}) {
     if (!point) {
         coreError('loop render-hooks requires a <point> argument. Valid points: ' + CANONICAL_POINTS.join(', '));
         return;
     }
-    // Load registry at call time (generated file, not at module load time)
-    // eslint-disable-next-line @typescript-eslint/no-require-imports
-    const registry = require('./capability-registry.cjs');
-    // FIX 1: Pass loadConfig result as `config` (level 1 of precedence);
-    // raw config.json reads (levels 2+3) happen per-hook inside _resolveActivationValue
-    // via the `cwd` argument passed to resolveLoopHooks.
-    const config = loadConfig(cwd);
+    // --active-cap <capId> mode: emit 'true' or 'false' only (scanner-safe, no JSON envelope)
+    const activeCapId = typeof options['activeCap'] === 'string' ? options['activeCap'] : undefined;
+    if (activeCapId !== undefined && activeCapId === '') {
+        coreError('--active-cap requires a <capId> value (e.g. --active-cap tdd)');
+        return;
+    }
+    const runtimeConfigDir = typeof options['configDir'] === 'string'
+        ? options['configDir']
+        : undefined;
+    const state = resolveCapabilityRuntimeState(cwd, runtimeConfigDir);
+    const registry = state.registry;
+    const config = state.config || loadConfig(cwd);
+    const capabilityStatesById = new Map();
+    for (const cap of state.capabilities || []) {
+        capabilityStatesById.set(cap.id, cap);
+    }
     let resolved;
     try {
-        resolved = resolveLoopHooks({ point, registry, config, cwd });
+        resolved = resolveLoopHooks({ point, registry, config, cwd, capabilityStatesById });
     }
     catch (err) {
         const msg = (err instanceof Error) ? err.message : String(err);
         coreError(msg);
         return;
     }
+    // --active-cap mode: print exactly 'true' or 'false' with no envelope
+    if (activeCapId !== undefined) {
+        const isActive = resolved.activeHooks.some((h) => h.capId === activeCapId);
+        process.stdout.write(isActive ? 'true\n' : 'false\n');
+        return;
+    }
     const rendered = renderLoopHooks(resolved);
     const envelope = {
         point: resolved.point,
         activeHooks: resolved.activeHooks,
         rendered,
     };
+    if (state.warnings && state.warnings.length > 0) {
+        envelope.warnings = state.warnings;
+    }
     coreOutput(envelope, raw);
 }
 module.exports = {

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

@@ -55,6 +55,30 @@ function _resolveRuntimeTier(config, tier) {
         overrides: config['model_profile_overrides'],
     });
 }
+// Reverse of the Claude tier-default IDs, plus the Fable alias which Claude
+// Code's Agent tool accepts but which is not a GSD model-profile tier (#1133).
+const CLAUDE_POLICY_ID_TO_ALIAS = {
+    ...Object.fromEntries(Object.entries(model_catalog_cjs_1.MODEL_ALIAS_MAP)
+        .filter((e) => typeof e[1] === 'string')
+        .map(([aliasName, id]) => [id, aliasName])),
+    'claude-fable-5': 'fable',
+};
+const CLAUDE_AGENT_ALIASES = new Set(['opus', 'sonnet', 'haiku', 'fable']);
+// Dedupe stderr warnings so repeated agent resolutions don't spam (#1133).
+const _modelPolicyUnmappableWarned = new Set();
+function warnModelPolicyUnmappable(agentType, policyModel, tier) {
+    const key = `${agentType}::${policyModel}::${tier}`;
+    if (_modelPolicyUnmappableWarned.has(key))
+        return;
+    _modelPolicyUnmappableWarned.add(key);
+    // MUST go to stderr — resolve-model's JSON result is parsed from stdout.
+    process.stderr.write(`gsd: warning — model_policy resolved "${policyModel}" for ${agentType}, ` +
+        `but it has no Claude agent alias; using "${tier}" instead.\n`);
+}
+// Test-only: reset the model_policy warn-dedupe cache between cases (#1133).
+function _resetModelPolicyWarningCacheForTests() {
+    _modelPolicyUnmappableWarned.clear();
+}
 /**
  * #49 — Provider-neutral model policy preset resolution.
  */
@@ -132,15 +156,32 @@ function resolveModelInternal(cwd, agentType) {
         : (profile === 'inherit'
             ? 'inherit'
             : (agentModels ? (agentModels[profile] || agentModels['balanced']) : null));
-    // 2.5. model_policy preset (#49)
+    // 2.5. model_policy preset (#49, #1133)
     const configRuntime = config['runtime'];
-    if (configRuntime && configRuntime !== 'claude' && tier && tier !== 'inherit') {
+    if (tier && tier !== 'inherit') {
+        const onClaude = !configRuntime || configRuntime === 'claude';
+        const effectiveRuntime = configRuntime || 'claude';
         const mergedPolicy = config['model_policy']
-            ? { ...config['model_policy'], runtime: configRuntime }
+            ? { ...config['model_policy'], runtime: effectiveRuntime }
             : null;
         const policyModel = resolveModelPolicy(mergedPolicy, tier);
-        if (policyModel)
-            return policyModel;
+        if (policyModel) {
+            // Non-Claude runtimes take full model IDs verbatim (unchanged behavior).
+            if (!onClaude)
+                return policyModel;
+            // Claude Code's Agent tool takes tier aliases (opus/sonnet/haiku/fable),
+            // not full model IDs — map the policy-resolved ID back to an alias (#1133).
+            const aliasForId = CLAUDE_POLICY_ID_TO_ALIAS[policyModel];
+            if (aliasForId)
+                return aliasForId;
+            // The policy value may already be a bare Claude agent alias (e.g. "fable").
+            if (CLAUDE_AGENT_ALIASES.has(policyModel))
+                return policyModel;
+            // No Claude alias for this ID (e.g. a pinned minor version like
+            // claude-opus-4-5). Warn once and fall through to the tier alias rather
+            // than returning an ID Claude Code cannot spawn.
+            warnModelPolicyUnmappable(agentType, policyModel, tier);
+        }
     }
     // 3. Runtime-aware resolution (#2517)
     if (configRuntime && configRuntime !== 'claude' && tier && tier !== 'inherit') {
@@ -413,6 +454,7 @@ module.exports = {
     resolveTierEntry,
     resolveModelPolicy,
     resolveModelInternal,
+    _resetModelPolicyWarningCacheForTests,
     VALID_GRANULARITIES,
     resolveGranularityInternal,
     assertValidGranularityOverride,

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

@@ -32,6 +32,7 @@ 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 phase_lifecycle_cjs_1 = require("./phase-lifecycle.cjs");
+const clock_cjs_1 = require("./clock.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- uat-predicate.cjs is an export= CommonJS module
 const uatPredicate = require("./uat-predicate.cjs");
 const { evaluateUatPassed } = uatPredicate;
@@ -559,16 +560,29 @@ function cmdPhaseAdd(cwd, description, raw, customId) {
             _dirName = `${prefix}${_newPhaseId}-${slug}`;
         }
         else {
-            const phasePattern = /#{2,4}\s*Phase\s+(\d+)[A-Z]?(?:\.\d+)*:/gi;
-            let maxPhase = 0;
+            // Collect all phase numbers visible in the current-milestone content.
+            // 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;
+            // 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")
+            // are counted and cannot collide with a freshly-added phase. (#1229)
+            const bulletPattern = /^[ \t]*-[ \t]*\[[^\]]*\][ \t]*\*{0,2}Phase[ \t]+(\d+)(?=[:.\s*]|$)/gim;
+            const usedPhaseNums = new Set();
             let m;
-            while ((m = phasePattern.exec(content)) !== null) {
+            while ((m = headerPattern.exec(content)) !== null) {
                 const num = parseInt(m[1], 10);
-                if (num === 999)
-                    continue;
-                if (num > maxPhase)
-                    maxPhase = num;
+                if (num !== 999)
+                    usedPhaseNums.add(num);
+            }
+            while ((m = bulletPattern.exec(content)) !== null) {
+                const num = parseInt(m[1], 10);
+                if (num !== 999)
+                    usedPhaseNums.add(num);
             }
+            // 3) On-disk phase directories (e.g. phases/11-foo/ with no header yet)
             const phasesOnDisk = node_path_1.default.join(planningDir(cwd), 'phases');
             if (node_fs_1.default.existsSync(phasesOnDisk)) {
                 const dirNumPattern = /^(?:[A-Z][A-Z0-9]*-)?(\d+)-/;
@@ -577,13 +591,16 @@ function cmdPhaseAdd(cwd, description, raw, customId) {
                     if (!match)
                         continue;
                     const num = parseInt(match[1], 10);
-                    if (num === 999)
-                        continue;
-                    if (num > maxPhase)
-                        maxPhase = num;
+                    if (num !== 999)
+                        usedPhaseNums.add(num);
                 }
             }
-            _newPhaseId = maxPhase + 1;
+            // phase.add appends after the highest *used* number. Collecting numbers from
+            // section headers, roadmap bullets, AND on-disk dirs above is what prevents the
+            // #1229 collision (a bullet-only Phase N is now counted), so max+1 cannot reuse
+            // an existing number.
+            const maxUsed = usedPhaseNums.size > 0 ? Math.max(...usedPhaseNums) : 0;
+            _newPhaseId = maxUsed + 1;
             const paddedNum = String(_newPhaseId).padStart(2, '0');
             _dirName = `${prefix}${paddedNum}-${slug}`;
         }
@@ -1019,7 +1036,7 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
     const roadmapPath = node_path_1.default.join(planningDir(cwd), 'ROADMAP.md');
     const statePath = node_path_1.default.join(planningDir(cwd), 'STATE.md');
     const phasesDir = node_path_1.default.join(planningDir(cwd), 'phases');
-    const today = new Date().toISOString().split('T')[0];
+    const today = clock_cjs_1.realClock.today();
     const phaseInfoRaw = findPhaseInternal(cwd, phaseNum);
     if (!phaseInfoRaw) {
         error(`Phase ${phaseNum} not found`);
@@ -1049,9 +1066,17 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
         }
         for (const file of phaseFiles.filter((f) => f.includes('-VERIFICATION') && f.endsWith('.md'))) {
             const content = node_fs_1.default.readFileSync(node_path_1.default.join(phaseFullDir, file), 'utf-8');
-            if (/status: human_needed/.test(content))
+            // #1159 (Defect A): read ONLY the frontmatter `status` key to avoid false positives
+            // from historical metadata in the file body (e.g. `previous_status: gaps_found`).
+            // A full-text regex like /status: gaps_found/ matches the substring inside
+            // `previous_status: gaps_found`, producing spurious warnings even when the
+            // current frontmatter status is `passed`.
+            const verFm = extractFrontmatter(content);
+            // Normalise to lower-case so `status: Passed` (title-case) is not missed.
+            const verStatus = typeof verFm['status'] === 'string' ? verFm['status'].trim().toLowerCase() : '';
+            if (verStatus === 'human_needed')
                 warnings.push(`${file}: needs human verification`);
-            if (/status: gaps_found/.test(content))
+            if (verStatus === 'gaps_found')
                 warnings.push(`${file}: has unresolved gaps`);
         }
     }
@@ -1074,15 +1099,20 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
                 const tableRowPattern = new RegExp(`^(\\|\\s*${phaseEscaped}\\.?\\s[^|]*(?:\\|[^\\n]*))$`, 'im');
                 roadmapContent = roadmapContent.replace(tableRowPattern, (fullRow) => {
                     const cells = fullRow.split('|').slice(1, -1);
+                    const dateShape = /^\d{4}-\d{2}-\d{2}$/;
                     if (cells.length === 5) {
                         cells[2] = ` ${summaryCount}/${planCount} `;
                         cells[3] = ' Complete    ';
-                        cells[4] = ` ${today} `;
+                        // Preserve only a valid ISO date (#1161: idempotent; self-heal garbage)
+                        const existingDate5 = cells[4].trim();
+                        cells[4] = dateShape.test(existingDate5) ? cells[4] : ` ${today} `;
                     }
                     else if (cells.length === 4) {
                         cells[1] = ` ${summaryCount}/${planCount} `;
                         cells[2] = ' Complete    ';
-                        cells[3] = ` ${today} `;
+                        // Preserve only a valid ISO date (#1161: idempotent; self-heal garbage)
+                        const existingDate4 = cells[3].trim();
+                        cells[3] = dateShape.test(existingDate4) ? cells[3] : ` ${today} `;
                     }
                     return '|' + cells.join('|') + '|';
                 });
@@ -1123,13 +1153,59 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
                             reqContent = reqContent.replace(new RegExp(`(\\|\\s*${reqEscaped}\\s*\\|[^|]+\\|)\\s*(?:Pending|In Progress)\\s*(\\|)`, 'gi'), '$1 Complete $2');
                         }
                     }
+                    // #1159 (Defect B): collect requirement IDs only from ACTIVE sections.
+                    // Requirements under headings whose text contains "deferred", "backlog",
+                    // "future", or "v2" (case-insensitive) are explicitly out of current scope
+                    // and must not be flagged as missing from the Traceability table.
+                    //
+                    // Strategy: walk lines, track heading depth, and toggle a "deferred" flag
+                    // when a heading matching the pattern is encountered.  A sub-heading (higher
+                    // depth) that is ITSELF in a deferred parent remains deferred unless it
+                    // opens a same-or-shallower heading that does NOT match the pattern.
+                    // Lines inside fenced code blocks (``` or ~~~) are treated as content, not
+                    // headings, to avoid false deferred-section detection from code examples.
+                    const DEFERRED_HEADING_RE = /\b(?:deferred|backlog|future|v\d+)\b/i;
                     const bodyReqIds = [];
-                    const bodyReqPattern = /\*\*([A-Z][A-Z0-9]*-\d+)\*\*/g;
-                    let bodyMatch;
-                    while ((bodyMatch = bodyReqPattern.exec(reqContent)) !== null) {
-                        const id = bodyMatch[1];
-                        if (!bodyReqIds.includes(id))
-                            bodyReqIds.push(id);
+                    // deferredDepth: the heading level that opened the current deferred block,
+                    // or 0 when we are in an active section.
+                    let deferredDepth = 0;
+                    let inFence = false;
+                    for (const line of reqContent.split(/\r?\n/)) {
+                        // Track fenced code blocks (``` or ~~~).
+                        if (/^\s*(?:```|~~~)/.test(line)) {
+                            inFence = !inFence;
+                            continue;
+                        }
+                        if (inFence)
+                            continue; // ignore content inside a code fence
+                        const headingM = line.match(/^(#{1,6})\s+(.*)/);
+                        if (headingM) {
+                            const depth = headingM[1].length;
+                            const text = headingM[2];
+                            if (deferredDepth > 0 && depth > deferredDepth) {
+                                // Sub-heading inside a deferred block: stays deferred regardless of name.
+                                continue;
+                            }
+                            // Heading at same level or shallower than current deferred opener,
+                            // or no active deferred block yet.
+                            if (DEFERRED_HEADING_RE.test(text)) {
+                                deferredDepth = depth; // enter a deferred block
+                            }
+                            else {
+                                deferredDepth = 0; // back in an active section
+                            }
+                            continue;
+                        }
+                        if (deferredDepth > 0)
+                            continue; // skip content in deferred sections
+                        // Collect bold REQ-ID patterns from active-section lines.
+                        const reqPat = /\*\*([A-Z][A-Z0-9]*-\d+)\*\*/g;
+                        let bodyMatch;
+                        while ((bodyMatch = reqPat.exec(line)) !== null) {
+                            const id = bodyMatch[1];
+                            if (!bodyReqIds.includes(id))
+                                bodyReqIds.push(id);
+                        }
                     }
                     const traceabilityHeadingMatch = reqContent.match(/^#{1,6}\s+Traceability\b/im);
                     const traceabilitySection = traceabilityHeadingMatch