@opengsd/gsd-core 1.10.0 → 1.11.0

package/gsd-core/bin/lib/refactor-trigger-command-router.cjs

@@ -0,0 +1,740 @@
+'use strict';
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+/**
+ * Refactor-trigger command router — CLI subcommand dispatcher for
+ * `gsd-tools refactor` (issue #1953).
+ *
+ * Follows `src/intel-command-router.cts` exactly: `routeHubCommandFamily`,
+ * `makeInvalidArgs` for validation failures, `output(value, raw)` for
+ * success, `_`-prefixed injection seams, lazy `require` of the heavy leaf
+ * module (`complexity-trigger.cjs`) and the adjacent modules
+ * (`git-base-branch.cjs`, `broken-windows.cjs`) inside the route function.
+ *
+ * Authoritative surfaces:
+ *   .gsd/phase/feat-1953-complexity-triggered-refactor/42-router-contract.md
+ *   .gsd/phase/feat-1953-complexity-triggered-refactor/41-api-contract.md
+ *
+ * `src/complexity-trigger.cts` stays a pure leaf (analyzer, evaluator,
+ * baseline persistence) — this module owns capability-activation gating,
+ * git invocation (via the `src/git-base-branch.cts` adapters), config
+ * reads, CLI arg parsing, phase-directory resolution, and the optional
+ * broken-windows ledger integration. It never duplicates the leaf's logic.
+ *
+ * Arg indexing:
+ *   args[0] = 'refactor'   (family — matched by dispatchCapabilityCommand)
+ *   args[1] = subcommand   (accept | decline | evaluate | status)
+ *   args[2..] = flags      (--phase, --since, --reason, --raw)
+ *
+ * Seams: `_complexity` (complexity-trigger.cjs), `_git` (git-base-branch.cjs),
+ * `_windows` (broken-windows.cjs — OPTIONAL; absent or a throwing `require`
+ * is the documented degrade path, never an error), `_core` (output capture).
+ * Production callers omit all four.
+ */
+const node_path_1 = __importDefault(require("node:path"));
+const node_fs_1 = __importDefault(require("node:fs"));
+const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const io = require("./io.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const commandRoutingHub = require("./command-routing-hub.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const cjsCommandRouterAdapter = require("./cjs-command-router-adapter.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const capabilityStateMod = require("./capability-state.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const capabilityActivationMod = require("./capability-activation.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const configLoaderMod = require("./config-loader.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const phaseLocatorMod = require("./phase-locator.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const planningWorkspaceMod = require("./planning-workspace.cjs");
+const { output } = io;
+const { makeInvalidArgs } = commandRoutingHub;
+const { routeHubCommandFamily } = cjsCommandRouterAdapter;
+const { isCapabilityActive } = capabilityStateMod;
+const { resolveConfigKey } = capabilityActivationMod;
+const { loadConfig } = configLoaderMod;
+const { findPhaseInternal, listMilestonePhaseDirs } = phaseLocatorMod;
+const { planningDir } = planningWorkspaceMod;
+const CAPABILITY_ID = 'refactor-trigger';
+// Default CoreModule implementation. `_core` seam overrides this entirely
+// for test injection (captures output calls without writing to real stdout).
+const _defaultCore = { output };
+// ─── Disabled response ──────────────────────────────────────────────────────
+function disabledResponse() {
+    return {
+        disabled: true,
+        message: 'refactor-trigger is not enabled. Enable with: gsd config-set refactor.trigger_enabled true',
+    };
+}
+// ─── Arg parsing ────────────────────────────────────────────────────────────
+// Positive integer, optionally zero-padded, optionally with dotted decimal
+// sub-phase segments (1, 01, 12, 3.1). Rejects 0, negative, letters, and
+// whitespace — matches the router contract's "positive integer or decimal
+// phase id" rule.
+const PHASE_VALUE_RE = /^0*[1-9]\d*(?:\.\d+)*$/;
+/**
+ * Reads a `--flag value` or `--flag=value` occurrence from `args`. Repeated
+ * occurrences are reported via `duplicated` (the last one wins in `value`,
+ * but callers should treat `duplicated` as invalid input). A token
+ * immediately following `--flag` that itself starts with `--` (or the flag
+ * being the last token) is NOT consumed as a value — `flagShaped` is set and
+ * `value` stays `''`, so `--phase --raw` never silently swallows `--raw`.
+ */
+function readFlag(args, flag) {
+    let present = false;
+    let value = '';
+    let count = 0;
+    let flagShaped = false;
+    const eqPrefix = `${flag}=`;
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === flag) {
+            count++;
+            present = true;
+            const next = args[i + 1];
+            if (next === undefined) {
+                value = '';
+            }
+            else if (next.startsWith('--')) {
+                value = '';
+                flagShaped = true;
+            }
+            else {
+                value = next;
+                flagShaped = false;
+            }
+        }
+        else if (a.startsWith(eqPrefix)) {
+            count++;
+            present = true;
+            value = a.slice(eqPrefix.length);
+            flagShaped = false;
+        }
+    }
+    return { present, value, duplicated: count > 1, flagShaped };
+}
+/**
+ * Validate `--phase`: required, and a positive integer or decimal phase id.
+ * Empty, whitespace-only, duplicated, `--phase=`, `--phase==N`, or a
+ * flag-shaped value all fail. Missing entirely -> REFACTOR_USAGE (no value
+ * was ever offered); present but invalid -> REFACTOR_INVALID_PHASE (a value
+ * was given but rejected). Never throws.
+ */
+function requirePhaseArg(args, complexity, usage) {
+    const flag = readFlag(args, '--phase');
+    if (!flag.present) {
+        return { ok: false, result: makeInvalidArgs('phase', usage, complexity.REASON.REFACTOR_USAGE) };
+    }
+    const trimmed = flag.value.trim();
+    if (flag.duplicated || flag.flagShaped || trimmed === '' || !PHASE_VALUE_RE.test(trimmed)) {
+        return {
+            ok: false,
+            result: makeInvalidArgs('phase', `Invalid --phase value: ${JSON.stringify(flag.value)}. ${usage}`, complexity.REASON.REFACTOR_INVALID_PHASE),
+        };
+    }
+    return { ok: true, phase: trimmed };
+}
+/**
+ * Resolve the on-disk phase directory for a validated `--phase` value. A
+ * phase that cannot be located on disk (never planned, wrong number, an
+ * archived milestone this call isn't scoped to) returns `null` — this is a
+ * distinct fact from a git failure (git is fine; the phase just doesn't
+ * exist), so callers report REFACTOR_INVALID_PHASE, never
+ * REFACTOR_GIT_UNAVAILABLE, for this case.
+ */
+function resolvePhaseDirForArg(cwd, phaseArg) {
+    const search = findPhaseInternal(cwd, phaseArg);
+    if (!search || search.found !== true)
+        return null;
+    return { phaseDir: search.directory, padded: search.phase_number };
+}
+/**
+ * Resolve `relFile` (a repo-relative path, typically from `git diff
+ * --name-only`) against `cwd` and refuse a path that escapes the project
+ * root. Returns the absolute path, or `null` when it escapes.
+ *
+ * Two layers: the string-level `startsWith` check is a cheap first gate but
+ * confines only the SYMLINK's own path, not its target — a symlink
+ * committed in the repo (e.g. `src/evil.cts -> /etc/passwd`) has an
+ * in-tree path that passes the string check, and `fs.readFileSync` on it
+ * would follow the link and read outside the root. `lstatSync` (which does
+ * NOT follow symlinks, unlike `statSync`) is the second gate: anything that
+ * is not a regular file — a symlink most of all — is refused outright.
+ * Refusing rather than resolving-and-re-confining is deliberate: it is
+ * simpler and strictly stricter (a symlink whose target legitimately lives
+ * inside the root is still refused, which is an acceptable false positive
+ * for this analyzer). An `lstatSync` failure (ENOENT on a broken symlink,
+ * EACCES, a race) is treated the same as "not a regular file" — never
+ * propagated — so callers can keep using their existing null-means-skip
+ * convention (`REASON.REFACTOR_FILE_UNREADABLE`) uniformly.
+ */
+function resolveConfinedPath(cwd, relFile) {
+    const root = node_path_1.default.resolve(cwd);
+    const resolved = node_path_1.default.resolve(root, relFile);
+    if (resolved !== root && !resolved.startsWith(root + node_path_1.default.sep))
+        return null;
+    try {
+        if (!node_fs_1.default.lstatSync(resolved).isFile())
+            return null;
+    }
+    catch {
+        return null;
+    }
+    return resolved;
+}
+function artifactFileName(padded, complexity) {
+    return `${padded}${complexity.PROPOSAL_SUFFIX}`;
+}
+function artifactAbsPath(cwd, phaseDir, padded, complexity) {
+    return node_path_1.default.join(cwd, phaseDir, artifactFileName(padded, complexity));
+}
+function candidateKey(file, name) {
+    return `${file}::${name}`;
+}
+// ─── Atomic write (proposal + ledger) ───────────────────────────────────────
+/**
+ * Atomic publish: write a sibling `.tmp.<pid>` file, then rename over the
+ * target via `retryRenameSync` (transient-Windows-lock-tolerant — matches
+ * `local/require-fs-op-fallback`, ADR-1703 Phase 6). On any failure, best-
+ * effort unlinks the temp file and rethrows.
+ */
+function writeTextAtomic(filePath, content) {
+    node_fs_1.default.mkdirSync(node_path_1.default.dirname(filePath), { recursive: true });
+    const tmp = `${filePath}.${process.pid}.tmp`;
+    node_fs_1.default.writeFileSync(tmp, content, 'utf8');
+    try {
+        (0, shell_command_projection_cjs_1.retryRenameSync)(tmp, filePath);
+    }
+    catch (err) {
+        try {
+            node_fs_1.default.unlinkSync(tmp);
+        }
+        catch { /* best-effort cleanup */ }
+        throw err;
+    }
+}
+// ─── Config reads ───────────────────────────────────────────────────────────
+/**
+ * Read `refactor.complexity_threshold` / `refactor.complexity_jump_delta` /
+ * `refactor.trigger_strict` via the same four-level precedence walk
+ * (`resolveConfigKey`) the capability-activation gate uses: loadConfig
+ * result -> workstream config.json -> root config.json -> registry
+ * `configSchema` default. Reading the frozen first-party registry directly
+ * is deliberate (not `capability-loader.cjs`'s `loadRegistry`): with
+ * `includeInstalled` omitted, `loadRegistry()` returns the exact same frozen
+ * object — refactor-trigger is first-party, so the overlay/consent machinery
+ * has nothing to add here and this avoids the extra indirection.
+ */
+function readEvalConfig(cwd) {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const registry = require('./capability-registry.cjs');
+    const config = loadConfig(cwd);
+    const threshold = resolveConfigKey('refactor.complexity_threshold', { config, cwd, registry }).value;
+    const jumpDelta = resolveConfigKey('refactor.complexity_jump_delta', { config, cwd, registry }).value;
+    const strict = resolveConfigKey('refactor.trigger_strict', { config, cwd, registry }).value;
+    // Read via the SAME four-level precedence walk as the `refactor.*` keys
+    // above — reusing `resolveConfigKey`/`loadConfig`/the frozen registry
+    // rather than a second config reader. A missing key resolves to the
+    // registry default (false), matching "treat a missing key as falsy".
+    const windowsEnforce = resolveConfigKey('workflow.windows_enforce', { config, cwd, registry }).value;
+    return { threshold, jumpDelta, strict: Boolean(strict), windowsEnforce: Boolean(windowsEnforce) };
+}
+// ─── Strict-mode enforcement-gap warning (#1953) ────────────────────────────
+const WINDOWS_ENFORCE_REMEDIATION = 'gsd config-set workflow.windows_enforce true';
+/**
+ * `refactor.trigger_strict` only ever APPENDS a deviation window to the
+ * broken-windows ledger — a ship only actually stops when the separate
+ * `workflow.windows_enforce` toggle is also on. A user who enables only
+ * `refactor.trigger_strict` gets tracking with no enforcement and, absent
+ * this warning, no signal that this is the case. Fires strictly on TRIGGERED
+ * evaluates with strict mode on, mirroring the existing ledger-recording
+ * gate: either the broken-windows capability could not record the window at
+ * all (`ledgerRecorded === false` — the existing degrade path), or it did,
+ * but `workflow.windows_enforce` is falsy. Never fires with strict off.
+ */
+function strictNotEnforcingWarning(complexity, ledgerRecorded, windowsEnforce) {
+    if (!ledgerRecorded) {
+        return {
+            reason: complexity.REASON.REFACTOR_STRICT_NOT_ENFORCING,
+            message: 'refactor.trigger_strict is on, but the broken-windows capability is unavailable, so ship will not '
+                + `actually be blocked. Install the broken-windows capability, then run: ${WINDOWS_ENFORCE_REMEDIATION}`,
+        };
+    }
+    if (!windowsEnforce) {
+        return {
+            reason: complexity.REASON.REFACTOR_STRICT_NOT_ENFORCING,
+            message: 'refactor.trigger_strict is on, but workflow.windows_enforce is off, so ship will not actually be '
+                + `blocked. Run: ${WINDOWS_ENFORCE_REMEDIATION}`,
+        };
+    }
+    return null;
+}
+// ─── Broken-windows integration (strict mode; OPTIONAL) ─────────────────────
+function windowsLedgerPath(cwd, windows) {
+    return node_path_1.default.join(cwd, '.planning', windows.LEDGER_FILE_NAME);
+}
+function readLedgerOrEmpty(cwd, windows) {
+    const ledgerPath = windowsLedgerPath(cwd, windows);
+    try {
+        const raw = node_fs_1.default.readFileSync(ledgerPath, 'utf8');
+        return windows.parseLedger(raw);
+    }
+    catch (e) {
+        const code = (e && typeof e === 'object' && 'code' in e) ? String(e.code) : '';
+        if (code === 'ENOENT')
+            return windows.emptyLedger(new Date().toISOString());
+        return null; // unreadable/malformed — degrade rather than throw
+    }
+}
+/**
+ * Structural identity match (#1953 defect 2): a deviation window's identity
+ * is the typed `phase`/`file`/`line` triple `appendWindow` already persists
+ * — never the human-readable `description` prose. A reworded description or
+ * a user editing `WINDOWS.md` prose can never break dedup.
+ */
+function findOpenDeviationEntry(ledger, phase, file, line) {
+    return ledger.entries.find((e) => e.status === 'open' && e.kind === 'deviation' && e.phase === phase && e.file === file && e.line === line) ?? null;
+}
+/**
+ * Shared require-or-degrade + ledger-read boilerplate for
+ * `recordStrictWindow` / `resolveLedgerWindow` (#1953 defect 5a). `_windows`
+ * unavailable (module absent, or its `require` throws) or the ledger
+ * unreadable both degrade to a `{ ok: false, note }` result — never an
+ * error, never throws.
+ */
+function loadWindowsOrDegrade(cwd, windowsOverride) {
+    let windows;
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        windows = windowsOverride ?? require('./broken-windows.cjs');
+    }
+    catch {
+        return { ok: false, note: 'broken-windows capability unavailable — proposal recorded locally only' };
+    }
+    const ledger = readLedgerOrEmpty(cwd, windows);
+    if (ledger === null) {
+        return { ok: false, note: 'broken-windows ledger unreadable — proposal recorded locally only' };
+    }
+    return { ok: true, windows, ledger };
+}
+/**
+ * Strict-mode window append (step 9 of `evaluate`). Degrades to
+ * `{ recorded: false, note }` per `loadWindowsOrDegrade` — never an error,
+ * never throws. Idempotent: re-evaluating the same still-untriaged phase
+ * finds the existing OPEN entry (matched structurally on phase + target
+ * file/line) and does not append a second one.
+ */
+function recordStrictWindow(cwd, padded, target, windowsOverride) {
+    const loaded = loadWindowsOrDegrade(cwd, windowsOverride);
+    if (!loaded.ok)
+        return { recorded: false, note: loaded.note };
+    const { windows, ledger } = loaded;
+    if (findOpenDeviationEntry(ledger, padded, target.file, target.startLine)) {
+        return { recorded: true, note: 'already recorded for this phase (idempotent)' };
+    }
+    const key = candidateKey(target.file, target.name);
+    const description = `${key} — complexity ${target.score}` +
+        (target.baseline !== null ? ` (baseline ${target.baseline}, delta ${target.delta})` : '');
+    const now = new Date().toISOString();
+    try {
+        const result = windows.appendWindow(ledger, { kind: 'deviation', phase: padded, file: target.file, line: target.startLine, description }, { now });
+        writeTextAtomic(windowsLedgerPath(cwd, windows), windows.renderLedger(result.ledger));
+        return { recorded: true };
+    }
+    catch (e) {
+        return { recorded: false, note: `failed to record broken-windows entry: ${e instanceof Error ? e.message : String(e)}` };
+    }
+}
+/**
+ * Resolve (mark fixed/waived) the ledger window matching phase + target
+ * file/line, if any. Never throws. Mirrors `recordStrictWindow`'s
+ * `{ recorded, note }` degrade shape (#1953 defect 2): every
+ * `resolved: false` path carries a `note` naming the real reason, so
+ * `accept`/`decline` never tell a user "it failed" without saying why.
+ */
+function resolveLedgerWindow(cwd, padded, file, line, kind, reasonText, windowsOverride) {
+    const loaded = loadWindowsOrDegrade(cwd, windowsOverride);
+    if (!loaded.ok)
+        return { resolved: false, note: loaded.note };
+    const { windows, ledger } = loaded;
+    const entry = findOpenDeviationEntry(ledger, padded, file, line);
+    if (!entry) {
+        return { resolved: false, note: 'no open broken-windows entry found for this phase/target — nothing to resolve' };
+    }
+    const now = new Date().toISOString();
+    try {
+        const updated = kind === 'accept'
+            ? windows.markFixed(ledger, entry.id, { now })
+            : windows.markWaived(ledger, entry.id, reasonText || 'declined', { now });
+        writeTextAtomic(windowsLedgerPath(cwd, windows), windows.renderLedger(updated));
+        return { resolved: true };
+    }
+    catch (e) {
+        return { resolved: false, note: `failed to resolve broken-windows entry: ${e instanceof Error ? e.message : String(e)}` };
+    }
+}
+// ─── evaluate ────────────────────────────────────────────────────────────────
+const EVALUATE_USAGE = 'Usage: gsd-tools refactor evaluate --phase <N> [--since <ref>] [--raw]';
+function handleEvaluate(args, cwd, raw, c, complexity, git, windowsOverride) {
+    const rest = args.slice(2);
+    const phaseCheck = requirePhaseArg(rest, complexity, EVALUATE_USAGE);
+    if (!phaseCheck.ok)
+        return phaseCheck.result;
+    // Step 3: resolve PHASE_DIR + anchor (phaseStartCommit, or --since override).
+    const resolved = resolvePhaseDirForArg(cwd, phaseCheck.phase);
+    if (resolved === null) {
+        c.output({ verdict: complexity.VERDICT.SKIPPED, reason: complexity.REASON.REFACTOR_INVALID_PHASE, phase: phaseCheck.phase }, raw);
+        return undefined;
+    }
+    const { phaseDir, padded } = resolved;
+    const sinceFlag = readFlag(rest, '--since');
+    const sinceOverride = sinceFlag.present && !sinceFlag.flagShaped ? sinceFlag.value.trim() : '';
+    const sinceRef = sinceOverride !== '' ? sinceOverride : git.phaseStartCommit(cwd, phaseDir);
+    if (sinceRef === null) {
+        c.output({ verdict: complexity.VERDICT.SKIPPED, reason: complexity.REASON.REFACTOR_GIT_UNAVAILABLE, phase: padded }, raw);
+        return undefined;
+    }
+    const touched = git.changedFilesSince(cwd, sinceRef);
+    if (touched === null) {
+        c.output({ verdict: complexity.VERDICT.SKIPPED, reason: complexity.REASON.REFACTOR_GIT_UNAVAILABLE, phase: padded }, raw);
+        return undefined;
+    }
+    // Step 4: empty touched set.
+    if (touched.length === 0) {
+        c.output({ verdict: complexity.VERDICT.BELOW_THRESHOLD, reason: complexity.REASON.REFACTOR_NO_TOUCHED_FILES, phase: padded }, raw);
+        return undefined;
+    }
+    // Step 5: filter with isAnalyzablePath; read each survivor. A read failure
+    // (or a path that escapes the project root) skips that one file with a
+    // reason and the run continues — never aborts the evaluation.
+    const analyzed = [];
+    // Only files that were SUCCESSFULLY analyzed feed nextBaseline's prune set
+    // — an unreadable file must never wipe that file's baseline history via
+    // the "file in analyzedFiles but function missing" prune rule.
+    const successfullyAnalyzedFiles = [];
+    for (const relFile of touched) {
+        if (!complexity.isAnalyzablePath(relFile))
+            continue;
+        const confined = resolveConfinedPath(cwd, relFile);
+        if (confined === null) {
+            analyzed.push({ file: relFile, ok: false, reason: complexity.REASON.REFACTOR_FILE_UNREADABLE });
+            continue;
+        }
+        let source;
+        try {
+            source = node_fs_1.default.readFileSync(confined, 'utf8');
+        }
+        catch {
+            analyzed.push({ file: relFile, ok: false, reason: complexity.REASON.REFACTOR_FILE_UNREADABLE });
+            continue;
+        }
+        const result = complexity.analyzeSource(source);
+        if (!result.ok) {
+            analyzed.push({ file: relFile, ok: false, reason: result.reason });
+        }
+        else {
+            analyzed.push({ file: relFile, ok: true, method: result.method, functions: result.functions });
+            successfullyAnalyzedFiles.push(relFile);
+        }
+    }
+    // Step 6.
+    const planningDirPath = planningDir(cwd);
+    const baselineRead = complexity.readBaseline(planningDirPath);
+    const evalConfig = readEvalConfig(cwd);
+    const evaluation = complexity.evaluateCandidates({
+        analyzed,
+        baseline: baselineRead.baseline,
+        threshold: evalConfig.threshold,
+        jumpDelta: evalConfig.jumpDelta,
+    });
+    // Step 7.
+    let artifactWritten = false;
+    let artifactPath = null;
+    let artifactWriteError = null;
+    if (evaluation.verdict === complexity.VERDICT.TRIGGERED && evaluation.target) {
+        const target = evaluation.target;
+        const proposal = {
+            schema_version: complexity.SCHEMA_VERSION,
+            status: 'proposed',
+            phase: padded,
+            target_file: target.file,
+            target_function: target.name,
+            score: target.score,
+            baseline: target.baseline,
+            delta: target.delta,
+            metric: 'decision-points',
+            recorded_at: new Date().toISOString(),
+            resolved_at: null,
+            reason: target.reasons.join(','),
+            candidates: evaluation.candidates,
+        };
+        artifactPath = artifactAbsPath(cwd, phaseDir, padded, complexity);
+        try {
+            writeTextAtomic(artifactPath, complexity.renderProposal(proposal));
+            artifactWritten = true;
+        }
+        catch (e) {
+            artifactWriteError = e instanceof Error ? e.message : String(e);
+        }
+    }
+    // Step 8: baseline write failure is reported but does not fail the command.
+    const nextBaselineValue = complexity.nextBaseline(baselineRead.baseline, analyzed, { analyzedFiles: successfullyAnalyzedFiles, phase: padded });
+    const baselineWrite = complexity.writeBaseline(planningDirPath, nextBaselineValue);
+    // Step 9: strict mode, TRIGGERED only.
+    let ledgerRecorded;
+    let ledgerNote;
+    const warnings = [];
+    if (evalConfig.strict && evaluation.verdict === complexity.VERDICT.TRIGGERED && evaluation.target) {
+        const strictResult = recordStrictWindow(cwd, padded, evaluation.target, windowsOverride);
+        ledgerRecorded = strictResult.recorded;
+        ledgerNote = strictResult.note;
+        const warning = strictNotEnforcingWarning(complexity, ledgerRecorded, evalConfig.windowsEnforce);
+        if (warning)
+            warnings.push(warning);
+    }
+    const result = {
+        verdict: evaluation.verdict,
+        phase: padded,
+        candidates: evaluation.candidates,
+        target: evaluation.target,
+        skipped: evaluation.skipped,
+        threshold_used: evaluation.thresholdUsed,
+        jump_delta_used: evaluation.jumpDeltaUsed,
+        artifact_written: artifactWritten,
+        artifact_path: artifactPath,
+        baseline_write: baselineWrite.ok,
+    };
+    if (artifactWriteError !== null)
+        result.artifact_write_error = artifactWriteError;
+    if (!baselineWrite.ok && baselineWrite.reason)
+        result.baseline_write_reason = baselineWrite.reason;
+    if (ledgerRecorded !== undefined)
+        result.ledger_recorded = ledgerRecorded;
+    if (ledgerNote !== undefined)
+        result.ledger_note = ledgerNote;
+    if (warnings.length > 0)
+        result.warnings = warnings;
+    c.output(result, raw);
+    return undefined;
+}
+// ─── status ──────────────────────────────────────────────────────────────────
+const STATUS_USAGE = 'Usage: gsd-tools refactor status [--phase <N>] [--raw]';
+function scanProposals(cwd, complexity) {
+    const phasesDir = node_path_1.default.join(planningDir(cwd), 'phases');
+    const results = [];
+    // #1953 (phase-enumeration-drift guard): phase-directory enumeration has one
+    // owner (`listMilestonePhaseDirs`, src/phase-locator.cts). Called unscoped
+    // (no `cwd` in opts) to preserve this scan's prior all-phases-directory
+    // reach — the only behavior change is that sentinel directories (backlog
+    // `0-*` / icebox `999-*`, per the canonical `isSentinelPhaseId`) are now
+    // excluded, and the enumeration order is `comparePhaseNum`-sorted rather
+    // than raw filesystem order.
+    const { value: dirs } = listMilestonePhaseDirs(phasesDir);
+    for (const dirName of dirs) {
+        const full = node_path_1.default.join(phasesDir, dirName);
+        let files;
+        try {
+            files = node_fs_1.default.readdirSync(full);
+        }
+        catch {
+            continue;
+        }
+        for (const fileName of files) {
+            if (!fileName.endsWith(complexity.PROPOSAL_SUFFIX))
+                continue;
+            try {
+                const text = node_fs_1.default.readFileSync(node_path_1.default.join(full, fileName), 'utf8');
+                const proposal = complexity.parseProposal(text);
+                if (proposal) {
+                    results.push({
+                        phase: proposal.phase,
+                        target_file: proposal.target_file,
+                        target_function: proposal.target_function,
+                        status: proposal.status,
+                        score: proposal.score,
+                    });
+                }
+            }
+            catch {
+                continue;
+            }
+        }
+    }
+    return results;
+}
+function handleStatus(args, cwd, raw, c, complexity) {
+    const rest = args.slice(2);
+    const phaseFlag = readFlag(rest, '--phase');
+    if (!phaseFlag.present) {
+        c.output({ proposals: scanProposals(cwd, complexity) }, raw);
+        return undefined;
+    }
+    const trimmed = phaseFlag.value.trim();
+    if (phaseFlag.duplicated || phaseFlag.flagShaped || trimmed === '' || !PHASE_VALUE_RE.test(trimmed)) {
+        return makeInvalidArgs('phase', `Invalid --phase value: ${JSON.stringify(phaseFlag.value)}. ${STATUS_USAGE}`, complexity.REASON.REFACTOR_INVALID_PHASE);
+    }
+    const resolved = resolvePhaseDirForArg(cwd, trimmed);
+    if (resolved === null) {
+        c.output({ found: false, phase: trimmed }, raw);
+        return undefined;
+    }
+    const artifactPath = artifactAbsPath(cwd, resolved.phaseDir, resolved.padded, complexity);
+    let text;
+    try {
+        text = node_fs_1.default.readFileSync(artifactPath, 'utf8');
+    }
+    catch {
+        c.output({ found: false, phase: resolved.padded }, raw);
+        return undefined;
+    }
+    const proposal = complexity.parseProposal(text);
+    if (proposal === null) {
+        c.output({ found: false, phase: resolved.padded }, raw);
+        return undefined;
+    }
+    c.output({ found: true, phase: resolved.padded, proposal }, raw);
+    return undefined;
+}
+// ─── accept / decline ──────────────────────────────────────────────────────
+/**
+ * Re-measure the target function's CURRENT complexity score by re-reading
+ * and re-analyzing `proposal.target_file` — `accept` re-anchors to the
+ * post-refactor score and `decline` to the current (unchanged) score, and
+ * both need the LIVE value, not the frozen `proposal.score` snapshot from
+ * evaluate-time. Falls back to `proposal.score` when the file is gone,
+ * unreadable, unparseable, or the function can no longer be found (e.g.
+ * renamed) — reanchorBaseline always needs *a* number, and the proposal's
+ * last-known score is the least-surprising fallback.
+ */
+function measureCurrentScore(cwd, proposal, complexity) {
+    const confined = resolveConfinedPath(cwd, proposal.target_file);
+    if (confined === null)
+        return proposal.score;
+    let source;
+    try {
+        source = node_fs_1.default.readFileSync(confined, 'utf8');
+    }
+    catch {
+        return proposal.score;
+    }
+    const result = complexity.analyzeSource(source);
+    if (!result.ok)
+        return proposal.score;
+    const fn = result.functions.find((f) => f.name === proposal.target_function);
+    return fn ? fn.score : proposal.score;
+}
+function dispositionUsage(kind) {
+    return kind === 'accept'
+        ? 'Usage: gsd-tools refactor accept --phase <N> [--raw]'
+        : 'Usage: gsd-tools refactor decline --phase <N> --reason "<text>" [--raw]';
+}
+function handleDisposition(kind, args, cwd, raw, c, complexity, windowsOverride) {
+    const rest = args.slice(2);
+    const usage = dispositionUsage(kind);
+    const phaseCheck = requirePhaseArg(rest, complexity, usage);
+    if (!phaseCheck.ok)
+        return phaseCheck.result;
+    let reasonText = '';
+    if (kind === 'decline') {
+        const reasonFlag = readFlag(rest, '--reason');
+        const trimmedReason = reasonFlag.value.trim();
+        if (!reasonFlag.present || reasonFlag.flagShaped || trimmedReason === '') {
+            return makeInvalidArgs('reason', usage, complexity.REASON.REFACTOR_DECLINE_REASON_EMPTY);
+        }
+        reasonText = reasonFlag.value;
+    }
+    const resolved = resolvePhaseDirForArg(cwd, phaseCheck.phase);
+    if (resolved === null) {
+        return makeInvalidArgs('phase', `No refactor proposal found for phase ${phaseCheck.phase}.`, complexity.REASON.REFACTOR_ARTIFACT_NOT_FOUND);
+    }
+    const artifactPath = artifactAbsPath(cwd, resolved.phaseDir, resolved.padded, complexity);
+    let text;
+    try {
+        text = node_fs_1.default.readFileSync(artifactPath, 'utf8');
+    }
+    catch {
+        return makeInvalidArgs('phase', `No refactor proposal found for phase ${resolved.padded}.`, complexity.REASON.REFACTOR_ARTIFACT_NOT_FOUND);
+    }
+    const proposal = complexity.parseProposal(text);
+    if (proposal === null) {
+        return makeInvalidArgs('phase', `Refactor proposal for phase ${resolved.padded} is unreadable.`, complexity.REASON.REFACTOR_ARTIFACT_NOT_FOUND);
+    }
+    if (proposal.status !== 'proposed') {
+        return makeInvalidArgs('phase', `Refactor proposal for phase ${resolved.padded} is already ${proposal.status}.`, complexity.REASON.REFACTOR_ALREADY_DISPOSITIONED);
+    }
+    const key = candidateKey(proposal.target_file, proposal.target_function);
+    const now = new Date().toISOString();
+    const liveScore = measureCurrentScore(cwd, proposal, complexity);
+    const targetCandidate = proposal.candidates.find((cand) => cand.file === proposal.target_file && cand.name === proposal.target_function) ?? proposal.candidates[0] ?? null;
+    const updatedProposal = {
+        ...proposal,
+        status: kind === 'accept' ? 'accepted' : 'declined',
+        resolved_at: now,
+        reason: kind === 'accept' ? proposal.reason : reasonText,
+    };
+    writeTextAtomic(artifactPath, complexity.renderProposal(updatedProposal));
+    const planningDirPath = planningDir(cwd);
+    const baselineRead = complexity.readBaseline(planningDirPath);
+    const nextBaselineValue = complexity.reanchorBaseline(baselineRead.baseline, key, liveScore, { phase: resolved.padded });
+    const baselineWrite = complexity.writeBaseline(planningDirPath, nextBaselineValue);
+    const ledgerResult = resolveLedgerWindow(cwd, resolved.padded, proposal.target_file, targetCandidate ? targetCandidate.startLine : -1, kind, reasonText, windowsOverride);
+    const dispositionResult = {
+        status: updatedProposal.status,
+        phase: resolved.padded,
+        target: key,
+        reanchored_to: liveScore,
+        baseline_write: baselineWrite.ok,
+        ledger_resolved: ledgerResult.resolved,
+    };
+    if (ledgerResult.note !== undefined)
+        dispositionResult.ledger_note = ledgerResult.note;
+    c.output(dispositionResult, raw);
+    return undefined;
+}
+// ─── Dispatch ────────────────────────────────────────────────────────────────
+/**
+ * Shared capability-active gate + lazy `complexity-trigger.cjs` require
+ * (#1953 defect 5b) — identical across all four subcommand handlers. Emits
+ * the disabled response and returns `undefined` without invoking `run` when
+ * the capability is off; otherwise resolves the module (respecting the
+ * `_complexity` test seam) and hands it to `run`.
+ */
+function withActiveComplexity(cwd, raw, c, complexityOverride, run) {
+    if (!isCapabilityActive(CAPABILITY_ID, cwd)) {
+        c.output(disabledResponse(), raw);
+        return undefined;
+    }
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const complexity = complexityOverride ?? require('./complexity-trigger.cjs');
+    return run(complexity);
+}
+function routeRefactorTriggerCommand({ args, cwd, raw, error, _complexity, _git, _windows, _core }) {
+    const c = _core ?? _defaultCore;
+    routeHubCommandFamily({
+        family: 'refactor',
+        args,
+        // Alphabetical for a stable unknown-subcommand message, matching intel/graphify.
+        subcommands: ['accept', 'decline', 'evaluate', 'status'],
+        handlers: {
+            evaluate: () => withActiveComplexity(cwd, raw, c, _complexity, (complexity) => {
+                // eslint-disable-next-line @typescript-eslint/no-require-imports
+                const git = _git ?? require('./git-base-branch.cjs');
+                return handleEvaluate(args, cwd, raw, c, complexity, git, _windows);
+            }),
+            status: () => withActiveComplexity(cwd, raw, c, _complexity, (complexity) => handleStatus(args, cwd, raw, c, complexity)),
+            accept: () => withActiveComplexity(cwd, raw, c, _complexity, (complexity) => handleDisposition('accept', args, cwd, raw, c, complexity, _windows)),
+            decline: () => withActiveComplexity(cwd, raw, c, _complexity, (complexity) => handleDisposition('decline', args, cwd, raw, c, complexity, _windows)),
+        },
+        unknownMessage: (subcommand, available) => `Unknown refactor subcommand. Available: ${available.join(', ')}`,
+        error,
+        cwd,
+        raw,
+    });
+}
+module.exports = {
+    routeRefactorTriggerCommand,
+};