arkgate 3.0.2 → 3.0.4

package/bin/lib/pilot-loop.mjs

@@ -0,0 +1,266 @@
+/**
+ * Q04 — productized pilot loop: extraction card → one pilot → re-doctor.
+ *
+ * Selects a single next pilot from patternBets / design smells, emits an
+ * extraction-card payload, and compares residual after re-doctor on pilot paths.
+ * Judgment only — never mechanical-safe; never multi-pilot batch apply.
+ */
+import { buildPatternBetsFromSmells } from './design-smells.mjs';
+
+/** Stable product id for JSON / tests. */
+export const PILOT_LOOP_ID = 'one-pilot-redoctor';
+
+/** Smell priority when choosing the single next pilot (lower = earlier). */
+const SMELL_PRIORITY = {
+  'facade-sql-in-routes': 0,
+  'io-under-application': 1,
+  'handler-in-persistence': 2,
+  'domain-logic-in-ui': 3,
+  'god-module': 4,
+  'soft-contract': 5,
+  'mixed-pattern-cluster': 6,
+};
+
+const DEFAULT_DO_NOT = [
+  'rewrite queries / touch schema / migrations',
+  'weaken ark.config.json to silence the smell',
+  'auto-apply as mechanical-safe or invent new mechanical-safe kinds',
+  'big-bang the whole monorepo',
+];
+
+/**
+ * Evidence entries that are real file paths (not layout: / layer: tokens).
+ * @param {string[]} evidence
+ * @returns {string[]}
+ */
+export function fileEvidencePaths(evidence = []) {
+  return (evidence || []).filter(
+    (e) =>
+      typeof e === 'string' &&
+      e.length > 0 &&
+      !e.startsWith('layout:') &&
+      !e.startsWith('layer:') &&
+      !e.startsWith('rule:')
+  );
+}
+
+/**
+ * Score a pattern bet for "do this pilot first".
+ * Prefers concrete src/ files and higher-impact smell ids.
+ * @param {object} bet
+ * @param {number} index
+ */
+function scoreBet(bet, index) {
+  const files = fileEvidencePaths(bet?.evidence);
+  const smellPri = SMELL_PRIORITY[bet?.smellId] ?? 50;
+  // Higher score wins; concrete files dominate; then smell priority; stable by index.
+  return files.length * 100 - smellPri * 10 - index;
+}
+
+/**
+ * Build extraction-card fields from one pattern bet (P03/P05 vocabulary).
+ * @param {object} bet
+ * @param {string[]} [preferredFiles]
+ */
+export function extractionCardFromBet(bet, preferredFiles) {
+  if (!bet || typeof bet !== 'object') return null;
+  const files = preferredFiles?.length
+    ? preferredFiles
+    : fileEvidencePaths(bet.evidence);
+  const evidence = files.length ? files : (bet.evidence || []).slice(0, 8);
+  const pilotTarget =
+    files[0] ||
+    (typeof bet.pilot === 'string' ? bet.pilot : null) ||
+    'src/**';
+
+  return {
+    id: PILOT_LOOP_ID,
+    patternBetId: bet.id || `pattern-b:${bet.smellId || 'unknown'}`,
+    smellId: bet.smellId || 'unknown',
+    pilot: typeof bet.pilot === 'string' ? bet.pilot : pilotTarget,
+    pilotTarget,
+    evidence,
+    move:
+      typeof bet.fix === 'string' && bet.fix.trim()
+        ? bet.fix.trim()
+        : 'Apply one bounded extraction for this smell on pilot paths only',
+    doNot: [...DEFAULT_DO_NOT],
+    successSignal:
+      typeof bet.successSignal === 'string'
+        ? bet.successSignal
+        : 'Smell evidence paths cleared on pilot without weakening the contract',
+    killSwitch:
+      typeof bet.killSwitch === 'string'
+        ? bet.killSwitch
+        : 'If pilot increases edge violations without design clarity, stop and re-map with /ark-explore',
+    neverMechanicalSafe: true,
+    class: 'judgment',
+    loopStep: 'one-pilot',
+    reDoctor: 'ark-check --doctor --json',
+    rePlan: 'ark-check --plan --json',
+    next:
+      '/ark-fix (one cluster) | /ark-autopilot (user ok on B) | re-doctor after pilot',
+  };
+}
+
+/**
+ * Select **one** next pilot from pattern bets (or build bets from smells).
+ * @param {object[] | null | undefined} patternBets
+ * @param {{ designSmells?: object[] }} [options]
+ * @returns {null | ReturnType<typeof extractionCardFromBet>}
+ */
+export function selectNextPilot(patternBets, options = {}) {
+  let bets = Array.isArray(patternBets) ? [...patternBets] : [];
+  if (bets.length === 0 && Array.isArray(options.designSmells) && options.designSmells.length) {
+    bets = buildPatternBetsFromSmells(options.designSmells);
+  }
+  if (bets.length === 0) return null;
+
+  let best = null;
+  let bestScore = -Infinity;
+  for (let i = 0; i < bets.length; i++) {
+    const bet = bets[i];
+    if (!bet || bet.neverMechanicalSafe === false) continue;
+    // Skip anything that claims mechanical-safe (honesty).
+    if (bet.class === 'mechanical-safe') continue;
+    const files = fileEvidencePaths(bet.evidence);
+    const sc = scoreBet(bet, i);
+    if (sc > bestScore) {
+      bestScore = sc;
+      best = { bet, files };
+    }
+  }
+  if (!best) return null;
+  return extractionCardFromBet(best.bet, best.files);
+}
+
+/**
+ * Human-readable extraction card block (P05 template parity).
+ * @param {ReturnType<typeof extractionCardFromBet>} card
+ * @returns {string | null}
+ */
+export function formatExtractionCard(card) {
+  if (!card) return null;
+  const doNot = (card.doNot || DEFAULT_DO_NOT).map((d) => `  - ${d}`).join('\n');
+  return [
+    '### Extraction card',
+    `Pilot: ${card.pilotTarget || card.pilot}`,
+    `Smell: ${card.smellId}`,
+    `Move: ${card.move}`,
+    'Do not:',
+    doNot,
+    `Success: ${card.successSignal}`,
+    `Kill-switch: ${card.killSwitch}`,
+    `Next: ${card.next}`,
+    '(Q04 pilot loop: one pilot at a time → re-doctor; never mechanical-safe)',
+  ].join('\n');
+}
+
+/**
+ * Doctor/plan JSON summary of the active pilot loop step.
+ * @param {{
+ *   designWeak?: boolean,
+ *   patternBets?: object[],
+ *   designSmells?: object[],
+ * }} opts
+ */
+export function summarizePilotLoop(opts = {}) {
+  const designWeak = opts.designWeak === true;
+  if (!designWeak) {
+    return {
+      active: false,
+      id: PILOT_LOOP_ID,
+      reason: 'not-design-weak',
+      oneAtATime: true,
+      neverMechanicalSafe: true,
+    };
+  }
+
+  const nextPilot = selectNextPilot(opts.patternBets, {
+    designSmells: opts.designSmells,
+  });
+  if (!nextPilot) {
+    return {
+      active: false,
+      id: PILOT_LOOP_ID,
+      reason: 'no-pattern-bets',
+      oneAtATime: true,
+      neverMechanicalSafe: true,
+    };
+  }
+
+  const remaining = Array.isArray(opts.patternBets) ? opts.patternBets.length : 0;
+
+  return {
+    active: true,
+    id: PILOT_LOOP_ID,
+    oneAtATime: true,
+    neverMechanicalSafe: true,
+    remainingBets: remaining,
+    nextPilot,
+    instruction:
+      'Apply ONE pilot from nextPilot (extraction card), then re-doctor. ' +
+      'Do not multi-pilot batch. patternBets never mechanical-safe. ' +
+      'Success = reduced smell evidence on pilot paths; residual outside pilot may remain.',
+    cardText: formatExtractionCard(nextPilot),
+  };
+}
+
+/**
+ * Compare design-smell residual on the pilot after a single change.
+ * Drives real before/after smell arrays (from detectDesignSmells).
+ *
+ * @param {{
+ *   beforeSmells: object[],
+ *   afterSmells: object[],
+ *   nextPilot: { smellId: string, evidence?: string[], pilotTarget?: string, pilot?: string },
+ * }} args
+ */
+export function comparePilotResidual({ beforeSmells, afterSmells, nextPilot }) {
+  const smellId = nextPilot?.smellId;
+  const pilotFiles = fileEvidencePaths(nextPilot?.evidence || []);
+  if (nextPilot?.pilotTarget && !pilotFiles.includes(nextPilot.pilotTarget)) {
+    if (
+      typeof nextPilot.pilotTarget === 'string' &&
+      !nextPilot.pilotTarget.startsWith('layout:') &&
+      !nextPilot.pilotTarget.includes('**')
+    ) {
+      pilotFiles.push(nextPilot.pilotTarget);
+    }
+  }
+
+  const beforeSmell = (beforeSmells || []).find((s) => s.id === smellId);
+  const afterSmell = (afterSmells || []).find((s) => s.id === smellId);
+
+  const beforeAll = fileEvidencePaths(beforeSmell?.evidence);
+  const afterAll = fileEvidencePaths(afterSmell?.evidence);
+
+  // Evidence on the pilot file set (exact path match).
+  const beforeOnPilot = pilotFiles.length
+    ? pilotFiles.filter((p) => beforeAll.includes(p))
+    : beforeAll;
+  const afterOnPilot = pilotFiles.length
+    ? pilotFiles.filter((p) => afterAll.includes(p))
+    : afterAll;
+
+  const pilotSmellCleared = !afterSmell;
+  const reduced =
+    afterOnPilot.length < beforeOnPilot.length ||
+    (pilotSmellCleared && beforeOnPilot.length > 0);
+
+  return {
+    smellId,
+    pilotFiles,
+    beforeEvidenceCount: beforeOnPilot.length,
+    afterEvidenceCount: afterOnPilot.length,
+    beforeEvidence: beforeOnPilot,
+    afterEvidence: afterOnPilot,
+    beforeSmellPresent: Boolean(beforeSmell),
+    afterSmellPresent: Boolean(afterSmell),
+    pilotSmellCleared,
+    reduced,
+    // Global residual may remain — honest Shape work.
+    beforeSmellCount: (beforeSmells || []).length,
+    afterSmellCount: (afterSmells || []).length,
+  };
+}

