arkgate 4.6.4 → 4.6.6

package/README.md

@@ -16,9 +16,11 @@ and makes sure a “green” check means something real.
 
 </div>
 
-> **ArkGate 4.6.3** is on npm `latest` — Codex CLI/local Desktop hard-block complete trusted `apply_patch`.
-> **4.6.4 is prepared** — `ark upgrade` tells Codex how to refresh, trust, restart, and verify it.
-> [4.6.4 notes](docs/releases/4.6.4.md) · [4.6.3](docs/releases/4.6.3.md) · [4.6.2](docs/releases/4.6.2.md) · [4.6.1](docs/releases/4.6.1.md) · [Docs hub](docs/README.md) · [Product voice](docs/product-voice.md)
+> **ArkGate 4.6.6** is current (this train). **4.6.5** remains npm `latest` until publish.
+> A tree is **adopted** only with a required GitHub status running `arkgate-check --strict-merge`,
+> or `.ark/adoption-stance.json` `stance: "advisory-only"`. Doctor is compact (`--doctor --all`
+> for Details). [4.6.6 notes](docs/releases/4.6.6.md) · [4.6.5](docs/releases/4.6.5.md) ·
+> [Docs hub](docs/README.md) · [Product voice](docs/product-voice.md)
 
 ---
 
@@ -41,12 +43,11 @@ npm install -D arkgate typescript
 npx arkgate start                 # preview files + commands
 npx arkgate start --apply         # compact contract + host router + CI plan
 npx arkgate-check --doctor        # control plane: status light + primary next action
+npx arkgate-check --doctor --all  # encyclopedia (Details)
 ```
 
 That is the product. Doctor is the control plane — when stuck, do **primary next action #1**.
-Doctor also shows **what to improve next** (architecture lenses such as separation of concerns and
-dependency inversion — **not a score**). Leftover lenses mean design work may remain even when
-imports are green. Details: [use.md — Improvement compass](docs/use.md#improvement-compass-not-a-score).
+JSON still carries improvement compass and coach (**not a score**). Compact human output does not.
 
 ```text
 start → doctor (+ compass) → /ark-adopt (session 0) → day-to-day /ark-place
