@aperant/framework 0.6.7 → 0.7.3

package/dist/cli/gate/gates/verify-approved.mjs

@@ -3,20 +3,53 @@
  * G4 verify-approved — blocking gate for `apt:ship`.
  *
  * Requires {task_dir}/qa_signoff.json to exist, parse, and carry
- * verdict === "approved". The ship skill's existing prose only asked the
- * agent to "confirm" approval; this gate enforces it deterministically.
+ * verdict === "approved" (BUG-013: normalized via parseQaSignoff — case
+ * and underscore/hyphen variants collapse to canonical). BUG-012: also
+ * accepts `approved-with-notes` when config.qa.approved_with_notes_threshold
+ * is set AND every dimension score meets the threshold (best-effort when
+ * dimensions are missing or in an unknown shape).
  *
- * NOTE: the file may use either `verdict` (newer) or `status` (older) field
- * name for the QA result. We accept both for forwards/backwards compatibility,
- * but only the string "approved" passes — "approved-with-notes" fails
- * because ship-time deserves the strongest signal.
+ * Accepts both `verdict` (newer) and `status` (older) field names — that
+ * normalization is delegated to parseQaSignoff.
  */
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { parseQaSignoff } from '../../consistency/parse-qa.mjs';
 import { registerGate } from '../registry.mjs';
