arkgate 3.0.0 → 3.0.1

package/bin/lib/doctor-plan.mjs

@@ -25,6 +25,12 @@ import {
   violationEdge,
 } from './violations.mjs';
 import { buildUnclassifiedSuggestions } from './suggestions.mjs';
+import {
+  detectDesignSmells,
+  buildPatternBetsFromSmells,
+  summarizeDesignFitness,
+  isDesignWeak,
+} from './design-smells.mjs';
 
 const color = {
   green: (s) => `\x1b[32m${s}\x1b[0m`,
@@ -142,7 +148,25 @@ export function runCoverage(root, config, files, rules, asJson) {
 // Co-pilot Phase F — turn active violations into a classified, ordered remediation PLAN with an
 // embedded GOAL. This is the `plan` primitive the future apply-loop (Phase H, `loop`) consumes
 // and the autopilot (Phase I) drives toward the `goal`. Read-only: it changes no files.
-export function buildRemediationPlan(root, activeViolations, governedPercent = null, totalFiles = null) {
+/**
+ * @param {string} root
+ * @param {object[]} activeViolations
+ * @param {number|null} [governedPercent]
+ * @param {number|null} [totalFiles]
+ * @param {object} [options]
+ * @param {object[]} [options.designSmells]
+ * @param {object[]} [options.patternBets]
+ * @param {object} [options.config]
+ * @param {string[]} [options.files]
+ * @param {object} [options.coverage]
+ */
+export function buildRemediationPlan(
+  root,
+  activeViolations,
+  governedPercent = null,
+  totalFiles = null,
+  options = {}
+) {
   // A plan with 0 violations but ~0% governed (or ZERO files in scope) is a FALSE green:
   // nothing is actually being checked. Treat as "not done — classify / fix include first."
   const governedLow = governedPercent != null && governedPercent < 50;
@@ -177,20 +201,54 @@ export function buildRemediationPlan(root, activeViolations, governedPercent = n
     judgment: countOf('judgment'),
     deferred: countOf('deferred'),
   };
+
+  // Plan B (pattern bets) — never mechanical-safe; additive within major (P03).
+  let designSmells = options.designSmells;
+  if (!designSmells && options.config && options.files) {
+    designSmells = detectDesignSmells(
+      root,
+      options.config,
+      options.files,
+      options.coverage ?? null
+    );
+  }
+  designSmells = designSmells ?? [];
+  const patternBets =
+    options.patternBets ?? buildPatternBetsFromSmells(designSmells);
+  const edgesMet = activeViolations.length === 0 && !notHonestlyEnforced;
+  const designWeak = isDesignWeak(designSmells, {
+    activeViolations: activeViolations.length,
+    governedPercent,
+    totalFiles,
+  });
+
+  let statement =
+    activeViolations.length > 0
+      ? `Resolve ${activeViolations.length} architecture violation(s) without weakening the contract.`
+      : emptyScope
+        ? 'No source files matched the contract include paths — this "clean" result checks nothing. Fix include/layers (monorepo → apps/packages, or /ark-adopt) so Ark has real code to govern.'
+        : governedLow
+          ? `No violations — but Ark governs only ${governedPercent}% of your code, so this "clean" result checks almost nothing. Classify the rest (ark-check --coverage, then /ark-adopt) so it's actually enforced.`
+          : 'No active violations — the architecture already meets its contract.';
+  if (designWeak) {
+    statement =
+      'No active edge violations — contract edges are clean, but design smells remain (ENFORCE · design-weak). Shape residual is plan B only; not healthy finished.';
+  }
+
   return {
     version: '1',
     goal: {
-      statement:
-        activeViolations.length > 0
-          ? `Resolve ${activeViolations.length} architecture violation(s) without weakening the contract.`
-          : emptyScope
-            ? 'No source files matched the contract include paths — this "clean" result checks nothing. Fix include/layers (monorepo → apps/packages, or /ark-adopt) so Ark has real code to govern.'
-            : governedLow
-              ? `No violations — but Ark governs only ${governedPercent}% of your code, so this "clean" result checks almost nothing. Classify the rest (ark-check --coverage, then /ark-adopt) so it's actually enforced.`
-              : 'No active violations — the architecture already meets its contract.',
-      // The loop's termination signal (Phase H): nothing left to remediate AND the contract
-      // actually governs real code. Empty scope or low coverage is not "met".
-      met: activeViolations.length === 0 && !notHonestlyEnforced,
+      statement,
+      // Edge remediation termination (Phase H). Design-weak does NOT flip met false
+      // (would break loop semantics) — it is reported separately for honesty.
+      met: edgesMet,
+      designWeak,
+      ...(designWeak
+        ? {
+            designWeakLabel:
+              'ENFORCE · design-weak — use patternBets / dual-plan B; never auto-apply as mechanical-safe',
+          }
+        : {}),
       ...(governedPercent != null ? { governedPercent } : {}),
       ...(totalFiles != null ? { totalFiles } : {}),
       ...(emptyScope ? { emptyScope: true } : {}),
@@ -198,17 +256,38 @@ export function buildRemediationPlan(root, activeViolations, governedPercent = n
       autoApplicable: counts.mechanicalSafe,
       needsDecision: counts.judgment,
       deferred: counts.deferred,
+      patternBetCount: patternBets.length,
     },
     counts,
     steps,
+    // Additive: pattern evolution bets derived from design smells (never auto).
+    patternBets,
+    designSmells,
   };
 }
 
 // `--plan`: print the classified remediation plan. Dual-focus output — a one-line headline
 // anyone can read, then the per-step detail a developer acts on. Read-only.
-export function runPlan(root, activeViolations, asJson, governedPercent = null, totalFiles = null) {
-  const plan = buildRemediationPlan(root, activeViolations, governedPercent, totalFiles);
+/**
+ * @param {object} [options] optional { config, files, coverage, designSmells, patternBets }
+ */
+export function runPlan(
+  root,
+  activeViolations,
+  asJson,
+  governedPercent = null,
+  totalFiles = null,
+  options = {}
+) {
+  const plan = buildRemediationPlan(
+    root,
+    activeViolations,
+    governedPercent,
+    totalFiles,
+    options
+  );
   // Honesty: a zero-violation plan with almost nothing governed is NOT "ok".
+  // design-weak still ok:true for edge goal.met, but JSON carries designWeak + patternBets.
   const planOk = plan.goal.met === true;
   if (asJson) {
     console.log(JSON.stringify({ ok: planOk, plan }, null, 2));
@@ -217,6 +296,13 @@ export function runPlan(root, activeViolations, asJson, governedPercent = null,
   console.log(color.bold(`Ark plan — ${path.basename(path.resolve(root)) || '.'}`));
   console.log('');
   console.log(plan.goal.statement);
+  if (plan.goal.designWeak) {
+    console.log(
+      color.yellow(
+        `  ENFORCE · design-weak — ${plan.patternBets?.length ?? 0} pattern bet(s) (never auto-apply)`
+      )
+    );
+  }
   if (governedPercent != null) {
     const pctLabel =
       governedPercent < 50
@@ -224,6 +310,14 @@ export function runPlan(root, activeViolations, asJson, governedPercent = null,
         : color.dim(`Governed: ${governedPercent}% of in-scope files`);
     console.log(pctLabel);
   }
+  if (plan.patternBets?.length && activeViolations.length === 0) {
+    console.log('');
+    console.log(color.bold('Pattern bets (B) — judgment only'));
+    for (const bet of plan.patternBets.slice(0, 5)) {
+      console.log(`  [decide] ${bet.smellId}  ${color.dim(bet.pilot)}`);
+      console.log(color.dim(`           success: ${bet.successSignal}`));
+    }
+  }
   if (activeViolations.length === 0) return plan;
   console.log('');
   console.log(
@@ -245,7 +339,7 @@ export function runPlan(root, activeViolations, asJson, governedPercent = null,
   console.log('');
   console.log(
     color.dim(
-      'Plan only — no files changed. "auto" = an agent can safely apply it; "decide" = your call.'
+      'Plan only — no files changed. "auto" = an agent can safely apply it; "decide" = your call. patternBets are never auto.'
     )
   );
   return plan;
@@ -283,6 +377,12 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
   const activeCount = violations.length - suppressed;
   const missingSkills = skillGaps.reduce((sum, gap) => sum + gap.missing, 0);
   const staleSkills = skillGaps.reduce((sum, gap) => sum + gap.stale, 0);
+  const designSmells = detectDesignSmells(root, config, files, cov);
+  const designFitness = summarizeDesignFitness(designSmells, {
+    activeViolations: activeCount,
+    governedPercent: cov.governed.percent,
+    totalFiles: cov.governed.totalFiles,
+  });
 
   if (asJson) {
     console.log(
@@ -304,6 +404,9 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
                 return p ? p.files / total : null;
               })(),
             }),
+            // Path-correct ENFORCE can still be design-weak (P02).
+            designFitness,
+            designSmells,
             governed: cov.governed,
             emptyLayers: cov.emptyLayers,
             layersWithoutRules: cov.layersWithoutRules,
@@ -412,7 +515,18 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
     enforce:
       'Guard — contract coverage is honest and checked edges are clean. You do not pick this mode; you arrived here. Next: keep the host-appropriate write path and CI check on; only NEW violations should fail.',
   };
-  line(modeMark, `${mode.toUpperCase()} — ${modeHelp[mode]}`);
+  const modeTitle =
+    mode === 'enforce' && designFitness.designWeak
+      ? 'ENFORCE · design-weak'
+      : mode.toUpperCase();
+  line(
+    modeMark,
+    `${modeTitle} — ${
+      designFitness.designWeak
+        ? 'Guard on edges is honest, but design smells remain (Shape residual). You do not pick this mode. Next: /ark-explore dual-plan B or /ark-autopilot for pattern bets — never treat empty plan A as healthy finished.'
+        : modeHelp[mode]
+    }`
+  );
   if (emptyScope) {
     line(
       bad,
@@ -420,6 +534,25 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
     );
   }
 
+  console.log('');
+  console.log(color.bold('Design fitness'));
+  if (designSmells.length === 0) {
+    line(ok, designFitness.label);
+  } else {
+    line(designFitness.designWeak ? warn : warn, designFitness.label);
+    for (const smell of designSmells.slice(0, 5)) {
+      line(' ', color.dim(`[${smell.id}] ${smell.message}`));
+      if (smell.evidence?.length) {
+        line(' ', color.dim(`evidence: ${smell.evidence.slice(0, 4).join(', ')}`));
+      }
+    }
+    if (designFitness.designWeak) {
+      actions.push(
+        'shape residual: /ark-explore (shape-focus) or /ark-autopilot dual-plan B — pattern bets are never mechanical-safe'
+      );
+    }
+  }
+
   console.log('');
   console.log(color.bold('Coverage'));
   const govMark =

package/dist/index.cjs

@@ -50,7 +50,7 @@ __export(gate_exports, {
 module.exports = __toCommonJS(gate_exports);
 
 // src/version.ts
-var version = "3.0.0";
+var version = "3.0.1";
 
 // 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.0";
+declare const version = "3.0.1";
 
 /** 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.0";
+declare const version = "3.0.1";
 
 /** 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.0";
+var version = "3.0.1";
 
 // src/domain/adapterContract.ts
 var ARK_ANALYSIS_RESULT_SCHEMA_VERSION = "1.0";

package/docs/agent-guide.md

@@ -75,6 +75,12 @@ To remove a compact host integration, preview `ark start --remove-host <host>` a
 only after review. Ark removes only its exact compact artifacts, leaves customized files untouched
 as unresolved decisions, and restores the integration with `ark start --tools <host> --apply`.
 
+**Skill roles (avoid overlap):** `/ark-explore` = map + dual-plan **seed** + Shape residual
+(no apply). `/ark-coverage` = Ark **fitness** only (governed/gates). `/ark-think` = one decision
+(2–3 options). `/ark-adopt` = brownfield Align/Stabilize + seed Shape B. `/ark-autopilot` =
+explore then apply A + propose/apply-with-ok B. `/ark-loop` = plan A only. Empty plan A is not
+“architecture healthy” if design-weak residual remains.
+
 **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
 applying: `/ark-explore`. The default compact router uses MCP/CLI directly. Never treat empty

package/docs/brownfield-adoption.md

@@ -86,10 +86,61 @@ violations — the ratchet only moves toward zero.
 `/ark-fix` resolves each cluster at the root cause; fixing a frozen violation shrinks the
 baseline permanently. Re-freeze lower with `--update-baseline` as you go.
 
+## 6. Shape residual — extraction cards (judgment assist, P05)
+
+When edges are green (`ark-check --plan` has empty `steps[]`) but doctor reports
+**ENFORCE · design-weak** (`designSmells` / `patternBets`), you are in **Shape** work. Plan A
+is done; plan **B** is not auto-applicable.
+
+Use one **extraction card** per pilot (I/O relocate, god-module split, domain-out-of-UI).
+Agents and humans fill the same fields — never invent a codemod engine or silent apply:
+
+```text
+### Extraction card
+Pilot: <one directory or feature path>
+Smell: <doctor designSmells[].id or agent-detected id>
+Move: <what moves, e.g. query bytes verbatim → OrderRepository adapter>
+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
+Success: <falsifiable signal, e.g. 0 routes import @prisma/client>
+Kill-switch: <when to stop, e.g. if 2 PRs still confuse ownership → stop layer add>
+Next: /ark-fix (one cluster) | /ark-autopilot (user ok on B) | /ark-explore shape-focus
+```
+
+CLI sensors:
+
+```bash
+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).
+
+### Optional: durable Shape plan (multi-PR)
+
+CLI `patternBets` and extraction cards are enough for a single session. If residual spans
+**multiple PRs or agents**, optionally persist one human-readable plan under the repo
+(e.g. `docs/plans/shape-<pilot>/README.md` or any team path) with:
+
+| Field | Source |
+|-------|--------|
+| Phase | Align / Stabilize / **Shape** |
+| Golden vs legacy patterns | explore concurrent-patterns table |
+| Smell ids / patternBets | `ark-check --doctor --json` / `--plan --json` |
+| Extraction cards | §6 template above |
+| Status of pilot | e.g. dual path (legacy + new) → real (only golden) when smells clear |
+
+This is **optional narrative**, not a gate. Ark does not require a docs skill or a fixed
+folder layout. Prefer one authority plan; promote or archive it when the pilot is real.
+
 ## What Ark does NOT do here
 
 Ark reorganizes and governs code — it never touches your data model. Migrating raw SQL to a
 repository moves the same query to another file; the schema, migrations, and the database are
 untouched. And the burn-down itself is the team's work (or a codemod, or an agent loop) — Ark
 diagnoses, orders it, and gives you the pattern; it doesn't auto-run hundreds of edits against
-your restricted data layer.
+your restricted data layer. **Extraction cards are judgment assists only** — no general codemod
+and no silent auto-apply of plan B.

package/docs/package-surface.md

@@ -15,6 +15,8 @@ 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. |
+| **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. |
 | **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.0",
+  "version": "3.0.1",
   "description": "ArkGate — architecture co-pilot for AI TypeScript (write gate, CI gate, plan/loop)",
   "type": "module",
   "main": "./dist/index.cjs",

package/server.json

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

package/templates/skills/ark-adopt.md

@@ -1,6 +1,6 @@
 ---
 name: ark-adopt
-description: Brownfield onboarding — exploratory match of contract to real product code, classify ungoverned dirs, mine business rules into the manifest, freeze only real debt. Deep source analysis required.
+description: Brownfield onboarding — match contract to real product code, classify ungoverned dirs, mine business rules, freeze only real debt, seed Shape dual-plan B for spaghetti residual. Deep source analysis required.
 ---
 
 # /ark-adopt — Bring Ark into an existing codebase
@@ -8,6 +8,18 @@ description: Brownfield onboarding — exploratory match of contract to real pro
 Goal: contract reflects **product reality**, most code governed, only genuine debt frozen
 with a burn-down. A green check over a wrong contract is a **false green**.
 
+**Adopt is Align + Stabilize, then seed Shape.** Freezing debt without a pattern plan leaves
+spaghetti “ENFORCE · design-weak”. Always end with dual-plan **B** seeds (or handoff explore)
+when design smells remain after the contract is honest.
+
+## When / not when
+
+| Use `/ark-adopt` when… | Do **not** use it when… |
+|------------------------|-------------------------|
+| Existing messy repo; contract ≠ folders | Empty greenfield shape → `/ark-architect` |
+| False-green / concentrated edge needs contract truth | Map-only without writing config/baseline → `/ark-explore` |
+| Mine loose business rules into Domain / intents | Single violation fix → `/ark-fix` |
+| Freeze **real** debt after contract is honest | Grind plan A only → `/ark-loop`; full apply loop → `/ark-autopilot` |
 
 ## Dual engine (mandatory)
 
@@ -78,22 +90,33 @@ Ark protects the **boundary around** a framework, not its internals. Nest/DI pub
    - Deliver section **“Así te lo re-soluciono en el manifiesto”** with before/after contract snippets.
 5. **Freeze only real debt** — `--update-baseline` (zero debt → **no empty baseline file** left behind).
 6. **Gates + skills** — `--install-agent-gates` (CI monorepo-aware when `frontend/package.json` exists).
-7. **Ratchet + opportunity plan** — ranked residual edges + **explore-style bets** (what to improve next week).
+7. **Ratchet + Shape seed (mandatory exploratory close)** — after freeze/gates:
+   - Name phase: **Align** (contract honesty) → **Stabilize** (baseline real) → **Shape** (golden pattern).
+   - If plan A is empty but the tree still shows concurrent patterns, god modules, facade SQL,
+     domain logic in UI, or semantic false-green: emit **dual-plan B** (3–5 bets) with pilot,
+     success signal, kill-switch, and extraction cards for I/O moves — same bar as `/ark-explore` §G.
+   - Do **not** claim “adopt complete / healthy” solely because the check is green.
+   - Prefer handoff `/ark-autopilot` for B execution with user ok, or `/ark-explore` shape-focus
+     if the user only wanted a plan.
 
 ## Operating modes
 
 Explain modes as **detected stages** (Setup / Align / Guard), not user settings.
+**Guard on the contract ≠ Shape done.** Say `ENFORCE · design-weak` when B residual remains.
 
 ## Verify
 
 `ark-check --root . --config ark.config.json --strict-config` (+ baseline only if non-empty file retained).
-Report: governed% before/after, files written, frozen count, false positives avoided, manifest/intent proposals applied or deferred, **top opportunities still open**.
+Report: governed% before/after, files written, frozen count, false positives avoided, manifest/intent
+proposals applied or deferred, **phase**, **top Shape / design-weak opportunities still open**
+(with success signals).
 
 ## Never
 
 - Freeze false positives to get green.
 - Force runtime kernel over existing Nest/DI.
 - Claim Enforce while governed% is low, cores empty with I/O in Application, or core bags ungoverned.
+- End adopt with only “baseline written” when design-weak residual is visible in files you opened.
 
 ## Completion contract (skill incomplete if missing)
 

package/templates/skills/ark-architect.md

@@ -5,6 +5,13 @@ description: Choose the application shape, adopt phase-1 layers, scaffold direct
 
 # /ark-architect — Choose your application shape and adopt Ark
 
+## When / not when
+
+| Use `/ark-architect` when… | Do **not** use it when… |
+|----------------------------|-------------------------|
+| Greenfield / thin tree; pick shape + phase-1 layers | Existing spaghetti brownfield → `/ark-adopt` (+ `/ark-explore` first if map missing) |
+| Enthusiast before heavy codegen | Enforcement residual on mature tree → `/ark-autopilot` |
+
 The user is building something new or early in Ark adoption. They may not know
 layered architecture jargon. Your job: translate **what they want to build**
 (application shape, not framework name) into an Ark preset, a phase-1 layer plan,

package/templates/skills/ark-autopilot.md

@@ -1,6 +1,6 @@
 ---
 name: ark-autopilot
-description: End-to-end architecture co-pilot — decision-grade explore first, dual plan (remediation + pattern improvements), mechanical-safe fixes, judgment design. CLI is a sensor; you read and remediate files.
+description: End-to-end co-pilot — explore first, dual plan A remediation + B pattern/Shape bets, mechanical-safe fixes, judgment design. Empty plan A is not healthy if design-weak. CLI is a sensor; you read and remediate files.
 ---
 
 # /ark-autopilot — Get to a sound architecture, end to end
@@ -11,15 +11,23 @@ execute **judgment** fixes you design from reading source (still validate with a
 never weaken the gate).
 
 **Not a plan grinder.** Empty `--plan` does **not** mean “architecture is healthy” without
-the explore pass and dual-plan section B (pattern bets).
+the explore pass and dual-plan section B (pattern / Shape bets).
 
+## When / not when
+
+| Use `/ark-autopilot` when… | Do **not** use it when… |
+|----------------------------|-------------------------|
+| “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` |
+| Spaghetti under ENFORCE: Shape work with user ok on B | Contract false-green first → `/ark-adopt` / `/ark-contract` STOP paths |
 
 ## Related onboarding
 
 - **Greenfield:** `/ark-architect` or `ark-check --recommend` / `ark start`.
 - **Brownfield:** `/ark-adopt` — match contract to reality; do not force a starter preset.
-- **Deep map only:** `/ark-explore` — full recon report without applying fixes.
-- **Adoption metrics only:** `/ark-coverage` — governed% + capability gaps (feeds dual plan B).
+- **Deep map only:** `/ark-explore` — full recon / dual-plan seed without applying.
+- **Adoption fitness only:** `/ark-coverage` — governed% + capability gaps (not pattern dual-plan).
 - **Default path:** `ark start` → `/ark-autopilot` → `ark-check --doctor`.
 
 ## Dual engine (mandatory)
@@ -64,30 +72,38 @@ Useful first wave: **core product tree** | **field path** (examples/starters) |
 
 Do this **before** grinding plan A — plan lists *violations*, not *product reality*.  
 Use the **`/ark-explore` decision-grade bar** (compressed into the autopilot report, not optional fluff).
-
-1. **Headline** — product one-liner + honesty (mode, governed%, false-green / false-promise risk).
-2. **Map** — entry points, lived layout vs globs (one screen).
-3. **Field path** — if `examples/` / gallery / starter docs exist: open ≥2, **run** their check when cheap; flag soft-green or broken demos. Else `Field path: n/a`.
-4. **Agent/gate reality** — installed hooks vs install templates (e.g. `--hook` vs `--hook-repair`); MCP; CI gate present.
-5. **Coupling** — fan-in / exports / importers for hotspots (LOC alone is a hint).
-6. **False-green soft block** — doctor/coverage: empty Domain/Persistence while Application owns I/O (`airtable`, `supabase`, `prisma`, `drizzle`, `repositories`, …). Doctor gap id: `contract-false-green-io-under-application`. If so:
+Include explore **§G** when spaghetti / design-weak signals fire.
+
+1. **Headline** — product one-liner + honesty (mode, governed%, false-green / false-promise /
+   **ENFORCE·design-weak** risk).
+2. **Map** — entry points, lived layout vs globs (one screen). **Concurrent patterns** table when ≥2 styles.
+3. **Phase ladder** — name **Align | Stabilize | Shape** (explore §G).
+4. **Field path** — if `examples/` / gallery / starter docs exist: open ≥2, **run** their check when cheap; flag soft-green or broken demos. Else `Field path: n/a` + internal norm.
+5. **Agent/gate reality** — installed hooks vs install templates (e.g. `--hook` vs `--hook-repair`); MCP; CI gate present.
+6. **Coupling** — fan-in / exports / importers for hotspots (LOC alone is a hint).
+7. **False-green soft block** — doctor/coverage: empty Domain/Persistence while Application owns I/O (`airtable`, `supabase`, `prisma`, `drizzle`, `repositories`, …). Doctor gap id: `contract-false-green-io-under-application`. If so:
    **STOP — do not continue this skill as complete.** **STOP — false-green: invoke /ark-adopt or /ark-contract before claiming ENFORCE.** Do not claim goal.met / ENFORCE from type-only cleanup while doctor reports `contract-false-green-io-under-application`.
-7. **Seed dual plan B** — 2–5 pattern / evolution bets ranked (impact × effort × enforceability).
+8. **Seed dual plan B** — 2–5 pattern / Shape bets ranked (impact × effort × enforceability). Each B row needs pilot + success signal; I/O bets need an **extraction card** (explore §G).
 
 Min bar: **≥12 source files** across **≥4 meaningful directories** (not only files in `steps[]`).  
-Standalone long report: `/ark-explore`. Adoption numbers deep-dive: `/ark-coverage`.
+Standalone long report: `/ark-explore`. Adoption fitness only: `/ark-coverage`.
 
 ## Dual plan (always emit)
 
 | Section | Source | Question | Auto-apply? |
 |---------|--------|----------|-------------|
-| **A. Remediation** | `--plan --json` + opened step files | What must change so the gate is honest? | Only `mechanical-safe` by default |
-| **B. Pattern / evolution** | Explore + coverage/doctor | What existing patterns should improve even if A is empty? | **Never** as mechanical-safe |
+| **A. Remediation** | `--plan --json` + opened step files | What must change so the **gate** is honest? | Only `mechanical-safe` by default |
+| **B. Pattern / Shape** | Explore §B/§G (not coverage alone) | What **design** must improve even if A is empty? | **Never** as mechanical-safe |
 
 **Section A** — group by edge; treat `peerIsolation` / cross-slice as **judgment**.  
-**Section B** examples: peerIsolation, move rules out of UI, strengthen starter/preset rules, write-path repair, split god orchestration modules, Domain placement / intents, import surface (`/runtime` vs root). Cap **3–5** B rows. Each row: evidence path + **así te lo re-soluciono** + next skill/command + success signal.
+**Section B** examples: choose golden pattern + pilot migrate-on-touch, peerIsolation, move rules out of UI, write-path repair, split god modules, Domain placement / intents, facade SQL → port/adapter (extraction card). Cap **3–5** B rows. Each row: evidence path + **así te lo re-soluciono** + next skill/command + **success signal** + **pilot** (+ kill-switch if new layer).
 
-B does **not** count as “architecture healthy finished.” Report B as `proposed | deferred | applied-with-user-ok`.
+B does **not** count as “architecture healthy finished.” Report B as `proposed | deferred | applied-with-user-ok`.  
+When A is empty and B is non-empty: status is **`goal.met on edges · Shape residual open`** — never “done” without listing B.
+Prefer CLI `patternBets[]` / `designSmells[]` when present; apply B only with explicit user ok using
+**extraction cards** (`docs/brownfield-adoption.md` §6) — never mechanical-safe, never silent.
+If B will take multiple PRs, offer (do not require) persisting a short Shape plan under the
+repo so the next agent session continues the same pilot — still never auto-apply B.
 
 ## Origin snapshot (day-zero picture)
 
@@ -136,12 +152,13 @@ B does **not** count as “architecture healthy finished.” Report B as `propos
 
 ## Done criteria
 
-- Explore pass completed (decision-grade map + paths + field path or n/a + B seeds).
-- Dual plan emitted (A and/or B; if both empty, one-line justification).
+- Explore pass completed (decision-grade map + paths + field path or n/a + phase + B seeds).
+- Dual plan emitted (A and/or B; if both empty, one-line justification with evidence no design-weak smells).
 - Origin present under `.ark/reports/origin.*` (frozen this run or earlier).
 - Every applied A step validated by real `ark-check`.
 - Final plan `goal.met` true **or** remaining A steps listed with file-level proposals.
-- Open **B opportunities** listed; report HTML paths cited.
+- Open **B / Shape opportunities** listed with success signals; report HTML paths cited when used.
+- If A empty and design-weak present: B listed — **Incomplete?** must not claim full healthy stop.
 
 ## Completion contract (skill incomplete if missing)
 

package/templates/skills/ark-contract.md

@@ -5,6 +5,13 @@ description: Safely edit ark.config.json (layers, rules, forbiddenGlobals, inten
 
 # /ark-contract — Change the architecture contract (safely)
 
+## When / not when
+
+| Use `/ark-contract` when… | Do **not** use it when… |
+|---------------------------|-------------------------|
+| Edit layers/rules/includes/intents with source evidence | Move product code without config change → `/ark-fix` / `/ark-loop` |
+| Concentrated-edge / false-green STOP from other skills | Full map without config edit → `/ark-explore` |
+
 The **one sanctioned way** to change layers/rules/`intentPrefixes`/includes.
 Also used to **land mined business rules** into the executable manifest (`ark.config.json` + intent naming that `ark://manifest` exposes).