arkgate 4.6.3 → 4.6.5

package/bin/lib/ci-merge-boundary.mjs

@@ -0,0 +1,89 @@
+/**
+ * First-class writePath / CI honesty file (`.ark/ci-merge-boundary.json`).
+ * Agents must read this instead of grepping node_modules dist.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const CI_MERGE_BOUNDARY_REL = '.ark/ci-merge-boundary.json';
+export const CI_MERGE_BOUNDARY_SCHEMA = '1.0';
+
+/**
+ * @param {{
+ *   writePath?: object,
+ *   github?: { requiredStatusConfigured?: boolean, plan?: string, canRequire?: boolean, error?: string },
+ * }} input
+ */
+export function buildCiMergeBoundary(input = {}) {
+  const writePath = input.writePath && typeof input.writePath === 'object' ? input.writePath : {};
+  const inventory = writePath.inventory?.hosts && typeof writePath.inventory.hosts === 'object'
+    ? writePath.inventory.hosts
+    : {};
+  const perHost = {};
+  for (const [host, record] of Object.entries(inventory)) {
+    const caps = record?.capabilities && typeof record.capabilities === 'object' ? record.capabilities : {};
+    const configured = Boolean(record?.configured || caps['hard-write'] || caps['advisory-write']);
+    const fired = Boolean(writePath.enforcementState?.localWrite?.runtimeObserved);
+    const hard = caps['hard-write'] === true;
+    perHost[host] = {
+      configured,
+      fired,
+      state: configured && !fired ? 'configured-not-fired' : fired ? 'observed' : 'absent',
+      writePath: hard ? 'hard' : caps['advisory-write'] ? 'soft' : 'none',
+    };
+  }
+
+  const hookConfigured = Object.values(perHost).some((h) => h.configured);
+  const hookFired = Object.values(perHost).some((h) => h.fired);
+  const github = input.github && typeof input.github === 'object' ? input.github : {};
+  const workflowPresent = Boolean(
+    writePath.capabilities?.['merge-gate'] || writePath.inventory?.capabilities?.['merge-gate']
+  );
+  const required = github.requiredStatusConfigured === true;
+  const canRequire = github.canRequire !== false && github.plan !== 'free';
+  let ciState = 'absent';
+  if (workflowPresent && required) ciState = 'required';
+  else if (workflowPresent && !canRequire) ciState = 'present-but-github-free-cannot-require';
+  else if (workflowPresent) ciState = 'present-but-not-required';
+
+  return {
+    schemaVersion: CI_MERGE_BOUNDARY_SCHEMA,
+    notAScore: true,
+    path: CI_MERGE_BOUNDARY_REL,
+    hook: {
+      configured: hookConfigured,
+      fired: hookFired,
+      state: hookConfigured && !hookFired ? 'configured-not-fired' : hookFired ? 'observed' : 'absent',
+    },
+    writePath: perHost,
+    ci: {
+      workflowPresent,
+      requiredStatusConfigured: required,
+      state: ciState,
+    },
+    githubPlan: {
+      plan: github.plan ?? (canRequire ? 'unknown' : 'free'),
+      canRequire,
+      reason: canRequire ? null : 'github-free-cannot-require',
+    },
+    hookGreenIsNotTreeGreen: true,
+    scriptedEditsBypassPreToolUse: true,
+    note:
+      'Do not reverse-engineer node_modules/arkgate/dist. This file is the honesty surface for writePath and CI.',
+  };
+}
+
+export function writeCiMergeBoundary(root, input = {}) {
+  const payload = buildCiMergeBoundary(input);
+  const dir = path.join(root, '.ark');
+  fs.mkdirSync(dir, { recursive: true });
+  const dest = path.join(dir, 'ci-merge-boundary.json');
+  const next = `${JSON.stringify(payload, null, 2)}\n`;
+  try {
+    if (fs.existsSync(dest) && fs.readFileSync(dest, 'utf8') === next) return payload;
+  } catch {
+    /* rewrite */
+  }
+  fs.writeFileSync(dest, next);
+  return payload;
+}

package/bin/lib/config-contract.mjs

