arkgate 3.7.0 → 3.8.0

package/templates/skills/ark-upgrade.md

@@ -1,200 +1,140 @@
 ---
 name: ark-upgrade
-description: Update arkgate to the latest published version, then refresh gates and /ark-* skills for the active agent host (defer inactive hosts like Codex when not in use) and re-verify the architecture check. Autonomous.
+description: Upgrade ArkGate through a content-identity preview, preserve customized files, and verify the active host and architecture contract.
 ---
 
-# /ark-upgrade — Update ArkGate and refresh its gates
+# /ark-upgrade — managed ArkGate upgrade
 
-Update the `arkgate` dependency to the latest published version and
-bring the repo's generated artifacts and gates in line with it. This skill
-checks the registry itself — don't assume the copy in `node_modules` is current.
+Upgrade the published `arkgate` package and its managed gates without treating a
+filename, package version, or similar-looking file as proof of ownership. The
+preview is the source of truth: inspect it before applying anything.
 
-**Still on `ark-runtime-kernel`?** Migrate first (same product, new package name):
-
-```bash
-npm uninstall ark-runtime-kernel && npm install -D arkgate
-npx arkgate-check --install-agent-gates --force
-```
-
-Guide: `docs/migrate-from-ark-runtime-kernel.md` in the package (or on GitHub).
-
-**TypeScript 7 projects:** ArkGate falls back to a nested JS-API TypeScript when the
-project's `typescript` main export is version-only (TS 7.0). After upgrade, point users at
-`docs/typescript-support.md` if the gate or `ARK_DEBUG_TS=1` mentions fallback. Dual install
-(TS6 JS API + TS7 CLI) is optional for tooling that still needs classic `tsc` APIs.
-
-**MCP double-bin check (identity cutover):** after upgrade, open `.mcp.json` and
-`.cursor/mcp.json`. `args` must contain **exactly one** of `arkgate-mcp` / `ark-mcp`
-(prefer `arkgate-mcp`), never both. If both appear, run:
-
-```
-npx arkgate-check --install-agent-gates --migrate-commands
-```
-
-`ark upgrade` already runs migrate-commands; re-run it if an older 2.x left dual names.
-
-**Adoption completeness:** run `npx arkgate-check --doctor` (or `--doctor --json`) and
-read the **Adoption** section — host gaps, Codex home temp paths, optional-but-populated
-core layers, missing origin snapshot, baseline policy. Fix commands are printed per gap.
-HTML reports include the same Adoption card (separate from the 0–100 fitness score).
-
-**Active host vs deferred hosts:** green the **session host** (Grok, Claude, Cursor, …)
-and repo gates first. Codex home (`$CODEX_HOME` prompts + `config.toml` MCP multi-project)
-is **deferred** unless this session is Codex or the user asked to fix Codex. Doctor marks
-those gaps `deferred` / info and does not put them in Top actions. A temp/upgrade MCP
-`--root` stays urgent (fail-closed rewrite). Never set **Incomplete?** because of deferred
-Codex debt.
+For greenfield onboarding, start with `/ark-architect` (or
+`ark-check --recommend`); for a brownfield repository, use `/ark-adopt` before
+this upgrade flow.
 
 ## Dual engine (mandatory)
 