+/**
+ * Extract dimension scores from the qa_signoff.json shape. We've seen two
+ * shapes in the wild:
+ *   - Array: `dimensions: [{name: 'security', score: 0.9}, ...]`
+ *   - Object: `dimensions: {security: 0.9, performance: 0.85}` OR
+ *     `dimensions: {security: {score: 0.9}, ...}`
+ * Returns an array of numeric scores, or null when no recognizable shape
+ * is present (best-effort accept per brief).
+ */
+function extractDimensionScores(doc) {
+    const dims = doc.dimensions ?? doc.qa?.dimensions ?? null;
+    if (!dims)
+        return null;
+    if (Array.isArray(dims)) {
+        const scores = dims
+            .map((d) => (typeof d?.score === 'number' ? d.score : null))
+            .filter((s) => s !== null);
+        return scores.length > 0 ? scores : null;
+    }
+    if (typeof dims === 'object') {
+        const scores = [];
+        for (const v of Object.values(dims)) {
+            if (typeof v === 'number')
+                scores.push(v);
+            else if (typeof v?.score === 'number')
+                scores.push(v.score);
+        }
+        return scores.length > 0 ? scores : null;
+    }
+    return null;
+}
 const gate = {
     id: 'verify-approved',
-    description: 'qa_signoff.json exists with verdict === "approved"',
+    description: 'qa_signoff.json exists with verdict === "approved" (or "approved-with-notes" when configured)',
     severity: 'blocking',
     skills: ['ship'],
     async check(ctx) {
@@ -40,18 +73,64 @@ const gate = {
                 inputs,
             };
         }
-        const verdict = doc.verdict ?? doc.status ?? null;
-        if (verdict !== 'approved') {
+        // BUG-013: route through parseQaSignoff so the verdict is
+        // case-insensitive AND tolerates `_↔-` (so 'APPROVED', 'Approved',
+        // ' approved ', 'APPROVED_WITH_NOTES' all behave canonically). The
+        // pre-fix gate compared the raw string against `'approved'` which
+        // false-rejected every legitimate variant.
+        const { verdict } = parseQaSignoff(doc);
+        if (verdict === 'approved') {
             return {
-                status: 'fail',
-                reason: `qa_signoff.json verdict is "${verdict}" (expected "approved")`,
-                evidence: { verdict },
+                status: 'pass',
+                reason: 'qa_signoff.json verdict normalized to "approved"',
+                inputs,
+            };
+        }
+        // BUG-012: accept `approved-with-notes` when the project has opted
+        // in via config.qa.approved_with_notes_threshold. The threshold is
+        // the minimum per-dimension score required. Best-effort: when
+        // dimensions are missing / in an unknown shape we still accept and
+        // log, rather than hard-failing, so projects that haven't started
+        // scoring dimensions yet aren't blocked.
+        if (verdict === 'approved-with-notes') {
+            const threshold = ctx.config?.qa?.approved_with_notes_threshold;
+            if (typeof threshold !== 'number') {
+                return {
+                    status: 'fail',
+                    reason: 'qa_signoff.json verdict is "approved-with-notes" but config.qa.approved_with_notes_threshold is not set',
+                    evidence: { verdict, threshold: threshold ?? null },
+                    inputs,
+                };
+            }
+            const scores = extractDimensionScores(doc);
+            if (scores === null) {
+                return {
+                    status: 'pass',
+                    reason: `qa_signoff.json verdict is "approved-with-notes" and threshold ${threshold} is enabled; dimensions missing or unknown-shape — accepting best-effort`,
+                    evidence: { verdict, threshold, dimensions_present: false },
+                    inputs,
+                };
+            }
+            const failing = scores.filter((s) => s < threshold);
+            if (failing.length > 0) {
+                return {
+                    status: 'fail',
+                    reason: `qa_signoff.json verdict is "approved-with-notes" but ${failing.length}/${scores.length} dimension score(s) below threshold ${threshold}`,
+                    evidence: { verdict, threshold, scores, failing },
+                    inputs,
+                };
+            }
+            return {
+                status: 'pass',
+                reason: `qa_signoff.json verdict is "approved-with-notes" and all ${scores.length} dimension score(s) meet threshold ${threshold}`,
+                evidence: { verdict, threshold, scores },
                 inputs,
             };
         }
         return {
-            status: 'pass',
-            reason: 'qa_signoff.json.verdict === "approved"',
+            status: 'fail',
+            reason: `qa_signoff.json verdict is "${verdict}" (expected "approved" or "approved-with-notes" with threshold)`,
+            evidence: { verdict },
             inputs,
         };
     },

package/dist/cli/gate/gates/verify-approved.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"verify-approved.mjs","sourceRoot":"","sources":["../../../../src/cli/gate/gates/verify-approved.mjs"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAClD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAChC,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAE9C,MAAM,IAAI,GAAG;IACZ,EAAE,EAAE,iBAAiB;IACrB,WAAW,EAAE,oDAAoD;IACjE,QAAQ,EAAE,UAAU;IACpB,MAAM,EAAE,CAAC,MAAM,CAAC;IAChB,KAAK,CAAC,KAAK,CAAC,GAAG;QACd,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,iBAAiB,CAAC,CAAA;QACjD,MAAM,MAAM,GAAG,CAAC,IAAI,CAAC,CAAA;QACrB,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;YACvB,OAAO;gBACN,MAAM,EAAE,MAAM;gBACd,MAAM,EAAE,8BAA8B,IAAI,EAAE;gBAC5C,MAAM;aACN,CAAA;QACF,CAAC;QACD,IAAI,GAAG,CAAA;QACP,IAAI,CAAC;YACJ,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAA;QAC9C,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACd,OAAO;gBACN,MAAM,EAAE,MAAM;gBACd,MAAM,EAAE,mCAAmC,GAAG,CAAC,OAAO,EAAE;gBACxD,MAAM;aACN,CAAA;QACF,CAAC;QACD,MAAM,OAAO,GAAG,GAAG,CAAC,OAAO,IAAI,GAAG,CAAC,MAAM,IAAI,IAAI,CAAA;QACjD,IAAI,OAAO,KAAK,UAAU,EAAE,CAAC;YAC5B,OAAO;gBACN,MAAM,EAAE,MAAM;gBACd,MAAM,EAAE,+BAA+B,OAAO,yBAAyB;gBACvE,QAAQ,EAAE,EAAE,OAAO,EAAE;gBACrB,MAAM;aACN,CAAA;QACF,CAAC;QACD,OAAO;YACN,MAAM,EAAE,MAAM;YACd,MAAM,EAAE,wCAAwC;YAChD,MAAM;SACN,CAAA;IACF,CAAC;CACD,CAAA;AAED,YAAY,CAAC,IAAI,CAAC,CAAA;AAClB,eAAe,IAAI,CAAA"}
+{"version":3,"file":"verify-approved.mjs","sourceRoot":"","sources":["../../../../src/cli/gate/gates/verify-approved.mjs"],"names":[],"mappings":"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"}

package/dist/cli/help.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"help.d.mts","sourceRoot":"","sources":["../../src/cli/help.mjs"],"names":[],"mappings":"AAMA,kCAgIC"}
+{"version":3,"file":"help.d.mts","sourceRoot":"","sources":["../../src/cli/help.mjs"],"names":[],"mappings":"AAMA,kCAsIC"}

package/dist/cli/help.mjs

@@ -29,9 +29,10 @@ Commands:
   task update <dir> --id <id> [--lifecycle-phase <p>] [--pr-url <url>] [--subtasks-total <N>] [--depends-on <refs>]  Update non-linkage task state; --pr-url may arm ci-watch per ci_watch.after_ship
   task move <dir> --id <id> [--to-scope <s>] [--to-milestone <id>] [--to-phase <id>] [--to-roadmap-ref-url <url>] [--reason <text>] [--force]  Reassign scope/milestone/phase with history
   task close <dir> --id <task-id> [--verdict <v>]  Close task and move to completed
+  task close-merged <dir> [--task <id>] [--narrate-only] [--dry-run]   Sweep shipped-pending-merge tasks for confirmed merges (--narrate-only returns pending_narration[] entries read-only without closing).
   task narration-drain <dir> --task <task-id>     Remove a row from state.pending_narration[] under withFileLock (called by /apt:close-task --narrate-only after a successful narrator spawn)
   task complete-subtask <dir> --task-id <id> --subtask-id <sid|a+b+c> [--commit <sha>] [--notes <text>]  Atomic plan ↔ build-progress sync
-  features-audit <dir> [--diff-files <csv>|--since <ref>] [--apply-stubs] [--format json|md]  Audit features registry for unregistered feature-qualifying files
+  features-audit <dir> [--task-id <id>] [--no-worktree-redirect] [--diff-files <csv>|--since <ref>] [--apply-stubs] [--format json|md]  Audit features registry for unregistered feature-qualifying files (BUG-025b: --task-id redirects writes to active task's worktree)
   docs-audit <dir> [--diff-files <csv>|--since <ref>|--dry-run] [--policy <path>] [--format json|md]  Audit documented surfaces for docs-drift
 
   lock claim <dir> --subtask <id>       Claim exclusive lock on a subtask
@@ -107,7 +108,9 @@ Commands:
 
   migrate-pr-reviews <project-dir>       Migrate legacy .aperant/reviews/ → .aperant/pr-reviews/pr-{N}/rounds/{R}/ (idempotent)
 
-  validate-evidence <findings-dir> --worktree <path>   Enforce the Evidence Rule (literal substring + multi-file check); mutates findings markdown in place
+  validate-evidence <findings-dir> --worktree <path> [--allow-approx-evidence] [--approx-floor <n>] [--llm-validator-confirmed]   Enforce the Evidence Rule (literal substring + multi-file check); mutates findings markdown in place. BUG-014: --allow-approx-evidence opts into Jaccard + line-anchor fallback (downgrade to dismissed_evidence_approx_confirmed unless --llm-validator-confirmed promotes to confirmed_valid_approx).
+
+  vitest doctor <project-dir> [--format json|md]   BUG-026: walk vitest.config.{ts,js,mjs} files, report NODE_ENV/jsxAutomaticShim matrix, warn when JSX-rendering tests lack jsxAutomaticShim coverage (exits 1 on warnings)
 
   wfrun validate <workflow.yaml>                         C17: parse + schema-check a declarative YAML workflow (exits 0 on success)
   wfrun plan <workflow.yaml> [--input k=v …]             C17: resolve DAG waves + inputs, emit run-plan JSON (no side effects)
@@ -123,6 +126,9 @@ Commands:
   pr-review record-comment <dir> --pr <N> --round <R> --url <url> --body-hash <sha256> [--review-id <id>] [--posted-at <iso>]  Append entry to comment_timeline (Phase 6b)
   pr-review audit-fixer <dir> --review-dir <path> --iteration <N> --fixer <name> --worktree <path> --status-line <str>  Audit fixer output against git state; exits 0 with JSON envelope (verdict: verified|hallucinated|skipped)
 
+  ci-watch start|stop|status|tick <dir> [--pr <N>] [...]   /apt:watch-ci primitives — see SKILL.md for full flag matrix
+  ci-watch sweep <dir> --orphaned [--dry-run]              BUG-027: enumerate ci-watches state files, query gh per PR, remove terminal-state (MERGED|CLOSED) entries (manual GC; rate-limited)
+
 Flags:
   --version                             Print version and exit
   --help                                Print usage and exit

package/dist/cli/help.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"help.mjs","sourceRoot":"","sources":["../../src/cli/help.mjs"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAA;AAE1C,MAAM,UAAU,SAAS;IACxB,MAAM,IAAI,GAAG,GAAG,UAAU,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;oBA4HT,CAAA;IAEnB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,IAAI,CAAC,CAAA;AAClC,CAAC"}
+{"version":3,"file":"help.mjs","sourceRoot":"","sources":["../../src/cli/help.mjs"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAA;AAE1C,MAAM,UAAU,SAAS;IACxB,MAAM,IAAI,GAAG,GAAG,UAAU,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;oBAkIT,CAAA;IAEnB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,IAAI,CAAC,CAAA;AAClC,CAAC"}

package/dist/cli/host/detect.d.mts

@@ -32,20 +32,133 @@ export function detectHost(opts?: {
     };
     aperant_terminal: boolean;
     aperant_socket: string | null;
+    partner_transports: {
+        codex: ({
+            rung: string;
+            detected: boolean;
+            reason: string;
+            invocation?: undefined;
+        } | {
+            rung: string;
+            detected: string;
+            invocation: string;
+            reason?: undefined;
+        } | {
+            rung: string;
+            detected: boolean;
+            invocation: any;
+            reason?: undefined;
+        })[];
+        claude: ({
+            rung: string;
+            detected: boolean;
+            reason: string;
+            invocation?: undefined;
+        } | {
+            rung: string;
+            detected: string;
+            invocation: string;
+            reason?: undefined;
+        } | {
+            rung: string;
+            detected: boolean;
+            invocation: any;
+            reason?: undefined;
+        })[];
+        gemini: ({
+            rung: string;
+            detected: boolean;
+            reason: string;
+            invocation?: undefined;
+        } | {
+            rung: string;
+            detected: string;
+            invocation: string;
+            reason?: undefined;
+        } | {
+            rung: string;
+            detected: boolean;
+            invocation: any;
+            reason?: undefined;
+        })[];
+    };
 };
 /**
- * host/detect.mjs — AI CLI host detection (C29).
+ * Partner-transport ladder used by `apt:spar` (FRAMEWORK-BUG-024).
+ *
+ * For each partner (codex / claude / gemini) we resolve a 3-rung ladder in
+ * preference order — MCP first (cleanest integration), then plugin shim
+ * (codex only), then raw CLI on $PATH. The first rung with `detected: true`
+ * wins; the spar skill's gate fails only when all three rungs report
+ * `detected: false`.
+ *
+ * Detection is best-effort and side-effect-free w/r/t the FS — only
+ * `existsSync` reads. No spawn, no network. The MCP rung uses
+ * `detected: "runtime-host-only"` when the framework process cannot probe
+ * the host's deferred-tool registry (the common case — MCP availability
+ * is host-internal), signalling the SKILL body to self-check at invocation
+ * time rather than fail the gate.
  *
- * Detection maintenance: env-var mappings for each runtime below are the
- * authoritative signal. They must be re-verified against each CLI's current
- * public docs every quarter. See packages/framework/docs/intents.md
- * §Host-detection-maintenance for the process.
+ * Pure function w/r/t injected `env` + `existsSync` so tests can mock both
+ * without monkey-patching `process.env` or `node:fs`.
  *
- * For env vars that could not be confirmed from public docs at the time of
- * writing, we leave a TODO comment with the docs URL. These branches still
- * ship — we prefer best-effort coverage + structured unknown-host error
- * for misses over silently routing into the wrong runtime.
+ * @param {object} [opts]
+ * @param {NodeJS.ProcessEnv} [opts.env] — defaults to `process.env`
+ * @param {(p: string) => boolean} [opts.existsSync] — defaults to `node:fs` existsSync
  */
+export function detectPartnerTransports(opts?: {
+    env?: NodeJS.ProcessEnv | undefined;
+    existsSync?: ((p: string) => boolean) | undefined;
+}): {
+    codex: ({
+        rung: string;
+        detected: boolean;
+        reason: string;
+        invocation?: undefined;
+    } | {
+        rung: string;
+        detected: string;
+        invocation: string;
+        reason?: undefined;
+    } | {
+        rung: string;
+        detected: boolean;
+        invocation: any;
+        reason?: undefined;
+    })[];
+    claude: ({
+        rung: string;
+        detected: boolean;
+        reason: string;
+        invocation?: undefined;
+    } | {
+        rung: string;
+        detected: string;
+        invocation: string;
+        reason?: undefined;
+    } | {
+        rung: string;
+        detected: boolean;
+        invocation: any;
+        reason?: undefined;
+    })[];
+    gemini: ({
+        rung: string;
+        detected: boolean;
+        reason: string;
+        invocation?: undefined;
+    } | {
+        rung: string;
+        detected: string;
+        invocation: string;
+        reason?: undefined;
+    } | {
+        rung: string;
+        detected: boolean;
+        invocation: any;
+        reason?: undefined;
+    })[];
+};
 /**
  * Canonical list of runtime identifiers accepted by detectHost's
  * `overrideCli` parameter AND by the route command's `--runtime <id>` flag.

package/dist/cli/host/detect.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"detect.d.mts","sourceRoot":"","sources":["../../../src/cli/host/detect.mjs"],"names":[],"mappings":"AAwCA;;;;;;;;;;;;;;;;;GAiBG;AACH,kCARG;IAAsB,WAAW;CAOnC;;;;;;;;;;;;;;EA6JA;AAtND;;;;;;;;;;;;GAYG;AAEH;;;;;;;GAOG;AACH,gDAgBE"}
+{"version":3,"file":"detect.d.mts","sourceRoot":"","sources":["../../../src/cli/host/detect.mjs"],"names":[],"mappings":"AA2CA;;;;;;;;;;;;;;;;;GAiBG;AACH,kCARG;IAAsB,WAAW;CAOnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA8JA;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,+CAHG;IAAiC,GAAG;IACE,UAAU,QAApC,MAAM,KAAK,OAAO;CAChC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAyBA;AA1PD;;;;;;;GAOG;AACH,gDAgBE"}

package/dist/cli/host/detect.mjs

@@ -11,6 +11,8 @@
  * ship — we prefer best-effort coverage + structured unknown-host error
  * for misses over silently routing into the wrong runtime.
  */
+import { existsSync as fsExistsSync } from 'node:fs';
+import { delimiter as PATH_DELIMITER, join as pathJoin } from 'node:path';
 /**
  * Canonical list of runtime identifiers accepted by detectHost's
  * `overrideCli` parameter AND by the route command's `--runtime <id>` flag.
@@ -213,6 +215,136 @@ export function detectHost(opts = {}) {
         capabilities,
         aperant_terminal: isAperantTerminal,
         aperant_socket: aperantSocket,
+        partner_transports: detectPartnerTransports({ env }),
     };
 }
+/**
+ * Partner-transport ladder used by `apt:spar` (FRAMEWORK-BUG-024).
+ *
+ * For each partner (codex / claude / gemini) we resolve a 3-rung ladder in
+ * preference order — MCP first (cleanest integration), then plugin shim
+ * (codex only), then raw CLI on $PATH. The first rung with `detected: true`
+ * wins; the spar skill's gate fails only when all three rungs report
+ * `detected: false`.
+ *
+ * Detection is best-effort and side-effect-free w/r/t the FS — only
+ * `existsSync` reads. No spawn, no network. The MCP rung uses
+ * `detected: "runtime-host-only"` when the framework process cannot probe
+ * the host's deferred-tool registry (the common case — MCP availability
+ * is host-internal), signalling the SKILL body to self-check at invocation
+ * time rather than fail the gate.
+ *
+ * Pure function w/r/t injected `env` + `existsSync` so tests can mock both
+ * without monkey-patching `process.env` or `node:fs`.
+ *
+ * @param {object} [opts]
+ * @param {NodeJS.ProcessEnv} [opts.env] — defaults to `process.env`
+ * @param {(p: string) => boolean} [opts.existsSync] — defaults to `node:fs` existsSync
+ */
+export function detectPartnerTransports(opts = {}) {
+    const env = opts.env ?? process.env;
+    const exists = opts.existsSync ?? fsExistsSync;
+    const pathEntries = (env.PATH ?? '').split(PATH_DELIMITER).filter(Boolean);
+    return {
+        codex: [
+            detectMcpRung('codex', env),
+            detectPluginShim('codex', env, exists),
+            detectRawCli('codex', pathEntries, exists),
+        ],
+        claude: [
+            detectMcpRung('claude', env),
+            // No plugin shim exists for Claude today — kept as `detected: false`
+            // for ladder-shape symmetry so consumers can index by rung uniformly.
+            { rung: 'plugin', detected: false, reason: 'no plugin shim for claude' },
+            detectRawCli('claude', pathEntries, exists),
+        ],
+        gemini: [
+            detectMcpRung('gemini', env),
+            { rung: 'plugin', detected: false, reason: 'no plugin shim for gemini' },
+            detectRawCli('gemini', pathEntries, exists),
+        ],
+    };
+}
+/**
+ * MCP rung — detected if the host exposes its deferred-tool manifest via
+ * `CLAUDE_MCP_DEFERRED_TOOLS` (a JSON array of tool names) AND a matching
+ * `mcp__<partner>-mcp__*` entry is present. When the env var is absent the
+ * framework cannot observe the host's tool registry from outside, so we
+ * return `detected: "runtime-host-only"` — the SKILL body interprets this
+ * as "try it; if the host has the tool, use it; otherwise fall through".
+ */
+function detectMcpRung(partner, env) {
+    const toolPrefix = mcpToolPrefix(partner);
+    const manifest = env.CLAUDE_MCP_DEFERRED_TOOLS;
+    if (manifest) {
+        try {
+            const tools = JSON.parse(manifest);
+            if (Array.isArray(tools) &&
+                tools.some((t) => typeof t === 'string' && t.startsWith(toolPrefix))) {
+                return { rung: 'mcp', detected: true, invocation: `${toolPrefix}*` };
+            }
+            return {
+                rung: 'mcp',
+                detected: false,
+                reason: `no ${toolPrefix}* tool in CLAUDE_MCP_DEFERRED_TOOLS`,
+            };
+        }
+        catch {
+            // Malformed manifest — fall through to runtime-deferred
+        }
+    }
+    return { rung: 'mcp', detected: 'runtime-host-only', invocation: `${toolPrefix}*` };
+}
+function mcpToolPrefix(partner) {
+    if (partner === 'codex')
+        return 'mcp__codex-mcp__';
+    if (partner === 'claude')
+        return 'mcp__claude-code-mcp__';
+    if (partner === 'gemini')
+        return 'mcp__gemini-mcp__';
+    return `mcp__${partner}-mcp__`;
+}
+/**
+ * Plugin-shim rung — Claude Code plugins drop helper scripts under
+ * `${CLAUDE_PLUGIN_ROOT}/scripts/<partner>-companion.mjs`. Only codex
+ * ships a companion today; the caller passes `'codex'` to probe.
+ */
+function detectPluginShim(partner, env, exists) {
+    const root = env.CLAUDE_PLUGIN_ROOT;
+    if (!root) {
+        return { rung: 'plugin', detected: false, reason: 'CLAUDE_PLUGIN_ROOT unset' };
+    }
+    const script = pathJoin(root, 'scripts', `${partner}-companion.mjs`);
+    if (!exists(script)) {
+        return { rung: 'plugin', detected: false, reason: `${script} not found` };
+    }
+    return { rung: 'plugin', detected: true, invocation: `node "${script}" task` };
+}
+/**
+ * Raw-CLI rung — probe pre-split $PATH entries for the partner binary using
+ * existsSync (no spawn). Accepts a pre-split array so detectPartnerTransports
+ * can parse $PATH once and share it across all partner probes.
+ *
+ * The binary name matches the partner id for all three currently-supported
+ * partners (codex / claude / gemini).
+ */
+function detectRawCli(partner, pathEntries, exists) {
+    const bin = partner;
+    for (const dir of pathEntries) {
+        const candidate = pathJoin(dir, bin);
+        if (exists(candidate)) {
+            return { rung: 'cli', detected: true, invocation: rawCliInvocation(partner) };
+        }
+    }
+    return { rung: 'cli', detected: false, reason: `${bin} not found on $PATH` };
+}
+function rawCliInvocation(partner) {
+    if (partner === 'codex')
+        return 'codex exec';
+    if (partner === 'claude')
+        return 'claude -p';
+    if (partner === 'gemini')
+        return 'gemini -m';
+    return partner;
+}
 //# sourceMappingURL=detect.mjs.map

package/dist/cli/host/detect.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"detect.mjs","sourceRoot":"","sources":["../../../src/cli/host/detect.mjs"],"names":[],"mappings":"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"}
+{"version":3,"file":"detect.mjs","sourceRoot":"","sources":["../../../src/cli/host/detect.mjs"],"names":[],"mappings":"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"}

package/dist/cli/install/legacy-paths.d.mts

@@ -0,0 +1,38 @@
+/**
+ * install/legacy-paths.mjs — shared registry of legacy install topologies
+ * the framework once wrote to but no longer owns. Single source of truth
+ * for both:
+ *
+ *   - BUG-021: `runLegacyCleanup` in `install/runtime-migrate.mjs` knows
+ *     which files under a legacy root are framework-owned (safe to
+ *     remove) vs user-added (preserve).
+ *   - BUG-022: `readSkillInstallState` in `util/skill-installs.mjs` falls
+ *     back to `version_file` here when no manifest is present, so a
+ *     pre-manifest install still surfaces as "installed" rather than
+ *     "missing-skills".
+ *
+ * Derivation: the codex `framework_files` list was extracted from
+ * `git show 1a8dd8a8 --stat` (the original "make Codex a first-class
+ * skill install surface" commit) — every `.agents/skills/…` path the
+ * installer once wrote, including the `.apt-version` stamp and the
+ * apt-pr-review / apt-discuss / apt-verify-proof sub-files. When the
+ * codex installer was retargeted to `.codex/`, that entire tree became
+ * orphaned on upgrading projects.
+ *
+ * Schema:
+ *   { [runtimeId]: {
+ *       install_root:     relative path the runtime once wrote into,
+ *       version_file:     relative path of the legacy `.apt-version` stamp,
+ *       framework_files:  array of relative paths the installer once owned
+ *                         (under install_root).
+ *   } }
+ *
+ * Frozen via Object.freeze so callers cannot mutate the shared registry.
+ */
+/** @type {Record<string, { install_root: string, version_file: string, framework_files: ReadonlyArray<string> }>} */
+export const LEGACY_INSTALL_PATHS: Record<string, {
+    install_root: string;
+    version_file: string;
+    framework_files: ReadonlyArray<string>;
+}>;
+//# sourceMappingURL=legacy-paths.d.mts.map

package/dist/cli/install/legacy-paths.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"legacy-paths.d.mts","sourceRoot":"","sources":["../../../src/cli/install/legacy-paths.mjs"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,qHAAqH;AACrH,mCADW,MAAM,CAAC,MAAM,EAAE;IAAE,YAAY,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,eAAe,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;CAAE,CAAC,CAoC/G"}

package/dist/cli/install/legacy-paths.mjs

@@ -0,0 +1,69 @@
+/**
+ * install/legacy-paths.mjs — shared registry of legacy install topologies
+ * the framework once wrote to but no longer owns. Single source of truth
+ * for both:
+ *
+ *   - BUG-021: `runLegacyCleanup` in `install/runtime-migrate.mjs` knows
+ *     which files under a legacy root are framework-owned (safe to
+ *     remove) vs user-added (preserve).
+ *   - BUG-022: `readSkillInstallState` in `util/skill-installs.mjs` falls
+ *     back to `version_file` here when no manifest is present, so a
+ *     pre-manifest install still surfaces as "installed" rather than
+ *     "missing-skills".
+ *
+ * Derivation: the codex `framework_files` list was extracted from
+ * `git show 1a8dd8a8 --stat` (the original "make Codex a first-class
+ * skill install surface" commit) — every `.agents/skills/…` path the
+ * installer once wrote, including the `.apt-version` stamp and the
+ * apt-pr-review / apt-discuss / apt-verify-proof sub-files. When the
+ * codex installer was retargeted to `.codex/`, that entire tree became
+ * orphaned on upgrading projects.
+ *
+ * Schema:
+ *   { [runtimeId]: {
+ *       install_root:     relative path the runtime once wrote into,
+ *       version_file:     relative path of the legacy `.apt-version` stamp,
+ *       framework_files:  array of relative paths the installer once owned
+ *                         (under install_root).
+ *   } }
+ *
+ * Frozen via Object.freeze so callers cannot mutate the shared registry.
+ */
+/** @type {Record<string, { install_root: string, version_file: string, framework_files: ReadonlyArray<string> }>} */
+export const LEGACY_INSTALL_PATHS = Object.freeze({
+    codex: Object.freeze({
+        install_root: '.agents/skills',
+        version_file: '.agents/skills/.apt-version',
+        framework_files: Object.freeze([
+            '.apt-version',
+            'apt/SKILL.md',
+            'apt-debug/SKILL.md',
+            'apt-discuss/SKILL.md',
+            'apt-discuss/examples/rationalization-example.md',
+            'apt-docs/SKILL.md',
+            'apt-execute/SKILL.md',
+            'apt-pause/SKILL.md',
+            'apt-plan/SKILL.md',
+            'apt-pr-review/SCHEMA.md',
+            'apt-pr-review/SKILL.md',
+            'apt-pr-review/prompts/fp-gate-codex.md',
+            'apt-pr-review/templates/external-comment.md',
+            'apt-quick/SKILL.md',
+            'apt-resume/SKILL.md',
+            'apt-review/SKILL.md',
+            'apt-roadmap/SKILL.md',
+            'apt-roundtable/SKILL.md',
+            'apt-run/SKILL.md',
+            'apt-scan/SKILL.md',
+            'apt-setup/SKILL.md',
+            'apt-ship/SKILL.md',
+            'apt-stress-test/SKILL.md',
+            'apt-verify/SKILL.md',
+            'apt-verify-proof/SKILL.md',
+            'apt-verify-proof/references/multi-model-setup.md',
+            'apt-verify-proof/references/multi-model-verification.md',
+            'apt-verify-proof/references/proof-capture.md',
+        ]),
+    }),
+});
+//# sourceMappingURL=legacy-paths.mjs.map

package/dist/cli/install/legacy-paths.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"legacy-paths.mjs","sourceRoot":"","sources":["../../../src/cli/install/legacy-paths.mjs"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,qHAAqH;AACrH,MAAM,CAAC,MAAM,oBAAoB,GAAG,MAAM,CAAC,MAAM,CAAC;IACjD,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC;QACpB,YAAY,EAAE,gBAAgB;QAC9B,YAAY,EAAE,6BAA6B;QAC3C,eAAe,EAAE,MAAM,CAAC,MAAM,CAAC;YAC9B,cAAc;YACd,cAAc;YACd,oBAAoB;YACpB,sBAAsB;YACtB,iDAAiD;YACjD,mBAAmB;YACnB,sBAAsB;YACtB,oBAAoB;YACpB,mBAAmB;YACnB,yBAAyB;YACzB,wBAAwB;YACxB,wCAAwC;YACxC,6CAA6C;YAC7C,oBAAoB;YACpB,qBAAqB;YACrB,qBAAqB;YACrB,sBAAsB;YACtB,yBAAyB;YACzB,kBAAkB;YAClB,mBAAmB;YACnB,oBAAoB;YACpB,mBAAmB;YACnB,0BAA0B;YAC1B,qBAAqB;YACrB,2BAA2B;YAC3B,kDAAkD;YAClD,yDAAyD;YACzD,8CAA8C;SAC9C,CAAC;KACF,CAAC;CACF,CAAC,CAAA"}