arkgate 3.0.1 → 3.0.3

package/CHANGELOG.md

@@ -4,7 +4,44 @@ All notable changes to ArkGate (`arkgate`; formerly `ark-runtime-kernel`) are do
 
 ## Unreleased
 
-No changes are scheduled after 3.0.1.
+No changes are scheduled after 3.0.3.
+
+## 3.0.3 — 2026-07-13
+
+### Added
+
+- **Post-green path (Q01):** when design residual remains under edge-clean ENFORCE, doctor
+  JSON exposes `postGreenPath` / `primaryNextAction` / `healthyFinishedForbidden` for a single
+  “clarify for AI / Shape” door (`clarify-for-ai`). Skill routing maps messy/design-weak work
+  to that path — no skill shopping.
+- **Smell outcomes (Q02):** each stable `designSmells[]` id carries plain-language `outcome`
+  for newbies; technical `message` retained; doctor human prints outcome first.
+- **Golden pattern (Q03):** optional `.ark/golden-pattern.json` (`name` + `norm`, optional
+  `newCodeHome` / `examplePath`). Surfaced on `ark_place`, `ark_prepare_write`, and
+  `doctor.goldenPattern` as **advisory for NEW code only**. Absent is OK; never ENFORCE;
+  never clears design-weak; malformed fails closed.
+- **Pilot loop (Q04):** `plan.pilotLoop` / `doctor.pilotLoop` select **one** next extraction
+  card (`nextPilot`: pilot target, move, success, kill-switch). One pilot → re-doctor;
+  residual outside the pilot may remain; never multi-pilot batch; never mechanical-safe.
+- **AI-velocity eval (Q05):** `npm run eval:ai-velocity` compares the same fixed feature
+  scenario on design-weak vs golden-path arms. Metric `placementTurns` (agent-equivalent);
+  golden must be strictly better. Fixture-measured (no live LLM); method string lives next
+  to the number in `eval/ai-velocity-report.json`.
+- **Skills:** `/ark-place` honors golden; explore/autopilot document pilot loop; `/ark-explain`
+  opens `ark-report.html` in the default browser after generating the showcase report.
+
+### Documentation
+
+- package-surface, agent-guide, brownfield pilot-loop section, eval README, Phase Q ROADMAP
+  evidence for Q01–Q05. Release note: `docs/releases/3.0.3.md`.
+
+## 3.0.2 — 2026-07-13
+
+### Documentation
+
+- Sync consumer-facing agent docs with 3.0.1 design-depth skills: `designFitness` /
+  `patternBets`, extraction cards, dual-plan B honesty in agent-guide, AI gates, and the
+  autopilot demo. Release note status for 3.0.1 marked published.
 
 ## 3.0.1 — 2026-07-13
 

package/README.md

@@ -38,6 +38,7 @@ If you remember nothing else:
 | Gate failed after an edit | `/ark-fix` |
 | “Where does this new file go?” | `/ark-place` |
 | Contract globs / layers wrong | `/ark-contract` |
