arkgate 4.8.18 → 4.8.20

package/bin/lib/physical-cohesion.mjs

@@ -15,6 +15,7 @@
  * as W01 layer roles: a miss costs a warning line, never a verdict.
  */
 import path from 'node:path';
+import { layerForRelativePath, sliceIdForPath } from '../ark-layer-match.mjs';
 
 /** ADR 0010 D3 — corpus-calibrated, fixed. */
 const CLUSTER_MIN = 40;
@@ -126,76 +127,92 @@ export function computePhysicalCohesion(root, files) {
   };
 }
 
+function governedDestinationDir(anchor, concept) {
+  return !anchor || anchor === '.' ? concept : `${anchor}/${concept}`;
+}
+
+function anchorIsConsolidationSubtree(anchor, concept) {
+  return String(anchor).split('/').some((part) => part === concept);
+}
+
+function declaredSliceFolders(rules) {
+  const out = [];
+  const seen = new Set();
+  for (const rule of Array.isArray(rules) ? rules : []) {
+    const folders = Array.isArray(rule?.sliceFolders) ? rule.sliceFolders : [];
+    for (const folder of folders) {
+      if (typeof folder !== 'string' || folder.length === 0 || seen.has(folder.toLowerCase())) continue;
+      seen.add(folder.toLowerCase());
+      out.push(folder);
+    }
+  }
+  return out;
+}
+
+function destinationKeepsLayerAndSlice(fromRel, toRel, layers, sliceFolders) {
+  return layerForRelativePath(fromRel, layers) === layerForRelativePath(toRel, layers)
+    && sliceIdForPath(fromRel, sliceFolders) === sliceIdForPath(toRel, sliceFolders);
+}
+
+function withheldPilot(concept, note) {
+  return { proposed: true, applied: false, neverMechanicalSafe: true, concept, note, nextPilot: null };
+}
+
 /**
- * R2 — the proposed reshape pilot for the TOP finding (one at a time, Q04
- * discipline; ADR 0010 D4–D7). Proposal only: no apply path exists. Moves
- * target the smallest convention-free anchor; sampled `to` paths must fall
- * under the consolidated feature directory the agent will create via the
- * governed write path (T02 preflight validates every real move there).
+ * R2 — proposed reshape pilot (ADR 0010 D4–D7). `to` is `concept/` under the
+ * source anchor and is kept only when the generated layer and slice matchers
+ * agree. Tooling does not import Kernel preflight. Withheld when every
+ * candidate fails.
  */