@@ -154,6 +154,8 @@ export const ARK_CONFIG_SCHEMA = {
                 pure: { type: 'boolean' },
                 mayImportInfrastructure: { type: 'boolean' },
                 optional: { type: 'boolean' },
+                reserved: { type: 'boolean' },
+                allowEmpty: { type: 'boolean' },
             },
         },
         rule: {

package/bin/lib/diagnostic-catalog.mjs

@@ -32,7 +32,7 @@ function entry(ruleId, category, title, why, fix, extras) {
  */
 export const DIAGNOSTIC_CATALOG = Object.freeze([
     // ── layer / graph ────────────────────────────────────────────────────────
-    entry('LAYER_IMPORT_VIOLATION', 'layer', 'Layer import not allowed', 'A module import (or re-export) crosses a layer edge that ark.config.json does not allow. The architecture contract forbids that dependency direction so outer infrastructure cannot leak into pure or inner layers.', 'Define a port in the source layer, inject the outer-layer implementation, or move/share the type with `import type` when the edge is type-only — then preflight again. Do not weaken the layer rule without a hash-bound policy acknowledgement.'),
+    entry('LAYER_IMPORT_VIOLATION', 'layer', 'Layer import not allowed', 'A module import (or re-export) crosses a layer edge that ark.config.json does not allow. The architecture contract forbids that dependency direction so outer infrastructure cannot leak into pure or inner layers.', 'Branch by import kind: constants/types/pure → adopt into DomainModel or SharedKernel (do not invent a port); kernel/events/bootstrap from Persistence → inject a port or move the map to SharedTypes (Persistence must not emit); define a port only when the target is a real use-case. Type-only edges use `import type`. Then preflight again. Do not weaken the layer rule without a hash-bound policy acknowledgement.'),
     entry('LAYER_INTENT_REFERENCE_VIOLATION', 'layer', 'Intent referenced across a blocked layer edge', 'A string intent (or intent-like reference) names a layer that the file’s layer may not reach under the contract rules — the same plane as import edges, for event/intent coupling.', 'Reference that intent from a layer allowed to know about it (usually an adapter or application layer), or relocate the reference — then preflight again.'),
     entry('LAYER_REFERENCE_VIOLATION', 'layer', 'Layer reference blocked (snippet / AI gate)', 'Snippet analysis found an intent or string reference that would couple layers in a direction the architecture profile forbids.', 'Move the reference to an allowed layer or introduce a port/event boundary, then re-run the snippet gate.'),
     entry('CIRCULAR_DEPENDENCY', 'layer', 'Dependency cycle', 'Two or more modules import each other in a loop. Cycles make ownership unclear and break stable layer direction.', 'Extract the shared dependency into a third module, invert one edge behind a port, or merge units that are truly one — then preflight again.'),
@@ -55,7 +55,7 @@ export const DIAGNOSTIC_CATALOG = Object.freeze([
     entry('ARKRULE_STRUCTURE', 'arkrules', 'ArkRule structure sensor failed', 'An opt-in ArkRules structure sensor (private state, factory shape, event publish, …) failed on a governed file for a declared arkruleId.', 'Restore the declared structure for the ArkRule (see arkruleSource), then preflight again. Do not demote the rule without a hash-bound policy acknowledgement.'),
     entry('ARKRULE_INVARIANT', 'arkrules', 'ArkRule invariant failed', 'Reserved / remediation-recognized code for invariant-plane failures bound to an ArkRule id (coverage path also emits INVARIANT_UNCOVERED).', 'Fix the invariant for the ArkRule declared in arkrules/<Layer>.json, then preflight again. Do not demote without acknowledgement.'),
     entry('ARKRULE_SCOPE_EMPTY', 'arkrules', 'ArkRule appliesTo matched zero files', 'An ArkRule’s appliesTo globs matched no governed files — the rule cannot observe what it claims to protect.', 'Fix appliesTo globs so they match governed files, or remove the rule. Enforced empty scope fails; advisory empty scope warns.', { oftenAdvisory: true }),
-    entry('INVARIANT_UNCOVERED', 'arkrules', 'Invariant without coverage evidence', 'An ArkRules invariant is under contract but no covering test title or declared symbol evidence was found (or coverage is partial).', 'Add a test title or declared symbol covering the arkruleId, then preflight again. Missing test globs report partial — never fake green.'),
+    entry('INVARIANT_UNCOVERED', 'arkrules', 'Invariant without coverage evidence', 'An ArkRules invariant is under contract but no covering test title or declared symbol evidence was found (or coverage is partial). Kind is never-had-tests (adopt residual) vs tests-disappeared (suite exists).', 'Add a test title or declared symbol covering the arkruleId, then preflight again. Treat never-had-tests as adopt residual; treat tests-disappeared as a regression. Missing test globs report partial — never fake green.'),
     // ── atomic preflight / change set ────────────────────────────────────────
     entry('INVALID_CHANGE_PATH', 'preflight', 'Unsafe change path', 'A change set entry is not a safe, non-empty project-relative path (absolute, escape, empty, or NUL).', 'Use canonical project-relative paths only in the atomic change set, then preflight again.'),
     entry('DUPLICATE_CHANGE_PATH', 'preflight', 'Duplicate path in change set', 'The atomic change set lists more than one operation for the same path.', 'Collapse to one create/update/delete per path, then preflight again.'),
@@ -69,7 +69,8 @@ export const DIAGNOSTIC_CATALOG = Object.freeze([
     entry('ATOMIC_PREFLIGHT_UNAVAILABLE', 'preflight', 'Atomic preflight unavailable', 'The host/MCP path could not run the atomic preflight engine (missing facts, incomplete setup, or unsupported mode).', 'Use resolved-candidate facts / ark_prepare_change with a complete batch, or fall back to ark-check on disk. Do not treat missing preflight as green.'),
     entry('DESIGN_SMELL_REGRESSION', 'preflight', 'Design smell regression on base-relative ratchet', 'Compared to the base ref, the candidate introduces or worsens a blocking design-smell class (e.g. domain-logic-in-ui) under --fail-on-new-smells.', 'Revert the regression or redesign so the smell does not worsen versus base, then re-run with the same base ref.'),
     // ── analysis completeness / host ─────────────────────────────────────────
-    entry('ANALYSIS_PARSE_INCOMPLETE', 'analysis', 'Parse incomplete', 'Governed source could not be fully parsed; analysis is partial and must not paint green.', 'Fix syntax/parse errors in governed files (or restore a usable TypeScript host), then re-run. Partial never means pass.'),
+    entry('ANALYSIS_PARSE_INCOMPLETE', 'analysis', 'Parse incomplete', 'Governed source could not be fully parsed; evidence includes the TypeScript diagnostic (line + message). Incremental mid-edit parse is normal for agents. Contract exclude paths skip the write hook.', 'Finish the source or fix the reported syntax error, then re-run `npx arkgate-check`. The write hook does not deny solely on mid-edit parse. Partial never means pass.'),
+    entry('LEXICAL_EVIDENCE_INCOMPLETE', 'analysis', 'Lexical evidence incomplete', 'Single-file validation cannot prove project module resolution. The write hook is already the verdict.', 'Re-run `npx arkgate-check --root . --config ark.config.json`, or treat the hook deny as final. Do not call ark_prepare_change from a hook deny.'),
     entry('ANALYSIS_HOST_UNAVAILABLE', 'analysis', 'Analysis host unavailable', 'No usable TypeScript / analysis host was available for this invocation.', 'Install a supported TypeScript version visible to the project, then re-run. Unavailable analysis is fail-closed.'),
     entry('ADAPTER_NOT_ALLOWED_FOR_PORT', 'adapter', 'Adapter not allowed for port', 'Runtime/port wiring selected an adapter implementation that the architecture profile does not allow for that port.', 'Bind an allowed adapter for the port, or adjust the profile with an explicit policy decision — then re-run.'),
     // ── AI snippet gate policy surface ───────────────────────────────────────
@@ -88,7 +89,7 @@ export const DIAGNOSTIC_CATALOG = Object.freeze([
     entry('CONFIG_INVALID_FORBIDDEN_GLOBALS', 'config', 'Invalid forbiddenGlobals', 'A layer’s forbiddenGlobals is not an array of strings; the entry is ignored.', 'Use an array of strings (e.g. ["fetch", "Date.now"]).', { oftenAdvisory: true }),
     entry('CONFIG_LAYER_WITHOUT_PATTERNS', 'config', 'Layer without patterns', 'A named layer has no file patterns and will never classify files.', 'Add patterns globs that match the layer’s source tree.', { oftenAdvisory: true }),
     entry('CONFIG_INVALID_LAYER_PATTERN', 'config', 'Invalid layer pattern', 'A layer pattern is not a valid glob / failed to compile.', 'Fix the pattern syntax for that layer.', { oftenAdvisory: true }),
-    entry('CONFIG_LAYER_PATTERN_NO_MATCHES', 'config', 'Layer pattern matched no files', 'A layer pattern matched zero included files (often a typo or include mismatch).', 'Adjust the pattern or include roots so governed files match.', { oftenAdvisory: true }),
+    entry('CONFIG_LAYER_PATTERN_NO_MATCHES', 'config', 'Layer pattern matched no files', 'A layer pattern matched zero included files (often a typo or include mismatch). Reserved/allowEmpty houses do not emit this.', 'Adjust the pattern or include roots, or mark the layer reserved/allowEmpty if the glob is a future house.', { oftenAdvisory: true }),
     entry('CONFIG_DUPLICATE_LAYER', 'config', 'Duplicate layer name', 'The same layer name appears more than once in configuration.', 'Rename or merge duplicate layer entries.', { oftenAdvisory: true }),
     entry('CONFIG_RULE_UNKNOWN_FROM_LAYER', 'config', 'Rule unknown from layer', 'A dependency rule references a source layer name that is not declared.', 'Fix the rule’s from field to a declared layer name.', { oftenAdvisory: true }),
     entry('CONFIG_RULE_UNKNOWN_TO_LAYER', 'config', 'Rule unknown to layer', 'A dependency rule references a target layer name that is not declared.', 'Fix the rule’s to field to a declared layer name.', { oftenAdvisory: true }),

package/bin/lib/doctor-next-actions.mjs

@@ -9,6 +9,16 @@ import { mergePostGreenTopActions } from './post-green-path.mjs';
 
 export function collectDoctorNextActions(ctx) {
   const actions = [];
+  const gatesInstalled = Array.isArray(ctx.gatesMissing) && ctx.gatesMissing.length === 0;
+  const planAEmpty = !ctx.activeCount;
+  const enforceEmptyPlan =
+    ctx.operatingMode === 'enforce' && planAEmpty && gatesInstalled;
+  if (enforceEmptyPlan) {
+    actions.push(
+      ctx.postGreenPath?.action ||
+        '/ark-explore shape-focus → /ark-autopilot (one B pilot)  # ENFORCE + empty plan A → Shape, not reinstall gates'
+    );
+  }
   if (!ctx.analysisComplete) actions.push('restore complete analysis, then rerun ark-check --doctor');
   if (ctx.designSmells.length > 0 && ctx.postGreenPath) actions.push(ctx.postGreenPath.action);
   if (ctx.coverageHonesty.greenIsNotEnforcement && ctx.coverageHonesty.worseThanNoGate) {
@@ -31,8 +41,8 @@ export function collectDoctorNextActions(ctx) {
       `resolve the non-baselined violations — see the classified plan (${arkCommand(ctx.root, 'ark-check', '--plan')}), then /ark-autopilot`
     );
   }
-  if (ctx.writePath?.gap?.fix) actions.push(ctx.writePath.gap.fix);
-  if (ctx.gatesMissing.length > 0) {
+  if (ctx.writePath?.gap?.fix && !gatesInstalled) actions.push(ctx.writePath.gap.fix);
+  if (!gatesInstalled && ctx.gatesMissing.length > 0) {
     actions.push(`install gates (${arkCommand(ctx.root, 'ark-check', '--install-agent-gates')})`);
   }
   const humanSkillGaps = skillGapsForActiveHost(ctx.skillGaps);
@@ -45,10 +55,12 @@ export function collectDoctorNextActions(ctx) {
   if (legacyCodex) {
     actions.push('install Codex SKILL.md catalog (--install-agent-gates --skills-only --tools codex --force)');
   }
-  if (remMiss + remStale > 0) {
-    actions.push('refresh /ark-* skills (--install-agent-gates --skills-only --force)');
+  if (remMiss > 0) {
+    actions.push('install missing /ark-* skills (--install-agent-gates --skills-only --force)');
+  } else if (remStale > 0) {
+    actions.push('refresh stale /ark-* skills (--install-agent-gates --skills-only --force) — gates are installed, catalog is stale');
   }
-  if (ctx.codexHomeGap && ctx.codexConcernActive) {
+  if (ctx.codexHomeGap && ctx.codexConcernActive && ctx.codexHomeGap.preferProject !== true) {
     actions.push(
       ctx.codexHomeGap.catalogMetadataInvalid
         ? 'repair invalid Codex home catalog metadata after verifying the newest installed version'

package/bin/lib/doctor-plan.mjs

@@ -75,6 +75,7 @@ import {
   buildDeepModuleCoachAdvisory,
   printDeepModuleCoachSection,
 } from './deep-module-coach.mjs';
+import { writeCiMergeBoundary } from './ci-merge-boundary.mjs';
 
 const color = {
   green: (s) => `\x1b[32m${s}\x1b[0m`,
@@ -535,6 +536,15 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
   const adoption = collectAdoptionGaps(root, config, cov);
   // Prefer writePath from adoption (same detector); recompute only if missing (tests/stubs).
   const writePath = adoption.writePath ?? detectWritePathCapabilities(root);
+  let ciMergeBoundary = null;
+  try {
+    ciMergeBoundary = writeCiMergeBoundary(root, {
+      writePath,
+      github: adoption.deployPath?.github ?? writePath.enforcementState?.ciMerge ?? {},
+    });
+  } catch {
+    ciMergeBoundary = null;
+  }
   const baseline = readBaseline(root, '.ark-baseline.json');
   const occurrenceKeys = baselineOccurrenceKeys(violations);
   const currentKeys = new Set(occurrenceKeys);
@@ -682,6 +692,8 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
     (options.writeJson ?? console.log)(
       JSON.stringify(
         {
+          schemaVersion: '1.0',
+          envelope: 'doctor',
           ok: analysisComplete && (options.designDelta?.valid ?? true),
           doctor: {
             completeness,
@@ -767,6 +779,7 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
             skillGaps,
             ...(agentHomeGaps.length > 0 ? { agentHomeGaps } : {}),
             staleRunnerFiles: staleRunners,
+            ciMergeBoundary,
             writePath: {
               activeHost: writePath.activeHost,
               support: writePath.support,
@@ -897,6 +910,7 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
     safetyHasEntries,
     showNewHere,
     designFitness,
+    operatingMode,
   });
   console.log('');
   if (isDoctorHealthyNothingToDo(designFitness, uniqueActions)) {

package/bin/lib/enforcement-honesty.mjs

@@ -523,6 +523,8 @@ export function buildProductHonesty(input = {}) {
     primaryMessage,
     primaryNextAction,
     headline,
+    hookGreenIsNotTreeGreen: true,
+    scriptedEditsBypassPreToolUse: true,
   };
 }
 

package/bin/lib/graph-blind.mjs

@@ -16,8 +16,16 @@ import { normalize } from './scan-files.mjs';
 
 const MAX_LIST = 8;
 const MAX_FILE_BYTES = 256 * 1024;
-/** Full AST scan stays off huge trees so doctor resident warm keeps the 500 ms UX ceiling. */
-const MAX_FULL_SCAN_FILES = 2500;
+/** Floor for tiny trees. Large included Next.js trees must still scan. */
+const GRAPH_SCAN_FLOOR = 2500;
+/** Hard cap so a 10k fixture cannot blow the doctor resident warm UX ceiling. */
+const GRAPH_SCAN_HARD_CAP = 8000;
+
+/** Threshold scales with the included tree — never a hard 2500 that defers a 3300-file app. */
+export function graphScanLimit(includedCount) {
+  const count = Number(includedCount) || 0;
+  return Math.min(GRAPH_SCAN_HARD_CAP, Math.max(GRAPH_SCAN_FLOOR, count));
+}
 const LEXICAL_GATE = /\b(?:import|require)\s*\(|\bimport\s+\w+\s*=\s*require\s*\(/;
 
 /**
@@ -123,9 +131,9 @@ export function detectGraphBlindSpots(ts, root, files = []) {
     };
   }
 
-  // Large-tree deferral: re-reading every path for an advisory sensor would blow the
-  // doctorResidentWarm 500 ms absolute UX ceiling at the 10k perf fixture.
-  if (files.length > MAX_FULL_SCAN_FILES) {
+  // Large-tree deferral: only above the proportional cap (included count, floor 2500, cap 8000).
+  const scanLimit = graphScanLimit(files.length);
+  if (files.length > scanLimit) {
     return {
       available: true,
       advisory: true,
@@ -136,7 +144,7 @@ export function detectGraphBlindSpots(ts, root, files = []) {
       otherNonLiteralCount: 0,
       truncated: 0,
       edges: [],
-      note: `Graph-blind full scan deferred (${files.length} files > ${MAX_FULL_SCAN_FILES}). Non-literal dynamic import/require remain unresolvable in architecture analysis; advisory incomplete-graph honesty is not enumerated at this scale.`,
+      note: `Graph-blind full scan deferred (${files.length} files > proportional limit ${scanLimit}). Non-literal dynamic import/require remain unresolvable in architecture analysis; advisory incomplete-graph honesty is not enumerated at this scale.`,
     };
   }
 
@@ -177,6 +185,7 @@ export function detectGraphBlindSpots(ts, root, files = []) {
     available: true,
     advisory: true,
     blockerGrade: false,
+    deferred: false,
     count: edges.length,
     templateInterpolationCount,
     otherNonLiteralCount,

package/bin/lib/install-migrate.mjs

@@ -635,6 +635,16 @@ export function runInstallAgentGates(args) {
       homeResults.push({ relativePath: dir, status: 'failed' });
     }
     if (homeResults.length === 0) {
+      const skillName = (skill) =>
+        Array.isArray(skill) ? skill[0] : skill?.name || skill;
+      const projectHasCatalog = skills.some((skill) =>
+        fs.existsSync(path.join(root, '.agents', 'skills', skillName(skill), 'SKILL.md'))
+      );
+      if (projectHasCatalog) {
+        console.log(
+          '  Project .agents/skills already has this catalog; home write is optional. Prefer the project copy.'
+        );
+      }
       for (const result of installSkillCatalog({
         directory: dir,
         skills,

package/bin/lib/invariant-coverage.mjs

@@ -79,11 +79,14 @@ export function evaluateInvariantCoverage(input) {
         if (!covered || partial) {
             // Enforced + proven uncovered → failsStrict; partial always advisory (never fake green).
             const failsStrict = inv.mode === 'enforced' && !partial;
+            const kind = testGlobsMissing || testFiles.length === 0 ? 'never-had-tests' : 'tests-disappeared';
             violations.push({
                 ruleId: 'INVARIANT_UNCOVERED',
                 message: partial
-                    ? `Invariant ${inv.id} coverage cannot be proven (test globs missing or empty); reporting partial, not covered.`
-                    : `Invariant ${inv.id} is not covered by a test title or declared symbol.`,
+                    ? `Invariant ${inv.id} coverage cannot be proven (test globs missing or empty); reporting partial, not covered (never-had-tests).`
+                    : kind === 'tests-disappeared'
+                        ? `Invariant ${inv.id} is not covered by a test title or declared symbol (tests-disappeared — suite exists).`
+                        : `Invariant ${inv.id} is not covered by a test title or declared symbol (never-had-tests).`,
                 file: inv.provenance.sourceFile,
                 line: 1,
                 arkruleId: inv.id,
@@ -91,6 +94,7 @@ export function evaluateInvariantCoverage(input) {
                 fromLayer: inv.provenance.layer,
                 severity: failsStrict ? 'error' : 'warning',
                 failsStrict,
+                kind,
             });
         }
     }

package/bin/lib/managed-upgrade.mjs

@@ -134,7 +134,7 @@ const HOST_SIGNALS = {
   ],
   codex: ['.codex/hooks.json', '.codex/config.toml', '.agents/skills/ark-upgrade/SKILL.md'],
   grok: ['.grok/config.toml', '.grok/hooks/ark-write-gate.json', '.grok/skills/ark-upgrade/SKILL.md'],
-  antigravity: ['.agents/hooks.json', '.agents/skills/ark-upgrade/SKILL.md'],
+  antigravity: ['.agents/hooks.json'],
   opencode: ['opencode.json', '.opencode/skills/ark-upgrade/SKILL.md'],
   windsurf: ['.windsurf/rules/ark.md', '.windsurf/workflows/ark-upgrade.md'],
   cline: ['.clinerules/ark.md', '.clinerules/workflows/ark-upgrade.md'],
@@ -307,8 +307,13 @@ function resolveSelection(root, options, manifest) {
   const explicit = normalizeToolsList(options.tools);
   const compactHost = compactRouterHost(root);
   let hosts;
-  if (explicit.length > 0) hosts = normalizeHosts(explicit);
-  else if (manifest) hosts = normalizeHosts(manifest.hosts);
+  if (explicit.length > 0) {
+    const kept = manifest
+      ? normalizeHosts(manifest.hosts)
+      : detectedManagedHosts(root);
+    // Preview/apply default is hosts-keep: --tools unions, never retires other hosts.
+    hosts = normalizeHosts([...kept, ...explicit]);
+  } else if (manifest) hosts = normalizeHosts(manifest.hosts);
   else if (compactHost !== null) hosts = compactHost === 'none' ? [] : normalizeHosts([compactHost]);
   else {
     hosts = detectedManagedHosts(root);
@@ -725,7 +730,7 @@ export function buildPostUpgradeChecks(root, options = {}) {
     neverGateInput: true,
     checks,
     mcpNote:
-      'If you used Ark MCP this session: restart/retarget MCP after package bump so process arkgateVersion matches project install; always pass project.expectedRoot + expectedProjectId (WI01). Prefer project-local CLI until identity matched and versions align.',
+      'If you used Ark MCP this session: restart/retarget after the package bump. A stale process is non-authoritative and project tools return PROCESS_PACKAGE_STALE; always pass project.expectedRoot + expectedProjectId. Prefer project-local CLI until identity and package versions align.',
   };
 }
 

package/bin/lib/presets.mjs

@@ -179,6 +179,28 @@ export const PERSISTENCE_PATH_PATTERNS = Object.freeze([
  * Application orchestration under lib without the whole-src-lib vacuum.
  * Never use lone `src/**` or bare `src/lib/**` as Application on Next/event trees.
  */
+/** Types and constants — SharedKernel, not Application vacuum. */
+export const SHARED_KERNEL_PATH_PATTERNS = Object.freeze([
+  'src/shared/**',
+  'src/types/**',
+  'src/**/types.ts',
+  'src/**/constants.ts',
+  'src/**/types/**',
+  'src/**/constants/**',
+  '**/shared/kernel/**',
+  'src/shared/kernel/**',
+]);
+
+/** Wiring / DI / bootstrap — CompositionRoot, not Domain. */
+export const COMPOSITION_ROOT_PATH_PATTERNS = Object.freeze([
+  'src/**/composition/**',
+  'src/**/factories/**',
+  'src/**/container.ts',
+  'src/**/bootstrap.ts',
+  '**/composition/**',
+  '**/factories/**',
+]);
+
 export const APPLICATION_LIB_ORCHESTRATION_PATTERNS = Object.freeze([
   'src/lib/actions/**',
   'src/lib/services/**',

package/bin/lib/remediation.mjs

@@ -41,17 +41,57 @@ export const KNOWN_FIX_CLASSES = [
     'break-cycle',
     'review-contract',
 ];
+const PURE_SHARED_RE = /(^|\/)(constants|types|enums|shared-types|shared\/(?:types|constants)|test-projects)(\/|\.|$)|(?:^|\/)[^/]*(?:constants|types)(?:\.[cm]?[jt]sx?)?$/i;
+const KERNEL_EMIT_RE = /(^|\/)(?:kernel(?:\/|$)|events?(?:\/|\.|$)|bootstrap(?:\.[cm]?[jt]sx?)?$|emitter(?:\.[cm]?[jt]sx?)?$)|(?:^|\/)(?:intents?|publish)(?:\/|\.|$)/i;
+const USE_CASE_RE = /(use-?cases?|usecases?|application|orchestrat|services?|handlers?)(\/|\.|$)/i;
+export function classifyLayerImportKind(target, extra) {
+    const value = String(target ?? '')
+        .replace(/\\/g, '/')
+        .trim();
+    const from = String(extra?.fromLayer ?? '');
+    const to = String(extra?.toLayer ?? '');
+    if (PURE_SHARED_RE.test(value))
+        return 'pure-shared';
+    if (from === 'PersistenceAdapters' &&
+        (KERNEL_EMIT_RE.test(value) || /events?|intents?|kernel|bootstrap/i.test(`${to} ${value}`))) {
+        return 'kernel-emit';
+    }
+    if (USE_CASE_RE.test(value) ||
+        ((from === 'DomainModel' || from === 'ApplicationOrchestration') &&
+            to === 'PersistenceAdapters')) {
+        return 'use-case';
+    }
+    if (!value)
+        return 'unknown';
+    return 'unknown';
+}
+export function layerImportNextAction(violation) {
+    if (violation.typeOnly || violation.targetTypeOnlyExports || violation.namedBindingsTypeOnly) {
+        return 'Move the referenced type to a mutually allowed layer, use `import type`, then preflight again.';
+    }
+    if (violation.peerIsolation) {
+        return 'Extract the shared dependency to a shared layer, test at the public interface, then preflight again.';
+    }
+    const kind = classifyLayerImportKind(typeof violation.target === 'string' ? violation.target : '', {
+        fromLayer: typeof violation.fromLayer === 'string' ? violation.fromLayer : undefined,
+        toLayer: typeof violation.toLayer === 'string' ? violation.toLayer : undefined,
+    });
+    if (kind === 'pure-shared') {
+        return 'Adopt the imported constants/types/pure module into DomainModel or SharedKernel (do not inject a port). Then preflight again.';
+    }
+    if (kind === 'kernel-emit') {
+        return 'Persistence must not emit. Inject a port or move the event map to SharedTypes; do not import kernel/events/bootstrap from a repository. Then preflight again.';
+    }
+    if (kind === 'use-case' || violation.portProofEligible) {
+        return `Define a port in ${violation.fromLayer ?? 'the source layer'}, inject the ${violation.toLayer ?? 'outer-layer'} implementation, test at the public interface, then preflight again.`;
+    }
+    return 'Classify the import: if it is constants/types/pure, adopt into DomainModel or SharedKernel; define a port only if the target is a real use-case. Then preflight again.';
+}
 /** One deterministic re-entry action shared by human and machine denial surfaces. */
 export function deterministicNextAction(violation) {
     switch (violation.ruleId) {
         case 'LAYER_IMPORT_VIOLATION':
-            if (violation.typeOnly || violation.targetTypeOnlyExports || violation.namedBindingsTypeOnly) {
-                return 'Move the referenced type to a mutually allowed layer, use `import type`, then preflight again.';
-            }
-            if (violation.peerIsolation) {
-                return 'Extract the shared dependency to a shared layer, test at the public interface, then preflight again.';
-            }
-            return `Define a port in ${violation.fromLayer ?? 'the source layer'}, inject the ${violation.toLayer ?? 'outer-layer'} implementation, test at the public interface, then preflight again.`;
+            return layerImportNextAction(violation);
         case 'FORBIDDEN_GLOBAL':
             return `Inject ${violation.target ?? 'the capability'} through a port, test at the public interface, then preflight again.`;
         case 'CAPABILITY_VIOLATION':
@@ -222,9 +262,33 @@ export function enrichViolationWithFixClass(violation) {
                     'Cross-slice import blocked (peerIsolation). Do not import another feature/context directly — extract shared code to a shared layer, or coordinate via events/ports. Moving code across slices is a judgment call, not a mechanical auto-fix.';
             }
             else {
-                enriched.fixClass = 'port-inversion';
-                enriched.effort = 'medium';
-                enriched.enthusiastHint = `${violation.fromLayer ?? 'This layer'} must not import ${violation.toLayer ?? 'that layer'} directly. Define an interface (port) where you need the capability and inject the implementation from the outer layer.`;
+                const kind = classifyLayerImportKind(typeof violation.target === 'string' ? violation.target : '', {
+                    fromLayer: typeof violation.fromLayer === 'string' ? violation.fromLayer : undefined,
+                    toLayer: typeof violation.toLayer === 'string' ? violation.toLayer : undefined,
+                });
+                if (kind === 'pure-shared') {
+                    enriched.fixClass = 'file-move';
+                    enriched.effort = 'small';
+                    enriched.enthusiastHint =
+                        'This import is constants/types/pure — adopt it into DomainModel or SharedKernel. Do not inject a port.';
+                }
+                else if (kind === 'kernel-emit') {
+                    enriched.fixClass = 'port-inversion';
+                    enriched.effort = 'medium';
+                    enriched.enthusiastHint =
+                        'A repository must not import kernel/events/bootstrap. Persistence does not emit — inject a port or move the map to SharedTypes.';
+                }
+                else if (kind === 'use-case' || violation.portProofEligible) {
+                    enriched.fixClass = 'port-inversion';
+                    enriched.effort = 'medium';
+                    enriched.enthusiastHint = `${violation.fromLayer ?? 'This layer'} must not import ${violation.toLayer ?? 'that layer'} directly. Define an interface (port) where you need the capability and inject the implementation from the outer layer.`;
+                }
+                else {
+                    enriched.fixClass = 'review-contract';
+                    enriched.effort = 'medium';
+                    enriched.enthusiastHint =
+                        'Do not assume a port. If the target is constants/types/pure, adopt it into Domain or SharedKernel; define a port only for a real use-case.';
+                }
             }
             break;
         case 'FORBIDDEN_GLOBAL':

package/bin/lib/skill-install.mjs

@@ -688,7 +688,9 @@ export function assessCodexSkillParity(root) {
 
   const repoNeedsAttention =
     repoInPlay && (repo.missing > 0 || repo.stale > 0 || repo.legacyPromptsOnly);
+  const repoCatalogComplete = repoInPlay && repo.missing === 0 && !repo.legacyPromptsOnly;
   const homeNeedsAttention =
+    !repoCatalogComplete &&
     newerHomeCatalog === null &&
     homeInPlay &&
     (home.missing > 0 ||

package/bin/lib/snippet-analysis.mjs

@@ -1,6 +1,26 @@
 /** Fail-closed completeness evidence for one proposed source snippet. */
 import { ANALYSIS_COMPLETENESS } from './analysis-completeness.mjs';
 
+export function flattenTsParseDiagnostics(ts, diagnostics, sourceFile) {
+  if (!Array.isArray(diagnostics) || !ts) return [];
+  return diagnostics.map((diagnostic) => {
+    const message = ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n');
+    let line = 1;
+    let column = 1;
+    if (typeof diagnostic.start === 'number' && sourceFile?.getLineAndCharacterOfPosition) {
+      const pos = sourceFile.getLineAndCharacterOfPosition(diagnostic.start);
+      line = (pos.line ?? 0) + 1;
+      column = (pos.character ?? 0) + 1;
+    }
+    return {
+      line,
+      column,
+      message: String(message || '').trim() || 'parse error',
+      code: diagnostic.code,
+    };
+  });
+}
+
 function finding(ruleId, message, file, nextAction) {
   return {
     ruleId,
@@ -54,6 +74,11 @@ export function validateSnippetAnalysis({ gate, ts, source, context = {} }) {
     if (!Array.isArray(parsed.parseDiagnostics)) throw new Error('parse diagnostics unavailable');
     const diagnosticCount = parsed.parseDiagnostics.length;
     if (diagnosticCount > 0) {
+      const tsDiagnostics = flattenTsParseDiagnostics(ts, parsed.parseDiagnostics, parsed);
+      const first = tsDiagnostics[0];
+      const detail = first
+        ? `line ${first.line}: ${first.message}`
+        : `${diagnosticCount} parse diagnostic(s)`;
       return {
         mode: 'lexical-compatibility',
         valid: false,
@@ -62,18 +87,25 @@ export function validateSnippetAnalysis({ gate, ts, source, context = {} }) {
         completenessReasons: [
           {
             code: 'ANALYSIS_PARSE_INCOMPLETE',
-            message: `The proposed source has ${diagnosticCount} parse diagnostic(s).`,
+            message: `The proposed source has ${diagnosticCount} parse diagnostic(s). ${detail}`,
             ...(file ? { file } : {}),
+            line: first?.line,
+            tsDiagnostics,
           },
         ],
         violations: [
           ...base.violations,
-          finding(
-            'ANALYSIS_PARSE_INCOMPLETE',
-            `Analysis partial: proposed source has ${diagnosticCount} parse diagnostic(s).`,
-            file,
-            'Fix the syntax until the TypeScript parser reports zero diagnostics, then validate again.'
-          ),
+          {
+            ...finding(
+              'ANALYSIS_PARSE_INCOMPLETE',
+              `Analysis partial: ${detail}`,
+              file,
+              'Incremental mid-edit parse errors are normal. Finish the source, then re-run `npx arkgate-check` (or the write hook). Do not call ark_prepare_change from a hook deny.'
+            ),
+            line: first?.line ?? 1,
+            column: first?.column ?? 1,
+            evidence: { tsDiagnostics, diagnosticCount },
+          },
         ],
       };
     }
@@ -87,7 +119,7 @@ export function validateSnippetAnalysis({ gate, ts, source, context = {} }) {
         {
           code: 'LEXICAL_EVIDENCE_INCOMPLETE',
           message:
-            'Single-file validation cannot prove project module resolution or complete candidate evidence; use ark_prepare_change for a parity-capable verdict.',
+            'Single-file validation cannot prove project module resolution. The write hook is already the verdict, or re-run `npx arkgate-check --root . --config ark.config.json`. Do not call ark_prepare_change from a hook deny.',
           ...(file ? { file } : {}),
         },
       ],