-| Engine | Role |
-|--------|------|
-| **Deterministic** | CLI / MCP / contract sensors — exit codes, plan kinds, coverage numbers, install status |
-| **Exploratory** | You open **this** repo's real files and product surface before concluding |
-
-The CLI is a **sensor**, never the whole job. Claiming done without the exploratory bar for this skill is **incomplete**.
-
+Use the semantic sensor (`ark-check --doctor --json` plus the strict contract
+check) and direct inspection of every managed file the preview will change.
+Neither signal replaces the other.
+
+## Safety contract
+
+- `ark upgrade` is read-only. It reports the selected profile and hosts, every
+  managed asset, its content state, and the exact next command.
+- The first `ark upgrade --apply` updates the dependency and lockfile, then runs
+  the newly installed CLI to produce another read-only preview. It does **not**
+  apply that preview's gate or skill changes.
+- The post-update/no-install preview's `nextCommand` includes
+  `--plan-digest <sha256:…>` and applies only that exact candidate. A changed file
+  or selection invalidates the digest instead of being overwritten.
+- Missing or conflicted assets previously recorded as managed require explicit
+  `--accept-conflicts`. Stop and obtain user consent before using it.
+- Customized files are preserved. Unrelated source files and similar filenames
+  are never adopted. The command never writes a Codex home or another global
+  directory implicitly.
+- Do not combine this flow with legacy `--force`, `--migrate-commands`, or
+  `--codex-home` repair commands. Diagnose any older adoption debt separately.
+
+## Read the states
+
+| State | Meaning | Action |
+|---|---|---|
+| `current` | Content identity matches the candidate. | Record/adopt safely; metadata-only stamps may refresh. |
+| `stale` | Recorded managed content still matches its old identity. | Safe candidate replacement. |
+| `missing` | Candidate is absent. | Create if new; require consent if a recorded asset was deleted. |
+| `customized` | User content diverged without a competing managed base. | Preserve it. |
+| `conflicted` | Both managed base and user content diverged. | Preserve and require explicit consent. |
+| `retired` | A recorded asset is no longer selected by the candidate. | Preserve its file and manifest identity; take no action. |
+
+## Procedure
+
+1. **Establish versions and context.** Read the installed
+   `node_modules/arkgate/package.json`, query `npm view arkgate version`, identify
+   the repository package manager, and open the intervening entries in the
+   shipped `CHANGELOG.md` (fall back to registry or release notes and name that
+   source). Do not infer “latest” from `node_modules` alone.
+
+2. **Preview managed content.** Run:
+
+   ```bash
+   ark upgrade --json
+   ```
+
+   Pass `--root <path>` and `--tools <active-host>` when selection would otherwise
+   be ambiguous. Open the reported files that matter to this repository. Confirm
+   that customized files remain non-applying and that any deletion/conflict is
+   blocked.
+
+3. **Update and re-preview.** If the registry is newer, run:
+
+   ```bash
+   ark upgrade --apply
+   ```
+
+   This updates through the detected package manager and hands control to the new
+   package for a fresh preview. Review that new preview; do not assume the old
+   candidate and new candidate are identical. If already on the latest package,
+   retain the current read-only preview.
+
+   For pnpm repositories with `minimumReleaseAge`, use the repository's existing
+   trusted first-party exception mechanism when the new release is still cooling
+   off, and prove `pnpm install --frozen-lockfile` succeeds.
+
+4. **Apply only the reviewed candidate.** When there are no blocked assets, run
+   the preview's exact `nextCommand`, whose shape is:
+
+   ```bash
+   ark upgrade --apply --no-install --plan-digest <preview-digest>
+   ```
+
+   If recorded deletion/conflict recovery is desired, ask first and then add
+   `--accept-conflicts`. Never add it merely to make the run green. Run a second
+   preview and require `summary.changed: 0`.
+
+5. **Verify enforcement and architecture.** Run `ark-check --doctor --json` and
+   the same fail-closed architecture command used by managed apply (normally
+   `ark-check --root . --config ark.config.json --strict-merge --json`). Require
+   `completeness: "complete"` and `ok: true`. Treat provider-unavailable CI
+   required-check evidence as `unverified`, never as proof that merges are
+   blocked. If new violations appear, hand off to `/ark-fix` for a small set or
+   `/ark-loop` / `/ark-autopilot` for residual debt; do not regenerate a baseline
+   without explicit approval.
+
+## Active host vs deferred hosts
+
+**Active host:** its repo-local gate, skills, MCP/advisory surface, doctor evidence,
+and strict check must be coherent before completion.
+
+**Deferred hosts:** inactive hosts may remain untouched and must be named with a
+future repair command when relevant. Deferred hosts never make Incomplete? `yes`
+once the active host and shared repository surfaces are verified. A temporary
+upgrade path or an actively selected host is not deferred.
+
+The managed manifest retains the selected host set, so a later preview does not
+silently switch to a different host. Home-level Codex setup is separate and is
+never an implicit side effect of this skill.
 
 ## Subagent fan-out (optional, host-dependent)
 
