arkgate 4.6.3 → 4.6.5

package/CHANGELOG.md

@@ -5,6 +5,64 @@ in the immutable pre-2.0 archive linked below.
 
 ## Unreleased
 
+## 4.6.5 — 2026-08-19
+
+**Patch** over **4.6.4**. Adoption, placement, doctor, upgrade, and write-path honesty for
+existing Next.js trees and multi-host teams. **No required config migration.**
+
+**Status: current** (shipping as `arkgate@4.6.5`; see `docs/releases/4.6.5.md`).
+
+### Changed
+
+- **Adopt starter:** existing trees get SharedKernel (types/constants), CompositionRoot (wiring),
+  and `src/**/domain/**`. Flattened `src/lib/**` is not dumped into Application. Adopt writes
+  `.ark/golden-pattern.json` (load-bearing for place).
+- **Place:** `filePath` is required (fail-closed). Never invents `components/*.tsx` or defaults
+  to Presentation.
+- **LAYER_IMPORT nextAction:** branches by import kind — constants/types → Domain/SharedKernel;
+  kernel/events from Persistence → do not emit; port only for a real use-case.
+- **Reserved empty globs:** `reserved` / `allowEmpty` so `--strict-config` does not fail on
+  future houses. Typo warning only if the glob is not reserved.
+- **Parse / lexical:** `ANALYSIS_PARSE_INCOMPLETE` includes the TypeScript line + message.
+  Contract `exclude` paths skip the write hook. Incremental mid-edit parse does not deny.
+  `LEXICAL_EVIDENCE_INCOMPLETE` hook deny does not tell the agent to call `ark_prepare_change`.
+- **WritePath / CI honesty:** `.ark/ci-merge-boundary.json` — hook configured-not-fired,
+  per-host writePath (Claude hard vs Cursor soft), CI present-but-not-required, GitHub Free
+  cannot require. Hook green is not tree green.
+- **Upgrade:** preview default is hosts keep (union `--tools` with existing). Apply installs
+  the bumped package unless `--no-install`. Projection writes AGENTS.md and CLAUDE.md.
+  Prefer project `.agents/skills`; home must not duplicate the catalog.
+- **Doctor JSON:** stable envelope `{ schemaVersion, envelope: "doctor", ok, doctor }`.
+  ENFORCE + empty plan A → Shape, not reinstall gates. Distinguishes installed vs stale skills.
+- **Graph scan:** threshold scales with included file count (floor 2500, cap 8000) so a
+  ~3300-file Next.js tree is not deferred.
+- **INVARIANT_UNCOVERED:** `never-had-tests` (adopt residual) vs `tests-disappeared` (regression).
+- **CLI-first:** identity handshake is optional when the CLI already resolved the root.
+
+## 4.6.4 — 2026-08-18
+
+**Patch** over **4.6.3**. `ark upgrade` now tells Codex users how to activate the local
+`apply_patch` boundary after upgrading: refresh the project hook, restart Codex/local Desktop,
+trust the exact hook definition, and verify `doctor.writePath` after a governed patch.
+**No required config migration.**
+
+**Status: published** (on npm `latest` until 4.6.5 lands; see `docs/releases/4.6.4.md`).
+
+### Changed
+
+- **Upgrade JSON:** `whatsNew.items` includes stable id `codex-hard-write` with the exact
+  `--install-agent-gates --tools codex --force` command and evidence to inspect.
+- **Upgrade human output:** **Suggested improvements** prints the same refresh/restart/trust/check
+  path on preview and apply, including nothing-to-apply previews.
+- **Upgrade skill:** flat and Agent Skills guidance tells Codex to exercise a governed
+  `apply_patch` and keeps hosted/specialized/shell/direct/incomplete/human paths CI-backed.
+- **Stale MCP fail-closed:** when process version no longer matches the project install,
+  `ark_identity` reports non-authoritative evidence and project tools return
+  `PROCESS_PACKAGE_STALE` until restart/retarget.
+- **Global CLI handoff:** a modern stale global `ark upgrade` delegates the original invocation
+  to the project-local `node_modules/arkgate/bin/ark.mjs` instead of managing from the wrong PATH
+  version. Pre-4.6.4 globals still require one `npx arkgate upgrade` entry.
+
 ## 4.6.3 — 2026-08-18
 
 **Patch** over **4.6.2**. Codex CLI and local ChatGPT Desktop/App Server now get a
@@ -12,7 +70,8 @@ runtime-proven pre-write block for complete `apply_patch` calls. ArkGate accepts
 `tool_input.command` payload, while incomplete, hosted, specialized, shell/direct, and human
 write paths remain CI-backed. **No required config migration.**
 
-**Status: prepared** (not yet on npm `latest`; see `docs/releases/4.6.3.md`).
+**Status: published** (npm `latest` from signed tag `v4.6.3`; OIDC run `32167523804`;
+see `docs/releases/4.6.3.md`).
 
 ### Changed
 
@@ -804,8 +863,8 @@ Not a rewrite of the analysis engine. No plan-B silent codemod. No fake hard wri
 
 ## 3.8.3 — 2026-07-22
 
-Corrective **patch** over 3.8.2 from multi-repo field evidence (PROPIA pnpm workspace upgrade;
-Amarilla greenfield `start`). **No required config migration.** Z09 / residual `RB-11` remain open.
+Corrective **patch** over 3.8.2 from multi-repo field evidence (pnpm workspace upgrade;
+greenfield `start`). **No required config migration.** Z09 / residual `RB-11` remain open.
 
 ### Fixed
 