-export function computeReshapePilot(cohesion, files, root) {
+export function computeReshapePilot(cohesion, files, root, contract) {
   const top = cohesion?.findings?.[0];
   if (!top) return null;
-  // Recompute the FULL anchor map for the top concept: the finding's anchors
-  // are display-filtered (>= MIRROR_MIN, capped), and pilot selection over
-  // that trimmed list falsely reported "nothing to move" when the only
-  // movable anchor sat below the display floor (cross-model review finding).
+  const layers = contract?.layers;
+  const sliceFolders = declaredSliceFolders(contract?.rules);
+  // Full anchor map: the finding's anchors are display-filtered (>= MIRROR_MIN).
   const byAnchor = new Map();
   const relOf = (abs) => path.relative(root, abs).split(path.sep).join('/');
-  for (const abs of Array.isArray(files) ? files : []) {
+  const fileList = Array.isArray(files) ? files : [];
+  for (const abs of fileList) {
     const rel = relOf(abs);
-    const r = classifyPhysical(rel);
-    if (!r || r.concept !== top.concept) continue;
-    byAnchor.set(r.anchor, (byAnchor.get(r.anchor) ?? 0) + 1);
+    const ranked = classifyPhysical(rel);
+    if (!ranked || ranked.concept !== top.concept) continue;
+    byAnchor.set(ranked.anchor, (byAnchor.get(ranked.anchor) ?? 0) + 1);
   }
-  const targetDir = `src/features/${top.concept}`;
   const movable = [...byAnchor.entries()]
-    .filter(
-      ([anchor]) =>
-        !CONVENTION_ANCHOR_RE.test(`${anchor}/`) &&
-        // The consolidation target subtree is DONE, not a source — without
-        // this the loop re-proposes the files it just moved, forever
-        // (end-to-end pilot-loop finding).
-        anchor !== targetDir &&
-        !anchor.startsWith(`${targetDir}/`)
-    )
+    .filter(([anchor]) => !CONVENTION_ANCHOR_RE.test(`${anchor}/`) && !anchorIsConsolidationSubtree(anchor, top.concept))
     .map(([anchor, count]) => ({ path: anchor, files: count }))
     .sort((a, b) => a.files - b.files || (a.path < b.path ? -1 : 1));
   if (movable.length === 0) {
-    return {
-      proposed: true,
-      applied: false,
-      neverMechanicalSafe: true,
-      concept: top.concept,
-      note: 'Every remaining anchor for this concept is fixed by framework convention or already consolidated — nothing to move; consider the merge-card review instead.',
-      nextPilot: null,
-    };
+    return withheldPilot(top.concept, 'Every remaining anchor for this concept is fixed by framework convention or already consolidated — nothing to move; consider the merge-card review instead.');
+  }
+  const legalAnchors = [];
+  for (const anchor of movable) {
+    const targetDir = governedDestinationDir(anchor.path, top.concept);
+    const legal = fileList.map(relOf).filter((rel) => {
+      const ranked = classifyPhysical(rel);
+      if (!ranked || ranked.concept !== top.concept || ranked.anchor !== anchor.path) return false;
+      const to = `${targetDir}/${rel.split('/').at(-1)}`;
+      return destinationKeepsLayerAndSlice(rel, to, layers, sliceFolders);
+    }).sort().map((rel) => ({ from: rel, to: `${targetDir}/${rel.split('/').at(-1)}` }));
+    if (legal.length > 0) legalAnchors.push({ ...anchor, targetDir, legal });
+  }
+  if (legalAnchors.length === 0) {
+    return withheldPilot(top.concept, 'No governed destination keeps the layer and the slice.');
   }
-  // Smallest movable cluster worth piloting; if none reaches the floor, take
-  // the largest movable anchor so the pilot still exists and stays honest.
-  const pilotAnchor = movable.find((a) => a.files >= 10) ?? movable[movable.length - 1];
-  const rels = (Array.isArray(files) ? files : [])
-    .map(relOf)
-    .filter((rel) => {
-      const r = classifyPhysical(rel);
-      return r && r.concept === top.concept && r.anchor === pilotAnchor.path;
-    })
-    .sort();
-  const moves = rels.slice(0, MAX_MOVE_SAMPLE).map((rel) => ({
-    from: rel,
-    to: `${targetDir}/${rel.split('/').at(-1)}`,
-  }));
+  // Smallest cluster of at least 10 files; otherwise the largest movable anchor.
+  const pilotAnchor = legalAnchors.find((a) => a.files >= 10) ?? legalAnchors.at(-1);
   return {
     proposed: true,
     applied: false,
     neverMechanicalSafe: true,
     concept: top.concept,
     nextPilot: {
-      pilotTarget: `${top.concept} @ ${pilotAnchor.path} (${pilotAnchor.files} file(s))`,
-      move: `Consolidate the ${top.concept} cluster from ${pilotAnchor.path} under ${targetDir}/ — one anchor only, moves proposed as an architecture change map and validated by the atomic preflight before any write.`,
-      moveSample: moves,
-      movesTotal: rels.length,
-      successSignal: `re-run doctor: the ${top.concept} cluster count drops and the verdict stays green`,
+      pilotTarget: `${top.concept} @ ${pilotAnchor.path} (${pilotAnchor.legal.length} file(s))`,
+      move: `Consolidate the ${top.concept} cluster from ${pilotAnchor.path} under ${pilotAnchor.targetDir}/ — one anchor only, same layer and slice, moves proposed as an architecture change map and validated by the atomic preflight before any write.`,
+      moveSample: pilotAnchor.legal.slice(0, MAX_MOVE_SAMPLE),
+      movesTotal: pilotAnchor.legal.length,
+      successSignal: `re-run doctor: the ${top.concept} cluster count drops, layer and slice id unchanged, card still proposed`,
       killSwitch: 'revert this move set; nothing else was touched',
       doNot: [
         'never move files under app/ or pages/ — fixed by framework convention',

package/bin/lib/presets.mjs

@@ -10,6 +10,7 @@ import {
   DEFAULT_DOMAIN_FORBIDDEN_GLOBALS,
   discoverRepoUnits,
   DEFAULT_INTENT_PREFIXES,
+  monorepoRoleSourceGlobs,
   resolveIncludeRoots,
 } from '../ark-shared.mjs';
 import { withArkConfigMetadata } from './config-contract.mjs';
@@ -630,20 +631,18 @@ export const ARCHITECTURE_PRESETS = {
     // Turborepo: apps/ + packages/; Nx enterprise: apps/ + libs/ (+ packages/).
     if (include.length === 0) include = ['packages', 'apps', 'libs'];
     // Library Domain bags stay under packages/ or libs/ — never api/** or client/**.
-    const roleGlobs = (roles, domainScoped) =>
-      !root
-        ? []
-        : units
-            .filter((unit) => roles.includes(unit.role) && !(domainScoped && unit.root === '.'))
-            .flatMap((unit) =>
-              (unit.sourceRoots ?? []).map((sourceRoot) => {
-                const base = unit.root === '.' ? sourceRoot : sourceRoot === '.' ? unit.root : `${unit.root}/${sourceRoot}`;
-                return base === '.' ? null : `${base}/**`;
-              })
-            )
-            .filter((pattern) => pattern && (!domainScoped || /^(packages|libs)\//.test(pattern)));
-    const librarySourcePatterns = roleGlobs(['library'], true);
-    const applicationSourcePatterns = roleGlobs(['application', 'cli'], false);
+    const librarySourcePatterns = monorepoRoleSourceGlobs(units, ['library'], {
+      root,
+      domainScoped: true,
+    });
+    const applicationSourcePatterns = monorepoRoleSourceGlobs(units, ['application', 'cli'], {
+      root,
+      uiMode: 'not-ui',
+    });
+    const uiApplicationSourcePatterns = monorepoRoleSourceGlobs(units, ['application', 'cli'], {
+      root,
+      uiMode: 'ui',
+    });
     return presetWithOverlays(
       {
         include,
@@ -689,6 +688,7 @@ export const ARCHITECTURE_PRESETS = {
               '**/http/**',
               '**/routes/**',
               '**/hooks/**',
+              ...uiApplicationSourcePatterns,
               // No bare **/lib/** — NEW-ADOPT-LIB-AS-PRESENTATION / NEW-APP-VACUUM-LIB.
             ],
             optional: true,

package/bin/lib/reshape-decisions.mjs

@@ -214,7 +214,7 @@ export function computeReshapeDecisionMemory(root, files, today = new Date().toI
 }
 
 /** Select one actionable finding while respecting explicit current verdicts. */
-export function computeDecisionAwareReshapePilot(cohesion, files, root, analysis) {
+export function computeDecisionAwareReshapePilot(cohesion, files, root, analysis, contract) {
   const findings = Array.isArray(cohesion?.findings) ? cohesion.findings : [];
   if (findings.length === 0) return null;
   const currentByTarget = new Map(
@@ -224,7 +224,7 @@ export function computeDecisionAwareReshapePilot(cohesion, files, root, analysis
     const anchors = analysis.anchorSets.get(finding.concept) ?? [];
     const decision = currentByTarget.get(targetKey(finding.concept, anchors));
     if (decision?.suppressesPilot) continue;
-    const pilot = computeReshapePilot({ ...cohesion, findings: [finding] }, files, root);
+    const pilot = computeReshapePilot({ ...cohesion, findings: [finding] }, files, root, contract);
     if (!pilot?.nextPilot) return pilot;
     return {
       ...pilot,

package/bin/lib/rules-under-contract.mjs

@@ -6,7 +6,7 @@
  */
 import path from 'node:path';
 import { loadEffectiveArkRulesFromDisk } from './effective-contract-load.mjs';
-import { evaluateInvariantCoverage } from './invariant-coverage.mjs';
+import { evaluateInvariantCoverage, formatCoverageDiscards } from './invariant-coverage.mjs';
 import {
   coverageOptionsFromConfig,
   invariantIdsFromCatalog,
@@ -138,9 +138,9 @@ export function summarizeRulesUnderContract(root, config, facts, classification)
       fileContents: coverageInputs.fileContents,
       testFiles: coverageInputs.testFiles,
       testGlobsMissing: coverageInputs.testGlobsMissing,
-      // No coverageStats / coverageRoots: this caller reads coverage ROWS and
-      // drops the violations, and both only shape violation messages. Passing
-      // them would look like wiring while changing nothing observable here.
+      // Stats shape the green doctor line (discard counts), not only a failing
+      // sentence. Roots stay out: this caller drops violations.
+      ...(coverageInputs.stats ? { coverageStats: coverageInputs.stats } : {}),
       coverageBudgetExhausted: coverageInputs.coverageBudgetExhausted === true,
     });
     const covById = new Map(
@@ -189,6 +189,9 @@ export function summarizeRulesUnderContract(root, config, facts, classification)
     const uncoveredTruncated = Math.max(0, uncoveredAll.length - UNCOVERED_CATALOG_MAX);
     const uncovered = uncoveredAll.slice(0, UNCOVERED_CATALOG_MAX);
 
+    const symbolEvidence = (coverage.coverage ?? [])
+      .filter((row) => typeof row.symbolEvidenceFile === 'string' && row.symbolEvidenceFile.length > 0)
+      .map((row) => ({ id: row.invariantId, file: row.symbolEvidenceFile }));
     const coveredAll = (coverage.coverage ?? [])
       .filter((row) => row.covered)
       .map((row) => ({
@@ -196,6 +199,9 @@ export function summarizeRulesUnderContract(root, config, facts, classification)
         layer: row.layer ?? null,
         mode: row.mode ?? null,
         description: row.description ?? null,
+        ...(typeof row.symbolEvidenceFile === 'string' && row.symbolEvidenceFile.length > 0
+          ? { symbolEvidenceFile: row.symbolEvidenceFile }
+          : {}),
       }));
     const coveredTruncated = Math.max(0, coveredAll.length - COVERED_SAMPLE_MAX);
     const coveredSample = coveredAll.slice(0, COVERED_SAMPLE_MAX);
@@ -259,6 +265,8 @@ export function summarizeRulesUnderContract(root, config, facts, classification)
       uncoveredTruncated,
       coveredSample,
       coveredTruncated,
+      symbolEvidence,
+      ...(coverageInputs.stats ? { coverageStats: coverageInputs.stats } : {}),
       mergePlanes,
       notAScore: true,
       note: 'ArkRules plane (intra-layer) — counts and catalog, never a score. Green with uncovered residual must say so. Structure sensors are heuristics; invariants are catalog+coverage evidence, not a business runtime.',
@@ -280,6 +288,27 @@ export function summarizeRulesUnderContract(root, config, facts, classification)
   }
 }
 
+/**
+ * Symbol witness paths and discard counts. Printed on green runs too —
+ * a passing check used to hide both. Depth and byte caps stay internal;
+ * only the counts already in the failure sentence are shown.
+ * @param {ReturnType<typeof summarizeRulesUnderContract>|null|undefined} section
+ * @returns {string[]}
+ */
+export function formatArkRulesEvidenceLines(section) {
+  if (!section || typeof section !== 'object') return [];
+  const lines = [];
+  const evidence = Array.isArray(section.symbolEvidence) ? section.symbolEvidence : [];
+  for (const row of evidence) {
+    if (typeof row?.file !== 'string' || row.file.length === 0) continue;
+    const id = typeof row.id === 'string' && row.id.length > 0 ? row.id : 'invariant';
+    lines.push(`ArkRules: ${id} symbol ${row.file}`);
+  }
+  const discard = formatCoverageDiscards(section.coverageStats);
+  if (discard) lines.push(`ArkRules:${discard}`);
+  return lines;
+}
+
 /**
  * Compact / details doctor lines. Empty when the map is off — absence is silent.
  * @param {ReturnType<typeof summarizeRulesUnderContract>|null|undefined} section
@@ -332,6 +361,7 @@ export function formatArkRulesDoctorLines(section) {
   else if (typeof section.note === 'string' && /failed/i.test(section.note)) {
     lines.push(`ArkRules: ${section.note}`);
   }
+  lines.push(...formatArkRulesEvidenceLines(section));
   return lines;
 }
 
@@ -475,6 +505,7 @@ export function formatRulesUnderContractHtml(section, esc) {
         <code>${escape(c.id)}</code>
         <span class="tag">covered</span>
         <span class="dim">· ${escape(c.layer || '?')}</span>
+        ${c.symbolEvidenceFile ? `<span class="dim">· ${escape(c.symbolEvidenceFile)}</span>` : ''}
         ${c.description ? `<div class="msg">${escape(c.description)}</div>` : ''}
       </li>`
     )
@@ -528,6 +559,11 @@ export function formatRulesUnderContractHtml(section, esc) {
     }
     ${uncoveredBlock}
     ${coveredBlock}
+    ${
+      formatArkRulesEvidenceLines(section)
+        .map((line) => `<p class="muted" style="margin-top:.35rem;font-size:.84rem">${escape(line)}</p>`)
+        .join('')
+    }
     ${
       coveredSample.length || uncovered.length
         ? `<p class="muted" style="margin-top:.65rem;font-size:.84rem">Covered = catalog evidence found (symbol and/or test title). Not a claim that business semantics are fully proven end-to-end.</p>`

package/bin/lib/scan-files.mjs

@@ -4,7 +4,9 @@
  */
 import fs from 'node:fs';
 import path from 'node:path';
-import { isScanExcludedRelative } from '../ark-shared.mjs';
+import { isScanExcludedRelative, isSkippedSourceDir } from '../ark-shared.mjs';
+
+export { isSkippedSourceDir };
 
 export const SOURCE_FILE_NAME = /\.[cm]?[tj]sx?$/;
 
@@ -18,31 +20,6 @@ export function isGovernableSourceFile(name) {
   return SOURCE_FILE_NAME.test(name) && !name.endsWith('.d.ts') && !TEST_FILE_NAME.test(name);
 }
 
-export function isSkippedSourceDir(name) {
-  return (
-    name === 'node_modules' ||
-    name === 'dist' ||
-    name === 'coverage' ||
-    name === 'bench' ||
-    name === 'benches' ||
-    name === 'benchmark' ||
-    name === 'benchmarks' ||
-    name === 'docs' ||
-    name === 'documentation' ||
-    name === 'example' ||
-    name === 'examples' ||
-    name === 'fixture' ||
-    name === 'fixtures' ||
-    name === 'playground' ||
-    name === '__tests__' ||
-    name === '__mocks__' ||
-    name === 'e2e' ||
-    // Top-level style Nest/Jest folders (not "testing" helpers inside src)
-    name === 'test' ||
-    name === 'tests'
-  );
-}
-
 function isInsideRoot(root, target) {
   const rel = path.relative(root, target);
   return rel === '' || (!rel.startsWith(`..${path.sep}`) && rel !== '..' && !path.isAbsolute(rel));

package/bin/lib/skill-install.mjs

@@ -486,8 +486,9 @@ export function skillContentMatchesTemplate(installedContent, templateContent) {
  * Repo catalogs belong to that repo's installed package, so an explicit --force
  * may move them in either direction. Codex home is shared by every repo on the
  * machine: a package older than the installed home stamp must never win, even
- * under --force. In both scopes a version-stamp-only difference is a no-op; the
- * skill body is the capability contract.
+ * under --force. In both scopes a version-stamp-only difference is
+ * `stamp-refresh` (write without --force) so the picker shows this package;
+ * the skill body is the capability contract.
  *
  * @param {{
  *   existingContent?: string|null,

package/bin/lib/start-install-recovery.mjs

@@ -0,0 +1,156 @@
+/**
+ * Classified next steps when start / start --apply package install fails.
+ *
+ * Callers render `formatStartPackageInstallFailure`. Classification, Age window,
+ * pin-aware npx, and AgeExclude-must-be-in-config stay behind this module.
+ */
+import { spawnSync } from 'node:child_process';
+import { arkPackageRecoveryCommand } from './package-manager.mjs';
+
+const AGE_MARK = /ERR_PNPM_NO_MATURE_MATCHING_VERSION|minimumReleaseAge/i;
+const AGE_EXCLUDE_LINE =
+  'To add it locally later: put arkgate on minimumReleaseAgeExclude in pnpm config or pnpm-workspace.yaml (a CLI flag is not enough), or wait until the release is old enough.';
+const BIN_NOTE =
+  '`arkgate-check` is a command in the arkgate package — not its own npm package.';
+
+/**
+ * @param {unknown} hostOutput
+ * @returns {string[]}
+ */
+function hostOutputTail(hostOutput) {
+  if (!hostOutput || !String(hostOutput).trim()) return [];
+  return String(hostOutput)
+    .split('\n')
+    .map((line) => line.trimEnd())
+    .filter((line) => line.trim())
+    .slice(-6);
+}
+
+/**
+ * Exact npm version for `npx --package=arkgate@<pin>` when Age blocked add.
+ * @param {string|undefined} packageVersion
+ * @param {string|undefined} installCommand
+ * @returns {string|null}
+ */
+export function resolveStartInstallPackagePin(packageVersion, installCommand) {
+  const fromArg = String(packageVersion ?? '')
+    .trim()
+    .replace(/^arkgate@/i, '')
+    .replace(/^\^/, '')
+    .replace(/^v/i, '');
+  if (/^\d+\.\d+\.\d+/.test(fromArg)) return fromArg.match(/^\d+\.\d+\.\d+/)?.[0] ?? null;
+  const fromCmd = String(installCommand ?? '').match(/arkgate@\^?v?(\d+\.\d+\.\d+)/i);
+  return fromCmd?.[1] ?? null;
+}
+
+/**
+ * @typedef {{ kind: 'pnpm-age', ageWindow: string, headline: string }} PnpmAgeInstallFailure
+ * @typedef {{ kind: 'generic', hostTail: string[] }} GenericInstallFailure
+ * @typedef {PnpmAgeInstallFailure | GenericInstallFailure} ClassifiedStartInstallFailure
+ */
+
+/**
+ * Classify captured package-manager stdout+stderr. Age is one class.
+ * @param {unknown} hostOutput
+ * @returns {ClassifiedStartInstallFailure}
+ */
+export function classifyStartInstallFailure(hostOutput) {
+  const text = String(hostOutput ?? '');
+  if (AGE_MARK.test(text)) {
+    const days = text.match(/(\d+)\s*days?/i)?.[1];
+    const ageWindow = days ? `${days} days` : 'a cooling-off window';
+    const headline = days
+      ? `This repo waits before trusting new npm packages (pnpm Age — ${days} days).`
+      : 'This repo waits before trusting new npm packages (pnpm Age).';
+    return { kind: 'pnpm-age', ageWindow, headline };
+  }
+  return { kind: 'generic', hostTail: hostOutputTail(text) };
+}
+
+/**
+ * Plain Age headline, or null. Kept for the #268 one-liner tests.
+ * @param {unknown} hostOutput
+ * @returns {string|null}
+ */
+export function explainPnpmMaturityBlock(hostOutput) {
+  const classified = classifyStartInstallFailure(hostOutput);
+  return classified.kind === 'pnpm-age' ? classified.headline : null;
+}
+
+/**
+ * @typedef {{
+ *   kind: 'pnpm-age' | 'generic',
+ *   ageWindow?: string,
+ *   primaryCommand: string,
+ *   replayInstallCommand: string | null,
+ *   lines: string[],
+ * }} StartInstallRecovery
+ */
+
+/**
+ * Typed next-step for a failed start package install.
+ * Age never replays the doomed add; generic still names the exact command.
+ * @param {{
+ *   exitStatus: number,
+ *   installCommand: string,
+ *   hostOutput?: string,
+ *   packageVersion?: string,
+ * }} input
+ * @returns {StartInstallRecovery}
+ */
+export function startInstallRecovery(input) {
+  const exitStatus = input?.exitStatus ?? 1;
+  const installCommand = input?.installCommand ?? '';
+  const classified = classifyStartInstallFailure(input?.hostOutput);
+  const pin = resolveStartInstallPackagePin(input?.packageVersion, installCommand);
+  const honesty = `Package install failed (exit ${exitStatus}). Setup files are written; the local command is not installed yet.`;
+  if (classified.kind === 'pnpm-age') {
+    const doctor = arkPackageRecoveryCommand(
+      'arkgate-check',
+      '--doctor',
+      pin ? `arkgate@${pin}` : undefined
+    );
+    return {
+      kind: 'pnpm-age',
+      ageWindow: classified.ageWindow,
+      primaryCommand: doctor,
+      replayInstallCommand: null,
+      lines: [classified.headline, honesty, `  ${doctor}`, BIN_NOTE, AGE_EXCLUDE_LINE],
+    };
+  }
+  const doctor = arkPackageRecoveryCommand('arkgate-check', '--doctor');
+  return {
+    kind: 'generic',
+    primaryCommand: installCommand,
+    replayInstallCommand: installCommand,
+    lines: [...classified.hostTail, honesty, `  ${installCommand}`, `  ${doctor}`, BIN_NOTE],
+  };
+}
+
+/**
+ * Red next-step when post-apply package install fails.
+ * Host files may already be written; local bins may be missing.
+ * @param {{
+ *   exitStatus: number,
+ *   installCommand: string,
+ *   hostOutput?: string,
+ *   packageVersion?: string,
+ * }} input
+ */
+export function formatStartPackageInstallFailure(input) {
+  return startInstallRecovery(input).lines.join('\n');
+}
+
+/** Pipe the package manager so recovery can hide maturity internals. */
+export function runStartPackageInstall(command, commandArgs, cwd) {
+  const result = spawnSync(command, commandArgs, {
+    cwd,
+    stdio: ['ignore', 'pipe', 'pipe'],
+    encoding: 'utf8',
+  });
+  return {
+    status: result.status ?? 1,
+    stdout: result.stdout ?? '',
+    stderr: result.stderr ?? '',
+  };
+}

package/bin/lib/start-preview.mjs

@@ -5,7 +5,6 @@ import os from 'node:os';
 import path from 'node:path';
 import {
   arkCommand,
-  arkPackageRecoveryCommand,
   buildArchitectureRecommendation,
   START_APPLY_REFUSE_FOOTER,
 } from '../ark-shared.mjs';
@@ -40,8 +39,8 @@ const COMPACT_HOST_TEMPLATES = {
     ['.mcp.json', mcpJson(root)],
   ],
   cursor: (root) => [
-    ['.cursor/mcp.json', mcpJson(root)],
     ['.cursor/hooks.json', cursorHooks(root)],
+    ['.cursor/mcp.json', mcpJson(root)],
   ],
   codex: (root) => [
     ['.codex/hooks.json', codexHooks(root)],
@@ -83,6 +82,17 @@ function digest(content) {
   return `sha256:${crypto.createHash('sha256').update(content ?? Buffer.alloc(0)).digest('hex')}`;
 }
 
+function writeGateOrderGuarantee(tools) {
+  const host = typeof tools === 'string' ? tools.trim().toLowerCase() : '';
+  if (host === 'opencode') {
+    return 'Write gate: MCP prepare only (this host has no hard pre-hook). Required CI is the merge line.';
+  }
+  if (['claude', 'grok', 'antigravity', 'cursor', 'codex'].includes(host)) {
+    return 'Write gate: host pre-hook first; MCP prepare is fallback if that hook is missing or fail-open.';
+  }
+  return 'Write gate: host pre-hook first when the host has one; MCP prepare is fallback. Required CI is the merge line.';
+}
+
 function change(pathname, before, after) {
   return {
     path: pathname,
@@ -207,20 +217,6 @@ function commands(root, args, helpers) {
   return result;
 }
 
-/**
- * Red next-step when post-apply package install fails.
- * Host files may already be written; local bins may be missing.
- */
-export function formatStartPackageInstallFailure({ exitStatus, installCommand }) {
-  const doctor = arkPackageRecoveryCommand('arkgate-check', '--doctor');
-  return [
-    `Package install failed (exit ${exitStatus}). Setup files are written; the local command is not installed yet.`,
-    `  ${installCommand}`,
-    `  ${doctor}`,
-    '`arkgate-check` is a command in the arkgate package — not its own npm package.',
-  ].join('\n');
-}
-
 /**
  * @param {object} preview
  * @param {{ applying?: boolean }} [options] when applying=true, do not claim “no files were changed”
@@ -263,6 +259,10 @@ export function renderStartPreview(preview, options = {}) {
   if (preview.runtimeActivation) {
     console.log('Host: Codex is configured but not verified yet. Restart the host, then confirm this project.');
   }
+  const writeGateOrder = (preview.hostGuarantees || []).find((line) =>
+    String(line).startsWith('Write gate:')
+  );
+  if (writeGateOrder) console.log(writeGateOrder);
   if (preview.unresolvedDecisions.length > 0) {
     console.log('Unresolved decisions:');
     for (const decision of preview.unresolvedDecisions) console.log(`  ${decision}`);
@@ -503,6 +503,7 @@ export async function planStart(args, helpers) {
       commands: commands(root, args, helpers),
       hostGuarantees: [
         args.requireWriteHook ? `Hard-write hook verified for ${args.requireWriteHook}` : 'shared CI merge gate will be installed',
+        writeGateOrderGuarantee(args.tools),
         'preview phase performs no writes in the target project',
         'apply writes the exact bytes identified by each afterHash',
         ...(codexSelected

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

@@ -141,8 +141,9 @@ export function detectWritePathCapabilities(root, explicitHost, attempt) {
           ? 'OpenCode local write is advisory (MCP + optional experimental plugin — not a hard boundary; ' +
             'not equivalent to Claude/Grok/Antigravity PreToolUse hard-write). ' +
             'The hard merge backstop is a required GitHub status context running --strict-merge.'
-          : `Active host ${activeHost} has advisory prepare-write/autoPatch tools, ` +
-            'but no hard write boundary; CI can report failure, while merge blocking requires provider policy.';
+          : `Fell back to MCP prepare: active host ${activeHost} has no hard pre-hook. ` +
+            'Advisory prepare-write/autoPatch is the local write surface. ' +
+            'Next: install and trust the host write hook, or keep required CI as the merge line.';
     gap = {
       id: 'write-path-mcp-only',
       severity: 'info',

package/dist/{configTypes-VD0qcubY.d.ts → configTypes-VVknqcTJ.d.ts}

@@ -60,6 +60,8 @@ type ArkConfigRule = {
     sharedRoots?: string[];
     /** Directed slice→slice edges the repo declares on purpose. */
     allowedCrossSlice?: ArkConfigCrossSliceEdge[];
+    /** When `"deny"`, a declared shared root may not import a slice. */
+    sharedImportsSlice?: 'deny';
 };
 type ArkConfigCrossSliceEdge = {
     from: string;