package/bin/lib/post-green-path.mjs

@@ -0,0 +1,79 @@
+/**
+ * Q01 — Single post-green product path (“clarify for AI” / Shape).
+ *
+ * When edges are clean but design residual remains, doctor + agent routing name
+ * ONE door that chains map → dual-plan B. No skill shopping; no new skill basename.
+ * Plan B stays never mechanical-safe.
+ */
+
+/** Stable product id for JSON / tests. */
+export const POST_GREEN_PATH_ID = 'clarify-for-ai';
+
+/** Primary skill entry (map + dual-plan seed). Apply is second step of the same path. */
+export const POST_GREEN_PRIMARY_SKILL = '/ark-explore';
+
+/**
+ * Canonical human / agent next-action string (single door).
+ * Chained: explore shape-focus then autopilot only to apply B with user OK.
+ */
+export const POST_GREEN_PRIMARY_ACTION =
+  'Clarify for AI (Shape): /ark-explore shape-focus → dual-plan B, then /ark-autopilot only to apply B with your OK — never empty plan A = done; patternBets never mechanical-safe';
+
+/** Short label for tables / metrics. */
+export const POST_GREEN_PRIMARY_SHORT =
+  '/ark-explore shape-focus → /ark-autopilot (apply B with OK)  # clarify for AI';
+
+/**
+ * @param {{ designWeak?: boolean } | null | undefined} designFitness
+ * @returns {null | {
+ *   id: string,
+ *   primary: true,
+ *   skill: string,
+ *   applySkill: string,
+ *   flow: string,
+ *   action: string,
+ *   short: string,
+ *   neverMechanicalSafe: true,
+ *   healthyFinishedForbidden: true,
+ * }}
+ */
+export function buildPostGreenNextAction(designFitness) {
+  if (!designFitness?.designWeak) return null;
+  return {
+    id: POST_GREEN_PATH_ID,
+    primary: true,
+    skill: POST_GREEN_PRIMARY_SKILL,
+    applySkill: '/ark-autopilot',
+    flow: 'shape-focus',
+    action: POST_GREEN_PRIMARY_ACTION,
+    short: POST_GREEN_PRIMARY_SHORT,
+    neverMechanicalSafe: true,
+    healthyFinishedForbidden: true,
+  };
+}
+
+/**
+ * Put the single post-green door first; drop competing Shape guidance strings.
+ * @param {string[]} actions
+ * @param {ReturnType<typeof buildPostGreenNextAction>} postGreen
+ * @returns {string[]}
+ */
+export function mergePostGreenTopActions(actions, postGreen) {
+  const list = [...(actions || [])].filter(Boolean);
+  if (!postGreen?.action) return [...new Set(list)];
+
+  const competing =
+    /\/ark-explore|\/ark-autopilot|shape residual|dual-plan B|pattern bet|shape-focus|clarify for ai|design-weak/i;
+  const filtered = list.filter((a) => !competing.test(a));
+  return [postGreen.action, ...new Set(filtered)];
+}
+
+/**
+ * Whether doctor may print “Healthy — nothing to do”.
+ * @param {{ designWeak?: boolean } | null | undefined} designFitness
+ * @param {string[]} topActions
+ */
+export function isDoctorHealthyNothingToDo(designFitness, topActions = []) {
+  if (designFitness?.designWeak) return false;
+  return !topActions.some(Boolean);
+}