@@ -832,7 +891,7 @@ Amarilla greenfield `start`). **No required config migration.** Z09 / residual `
 
 ## 3.8.2 — 2026-07-22
 
-Corrective **patch** over 3.8.1 from PREDIAL WEB field evidence. Aligns doctor skill freshness with
+Corrective **patch** over 3.8.1 from field Next.js evidence. Aligns doctor skill freshness with
 managed upgrade content identity, hardens upgrade preview honesty, clarifies doctor writePath
 inventory vs this-invocation, ships the Y06 pure-layer opt-in advisory, and treats complete-catalog
 Codex leftover prompts as safe-to-delete. **No required config migration.** Z09 / residual `RB-11`
@@ -856,7 +915,7 @@ remain open.
 
 - **Y06 pure-layer opt-in nudge:** when a golden pattern names pure modules and no layer sets
   `pure: true`, doctor emits one advisory line (`doctor.pureLayerOptIn`). Never a blocker; never
-  auto-writes `pure: true`. Promoted from field evidence (PREDIAL WEB).
+  auto-writes `pure: true`. Promoted from field evidence (a Next.js app).
 
 ## 3.8.1 — 2026-07-22
 

package/README.md

@@ -16,9 +16,9 @@ and makes sure a “green” check means something real.
 
 </div>
 
-> **ArkGate 4.6.2** is on npm `latest` — first-contact copy (what to do in a few lines).
-> **4.6.3 is prepared** — Codex CLI/local Desktop hard-block complete trusted `apply_patch`.
-> [4.6.3 notes](docs/releases/4.6.3.md) · [4.6.2](docs/releases/4.6.2.md) · [4.6.1](docs/releases/4.6.1.md) · [4.6.0](docs/releases/4.6.0.md) · [Docs hub](docs/README.md) · [Product voice](docs/product-voice.md)
+> **ArkGate 4.6.5** is current (on npm after this release). Adopt/place honesty for existing Next.js
+> trees, stable doctor JSON, writePath/CI honesty file, hosts-keep upgrade, CLAUDE.md projection.
+> [4.6.5 notes](docs/releases/4.6.5.md) · [4.6.4](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) · [4.6.0](docs/releases/4.6.0.md) · [Docs hub](docs/README.md) · [Product voice](docs/product-voice.md)
 
 ---
 
@@ -216,8 +216,10 @@ 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.2 on npm `latest`) | [docs/releases/4.6.2.md](docs/releases/4.6.2.md) · [CHANGELOG](CHANGELOG.md) |
-| Prepared patch (4.6.3) | [docs/releases/4.6.3.md](docs/releases/4.6.3.md) |
+| Current release (4.6.5) | [docs/releases/4.6.5.md](docs/releases/4.6.5.md) · [CHANGELOG](CHANGELOG.md) |
+| Prior published (4.6.4 on npm `latest` until 4.6.5 lands) | [docs/releases/4.6.4.md](docs/releases/4.6.4.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) |
 | Prior (4.5.7) | [docs/releases/4.5.7.md](docs/releases/4.5.7.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,
@@ -573,6 +575,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 +688,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 +698,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 +751,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 +772,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 +803,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`));

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;
@@ -1960,11 +1968,14 @@ export async function runArkMcp({ hookInput } = {}) {
   }
 
   function contextFor(binding) {
+    const processPackage = processPackageHonesty();
     return {
       projectIdentity,
       binding,
-      authoritative: binding.authoritative,
-      processPackage: processPackageHonesty(),
+      // A correctly bound project is still non-authoritative when this long-lived
+      // process loaded a different package version than the project now resolves.
+      authoritative: binding.authoritative && !processPackage.processStale,
+      processPackage,
     };
   }
 
@@ -2041,13 +2052,36 @@ export async function runArkMcp({ hookInput } = {}) {
     );
   }
 
+  function staleProcessFailureResult(binding) {
+    const processPackage = processPackageHonesty();
+    return withProjectContext(
+      {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify({
+              ok: false,
+              error: {
+                code: 'PROCESS_PACKAGE_STALE',
+                message: processPackage.nextAction,
+              },
+            }),
+          },
+        ],
+        isError: true,
+      },
+      binding
+    );
+  }
+
   const TOOLS = [
     {
       name: 'ark_identity',
       description:
         'First call. Prove this MCP process is the right project: pass project.expectedRoot ' +
         '(exact absolute root) and reuse the returned projectId. Do this before any other Ark tool. ' +
-        'A missing, unmatched, or different root means restart the host and use the local CLI.',
+        'A missing/unmatched root or processPackage.processStale means restart/retarget the host ' +
+        'and use the project-local CLI until identity and package versions align.',
       inputSchema: { type: 'object', properties: {} },
     },
     {
@@ -2150,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',
@@ -2166,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.',
           },
         },
       },
@@ -2615,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);
@@ -3005,6 +3019,13 @@ export async function runArkMcp({ hookInput } = {}) {
           reply(id, bindingFailureResult(binding));
           return;
         }
+        // Keep ark_identity available so the host can diagnose the stale process,
+        // but fail every project tool closed until the MCP server restarts on the
+        // version installed for this root.
+        if (params?.name !== 'ark_identity' && processPackageHonesty().processStale) {
+          reply(id, staleProcessFailureResult(binding));
+          return;
+        }
         try {
           reply(id, withProjectContext(handler(params, binding), binding));
         } catch (error) {

package/bin/ark.mjs

@@ -831,6 +831,7 @@ async function main() {
         packageInstallArgv,
         runArkCheck,
         cliVersion: cliVersion(),
+        rawArgv: process.argv.slice(2),
         shouldSkipArkgateInstall,
       });
     } catch (error) {

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/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';