+| **Messy / spaghetti code** (even if the gate is green) | **`/ark-explore`** then **`/ark-autopilot`** — [below](#less-spaghetti-after-the-gate-is-green) |
 | New ArkGate version | `/ark-upgrade` |
 
 **Everything else is optional.** You do not need to learn “modes”, 11 skills, or the runtime
@@ -92,9 +93,36 @@ mode you configure:
 |-------|--------|-----------|
 | **Suggest** | New/thin project | Finish `start` + autopilot |
 | **Adapt** | Not fully protected yet | Keep autopilot / adopt until clean |
-| **Enforce** | Contract coverage is honest and checked edges are clean | Keep the host-appropriate write path; require the CI status if it must block merges |
+| **Enforce** | Contract coverage is honest and checked **edges** are clean | Keep write path + CI. If the tree is still a mess → [Shape flow](#less-spaghetti-after-the-gate-is-green) |
+| **Enforce · design-weak** | Edges clean, but doctor still sees design smells (`designSmells` / `patternBets`) | **`/ark-explore`** (shape-focus) → **`/ark-autopilot`** for dual-plan **B** — not “done” |
 
-You **arrive** at Enforce. You never “turn on Enforce”.
+You **arrive** at Enforce. You never “turn on Enforce”.  
+**Enforce does not mean the design is elegant** — only that the contract’s import edges are honest.
+
+---
+
+## Less spaghetti after the gate is green
+
+A green check can still leave god modules, SQL in routes, and three patterns at once.
+That residual is **Shape** work — plan **B**, never auto-applied as mechanical-safe.
+
+```text
+1.  /ark-explore              ← map + dual-plan B + extraction cards (no apply)
+2.  /ark-autopilot            ← apply A (edges); B only with your ok, one pilot at a time
+3.  npx arkgate-check --doctor
+    npx arkgate-check --plan --json   ← designWeak + patternBets when residual remains
+```
+
+| If… | Skill |
+|-----|--------|
+| Need the map / “what’s the golden pattern?” | `/ark-explore` |
+| Ready to execute the dual plan | `/ark-autopilot` |
+| Contract still lies (false-green, wrong globs) | `/ark-adopt` first, then explore |
+| One cluster only | `/ark-fix` (+ extraction card) |
+| Only care about governed% / gates installed | `/ark-coverage` (not the Shape map) |
+
+Phases: **Align** (honest contract) → **Stabilize** (real baseline) → **Shape** (golden pattern + pilot).  
+Details: [docs/brownfield-adoption.md](docs/brownfield-adoption.md) §6 · skills install: `npx arkgate-check --install-agent-gates`.
 
 ---
 

package/bin/ark-mcp.mjs

@@ -60,6 +60,7 @@ import { validateWithAutoPatch, resolveImportFileAbs } from './lib/auto-patch.mj
 import { composePrepareWrite } from './lib/prepare-write.mjs';
 import { loadArkConfigContract } from './lib/config-contract.mjs';
 import { ARK_ANALYSIS_RESULT_SCHEMA, createAdapterResult } from './lib/adapter-contract.mjs';
+import { loadGoldenPattern, attachGoldenToPlacement } from './lib/golden-pattern.mjs';
 
 const arkCheckBin = fileURLToPath(new URL('./ark-check.mjs', import.meta.url));
 
@@ -748,7 +749,9 @@ async function main() {
       name: 'ark_place',
       description:
         'Place a file in the architecture: pass filePath (preferred) and/or description. ' +
-        'Returns layer, mayImport / mustNotImport, forbiddenGlobals. Call BEFORE writing a new file. ' +
+        'Returns layer, mayImport / mustNotImport, forbiddenGlobals, and optional goldenPattern ' +
+        '(advisory for NEW code when .ark/golden-pattern.json exists — never clears design-weak). ' +
+        'Call BEFORE writing a new file. ' +
         'If only description is given, returns a conventional path proposal under a governed layer. ' +
         'Prefer ark_prepare_write when you already have the source snippet (place+validate+autoPatch in one call).',
       inputSchema: {
@@ -1007,7 +1010,11 @@ async function main() {
   // Deterministic placement guidance (in-process; no TS resolver needed): which layer a
   // path falls in, and — from the same rules ark-check enforces (default allow, explicit
   // `allowed:false` denies) — which layers it may and must not import.
+  // Q03: when present, attach optional `.ark/golden-pattern.json` (advisory for NEW code only).
   function placeResult(filePath, description) {
+    const golden = loadGoldenPattern(args.root);
+    const withGolden = (placement) => attachGoldenToPlacement(placement, golden);
+
     if ((typeof filePath !== 'string' || !filePath) && typeof description === 'string' && description.trim()) {
       const slug = description
         .trim()
@@ -1017,7 +1024,7 @@ async function main() {
         .slice(0, 48) || 'component';
       const proposedPath = `src/components/${slug}.tsx`;
       const layerName = inferLayer(proposedPath, config, args.root) || 'PresentationAdapters';
-      return {
+      return withGolden({
         filePath: proposedPath,
         proposed: true,
         description: description.trim(),
@@ -1026,7 +1033,7 @@ async function main() {
         note:
           'filePath was omitted — proposed a conventional path from description. ' +
           'Pass filePath explicitly for authoritative placement.',
-      };
+      });
     }
     if (typeof filePath !== 'string' || !filePath) {
       return {
@@ -1038,7 +1045,7 @@ async function main() {
     const layerName = inferLayer(filePath, config, args.root);
     if (!layerName) {
       const noLayers = configLayers.length === 0;
-      return {
+      return withGolden({
         filePath,
         layer: null,
         governed: noLayers,
@@ -1051,7 +1058,7 @@ async function main() {
             'rules enforced). Place it under a directory a layer in ark.config.json ' +
             'matches, or add a layer. See suggestedLayers for conventional homes.',
         suggestedLayers: suggestedLayers(),
-      };
+      });
     }
     const layerMeta = configLayers.find((layer) => layer.name === layerName);
     const rules = config.rules ?? DEFAULT_RULES;
@@ -1060,7 +1067,7 @@ async function main() {
       rules.some((rule) => !rule.allowed && rule.from === layerName && rule.to === to)
     );
     const mayImport = otherNames.filter((name) => !mustNotImport.includes(name));
-    return {
+    return withGolden({
       filePath,
       layer: layerName,
       governed: true,
@@ -1072,7 +1079,7 @@ async function main() {
       note:
         'mayImport = layers with no explicit deny (default is allow). Respect ' +
         'forbiddenGlobals, then verify the actual snippet with validate_code or ark_prepare_write.',
-    };
+    });
   }
 
   function runPlace(params) {

package/bin/lib/ai-velocity.mjs

@@ -0,0 +1,293 @@
+/**
+ * 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/ci-and-commands.mjs

@@ -158,21 +158,23 @@ Do **not** run overlapping skills for the same job. Pick **one** primary skill f
 | When | Invoke | Not this |
 |------|--------|----------|
 | Unsure / make architecture sound (apply path) | **/ark-autopilot** (default) | explore-only, coverage-only |
-| Map / residual / dual-plan **seed** / spaghetti Shape plan (no apply) | \`/ark-explore\` | coverage (fitness only), think (one decision) |
-| ENFORCE but design-weak / concurrent patterns / god modules | \`/ark-explore\` shape-focus or dual-plan seed → then autopilot for apply | loop (empty A is not done) |
+| **Messy / spaghetti / design-weak after green / clarify for AI** | **Single path:** \`/ark-explore\` shape-focus → dual-plan B, then \`/ark-autopilot\` only to apply B with OK | coverage, think, loop-as-done, skill-shopping |
+| Map / residual / dual-plan seed only (no apply, already know you want recon) | \`/ark-explore\` | coverage (fitness only) |
 | Greenfield shape / empty tree | \`/ark-architect\` | adopt |
 | Brownfield / wrong contract / false-green | \`/ark-adopt\` then \`/ark-contract\` if globs wrong | architect |
 | Edit \`ark.config.json\` layers/rules/intents | \`/ark-contract\` | fix/loop for config |
 | New file “where does this go?” | \`/ark-place\` | architect (unless greenfield shape missing) |
 | Gate violation on a change (small cluster) | \`/ark-fix\` | loop/autopilot unless bulk |
-| Drive plan **A** to goal.met | \`/ark-loop\` | explore (unless A empty + design residual) |
-| Ark **fitness** only (governed%, gates, baseline, install gaps) | \`/ark-coverage\` | explore (full recon) |
-| One design decision, 2–3 options | \`/ark-think\` | explore (full dual-plan) |
+| Drive plan **A** to goal.met | \`/ark-loop\` | explore (unless A empty + design residual → single Shape path above) |
+| Ark **fitness** only (governed%, gates, baseline, install gaps) | \`/ark-coverage\` | Shape / design-weak (use single path above) |
+| One design decision, 2–3 options | \`/ark-think\` | full Shape residual (use single path) |
 | Explain / HTML report tour | \`/ark-explain\` | explore |
 | Bump arkgate + refresh hosts | \`/ark-upgrade\` | — |
 | Optional runtime kernel evaluate | \`/ark-runtime\` | — |
 
-**Phases (brownfield honesty):** Align (contract truth) → Stabilize (real baseline) → Shape (golden pattern + pilot). Empty plan A after Stabilize still leaves Shape work — that is explore/autopilot **B**, not “healthy finished.”
+**Post-green door (Q01):** when doctor reports ENFORCE · design-weak, the **primary** next action is the single Shape path above — not a choice among explore / coverage / think. Doctor JSON: \`postGreenPath\` / \`primaryNextAction\`.
+
+**Phases (brownfield honesty):** Align (contract truth) → Stabilize (real baseline) → Shape (golden pattern + pilot). Empty plan A after Stabilize still leaves Shape work — that is the single post-green path, not “healthy finished.”
 
 ## Before editing TypeScript or JavaScript source files