package/bin/lib/prepare-write.mjs

@@ -115,6 +115,8 @@ export function composePrepareWrite(opts) {
     ...(placement?.message ? { placementMessage: placement.message } : {}),
     ...(placement?.note ? { placementNote: placement.note } : {}),
     ...(placement?.description ? { description: placement.description } : {}),
+    // Q03: pass through golden pattern from ark_place (advisory; absent is normal).
+    ...(placement?.goldenPattern ? { goldenPattern: placement.goldenPattern } : {}),
     valid: gate.valid,
     violations: gate.violations,
     ...(gate.autoPatch ? { autoPatch: gate.autoPatch } : {}),

package/bin/lib/skill-install.mjs

@@ -43,10 +43,11 @@ export function detectActiveAgentHost(env = process.env) {
     .toLowerCase();
   if (explicit) return explicit;
 
-  // Grok / xAI Build
+  // Grok / xAI Build (include GROK_AGENT — common session signal missing in older detect)
   if (
     envTruthy(env.GROK_BUILD) ||
     envTruthy(env.XAI_GROK) ||
+    envTruthy(env.GROK_AGENT) ||
     env.GROK_WORKSPACE_ROOT ||
     env.GROK_SESSION_ID
   ) {

package/bin/lib/write-path-detect.mjs

@@ -30,21 +30,32 @@ export function detectWritePathCapabilities(root, explicitHost) {
 
   const tools = installToolsForHost(activeHost);
   let gap = null;
+  // Repo inventory (any host) can show hard/advisory write while activeHost is
+  // unknown (plain shell / `npx ark-check --report` outside an agent session).
+  // Session projection stays mode=none (other hosts' hooks are not a guarantee for
+  // this process) — but do not open an adoption gap: gates exist on disk.
+  const inventoryHasWriteBoundary =
+    Boolean(inventory?.capabilities?.['hard-write']) ||
+    Boolean(inventory?.capabilities?.['advisory-write']);
   if (mode === 'none') {
-    gap = {
-      id: 'write-path-none',
-      severity: 'warn',
-      message:
-        `Active host ${activeHost} has no hard write boundary or advisory Ark MCP. ` +
-        (capabilities['merge-gate']
-          ? 'The CI check remains separate and does not block local writes.'
-          : 'No Ark CI check was detected either.'),
-      fix: arkCommand(
-        root,
-        'ark-check',
-        `--install-agent-gates --tools ${tools}`
-      ),
-    };
+    if (activeHost === 'unknown' && inventoryHasWriteBoundary) {
+      gap = null;
+    } else {
+      gap = {
+        id: 'write-path-none',
+        severity: 'warn',
+        message:
+          `Active host ${activeHost} has no hard write boundary or advisory Ark MCP. ` +
+          (capabilities['merge-gate']
+            ? 'The CI check remains separate and does not block local writes.'
+            : 'No Ark CI check was detected either.'),
+        fix: arkCommand(
+          root,
+          'ark-check',
+          `--install-agent-gates --tools ${tools}`
+        ),
+      };
+    }
   } else if (mode === 'reject-only') {
     gap = {
       id: 'write-path-reject-only',

package/dist/index.cjs

@@ -50,7 +50,7 @@ __export(gate_exports, {
 module.exports = __toCommonJS(gate_exports);
 
 // src/version.ts
-var version = "3.0.2";
+var version = "3.0.4";
 
 // src/domain/adapterContract.ts
 var ARK_ANALYSIS_RESULT_SCHEMA_VERSION = "1.0";

package/dist/index.d.cts

@@ -2,7 +2,7 @@ import { a as ArkConfigRule, b as ArkConfigLayer, A as ArkConfig, c as ArkConfig
 export { d as ARK_CONFIG_SCHEMA, e as ARK_CONFIG_SCHEMA_VERSION, l as loadArkConfigContract, p as parseArkConfigJson } from './configContract-BxSIwVRo.cjs';
 
 /** ArkGate library version — single source of truth. */
-declare const version = "3.0.2";
+declare const version = "3.0.4";
 
 /** Versioned public result contract shared by every ArkGate enforcement adapter. */
 declare const ARK_ANALYSIS_RESULT_SCHEMA_VERSION: "1.0";

package/dist/index.d.ts

@@ -2,7 +2,7 @@ import { a as ArkConfigRule, b as ArkConfigLayer, A as ArkConfig, c as ArkConfig
 export { d as ARK_CONFIG_SCHEMA, e as ARK_CONFIG_SCHEMA_VERSION, l as loadArkConfigContract, p as parseArkConfigJson } from './configContract-BxSIwVRo.js';
 
 /** ArkGate library version — single source of truth. */
-declare const version = "3.0.2";
+declare const version = "3.0.4";
 
 /** Versioned public result contract shared by every ArkGate enforcement adapter. */
 declare const ARK_ANALYSIS_RESULT_SCHEMA_VERSION: "1.0";

package/dist/index.js

@@ -1,5 +1,5 @@
 // src/version.ts
-var version = "3.0.2";
+var version = "3.0.4";
 
 // src/domain/adapterContract.ts
 var ARK_ANALYSIS_RESULT_SCHEMA_VERSION = "1.0";

package/docs/agent-guide.md

@@ -82,19 +82,45 @@ explore then apply A + propose/apply-with-ok B. `/ark-loop` = plan A only. Empty
 “architecture healthy” if design-weak residual remains. Full routing table: full-install
 `AGENTS.md` / [README skill table](../README.md#other-skills-only-when-you-need-them).
 
-**Design fitness (3.0.1+):** after edges are clean, doctor can still report **ENFORCE · design-weak**.
+**Design fitness (3.0.1+ / Phase Q 3.0.3):** after edges are clean, doctor can still report **ENFORCE · design-weak**.
 
 ```bash
-npx ark-check --doctor --json   # doctor.designFitness + doctor.designSmells[]
-npx ark-check --plan --json     # plan.goal.designWeak + plan.patternBets[] (never mechanical-safe)
+npx ark-check --doctor --json   # designFitness, designSmells[].outcome, postGreenPath, goldenPattern, pilotLoop
+npx ark-check --plan --json     # plan.goal.designWeak + plan.patternBets[] + plan.pilotLoop
 ```
 
-Smell ids (stable): `io-under-application`, `handler-in-persistence`, `god-module`,
-`domain-logic-in-ui`, `facade-sql-in-routes`, `mixed-pattern-cluster`, `soft-contract`.
-Each has `evidence[]` paths. Plan **B** bets include `pilot`, `successSignal`, `killSwitch`,
-and **`neverMechanicalSafe: true`** — loop/autoPatch must ignore them. For judgment I/O moves
-use **extraction cards** ([brownfield-adoption.md](brownfield-adoption.md) §6). Multi-PR residual
-may optionally be persisted as a short Shape plan under the repo; not a gate requirement.
+**Post-green path (Q01):** when design-weak, doctor sets `postGreenPath` / `primaryNextAction`
+(`clarify-for-ai`) — **one** Shape door: `/ark-explore` shape-focus → dual-plan B, then
+`/ark-autopilot` only to apply B with your OK. Do not skill-shop coverage/think for the same residual.
+
+**Pilot loop (Q04):** when design-weak, `pilotLoop.nextPilot` is **one** extraction card
+(pilot target, move, success, kill-switch). Apply **that one pilot only**, then re-doctor.
+Success = reduced smell evidence on pilot paths; residual outside the pilot may remain.
+Never multi-pilot batch; never mechanical-safe; never claim healthy finished while design-weak.
+
+**AI-velocity evidence (Q05):** deterministic fixture bench (no live LLM) compares the same
+feature add on design-weak vs golden-path trees. Run `npm run eval:ai-velocity`; metric is
+`placementTurns` (agent-equivalent steps to the DomainModel home). Method is stored next to
+the number in `eval/ai-velocity-report.json`. See [eval/README.md](../eval/README.md).
+
+Smell **ids** (stable JSON) plus **outcome** lines (plain language, Q02) on each
+`designSmells[]` object — prefer `outcome` for humans; keep `id` for automation:
+
+| id | Outcome (what to do / why the AI struggles) |
+|----|-----------------------------------------------|
+| `io-under-application` | Business code reaches DB/APIs directly — put I/O behind a port/adapter |
+| `handler-in-persistence` | HTTP handlers under storage folders — move handlers to API/UI |
+| `god-module` | Huge multi-job files — split the pilot by concern |
+| `domain-logic-in-ui` | can*/calculate* in UI — move pure rules into Domain |
+| `facade-sql-in-routes` | Routes import ORM/SQL — keep queries in repository/adapter |
+| `mixed-pattern-cluster` | Several layout styles — pick one golden pattern + pilot |
+| `soft-contract` | Layers without deny rules — add real walls, not soft green |
+
+Each smell also has `evidence[]` paths and `message` (technical detail). Plan **B** bets include
+`pilot`, `successSignal`, `killSwitch`, and **`neverMechanicalSafe: true`** — loop/autoPatch must
+ignore them. For judgment I/O moves use **extraction cards**
+([brownfield-adoption.md](brownfield-adoption.md) §6). Multi-PR residual may optionally be
+persisted as a short Shape plan under the repo; not a gate requirement.
 
 **Full-skill agent co-pilot:** after explicitly installing the `/ark-*` pack, use
 `/ark-autopilot` (explore-first, dual plan A remediation + B pattern bets). Recon without
@@ -223,16 +249,42 @@ reference, and explanation for the full path (recommend → init → gallery →
 5. Use `/ark-place` or `ark_place` for individual files after the contract exists.
 6. Verify with `ark-check --root . --config ark.config.json --strict`.
 
+### Golden pattern for new code (Q03)
+
+When the team has picked **one** layout style for *new* files (after Shape / pilot),
+you may record it as an optional side-car:
+
+```json
+// .ark/golden-pattern.json
+{
+  "schemaVersion": "1",
+  "name": "vertical-slice features",
+  "norm": "New features live under src/features/<slice>/; shared only in src/shared/.",
+  "newCodeHome": "src/features/",
+  "examplePath": "src/features/billing/createInvoice.ts"
+}
+```
+
+| Rule | Meaning |
+|------|---------|
+| **Optional** | Missing file is fine — no claim, no error. |
+| **Advisory** | `ark_place` / `ark_prepare_write` and doctor attach `goldenPattern` for **new** code only. |
+| **Not a gate** | Does **not** ENFORCE, does **not** clear design-weak, does not replace `ark.config.json`. |
+| **Malformed** | Invalid JSON or missing `name`/`norm` → `invalid: true`; fix or delete — do not treat as guidance. |
+
+Legacy paths stay migrate-on-touch; the golden norm limits where agents put **new** code.
+
 ### Write protocol (2.10+ / Track W)
 
 Prefer preparing the write before the host commits it to disk:
 
 | Surface | Role |
 |---------|------|
-| MCP **`ark_prepare_write`** | Place + constrain + validate + optional `autoPatch` + `judgmentBrief` + contentHash in one call |
+| MCP **`ark_prepare_write`** | Place + constrain + validate + optional `autoPatch` + `judgmentBrief` + contentHash + optional `goldenPattern` in one call |
 | Write-gate **`autoPatch`** | Mechanical-safe **import type** rewrites only; post-patch revalidation green or discarded |
 | PreToolUse **`--hook-repair`** | On deny: `ARK_REPAIR_JSON` / `ARK_AUTOPATCH_JSON` on stderr (still exit 2 — never silent write) |
 | Doctor **`writePath`** | Reports `repair` \| `reject-only` \| `mcp-only` \| `none` for installed gates |
+| Doctor **`goldenPattern`** | Optional Q03 advisory summary (`present` / `invalid`); never clears design-weak |
 
 Port-proof inject binding is **judgment** for auto-apply (signature/arity change), not write-path autoPatch.
 Full reference: [ai-gates.md](ai-gates.md). Loop-cost harness: `npm run eval:loop-cost`.

package/docs/brownfield-adoption.md

@@ -117,7 +117,28 @@ ark-check --doctor --json   # designFitness.designWeak + designSmells[].evidence
 ark-check --plan --json     # patternBets[] with neverMechanicalSafe: true
 ```
 
-Fixture for CI honesty: `tests/fixtures/design-weak-enforce/` (empty plan A + non-empty B).
+### Pilot loop (Q04) — one pilot at a time → re-doctor
+
+When doctor/plan report **ENFORCE · design-weak**, JSON also includes **`pilotLoop`**:
+
+| Field | Meaning |
+|-------|---------|
+| `pilotLoop.active` | `true` when design-weak and at least one pattern bet exists |
+| `pilotLoop.nextPilot` | **One** extraction card (same fields as §6) ranked from `patternBets` |
+| `pilotLoop.oneAtATime` | Always true — do not multi-pilot batch |
+| `pilotLoop.neverMechanicalSafe` | Always true — judgment only; re-doctor is the success sensor |
+
+**Loop:**
+
+1. Read `pilotLoop.nextPilot` (or fill the §6 card by hand).
+2. Apply **only** that pilot (bounded path(s) in `evidence` / `pilotTarget`).
+3. Re-run `ark-check --doctor --json` (and `--plan --json`).
+4. Success on this step = **reduced smell evidence on the pilot paths** (or that smell cleared). Residual outside the pilot may remain — that is honest Shape work, not failure.
+5. Pick the next `nextPilot` only after re-doctor; stop on kill-switch.
+
+Do **not** claim “healthy finished” while `designWeak` remains. Do **not** auto-apply pattern bets as mechanical-safe.
+
+Fixture for CI honesty: `tests/fixtures/design-weak-enforce/` (empty plan A + non-empty B + pilotLoop).
 
 ### Optional: durable Shape plan (multi-PR)
 

package/docs/package-surface.md

@@ -15,8 +15,12 @@ This document is the consumer contract for **what is stable** vs **what is exper
 | Surface | How you use it | Stability notes |
 |---------|----------------|-----------------|
 | **CLI** | `arkgate` / `arkgate-check` (aliases `ark` / `ark-check`) | Flags and human text may improve; **JSON output shapes** for `--json` (check, doctor, plan, coverage, recommend) are stable within a major. Additive fields OK; removals/renames are major. |
-| **Doctor design fitness (P02+)** | `ark-check --doctor --json` → `doctor.designFitness`, `doctor.designSmells[]` | Additive. Stable smell `id`s: `io-under-application`, `handler-in-persistence`, `god-module`, `domain-logic-in-ui`, `facade-sql-in-routes`, `mixed-pattern-cluster`, `soft-contract`. Each smell has `evidence[]` paths and `fix`. Does **not** fail the gate by itself. |
+| **Doctor design fitness (P02+)** | `ark-check --doctor --json` → `doctor.designFitness`, `doctor.designSmells[]` | Additive. Stable smell `id`s: `io-under-application`, `handler-in-persistence`, `god-module`, `domain-logic-in-ui`, `facade-sql-in-routes`, `mixed-pattern-cluster`, `soft-contract`. Each smell has `evidence[]`, `fix`, technical `message`, and plain-language **`outcome`** (Q02). Does **not** fail the gate by itself. |
+| **Post-green path (Q01)** | `doctor.postGreenPath`, `doctor.primaryNextAction`, `doctor.healthyFinishedForbidden` | Additive when `designFitness.designWeak`. Single Shape door (`id: clarify-for-ai`): explore shape-focus → dual-plan B → autopilot only with OK. Never empty plan A = healthy finished. |
+| **Golden pattern (Q03)** | Optional `.ark/golden-pattern.json`; doctor JSON `doctor.goldenPattern`; MCP `ark_place` / `ark_prepare_write` → `goldenPattern` | Additive, **advisory for NEW code only**. Required fields: `name`, `norm`; optional `newCodeHome`, `examplePath`, `schemaVersion`. **Absent is normal** (no claim). Never ENFORCE; never clears design-weak. Malformed → `invalid: true`, not silent guidance. |
 | **Plan pattern B (P03+)** | `ark-check --plan --json` → `plan.patternBets[]`, `plan.goal.designWeak` | Additive. Each bet: `id`, `smellId`, `pilot`, `evidence`, `successSignal`, `killSwitch`, **`neverMechanicalSafe: true`**, `class: "judgment"`. **Never** auto-applied by loop/autoPatch; not a `remediationKind` mechanical-safe. `goal.met` remains edge honesty only. |
+| **Pilot loop (Q04)** | `plan.pilotLoop` / `doctor.pilotLoop` | Additive. When design-weak: `active`, `oneAtATime`, `neverMechanicalSafe`, **`nextPilot`** extraction-card fields (`pilotTarget`, `smellId`, `move`, `successSignal`, `killSwitch`, `doNot[]`). **One pilot → re-doctor**; never multi-pilot batch; never mechanical-safe. |
+| **AI-velocity eval (Q05)** | `npm run eval:ai-velocity` → `eval/ai-velocity-report.json` | Fixture-measured (no live LLM). Same feature scenario on design-weak vs golden-path arms; metric **`placementTurns`** (agent-equivalent). Golden must be strictly better. Method string lives next to the number. Does not weaken the gate. |
 | **MCP tools** | `arkgate-mcp` / `ark://…` resources | Tool names and primary argument shapes are stable within a major. |
 | **`ark.config.json`** | Layer globs, rules, include/exclude, forbiddenGlobals, intent prefixes, `peerIsolation`, `dynamicImportAllowlist`, `safety` thresholds | Versioned by `schemaVersion`; unknown fields fail closed and migrations preserve the previous supported major. |
 | **`arkgate/schema/analysis-result`** | Public CLI/MCP/hook diagnostic envelope (`schemaVersion`, `valid`, `diagnostics`) | Versioned JSON Schema; committed v1 compatibility fixture protects rule, severity, location, and evidence fields. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkgate",
-  "version": "3.0.2",
+  "version": "3.0.4",
   "description": "ArkGate — architecture co-pilot for AI TypeScript (write gate, CI gate, plan/loop)",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -104,6 +104,7 @@
     "eval:corpus": "node eval/validate-corpus.mjs",
     "eval:comparative": "node eval/comparative-run.mjs",
     "eval:loop-cost": "node eval/loop-cost-run.mjs",
+    "eval:ai-velocity": "node eval/ai-velocity-run.mjs",
     "eval:adoption": "node eval/adoption-run.mjs",
     "test:adoption-harness": "vitest run tests/unit/eval/adoptionHarness.test.ts",
     "bench:scale": "node scripts/ark-scale-bench.mjs",

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/pedroknigge/arkgate",
     "source": "github"
   },
-  "version": "3.0.2",
+  "version": "3.0.4",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "arkgate",
-      "version": "3.0.2",
+      "version": "3.0.4",
       "runtimeHint": "npx",
       "transport": {
         "type": "stdio"

package/templates/skills/ark-autopilot.md

@@ -20,8 +20,12 @@ the explore pass and dual-plan section B (pattern / Shape bets).
 | “Make architecture sound” end-to-end | Map only, no apply → `/ark-explore` |
 | Brownfield or greenfield with apply | Only fitness numbers → `/ark-coverage` |
 | User wants A + B planned and A executed | Single edge fix → `/ark-fix`; plan A only → `/ark-loop` |
+| **Apply half of Q01 post-green path** (after explore map / when user wants full apply) | Skipping explore when doctor primary is Shape map-first |
 | Spaghetti under ENFORCE: Shape work with user ok on B | Contract false-green first → `/ark-adopt` / `/ark-contract` STOP paths |
 
+**Q01:** doctor’s single door is `/ark-explore` shape-focus → dual-plan B, **then** this skill only
+to apply B with OK. Prefer that order when `postGreenPath` / design-weak is the primary residual.
+
 ## Related onboarding
 
 - **Greenfield:** `/ark-architect` or `ark-check --recommend` / `ark start`.
@@ -47,6 +51,9 @@ decision-grade explore pass **and** without opening violating files.
 4. **Open every file** in plan A `steps[]` (and `target` if present) before classifying a fix.
 5. **“Así te lo re-soluciono”** for each A cluster and each B pattern bet.
 6. Apply A → re-run ark-check → rollback on regression. **Never auto-apply B** as mechanical-safe.
+7. **Q04 pilot loop for B:** when design-weak, take **`pilotLoop.nextPilot`** (one extraction card)
+   → apply **only** that pilot with user OK → **re-doctor**. Never multi-pilot batch B; residual
+   outside the pilot may remain and must not be called “healthy finished.”
 
 
 ## Subagent fan-out (optional, host-dependent)