arkgate 3.0.0 → 3.0.2

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.2";
 
 // 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.2";
 
 /** 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.2";
 
 /** 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.2";
 
 // src/domain/adapterContract.ts
 var ARK_ANALYSIS_RESULT_SCHEMA_VERSION = "1.0";

package/docs/agent-guide.md

@@ -75,10 +75,31 @@ 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 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**.
+
+```bash
+npx ark-check --doctor --json   # doctor.designFitness + doctor.designSmells[]
+npx ark-check --plan --json     # plan.goal.designWeak + plan.patternBets[] (never mechanical-safe)
+```
+
+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.
+
 **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
-`--plan` as “architecture healthy” without the explore pass.
+`--plan` steps as “architecture healthy” when `designWeak` / non-empty `patternBets` remain.
 
 `ark init --archetype <id>` maps playbook ids to named presets (`hexagonal`, `layered`,
 `feature-sliced`, `monorepo`). With `--yes` and no archetype, Ark auto-selects from

package/docs/ai-gates.md

@@ -50,6 +50,13 @@ you pass `--force`, so review and commit only the templates that match your proj
 `autoPatch` flags), the supported profile for the active host, and the evidence actually found.
 Supported capability and installed guarantee are deliberately separate.
 
+**Design fitness (3.0.1+):** the same doctor JSON may include `doctor.designFitness` and
+`doctor.designSmells[]` (path evidence). Edge-clean `operatingMode: enforce` can still set
+`designFitness.designWeak: true` (**ENFORCE · design-weak**). That is Shape residual, not a
+write-path failure. Companion plan JSON: `plan.patternBets[]` with `neverMechanicalSafe: true`
+— never treat as write-boundary `autoPatch` / mechanical-safe. See
+[package-surface.md](package-surface.md) and [brownfield-adoption.md](brownfield-adoption.md) §6.
+
 If your project uses Codex or Grok, treat MCP registration as part of the default
 setup, not an optional extra. Ark works best when the agent can read `ark://manifest`
 before it writes code; that is the fast path to avoiding architecture drift during

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/demos/03-copilot-autopilot.md

@@ -35,17 +35,22 @@ the layer globs so day-one **governed%** is real (not a false-green empty contra
 ### 2. See the plan yourself (optional)
 
 ```bash
-npx ark-check --plan            # human view (includes Governed: N%)
-npx ark-check --plan --json     # { ok, plan: { goal, counts, steps } }
+npx ark-check --plan            # human view (includes Governed: N%; pattern bets when design-weak)
+npx ark-check --plan --json     # { ok, plan: { goal, counts, steps, patternBets?, designSmells? } }
+npx ark-check --doctor --json   # designFitness / designSmells when residual is design-weak
 ```
 
-Each step is tagged `mechanical-safe` / `judgment` / `deferred` with a `confidence`,
+Each **A** step is tagged `mechanical-safe` / `judgment` / `deferred` with a `confidence`,
 `rationale`, and often `remediationKind`. Auto-safe kinds: type-only type move, pure-type **file**
 relocate, `import type` of pure-type modules, and named type-export imports from mixed modules
 (`import-type-of-type-exports`). `goal.met` is true only when
 there are no active violations **and** governed coverage is meaningful — so a clean plan that
 checks almost nothing is not "done."
 
+When edges are clean but design residual remains, JSON also sets `goal.designWeak` and
+`patternBets[]` (each with `neverMechanicalSafe: true`). Those are **B** (Shape) bets — not
+auto-applied. Extraction cards: [brownfield-adoption.md](../brownfield-adoption.md) §6.
+
 ### 3. Carry the plan out — the autopilot
 
 In your agent, run:
@@ -54,10 +59,12 @@ In your agent, run:
 /ark-autopilot
 ```
 
-It runs the whole flow (newbie tier): confirms the plan, hands off to `/ark-loop` to apply the
-`mechanical-safe` steps one at a time — **validating each with `ark-check` and rolling back any
-regression** — proposes each `judgment` step for a yes/no, loops until `goal.met`, and reports
-what was auto-applied vs proposed vs deferred. Nothing lands until you review the diff.
+It runs the whole flow (newbie tier): **explore first** (map + dual plan), hands off to
+`/ark-loop` for plan **A** `mechanical-safe` steps one at a time — **validating each with
+`ark-check` and rolling back any regression** — proposes each A `judgment` and each B
+pattern/Shape bet for a yes/no, and reports what was auto-applied vs proposed vs deferred.
+Nothing lands until you review the diff. Empty A with open B is **not** “architecture healthy
+finished.”
 
 Expert entry: skip the autopilot and use the pieces — `ark init` / `/ark-contract` to shape the
 contract, `ark-check --plan` for the work, `/ark-fix` for targeted fixes, `ark-check

package/docs/package-surface.md

@@ -15,11 +15,13 @@ 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. |
 | **Config JSON Schema** | `arkgate/schema` or `arkgate/schema/ark.config.schema.json` | Stable package resource subpaths for editor completion and contract tooling. |
-| **Agent skills** | `/ark-*` templates installed by `--install-agent-gates` | Skill *names* and “default flow” are stable; internal skill prose may evolve (e.g. explore dual-plan seed, day-zero origin order). |
+| **Agent skills** | `/ark-*` templates installed by `--install-agent-gates` | Skill *names* and “default flow” are stable; internal skill prose may evolve (e.g. When/not when, explore Shape dual-plan seed, extraction cards, day-zero origin order). |
 | **ESLint subpath** | `arkgate/eslint` | Config-driven layer/import rules; loads consumer `ark.config.json`. |
 | **GitHub Action** | `pedroknigge/arkgate` (see `action.yml`) | The `uses:` tag/SHA selects the checker source; `version` remains an optional exact npm compatibility override. |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkgate",
-  "version": "3.0.0",
+  "version": "3.0.2",
   "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.2",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "arkgate",
-      "version": "3.0.0",
+      "version": "3.0.2",
       "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,