-If the host supports **parallel subagents** and the task splits cleanly (e.g. multiple
-dirs to sample), fan out read-only scouts; otherwise **fall back to sequential**.
-Parent merges and still emits the **### Completion** contract. Never parallel-write
-the same files or weaken the gate.
-
-## Fast path
-
-One command does the whole flow — update the package, refresh gates + `/ark-*` skills
-(and best-effort Codex home prompts when `~/.codex` exists), migrate command runners,
-and run the strict check:
-
-```
-arkgate upgrade
-# (alias: ark upgrade)
-```
-
-Use it when the user just wants the update done. Run the detailed steps below instead when
-you need to inspect the changelog first, handle a pnpm cooling-off window, or the one-liner
-reports a problem to triage. Always refresh skills so agents pick up new `mechanical-safe`
-kinds and TS guidance:
-
-```
-npx arkgate-check --install-agent-gates --skills-only --force
-```
-
-## Steps
-
-1. **Check the registry, then update.** Compare the installed version
-   (`node_modules/arkgate/package.json`) against the latest published:
-   `npm view arkgate version`. If a newer version exists, update it —
-   `npm install -D arkgate@latest` (or the project's package manager:
-   `pnpm add -D` / `yarn add -D`) — so the lockfile moves too; a pinned lockfile
-   is exactly why "just re-run install" often stays on the old version. If the
-   installed version already equals the latest, say so and still run steps 3-4
-   (a prior version may have shipped skills/gates this repo never installed).
-   Do NOT report "no update available" from the `node_modules` version alone —
-   that reads stale.
-   **pnpm cooling-off:** if the repo enforces a pnpm `minimumReleaseAge` and the new
-   version was published inside that window (common for a freshly-cut release), a plain
-   `pnpm add` in loose mode can leave a lockfile that `pnpm install --frozen-lockfile` (what
-   CI runs) then REJECTS. Do it cleanly: add the exact `<pkg>@<version>` to
-   `minimumReleaseAgeExclude` in `pnpm-workspace.yaml` FIRST, bump the dependency spec, then
-   run a plain `pnpm install`, and verify with `pnpm install --frozen-lockfile` before moving
-   on. Only exclude a first-party package you trust.
-2. **Changelog triage** — read `node_modules/arkgate/CHANGELOG.md`
-   (shipped in the package) for the versions between old and new, and pick out
-   only entries that affect THIS repo (new flags, changed defaults, new gate
-   templates, new skills). Summarize each in one sentence with what, if
-   anything, the repo must do about it. If the file is absent (older releases
-   didn't ship it), fall back to `npm view arkgate@<version> ...` or
-   the GitHub release notes — say which source you used.
-3. **Refresh templates** — run `ark-check --install-agent-gates`. Without
-   `--force` it only writes missing files (new skills, new tool templates) and
-   skips existing ones. To pick up NEW versions of the `/ark-*` skills that a
-   package update shipped, run `ark-check --install-agent-gates --skills-only
-   --force`: `--skills-only` scopes the overwrite to the canonical skills and
-   leaves the gate files alone. Do NOT run a bare `--install-agent-gates --force`
-   to refresh skills — it also overwrites `AGENTS.md` (often customized with the
-   project's real layer table), `.claude/settings.json` (hooks/permissions), and
-   `.github/workflows/ark-check.yml` (CI) with the generic templates, silently
-   losing customizations. If the changelog says a GATE file changed, report the
-   diff and let the user decide; never rewrite settings/CI/AGENTS.md without
-   explicit approval.
-   **Active host first.** Refresh skills for the host running this skill (e.g.
-   `.grok/skills/`, `.claude/skills/`, `.cursor/commands/`). Repo-local copies for
-   other detected hosts are fine to refresh in the same pass when cheap.
-   **Codex is deferred when you are not on Codex.** Repo skills live in
-   `.agents/skills/<name>/SKILL.md`; optional home skills in
-   `$CODEX_HOME/skills/<name>/SKILL.md` (not legacy flat `$CODEX_HOME/prompts`).
-   When **on Codex**, refresh **both** repo catalog and home if doctor reports
-   missing/stale/legacy-prompts-only parity gaps. `ark upgrade` may best-effort
-   refresh home when it exists; still list Codex under **Deferred hosts** when
-   not on Codex and do **not** chase MCP multi-project / stale home skills until
-   the user is on Codex (or asks). Fix when needed:
-   `ark-check --install-agent-gates --skills-only --tools codex --force` and/or
-   `ark-check --install-agent-gates --skills-only --codex-home --force`
-   (and `--tools codex` / `--force` for primary MCP rebind). Exception: temp or
-   `ark-upgrade` MCP `--root` paths — leave fail-closed rewrite to the CLI; do not
-   block completion on multi-project noise.
-   **Migrate stale command runners.** The package-manager-aware command templates
-   (`pnpm exec` / `yarn` / `npx`) only apply to NEWLY written files, so a repo that adopted
-   Ark before they shipped keeps a stale `npx` in its EXISTING gate files
-   (`.claude/settings.json` hooks, `.mcp.json`, `AGENTS.md`, the `check:architecture` script).
-   In a pnpm/yarn repo that means the write gate runs on a command the repo forbids. Run
-   `ark-check --install-agent-gates --migrate-commands`: it rewrites ONLY the command runner
-   in those files, preserving every customization (no `--force` clobber). A normal `ark-check`
-   also flags this when it detects the mismatch.
-4. **Re-verify** — `ark-check --root . --config ark.config.json
-   --strict-config` (with `--baseline .ark-baseline.json` if present). A new
-   version may detect violations the old one missed: if new violations appear,
-   **STOP — do not continue this skill as complete.** **STOP — bulk residual debt: invoke /ark-loop or /ark-autopilot**
-   (or `/ark-fix` for a small set). If they are too numerous to fix
-   now, freezing them in the baseline (`--update-baseline`) is a valid stopgap
-   but it silences NEW violations, so it requires explicit user approval first
-   — never regenerate the baseline on your own to get a green check.
-
-## Operating rules
-
-- **Must green:** the **active session host** (skills + gates that host uses) and
-  shared repo surfaces (`.mcp.json` dual-bin, command runners, architecture check).
-- **May defer:** other hosts not used in this session. Always list them under
-  **Deferred hosts** with the fix command — do not treat them as Incomplete.
-  Codex home (global `$CODEX_HOME`) is the common case on Grok/Claude.
-- **Optional sync:** if other repo-local tool dirs already exist (`.cursor/`,
-  `.claude/`, …), refreshing their `/ark-*` skills is good hygiene when cheap;
-  it is not a reason to fail the skill when the active host is already current.
-- Never run `--force` blindly; customized files are the user's.
-- Stop only if the changelog documents a breaking config change with two valid
-  migration paths — then present both with a recommendation.
-
-## Related onboarding
-
-- After upgrade, re-run `ark-check --doctor` — `/ark-architect` and `ark-check --recommend` ship
-  with the package for **greenfield** shape adoption.
-- **Brownfield** repos: point users to `/ark-adopt` and `docs/brownfield-adoption.md`, not
-  `/ark-architect`. Demo: `docs/demos/02-brownfield-baseline-adoption.md`.
-- Refresh gates: `ark-check --install-agent-gates --force --skills-only` if skills are stale.
-
-## Verify and report
-
-End with a passing check. Report: latest published version, old → new version
-(or "already latest"), changelog entries that mattered here (plain language),
-files written/refreshed for the **active host**, deferred hosts (if any),
-skipped customized files needing a manual look, and the final check status.
+Parallelize independent preview, changelog, and enforcement checks when the
+host supports isolated subagents; otherwise fall back to sequential execution.
 
 ## Completion contract (skill incomplete if missing)
 
-End with **exactly** these headings (markdown `###`):
+Skill incomplete if missing any required verification or any field below.
+
+End with exactly this structure:
 
 ### Completion
 - **Sensor:** commands/tools run
-- **Opened:** real paths read (or `n/a` only if pure install/upgrade with no source analysis)
-- **Active host:** e.g. `grok` / `claude` / `cursor` / `codex` (skills/gates OK or note)
-- **Deferred hosts:** `none` | e.g. `codex — home MCP/prompts; fix when using Codex`
-- **Result:** one-line outcome
-- **Handoff:** `/ark-…` / CLI / `none`
-- **Incomplete?** `no` | `yes — <what is missing>`
-
-If a **STOP** handoff applies and you continued as if done, set **Incomplete?** to `yes`.
-**Deferred hosts (including Codex when not on Codex) never make Incomplete? yes.**
-**Skill incomplete if missing** any of the bullets above (use `none` for Deferred hosts when empty).
+- **Opened:** real project and changelog paths read
+- **Active host:** host and verified status
+- **Deferred hosts:** `none` or host plus future action
+- **Result:** old → new version and managed-upgrade outcome
+- **Handoff:** `/ark-…`, CLI action, or `none`
+- **Incomplete?** `no` or `yes — <missing work>`
+
+If a required verification did not run or a conflict remains blocked, report the
+task incomplete. Deferred hosts (including Codex when inactive) never make Incomplete? yes.

package/bin/lib/ai-velocity.mjs

@@ -1,293 +0,0 @@
-/**
- * Q05 — AI-velocity evidence (fixture-measured, no live LLM).
- *
- * Same fixed feature scenario on two arms:
- *   - design-weak: no golden norm → confused multi-path placement attempts
- *   - golden-path: `.ark/golden-pattern.json` newCodeHome → first attempt correct home
- *
- * Metric: **placementTurns** (agent-equivalent steps until a DomainModel landing).
- * Golden must be strictly better (fewer turns). Gate is never weakened.
- */
-import fs from 'node:fs';
-import path from 'node:path';
-import { layerForFile } from '../ark-shared.mjs';
-import { loadGoldenPattern, summarizeGoldenPattern } from './golden-pattern.mjs';
-import {
-  detectDesignSmells,
-  buildPatternBetsFromSmells,
-  summarizeDesignFitness,
-  assertPatternBetsNeverMechanicalSafe,
-} from './design-smells.mjs';
-import { collectGovernedFiles } from './scan-files.mjs';
-
-/** Fixed feature prompt + pure-domain snippet (same on both arms). */
-export const FEATURE_SCENARIO = {
-  id: 'add-pure-domain-canRefund',
-  prompt:
-    'Add a pure domain rule canRefund(status: string): boolean for order refund eligibility. No I/O, no ORM.',
-  fileName: 'canRefund.ts',
-  source:
-    "export function canRefund(status: string): boolean {\n  return status === 'paid';\n}\n",
-  /** Correct layer for this pure rule under the design-weak-enforce contract. */
-  correctLayer: 'DomainModel',
-  correctPath: 'src/domain/canRefund.ts',
-};
-
-/**
- * Agent-equivalent placement order when no golden guides new code (spaghetti confusion).
- * Wrong homes first (presentation / mixed), then domain — measured as friction.
- */
-export const DESIGN_WEAK_PLACEMENT_CANDIDATES = [
-  'src/features/orders/ui/canRefund.ts',
-  'src/routes/canRefund.ts',
-  'src/services/canRefund.ts',
-  FEATURE_SCENARIO.correctPath,
-];
-
-/**
- * @param {string} root
- * @param {object} config
- * @param {string} filePath relative
- */
-export function layerForPlacement(root, config, filePath) {
-  const layers = config?.layers || [];
-  if (!layers.length) return null;
-  return layerForFile(root, filePath, layers) || null;
-}
-
-/**
- * A landing is successful when the path is under the correct layer for the scenario.
- * Pure snippet has no imports — we do not invent gate denials; cost is placement friction.
- *
- * @param {string} root
- * @param {object} config
- * @param {string} filePath
- */
-export function isCorrectLanding(root, config, filePath) {
-  const layer = layerForPlacement(root, config, filePath);
-  return layer === FEATURE_SCENARIO.correctLayer;
-}
-
-/**
- * Build ordered placement attempts for an arm.
- * Golden with newCodeHome → single first attempt under that home.
- * Absent golden → design-weak candidate ladder.
- *
- * Accepts loadGoldenPattern result or summarizeGoldenPattern summary.
- * @param {object | null | undefined} golden
- */
-export function placementAttemptsForArm(golden) {
-  if (!golden || typeof golden !== 'object') {
-    return { guidedByGolden: false, attempts: [...DESIGN_WEAK_PLACEMENT_CANDIDATES] };
-  }
-
-  const present = golden.present === true;
-  const newCodeHome =
-    (typeof golden.newCodeHome === 'string' && golden.newCodeHome) ||
-    (typeof golden.golden?.newCodeHome === 'string' && golden.golden.newCodeHome) ||
-    null;
-
-  if (present && typeof newCodeHome === 'string' && newCodeHome.trim()) {
-    const home = newCodeHome.replace(/\\/g, '/').replace(/\/?$/, '/');
-    const rel = `${home}${FEATURE_SCENARIO.fileName}`.replace(/\/{2,}/g, '/');
-    return {
-      guidedByGolden: true,
-      attempts: [rel.startsWith('src/') || rel.startsWith('.') ? rel : rel.replace(/^\//, '')],
-    };
-  }
-
-  // Golden absent or no newCodeHome → full confused ladder (honest multi-layout friction).
-  return {
-    guidedByGolden: false,
-    attempts: [...DESIGN_WEAK_PLACEMENT_CANDIDATES],
-  };
-}
-
-/**
- * Measure placement turns for one arm (real layer resolution + golden load).
- *
- * @param {{
- *   root: string,
- *   config: object,
- *   armId: string,
- *   files?: string[],
- * }} opts
- */
-export function measureArmVelocity(opts) {
-  const { root, config, armId } = opts;
-  const goldenLoad = loadGoldenPattern(root);
-  const goldenSummary = summarizeGoldenPattern(goldenLoad);
-  const { guidedByGolden, attempts } = placementAttemptsForArm(goldenLoad);
-
-  const steps = [];
-  let placementTurns = 0;
-  let landedPath = null;
-  let landedLayer = null;
-
-  for (const candidate of attempts) {
-    placementTurns += 1;
-    const layer = layerForPlacement(root, config, candidate);
-    const ok = isCorrectLanding(root, config, candidate);
-    steps.push({
-      turn: placementTurns,
-      path: candidate,
-      layer,
-      correctLanding: ok,
-    });
-    if (ok) {
-      landedPath = candidate;
-      landedLayer = layer;
-      break;
-    }
-  }
-
-  // Real design residual sensors (honesty — not used to invent ENFORCE).
-  const files = opts.files ?? collectGovernedFiles(root, config);
-  const smells = detectDesignSmells(root, config, files, {
-    layersWithoutRules: [],
-    emptyLayers: [],
-    layers: [],
-  });
-  const patternBets = buildPatternBetsFromSmells(smells);
-  const designFitness = summarizeDesignFitness(smells, {
-    activeViolations: 0,
-    governedPercent: 100,
-    totalFiles: files.length,
-  });
-  const betsHonesty = assertPatternBetsNeverMechanicalSafe(patternBets);
-
-  return {
-    armId,
-    scenarioId: FEATURE_SCENARIO.id,
-    prompt: FEATURE_SCENARIO.prompt,
-    guidedByGolden,
-    goldenPattern: goldenSummary,
-    placementTurns: landedPath ? placementTurns : attempts.length + 1,
-    landed: Boolean(landedPath),
-    landedPath,
-    landedLayer,
-    steps,
-    designFitness: {
-      designWeak: designFitness.designWeak,
-      smellCount: designFitness.smellCount,
-      ids: designFitness.ids,
-    },
-    patternBetCount: patternBets.length,
-    patternBetsNeverMechanicalSafe: betsHonesty.ok,
-    metric: 'placementTurns',
-  };
-}
-
-/**
- * Compare two arms: golden must be strictly better on placementTurns.
- *
- * @param {ReturnType<typeof measureArmVelocity>} designWeakArm
- * @param {ReturnType<typeof measureArmVelocity>} goldenArm
- */
-export function compareVelocityArms(designWeakArm, goldenArm) {
-  const dw = designWeakArm.placementTurns;
-  const gp = goldenArm.placementTurns;
-  const goldenBetter = gp < dw;
-  const delta = dw - gp;
-  return {
-    metric: 'placementTurns',
-    designWeakTurns: dw,
-    goldenPathTurns: gp,
-    goldenStrictlyBetter: goldenBetter,
-    deltaTurns: delta,
-    relativeReduction: dw > 0 ? delta / dw : null,
-    method:
-      'Agent-equivalent placement attempts until DomainModel home for fixed pure-rule feature ' +
-      `(${FEATURE_SCENARIO.id}). Design-weak arm walks concurrent-layout candidates; ` +
-      'golden-path arm uses .ark/golden-pattern.json newCodeHome as first attempt. ' +
-      'No live LLM; gate not weakened; design-weak residual may remain on both arms.',
-  };
-}
-
-/**
- * Run full Q05 report object from two prepared roots (same config shape expected).
- *
- * @param {{
- *   designWeakRoot: string,
- *   goldenPathRoot: string,
- *   config: object,
- * }} opts
- */
-export function runAiVelocityComparison(opts) {
-  const designWeakArm = measureArmVelocity({
-    root: opts.designWeakRoot,
-    config: opts.config,
-    armId: 'design-weak',
-  });
-  const goldenArm = measureArmVelocity({
-    root: opts.goldenPathRoot,
-    config: opts.config,
-    armId: 'golden-path',
-  });
-  const comparison = compareVelocityArms(designWeakArm, goldenArm);
-
-  return {
-    schemaVersion: '1',
-    id: 'q05-ai-velocity',
-    mode: 'fixture-measured',
-    scenario: {
-      id: FEATURE_SCENARIO.id,
-      prompt: FEATURE_SCENARIO.prompt,
-      fileName: FEATURE_SCENARIO.fileName,
-      correctLayer: FEATURE_SCENARIO.correctLayer,
-      correctPath: FEATURE_SCENARIO.correctPath,
-      sourceBytes: Buffer.byteLength(FEATURE_SCENARIO.source, 'utf8'),
-    },
-    arms: {
-      'design-weak': designWeakArm,
-      'golden-path': goldenArm,
-    },
-    comparison,
-    honesty: {
-      designWeakArmStillDesignWeak: designWeakArm.designFitness.designWeak === true,
-      goldenDoesNotRequireClearingDesignWeak: true,
-      patternBetsNeverMechanicalSafe:
-        designWeakArm.patternBetsNeverMechanicalSafe &&
-        goldenArm.patternBetsNeverMechanicalSafe,
-      gateNotWeakened: true,
-      liveLlmRequired: false,
-    },
-    ok: comparison.goldenStrictlyBetter === true,
-  };
-}
-
-/**
- * Materialize golden-path arm: copy design-weak tree + write golden pattern.
- * Pure helper for harness / tests (caller owns temp lifecycle).
- *
- * @param {string} designWeakRoot
- * @param {string} destRoot
- * @param {{ name?: string, norm?: string, newCodeHome?: string }} [golden]
- */
-export function materializeGoldenPathArm(designWeakRoot, destRoot, golden = {}) {
-  copyTree(designWeakRoot, destRoot);
-  const arkDir = path.join(destRoot, '.ark');
-  fs.mkdirSync(arkDir, { recursive: true });
-  const body = {
-    schemaVersion: '1',
-    name: golden.name || 'domain-first pure rules',
-    norm:
-      golden.norm ||
-      'New pure business rules live under src/domain/; adapters and routes never own can*/policy helpers.',
-    newCodeHome: golden.newCodeHome || 'src/domain/',
-    examplePath: golden.examplePath || 'src/domain/canRefund.ts',
-  };
-  fs.writeFileSync(path.join(arkDir, 'golden-pattern.json'), JSON.stringify(body, null, 2) + '\n');
-  return body;
-}
-
-function copyTree(src, dst) {
-  fs.mkdirSync(dst, { recursive: true });
-  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
-    if (entry.name === 'node_modules' || entry.name === '.git') continue;
-    const s = path.join(src, entry.name);
-    const d = path.join(dst, entry.name);
-    if (entry.isDirectory()) copyTree(s, d);
-    else fs.copyFileSync(s, d);
-  }
-}

package/bin/lib/graph-cycles.mjs

@@ -1,6 +0,0 @@
-/** Compatibility adapter; canonical Tarjan evaluation lives in the bundled Kernel engine. */
-import { detectArchitectureCycles } from './analysis-engine.mjs';
-
-export function detectCycles(graph) {
-  return detectArchitectureCycles(graph);
-}