@@ -102,7 +103,7 @@ check: [4.3.0 — What ArkGate is / isn't](docs/releases/4.3.0.md#what-arkgate-i
 |-------|--------|-----------|
 | **Suggest** | Thin / new tree | Finish `start` → doctor |
 | **Adapt** | Not fully protected | Doctor action #1 |
-| **Enforce** | Honest edges under the contract | Keep write path + CI |
+| **Enforce** | Honest import edges, and no new UI business-rule files vs merge-base | Keep write path + CI |
 | **Enforce · design-weak** | Edges clean; design residual remains | Shape residual — not “done” |
 
 Details: [docs/use.md](docs/use.md).
@@ -216,8 +217,9 @@ for real systems. Details: [docs/production-hardening.md](docs/production-harden
 | Config · package surface · TS | [configuration](docs/configuration.md) · [package-surface](docs/package-surface.md) · [typescript-support](docs/typescript-support.md) |
 | Brownfield | [docs/brownfield-adoption.md](docs/brownfield-adoption.md) |
 | Security | [SECURITY.md](SECURITY.md) |
-| Current release (4.6.3 on npm `latest`) | [docs/releases/4.6.3.md](docs/releases/4.6.3.md) · [CHANGELOG](CHANGELOG.md) |
-| Prepared patch (4.6.4) | [docs/releases/4.6.4.md](docs/releases/4.6.4.md) |
+| Current release (4.6.6) | [docs/releases/4.6.6.md](docs/releases/4.6.6.md) · [CHANGELOG](CHANGELOG.md) |
+| Prior published (4.6.5 on npm `latest` until 4.6.6 lands) | [docs/releases/4.6.5.md](docs/releases/4.6.5.md) |
+| Prior published (4.6.3) | [docs/releases/4.6.3.md](docs/releases/4.6.3.md) |
 | Prior (4.6.2) | [docs/releases/4.6.2.md](docs/releases/4.6.2.md) |
 | Prior (4.6.1) | [docs/releases/4.6.1.md](docs/releases/4.6.1.md) |
 | Prior (4.6.0) | [docs/releases/4.6.0.md](docs/releases/4.6.0.md) |

package/bin/ark-check-runtime.mjs

@@ -87,9 +87,11 @@ import {
 import {
   ARCHITECTURE_PRESETS,
   APPLICATION_LIB_ORCHESTRATION_PATTERNS,
+  COMPOSITION_ROOT_PATH_PATTERNS,
   DOMAIN_PATH_PATTERNS,
   NEXT_API_APPLICATION_PATTERNS,
   PERSISTENCE_PATH_PATTERNS,
+  SHARED_KERNEL_PATH_PATTERNS,
   retrofitP0aApiApplicationPatterns,
   withDefaultArkRules,
   writeArkRulesTemplates,
@@ -103,10 +105,15 @@ import { runArchitectureScan } from './lib/architecture-scan.mjs';
 import { ANALYSIS_COMPLETENESS, analysisIncompleteStatement } from './lib/analysis-completeness.mjs';
 import { reportUnavailableAnalysis } from './lib/unavailable-analysis.mjs';
 import { validateHardWriteRequest } from './lib/enforcement-profiles.mjs';
-import { analyzePolicyTransition } from './lib/policy-delta-io.mjs';
+import {
+  analyzePolicyTransition,
+  discoverLocalBaseRef,
+  normalizePolicyBaseRef,
+} from './lib/policy-delta-io.mjs';
 import {
   applyAgainstRatchet,
   bindTeamBaseRefs,
+  contractSessionFrom,
   filterChangedGovernedFiles,
   runTeamPreflight,
   ungovernedDumpMessage,
@@ -120,6 +127,16 @@ import {
 } from './lib/project-root.mjs';
 import { demoteArkRuleTeethUnderClassificationFloor } from './lib/rules-under-contract.mjs';
 
+function resolveDesignDeltaBaseRef(root, explicit, env = process.env) {
+  const flag = typeof explicit === 'string' ? explicit.trim() : '';
+  if (flag) return flag;
+  const envRef = normalizePolicyBaseRef(env.ARK_POLICY_BASE_REF);
+  if (envRef) return envRef;
+  const githubBase = typeof env.GITHUB_BASE_REF === 'string' ? env.GITHUB_BASE_REF.trim() : '';
+  if (githubBase) return `origin/${githubBase}`;
+  return discoverLocalBaseRef(root) || undefined;
+}
+
 function parseArgs(argv) {
   const args = {
     root: process.cwd(),
@@ -573,6 +590,60 @@ function runSuggestInclude(args) {
   console.log(color.dim(payload.note));
 }
 
+const MATURE_LAYER_RULES = Object.freeze([
+  { from: 'SharedKernel', to: 'DomainModel', allowed: false },
+  { from: 'SharedKernel', to: 'ApplicationOrchestration', allowed: false },
+  { from: 'SharedKernel', to: 'PresentationAdapters', allowed: false },
+  { from: 'SharedKernel', to: 'PersistenceAdapters', allowed: false },
+  { from: 'SharedKernel', to: 'CompositionRoot', allowed: false },
+  { from: 'DomainModel', to: 'CompositionRoot', allowed: false },
+  { from: 'PresentationAdapters', to: 'CompositionRoot', allowed: false },
+  { from: 'PersistenceAdapters', to: 'CompositionRoot', allowed: false },
+]);
+
+function ensureMatureAdoptionLayers(layers, byLayer) {
+  const names = new Set(layers.map((layer) => layer.name));
+  const next = [...layers];
+  if (!names.has('SharedKernel')) {
+    next.push({
+      name: 'SharedKernel',
+      patterns: [...(byLayer.get('SharedKernel') ?? SHARED_KERNEL_PATH_PATTERNS)],
+      reserved: true,
+      allowEmpty: true,
+      description: 'Shared types and constants. Persistence and Presentation may import this; it imports nothing else.',
+    });
+  }
+  if (!names.has('CompositionRoot')) {
+    next.push({
+      name: 'CompositionRoot',
+      patterns: [...(byLayer.get('CompositionRoot') ?? COMPOSITION_ROOT_PATH_PATTERNS)],
+      reserved: true,
+      allowEmpty: true,
+      description: 'DI / bootstrap wiring. May import Domain and Persistence; Domain must not import this.',
+    });
+  }
+  return next;
+}
+
+function writeAdoptGoldenPattern(root) {
+  const dir = path.join(root, '.ark');
+  const dest = path.join(dir, 'golden-pattern.json');
+  if (fs.existsSync(dest)) return { wrote: false, path: '.ark/golden-pattern.json' };
+  fs.mkdirSync(dir, { recursive: true });
+  const golden = {
+    schemaVersion: '1',
+    name: 'feature-folders',
+    norm:
+      'New modules live under src/<feature>/{domain,application,composition,infrastructure}. ' +
+      'Types and constants go to SharedKernel. Wiring goes to CompositionRoot. ' +
+      'Presentation never imports Domain. Persistence never imports Application.',
+    newCodeHome: 'src',
+    examplePath: 'src/example/domain/model.ts',
+  };
+  fs.writeFileSync(dest, `${JSON.stringify(golden, null, 2)}\n`);
+  return { wrote: true, path: '.ark/golden-pattern.json' };
+}
+
 /**
  * Contract-adopt: expand include + layer patterns from ungoverned proposals.
  * Read-only unless --write. Does not weaken rules or baseline violations.
@@ -632,7 +703,9 @@ function runAdoptContract(args) {
     ...APPLICATION_LIB_ORCHESTRATION_PATTERNS,
     'api/**',
   ];
-  const domainPatterns = [...DOMAIN_PATH_PATTERNS];
+  const domainPatterns = [...DOMAIN_PATH_PATTERNS, 'src/**/domain/**'];
+  const sharedKernelPatterns = [...SHARED_KERNEL_PATH_PATTERNS];
+  const compositionRootPatterns = [...COMPOSITION_ROOT_PATH_PATTERNS];
 
   // Build pattern additions from unclassified suggestions (path-aware).
   const byLayer = new Map([
@@ -640,33 +713,45 @@ function runAdoptContract(args) {
     ['PersistenceAdapters', [...persistencePatterns]],
     ['ApplicationOrchestration', [...applicationPatterns]],
     ['DomainModel', [...domainPatterns]],
+    ['SharedKernel', [...sharedKernelPatterns]],
+    ['CompositionRoot', [...compositionRootPatterns]],
   ]);
   for (const suggestion of cov.suggestions ?? []) {
     if (suggestion.unrecognized || !suggestion.layer) continue;
-    // Never treat bare lib as Presentation solely.
+    const dir = String(suggestion.dir || '');
+    // Never dump bare lib/ into Presentation or Application.
+    if (dir === 'lib' || dir === 'src/lib' || dir.endsWith('/lib')) {
+      continue;
+    }
     if (
       suggestion.layer === 'PresentationAdapters' &&
-      (suggestion.dir === 'lib' || suggestion.dir.endsWith('/lib'))
+      (dir === 'lib' || dir.endsWith('/lib'))
     ) {
       continue;
     }
-    const list = byLayer.get(suggestion.layer) ?? [];
+    let layerName = suggestion.layer;
+    if (/(^|\/)(types|constants|shared)(\/|$)/i.test(dir)) layerName = 'SharedKernel';
+    else if (/(^|\/)(composition|factories|bootstrap)(\/|$)/i.test(dir)) layerName = 'CompositionRoot';
+    else if (/(^|\/)domain(\/|$)/i.test(dir)) layerName = 'DomainModel';
+    const list = byLayer.get(layerName) ?? [];
     const glob = suggestion.dir === '.' ? null : `${suggestion.dir}/**`;
-    if (glob && !list.includes(glob)) list.push(glob);
-    byLayer.set(suggestion.layer, list);
+    if (glob && !list.includes(glob) && glob !== 'src/lib/**' && glob !== 'lib/**') {
+      list.push(glob);
+    }
+    byLayer.set(layerName, list);
   }
 
-  const layers = (config.layers || []).map((layer) => {
+  const stripLibVacuum = (patterns) =>
+    (patterns || []).filter((p) => p !== '**/lib/**' && p !== 'lib/**' && p !== 'src/lib/**');
+
+  let layers = (config.layers || []).map((layer) => {
     const extras = byLayer.get(layer.name);
-    if (!extras?.length) return layer;
-    // Strip accidental bare lib/** if a previous adopt wrote it into Presentation.
-    const cleaned = (layer.patterns || []).filter((p) => {
-      if (layer.name !== 'PresentationAdapters') return true;
-      return p !== '**/lib/**' && p !== 'lib/**' && p !== 'src/lib/**';
-    });
+    const cleaned = stripLibVacuum(layer.patterns || []);
+    if (!extras?.length) return { ...layer, patterns: cleaned };
     const patterns = [...new Set([...cleaned, ...extras])];
     return { ...layer, patterns };
   });
+  layers = ensureMatureAdoptionLayers(layers, byLayer);
   // If no PresentationAdapters layer, leave layers as-is (don't invent full profile).
   const proposal = {
     ok: true,
@@ -681,6 +766,10 @@ function runAdoptContract(args) {
       persistencePatterns,
       applicationPatterns,
       domainPatterns,
+      sharedKernelPatterns,
+      compositionRootPatterns,
+      proposedLayers: ['SharedKernel', 'CompositionRoot', 'DomainModel'],
+      goldenPattern: '.ark/golden-pattern.json',
       totalFiles: cov.totalFiles,
       governedPercent: cov.governed.percent,
       unclassified: cov.unclassified.count,
@@ -698,12 +787,21 @@ function runAdoptContract(args) {
   }
 
   if (args.write) {
+    const existingRules = Array.isArray(config.rules) ? config.rules : [];
+    const rules = [...existingRules];
+    for (const rule of MATURE_LAYER_RULES) {
+      if (!rules.some((r) => r.from === rule.from && r.to === rule.to && r.allowed === rule.allowed)) {
+        rules.push(rule);
+      }
+    }
     const next = {
       ...config,
       include: proposal.after.include,
       layers,
+      rules,
     };
     fs.writeFileSync(configPath, `${JSON.stringify(next, null, 2)}\n`);
+    proposal.golden = writeAdoptGoldenPattern(root);
     proposal.wrote = true;
   }
 
@@ -720,7 +818,8 @@ function runAdoptContract(args) {
   );
   console.log(`  presentation patterns += ${uiPatterns.join(', ')}`);
   console.log(`  persistence patterns += (data clients / db / auth — never bare lib→Presentation)`);
-  console.log(`  application patterns += Next/Vercel API shells`);
+  console.log(`  application patterns += Next/Vercel API shells (never bare src/lib/**)`);
+  console.log(`  shared kernel += types/constants; composition root += wiring`);
   if (proposal.wrote) {
     console.log(color.green(`  wrote ${path.relative(root, configPath) || args.config}`));
     console.log(color.dim(`  Next: ${arkCommand(root, 'ark-check', '--coverage')} then --plan`));
@@ -1240,6 +1339,11 @@ async function main() {
       console.log('✔ Ark check passed (no governed source or constitution files in the diff).');
     } else {
       console.error(preflight.halt.message);
+      const blocking = policyDelta?.findings?.find(
+        (finding) =>
+          finding.classification === 'weakening' || finding.classification === 'judgment-required'
+      );
+      if (blocking?.nextAction) console.error(`Next: ${blocking.nextAction}`);
     }
     process.exitCode = preflight.halt.exitCode;
     return;
@@ -1322,7 +1426,17 @@ async function main() {
     populatedLayerCount,
   });
 
-  const designCheck = createDesignDeltaCheck({ enabled: args.failOnNewSmells, root, config, configPath: args.config, baseRef: args.baseRef, ts });
+  const createdPathsOnly = Boolean(args.strictMerge && !args.failOnNewSmells);
+  const designCheck = createDesignDeltaCheck({
+    enabled: args.failOnNewSmells || args.strictMerge,
+    createdPathsOnly,
+    missingBase: createdPathsOnly ? 'skip' : 'fail-closed',
+    root,
+    config,
+    configPath: args.config,
+    baseRef: resolveDesignDeltaBaseRef(root, args.baseRef),
+    ts,
+  });
   const designDelta = designCheck.result;
 
   if (args.doctor) {
@@ -1333,6 +1447,7 @@ async function main() {
       configWalkedUp: args.configWalkedUp === true,
       safety, designDelta,
       ts, parseHealth, completeness,
+      all: args.all === true,
     });
     if (designDelta) process.exitCode = !designDelta.complete ? 2 : designDelta.valid ? 0 : 1; return;
   }
@@ -1343,6 +1458,11 @@ async function main() {
   }
 
   if (args.updateBaseline) {
+    if (!contractSessionFrom(args)) {
+      console.error('Growing the baseline requires --contract-session. Freeze in a law-only PR.');
+      process.exitCode = 1;
+      return;
+    }
     const summary = summarizeViolations(violations);
     // Bloquear y avisar: a lopsided freeze buries a likely contract bug as "debt". Refuse it
     // (unless --force), diagnose, and point at the contract fix instead of the baseline.

package/bin/ark-mcp-runtime.mjs

@@ -21,6 +21,7 @@ import {
   detectWorkspaces,
   detectTsPackageRoots,
   resolveIncludeRoots,
+  isScanExcludedRelative,
 } from './ark-shared.mjs';
 import { effectiveCapabilityDeny, stableSerialize } from './lib/analysis-engine.mjs';
 import { createImportTargetResolver } from './lib/import-resolve.mjs';
@@ -866,6 +867,11 @@ function runHookPayload(payload, gate, config, args, ts, attemptContext, output
     emitHostAllow(output, { antigravityStyle, cursorStyle });
     return;
   }
+  const normalizedRel = rel.split(path.sep).join('/');
+  if (isScanExcludedRelative(normalizedRel, config)) {
+    emitHostAllow(output, { antigravityStyle, cursorStyle });
+    return;
+  }
 
   const source = proposedSource(toolName, toolInput);
   if (typeof source !== 'string') {
@@ -897,7 +903,6 @@ function runHookPayload(payload, gate, config, args, ts, attemptContext, output
           autoPatch: null,
         };
       })();
-  const normalizedRel = rel.split(path.sep).join('/');
   const designDelta = args.failOnNewSmells && layer
     ? evaluateWriteDesignDelta({
         root: args.root,
@@ -930,7 +935,10 @@ function runHookPayload(payload, gate, config, args, ts, attemptContext, output
     // New file: nothing pre-exists, every violation is new.
   }
   const newViolations = (result.violations ?? []).filter((violation) => {
-    if (String(violation.ruleId ?? violation.code).startsWith('ANALYSIS_')) return true;
+    const rule = String(violation.ruleId ?? violation.code);
+    // Incremental mid-edit parse errors are normal for agents — do not deny solely on them.
+    if (rule === 'ANALYSIS_PARSE_INCOMPLETE') return false;
+    if (rule.startsWith('ANALYSIS_')) return true;
     const key = violationKey(violation);
     const remaining = existingCounts.get(key) ?? 0;
     if (remaining === 0) return true;
@@ -2176,11 +2184,10 @@ export async function runArkMcp({ hookInput } = {}) {
     {
       name: 'ark_place',
       description:
-        'Place a file in the architecture: pass filePath (preferred) and/or description. ' +
-        'Returns layer, mayImport / mustNotImport, forbiddenGlobals, and optional goldenPattern ' +
-        '(advisory for NEW code when .ark/golden-pattern.json exists — never clears design-weak). ' +
+        'Place a file in the architecture: filePath is required (fail-closed without it — never invents components/*.tsx or defaults to Presentation). ' +
+        'Returns layer, mayImport / mustNotImport, forbiddenGlobals, and goldenPattern ' +
+        '(load-bearing for NEW code when .ark/golden-pattern.json exists — adopt generates it). ' +
         'Call BEFORE writing a new file. ' +
-        'If only description is given, returns a conventional path proposal under a governed layer. ' +
         'Prefer ark_prepare_write when you already have the source snippet (place+validate+autoPatch in one call).',
       inputSchema: {
         type: 'object',
@@ -2192,7 +2199,7 @@ export async function runArkMcp({ hookInput } = {}) {
           description: {
             type: 'string',
             description:
-              'What you are building (e.g. "Remotion caption overlay"). Used when filePath is omitted to propose a path.',
+              'What you are building. Does not invent a path — pass filePath. Without filePath the tool fail-closes.',
           },
         },
       },
@@ -2641,31 +2648,12 @@ export async function runArkMcp({ hookInput } = {}) {
     const golden = loadGoldenPattern(args.root);
     const withGolden = (placement) => attachGoldenToPlacement(placement, golden);
 
-    if ((typeof filePath !== 'string' || !filePath) && typeof description === 'string' && description.trim()) {
-      const slug = description
-        .trim()
-        .toLowerCase()
-        .replace(/[^a-z0-9]+/g, '-')
-        .replace(/^-|-$/g, '')
-        .slice(0, 48) || 'component';
-      const proposedPath = `src/components/${slug}.tsx`;
-      const layerName = inferLayer(proposedPath, config, args.root) || 'PresentationAdapters';
-      return withGolden({
-        filePath: proposedPath,
-        proposed: true,
-        description: description.trim(),
-        layer: layerName,
-        governed: Boolean(inferLayer(proposedPath, config, args.root)),
-        note:
-          'filePath was omitted — proposed a conventional path from description. ' +
-          'Pass filePath explicitly for authoritative placement.',
-      });
-    }
-    if (typeof filePath !== 'string' || !filePath) {
+    if (typeof filePath !== 'string' || !filePath.trim()) {
       return {
         error:
-          'Needs filePath and/or description. ' +
-          'Example: { "filePath": "src/components/Foo.tsx" } or { "description": "caption overlay UI component" }.',
+          'ark_place requires filePath. Fail-closed: will not invent a path (never default to Presentation or components/*.tsx). ' +
+          'Example: { "filePath": "src/lib/repositories/orders-repository.ts" }.',
+        failClosed: true,
       };
     }
     const layerName = inferLayer(filePath, config, args.root);

package/bin/ark.mjs

@@ -694,11 +694,13 @@ async function start(args) {
     // Modes are detected (Suggest/Adapt/Enforce), not user-picked settings.
     // Soft-block false-green using the same doctor adoption gap (no second detector).
     let falseGreenGap = null;
+    let adopted = null;
     try {
       const doc = JSON.parse(doctorCapture.stdout || '{}');
       falseGreenGap = (doc.doctor?.adoption?.gaps ?? []).find(
         (g) => g?.id === FALSE_GREEN_GAP_ID
       );
+      adopted = doc.doctor?.adoptionStance ?? null;
     } catch {
       falseGreenGap = null;
     }
@@ -714,9 +716,17 @@ async function start(args) {
       console.log(`  • ${falseGreenGap.message}`);
       console.log(`  • Next: ${falseGreenGap.fix}`);
     } else if (mode === 'enforce' && planOk) {
-      console.log('Done — status: ENFORCE (gates can honestly protect you).');
-      console.log('What happens now:');
-      console.log('  • Every edit is checked (in CI and, if wired, at write time).');
+      if (adopted === 'required-merge' || adopted === 'advisory-only-acked') {
+        console.log('Done — status: ENFORCE (gates can honestly protect you).');
+        console.log('What happens now:');
+        console.log('  • Every edit is checked (in CI and, if wired, at write time).');
+      } else {
+        console.log('Done — status: ENFORCE (contract edges clean; merge boundary not adopted).');
+        console.log('What happens now:');
+        console.log(
+          '  • CI workflow written; make the GitHub status required on arkgate-check --strict-merge, or write .ark/adoption-stance.json with stance: "advisory-only".'
+        );
+      }
     } else if (mode === 'suggest') {
       console.log('Done — status: SUGGEST (starting shape installed; expand as you grow).');
       console.log('What happens now:');

package/bin/lib/adapter-contract.mjs

@@ -8,6 +8,8 @@
  * Pure CLI helper (bin/lib/adapter-contract.mjs). Zero Node I/O.
  */
 
+import { layerImportNextAction } from './remediation.mjs';
+/** Versioned public result contract shared by every ArkGate enforcement adapter. */
 /**
  * 1.5 adds stable finding refs on every factory-emitted diagnostic (ACS06):
  * `findingRef`, `targetKey` (baseline-compatible), `docsCodePath`.
@@ -76,15 +78,17 @@ export function adapterDocsCodePath(ruleId) {
 }
 function nextActionForDiagnostic(ruleId, evidence, violation) {
     if (ruleId === 'LAYER_IMPORT_VIOLATION') {
-        if (evidence.typeOnly ||
-            violation.targetTypeOnlyExports === true ||
-            violation.namedBindingsTypeOnly === true) {
-            return 'Move the referenced type to a mutually allowed layer, use `import type`, then preflight again.';
-        }
-        if (violation.peerIsolation === true) {
-            return 'Extract the shared dependency to a shared layer, test at the public interface, then preflight again.';
-        }
-        return `Define a port in ${evidence.fromLayer ?? 'the source layer'}, inject the ${evidence.toLayer ?? 'outer-layer'} implementation, test at the public interface, then preflight again.`;
+        return layerImportNextAction({
+            ruleId,
+            typeOnly: evidence.typeOnly === true,
+            targetTypeOnlyExports: violation.targetTypeOnlyExports === true,
+            namedBindingsTypeOnly: violation.namedBindingsTypeOnly === true,
+            peerIsolation: violation.peerIsolation === true,
+            portProofEligible: violation.portProofEligible === true,
+            fromLayer: text(evidence.fromLayer) ?? undefined,
+            toLayer: text(evidence.toLayer) ?? undefined,
+            target: text(evidence.target) ?? text(violation.target) ?? undefined,
+        });
     }
     if (ruleId === 'FORBIDDEN_GLOBAL') {
         return `Inject ${evidence.target ?? 'the capability'} through a port, test at the public interface, then preflight again.`;

package/bin/lib/adoption-stance.mjs

@@ -0,0 +1,104 @@
+/**
+ * D0 adoption stance — required merge status or explicit advisory-only ack.
+ * Tooling I/O. Never invents GitHub required from workflow YAML presence.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const ADOPTION_STANCE_REL = '.ark/adoption-stance.json';
+export const ADOPTION_STANCE_VALUE = 'advisory-only';
+export const ADOPTED_REQUIRED_MERGE = 'required-merge';
+export const ADOPTED_ADVISORY_ACKED = 'advisory-only-acked';
+export const ADOPTED_NOT = 'not-adopted';
+
+export const NOT_ADOPTED_NEXT_ACTION =
+  'Make arkgate-check --strict-merge a required GitHub status, or write .ark/adoption-stance.json with stance: "advisory-only"';
+
+export const MERGE_BOUNDARY_NOT_REQUIRED = 'merge-boundary-not-required';
+
+/**
+ * @param {string} root
+ * @returns {{ schemaVersion?: string, stance?: string, ackedAt?: string, reason?: string } | null}
+ */
+export function readAdoptionStance(root) {
+  const file = path.join(root, ADOPTION_STANCE_REL);
+  if (!fs.existsSync(file)) return null;
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+    return parsed && typeof parsed === 'object' ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function stanceValue(stance) {
+  if (typeof stance === 'string') return stance;
+  if (stance && typeof stance === 'object' && typeof stance.stance === 'string') {
+    return stance.stance;
+  }
+  return null;
+}
+
+/**
+ * Closed enum: required-merge | advisory-only-acked | not-adopted.
+ * Workflow presence is never enough.
+ *
+ * @param {{
+ *   stance?: { stance?: string } | string | null,
+ *   github?: { arkCheckRequired?: unknown, requiredStatusConfigured?: unknown },
+ *   ci?: { state?: string, requiredStatusConfigured?: unknown },
+ * }} [input]
+ */
+export function classifyAdopted(input = {}) {
+  const github = input.github && typeof input.github === 'object' ? input.github : {};
+  const ci = input.ci && typeof input.ci === 'object' ? input.ci : {};
+  const required =
+    github.arkCheckRequired === true ||
+    github.requiredStatusConfigured === true ||
+    ci.requiredStatusConfigured === true ||
+    ci.state === 'required';
+  if (required) return ADOPTED_REQUIRED_MERGE;
+  if (stanceValue(input.stance) === ADOPTION_STANCE_VALUE) return ADOPTED_ADVISORY_ACKED;
+  return ADOPTED_NOT;
+}
+
+export function isAdopted(kind) {
+  return kind === ADOPTED_REQUIRED_MERGE || kind === ADOPTED_ADVISORY_ACKED;
+}
+
+/**
+ * Map doctor adoption + writePath into the ci-merge-boundary github input.
+ * Never sets requiredStatusConfigured false from a missing GitHub query.
+ *
+ * @param {object} [adoption]
+ * @param {object} [writePath]
+ */
+export function githubEvidenceForCiMergeBoundary(adoption, writePath) {
+  const github =
+    adoption?.enforcement?.github && typeof adoption.enforcement.github === 'object'
+      ? adoption.enforcement.github
+      : {};
+  const ci =
+    adoption?.enforcement?.ci && typeof adoption.enforcement.ci === 'object'
+      ? adoption.enforcement.ci
+      : {};
+  const ciMerge =
+    writePath?.enforcementState?.ciMerge && typeof writePath.enforcementState.ciMerge === 'object'
+      ? writePath.enforcementState.ciMerge
+      : {};
+  const required =
+    github.arkCheckRequired === true ||
+    github.requiredStatusConfigured === true ||
+    ciMerge.required === true;
+  return {
+    ...github,
+    ...(required ? { arkCheckRequired: true, requiredStatusConfigured: true } : {}),
+    workflowPresent:
+      github.workflowPresent === true ||
+      ci.hasArkCheckWorkflow === true ||
+      writePath?.capabilities?.['merge-gate'] === true ||
+      writePath?.inventory?.capabilities?.['merge-gate'] === true,
+    plan: github.plan,
+    canRequire: github.canRequire,
+  };
+}

package/bin/lib/agent-projection-command.mjs

@@ -261,6 +261,14 @@ export function runAgentProjectionCommand(args = {}) {
       profile: args.profile,
       arkgateVersion: args.arkgateVersion,
     });
+    const claudePlan = planAgentProjectionRefresh({
+      root: args.root,
+      config: args.config,
+      host: args.host || 'claude',
+      profile: args.profile,
+      arkgateVersion: args.arkgateVersion,
+      targetRelativePath: 'CLAUDE.md',
+    });
 
     if (stdoutOnly) {
       if (asJson) {
@@ -337,8 +345,10 @@ export function runAgentProjectionCommand(args = {}) {
     }
 
     let applyResult = { wrote: false, action: plan.action, path: plan.path };
+    let claudeApply = { wrote: false, action: claudePlan.action, path: claudePlan.path };
     if (doWrite) {
       applyResult = applyAgentProjectionRefresh(plan, { write: true });
+      claudeApply = applyAgentProjectionRefresh(claudePlan, { write: true });
     }
 
     if (asJson) {
@@ -349,6 +359,14 @@ export function runAgentProjectionCommand(args = {}) {
             arkgateVersion: plan.packageVersion,
             nonAuthoritative: true,
             path: plan.relativePath,
+            hosts: {
+              agentsMd: { path: plan.relativePath, wrote: applyResult.wrote, action: applyResult.action },
+              claudeMd: {
+                path: claudePlan.relativePath,
+                wrote: claudeApply.wrote,
+                action: claudeApply.action,
+              },
+            },
             action: applyResult.action,
             wrote: applyResult.wrote,
             wouldWrite: plan.wouldWrite,

package/bin/lib/agent-projection.mjs

@@ -148,10 +148,10 @@ export function buildAgentProjectionBody(facts) {
         '',
     ];
     if (profile === 'compact') {
-        lines.push('### Primary path', '', '1. Run doctor (`ark-check --doctor`) — status light + primary next action.', '2. Read the improvement compass (not a score). Name leftover work in plain language; never “done” on green imports alone while leftover design work remains.', '3. Call `ark_identity` with `project.expectedRoot` at the exact project root; reuse root + `projectId` on Ark MCP calls.', '4. Read architecture config with `ark_manifest` (same expectation). `ark://manifest` is compatibility-only / unverified.', '5. Place files inside configured layers; validate; run the check command above on violations — fix architecture, do not weaken the gate.', '6. Single door: import-rule debt → fix; leftover design work / residual shape lenses → map then guided apply with user OK.', '', '### Contract layers (summary)', '', formatAgentProjectionLayers(layers), '');
+        lines.push('### Primary path', '', '1. Run doctor (`ark-check --doctor`) — status light + primary next action. Prefer the project-local CLI; do not wait on MCP “still connecting”.', '2. Read the improvement compass (not a score). Name leftover work in plain language; never “done” on green imports alone while leftover design work remains.', '3. Identity handshake is optional when the CLI already resolved the project root. Call `ark_identity` only when using MCP evidence.', '4. Read architecture config with `ark_manifest` (same expectation) or the local `ark.config.json`. `ark://manifest` is compatibility-only / unverified.', '5. Place files inside configured layers; validate; run the check command above on violations — fix architecture, do not weaken the gate.', '6. Single door: import-rule debt → fix; leftover design work / residual shape lenses → map then guided apply with user OK.', '', '### Contract layers (summary)', '', formatAgentProjectionLayers(layers), '');
     }
     else {
-        lines.push('### Contract layers', '', formatAgentProjectionLayers(layers), '', 'When creating a **new** kind of code that no layer covers, update `ark.config.json` first (`/ark-adopt`), then place the file.', '', '### Diagnostic codes (short list)', '', formatAgentProjectionCatalogShortList(catalog, docsPath), '', '### Session truth', '', '- Machine snapshot: `ark status --json` (or MCP `ark_status`) — identity, activation honesty, last check, residual counts. **Not a score.**', '- Authoritative contract: `ark_manifest` after a matched `ark_identity` handshake.', '');
+        lines.push('### Contract layers', '', formatAgentProjectionLayers(layers), '', 'When creating a **new** kind of code that no layer covers, update `ark.config.json` first (`/ark-adopt`), then place the file.', '', '### Diagnostic codes (short list)', '', formatAgentProjectionCatalogShortList(catalog, docsPath), '', '### Session truth', '', '- Machine snapshot: `ark status --json` (or MCP `ark_status`) — identity, activation honesty, last check, residual counts. **Not a score.**', '- Authoritative contract: local `ark.config.json` / CLI, or `ark_manifest` after a matched `ark_identity` handshake. Identity is optional when CLI already resolved the root.', '- Host docs: the same projection schema is merged into `AGENTS.md` and `CLAUDE.md` (`ark agents-md --write`).', '');
     }
     lines.push('### Enforcement surfaces (authoritative)', '', AGENT_PROJECTION_ENFORCEMENT_SURFACES.map((surface) => `- \`${surface}\``).join('\n'), '');
     return lines.join('\n').replace(/\n{3,}/g, '\n\n').trimEnd() + '\n';