arkgate 4.8.23 → 4.8.25

package/bin/lib/sensor-promote-io.mjs

@@ -16,6 +16,7 @@ import {
   invariantIdsFromCatalog,
   loadInvariantCoverageInputs,
 } from './invariant-coverage-io.mjs';
+import { attachProbeEvidence } from './invariant-probe-io.mjs';
 
 /**
  * The root as the filesystem sees it. Comparing a realpath against a lexical
@@ -79,28 +80,11 @@ export function loadSensorMap(root, config, facts) {
   }));
 
   const catalogued = loaded.arkRules.invariants ?? [];
-  let coverageRows = [];
-  let partial = false;
-  if (catalogued.length > 0) {
-    const inputs = loadInvariantCoverageInputs(root, facts ?? { files: [] }, {
-      invariantIds: invariantIdsFromCatalog(loaded.arkRules),
-      ...coverageOptionsFromConfig(config),
-    });
-    const coverage = evaluateInvariantCoverage({
-      arkRules: loaded.arkRules,
-      fileContents: inputs.fileContents,
-      testFiles: inputs.testFiles,
-      testGlobsMissing: inputs.testGlobsMissing,
-      coverageBudgetExhausted: inputs.coverageBudgetExhausted === true,
-      ...(inputs.stats ? { coverageStats: inputs.stats } : {}),
-      // The declared roots decide `outsideDeclaredRoots`, which is one of the
-      // four reasons canPromoteInvariant refuses. Dropping them here would make
-      // this surface promise a promotion the gate then denies.
-      ...(inputs.coverageRoots ? { coverageRoots: inputs.coverageRoots } : {}),
-    });
-    coverageRows = coverage.coverage ?? [];
-    partial = coverage.partial === true;
-  }
+  const evaluated = evaluateCatalogCoverage(root, config, facts, loaded.arkRules);
+  // ADR 0039: a committed probe artifact can only subtract promotability.
+  // Read-only here — this path never runs a test.
+  const coverageRows = attachProbeEvidence(root, evaluated.rows, catalogued).rows;
+  const partial = evaluated.partial;
   const evidenceById = new Map(coverageRows.map((row) => [row.invariantId, row]));
 
   const invariants = catalogued.map((entry) => ({
@@ -120,6 +104,33 @@ export function loadSensorMap(root, config, facts) {
   };
 }
 
+/**
+ * Invariant coverage rows for a loaded catalog, evaluated the way the
+ * promotion judge needs them (declared `coverageRoots` included). `inputs` is
+ * the loaded file set, reused by the probe to pick covering tests.
+ */
+export function evaluateCatalogCoverage(root, config, facts, arkRules) {
+  const catalogued = arkRules?.invariants ?? [];
+  if (catalogued.length === 0) return { rows: [], partial: false, inputs: null };
+  const inputs = loadInvariantCoverageInputs(root, facts ?? { files: [] }, {
+    invariantIds: invariantIdsFromCatalog(arkRules),
+    ...coverageOptionsFromConfig(config),
+  });
+  const coverage = evaluateInvariantCoverage({
+    arkRules,
+    fileContents: inputs.fileContents,
+    testFiles: inputs.testFiles,
+    testGlobsMissing: inputs.testGlobsMissing,
+    coverageBudgetExhausted: inputs.coverageBudgetExhausted === true,
+    ...(inputs.stats ? { coverageStats: inputs.stats } : {}),
+    // The declared roots decide `outsideDeclaredRoots`, which is one of the
+    // four reasons canPromoteInvariant refuses. Dropping them here would make
+    // this surface promise a promotion the gate then denies.
+    ...(inputs.coverageRoots ? { coverageRoots: inputs.coverageRoots } : {}),
+  });
+  return { rows: coverage.coverage ?? [], partial: coverage.partial === true, inputs };
+}
+
 /**
  * Count the findings each declared rule produced in an analysis that already
  * ran. One run answers for every rule: the loop this replaces was one full

package/bin/lib/sensor-promotion.mjs

@@ -188,7 +188,7 @@ export function buildSensorMap(input) {
             sourceFile,
             description: nullable(rule.description),
             promotable: verdict.ok,
-            blocker: verdict.ok ? null : 'no-coverage-evidence',
+            blocker: verdict.ok ? null : verdict.blocker ?? 'no-coverage-evidence',
             reason: `${locate(rule.id, sourceFile)}: ${verdict.reason}`,
             coverageEvaluated: rule.coverage != null,
             ...ambiguity(rule.id),

package/bin/lib/skill-catalog-apply.mjs

@@ -19,7 +19,7 @@ function skillName(skill) {
   return Array.isArray(skill) ? skill[0] : skill?.name || skill;
 }
 
-export function projectCatalogReady(root, skillNames) {
+function projectCatalogReady(root, skillNames) {
   return skillNames.some((name) => fs.existsSync(path.join(root, canonicalSkillPath(name))));
 }
 

package/bin/lib/skill-install.mjs

@@ -7,7 +7,6 @@ import os from 'node:os';
 import path from 'node:path';
 import { arkCommand } from '../ark-shared.mjs';
 import {
-  parseSkillDescriptionVersion,
   stampSkillDescription,
   stripSkillDescriptionVersion,
 } from './agent-skills-package.mjs';
@@ -227,14 +226,14 @@ export function canonicalSkillPath(name) {
  * Hosts that natively load `.agents/skills` — do not also copy bytes there under
  * a second name. Cursor/Codex list every path they scan; two copies = two picker rows.
  */
-export const SKILL_NATIVE_AGENTS_HOSTS = Object.freeze(['codex', 'cursor', 'antigravity']);
+const SKILL_NATIVE_AGENTS_HOSTS = Object.freeze(['codex', 'cursor', 'antigravity']);
 
 /**
  * Hosts that do not scan `.agents/skills`. Adapter is a relative symlink to the
  * canonical catalog so Grok/Claude/OpenCode see the same bytes.
  * Cursor also scans `.claude/skills` — doctor warns; still one body + visible version.
  */
-export const SKILL_ADAPTER_LINKS = Object.freeze({
+const SKILL_ADAPTER_LINKS = Object.freeze({
   claude: (name) => ({
     link: `.claude/skills/${name}`,
     target: `../../${SKILL_CANONICAL_DIR}/${name}`,
@@ -299,10 +298,10 @@ export function arkPackageVersion() {
 }
 
 /**
- * Rewrite a YAML `description:` line with a visible `arkgate@<version>. ` prefix.
- * Preserves quoting. Hosts show this string in the skill picker (unlike arkVersion).
+ * Rewrite the value of a YAML `description:` line, preserving its quoting.
+ * `transform` returns the new value, or null to keep the line untouched.
  */
-function stampDescriptionYamlLine(line, version) {
+function rewriteDescriptionYamlLine(line, transform) {
   const match = String(line).match(/^(description:\s*)(.*)$/);
   if (!match) return line;
   let raw = match[2] ?? '';
@@ -311,26 +310,26 @@ function stampDescriptionYamlLine(line, version) {
     (raw.startsWith("'") && raw.endsWith("'") && raw.length >= 2);
   const quote = quoted ? raw[0] : '';
   const value = quoted ? raw.slice(1, -1) : raw;
-  const stamped = stampSkillDescription(value, version);
-  if (!quoted) return `${match[1]}${stamped}`;
-  const escaped = stamped.replaceAll('\\', '\\\\').replaceAll(quote, `\\${quote}`);
+  const next = transform(value);
+  if (next === null) return line;
+  if (!quoted) return `${match[1]}${next}`;
+  const escaped = next.replaceAll('\\', '\\\\').replaceAll(quote, `\\${quote}`);
   return `${match[1]}${quote}${escaped}${quote}`;
 }
 
+/**
+ * Rewrite a YAML `description:` line with a visible `arkgate@<version>. ` prefix.
+ * Preserves quoting. Hosts show this string in the skill picker (unlike arkVersion).
+ */
+function stampDescriptionYamlLine(line, version) {
+  return rewriteDescriptionYamlLine(line, (value) => stampSkillDescription(value, version));
+}
+
 function managedDescriptionYamlLine(line) {
-  const match = String(line).match(/^(description:\s*)(.*)$/);
-  if (!match) return line;
-  let raw = match[2] ?? '';
-  const quoted =
-    (raw.startsWith('"') && raw.endsWith('"') && raw.length >= 2) ||
-    (raw.startsWith("'") && raw.endsWith("'") && raw.length >= 2);
-  const quote = quoted ? raw[0] : '';
-  const value = quoted ? raw.slice(1, -1) : raw;
-  const stripped = stripSkillDescriptionVersion(value);
-  if (stripped === value) return line;
-  if (!quoted) return `${match[1]}${stripped}`;
-  const escaped = stripped.replaceAll('\\', '\\\\').replaceAll(quote, `\\${quote}`);
-  return `${match[1]}${quote}${escaped}${quote}`;
+  return rewriteDescriptionYamlLine(line, (value) => {
+    const stripped = stripSkillDescriptionVersion(value);
+    return stripped === value ? null : stripped;
+  });
 }
 
 // Insert `arkVersion: <v>` and a visible `arkgate@<v>. ` description prefix.
@@ -593,7 +592,7 @@ export function skillTemplates() {
  * Relative symlink so clones keep working. Fallback copy when the OS refuses links.
  * @returns {'linked'|'copied'|'current'|'skipped-customized'|'missing-canonical'}
  */
-export function ensureSkillAdapterLink(root, name, adapter, force = false) {
+function ensureSkillAdapterLink(root, name, adapter, force = false) {
   const canonicalDir = path.join(root, SKILL_CANONICAL_DIR, name);
   const canonicalFile = path.join(canonicalDir, 'SKILL.md');
   if (!fs.existsSync(canonicalFile)) return 'missing-canonical';
@@ -693,8 +692,6 @@ export function pruneHomeArkSkillDuplicates(root, skillNames = skillTemplateName
   return { ok: true, reason: 'pruned', removed };
 }
 
-export { parseSkillDescriptionVersion, stripSkillDescriptionVersion };
-
 // Skill names only, silent on a missing templates dir — for the freshness
 // advisory below, which must not print packaging warnings on every check run.
 export function skillTemplateNames() {
@@ -821,20 +818,15 @@ function readCodexHomeCatalogMetadata(file, kind) {
   }
 }
 
-function codexHomeCatalogState(skillsDir) {
-  const catalog = readCodexHomeCatalogMetadata(
-    path.join(skillsDir, CODEX_HOME_CATALOG),
-    'catalog'
-  );
-  const pending = readCodexHomeCatalogMetadata(
-    path.join(skillsDir, CODEX_HOME_PENDING_CATALOG),
-    'pending'
-  );
+/**
+ * Merge a home skill catalog and its pending catalog metadata: the floor is the
+ * newer of the two versions; either file present means metadata is in play.
+ * @param {{ exists: boolean, valid: boolean, version: string|null }} catalog
+ * @param {{ exists: boolean, valid: boolean, version: string|null }} pending
+ */
+export function homeCatalogFloorState(catalog, pending) {
   let floorVersion = catalog.version;
-  if (
-    pending.version &&
-    (!floorVersion || isVersionOlder(floorVersion, pending.version))
-  ) {
+  if (pending.version && (!floorVersion || isVersionOlder(floorVersion, pending.version))) {
     floorVersion = pending.version;
   }
   return {
@@ -846,6 +838,18 @@ function codexHomeCatalogState(skillsDir) {
   };
 }
 
+function codexHomeCatalogState(skillsDir) {
+  const catalog = readCodexHomeCatalogMetadata(
+    path.join(skillsDir, CODEX_HOME_CATALOG),
+    'catalog'
+  );
+  const pending = readCodexHomeCatalogMetadata(
+    path.join(skillsDir, CODEX_HOME_PENDING_CATALOG),
+    'pending'
+  );
+  return homeCatalogFloorState(catalog, pending);
+}
+
 function newerCodexHomeCatalogVersion(skillsDir, packageVersion, state = null) {
   if (!isValidSemver(packageVersion)) return null;
   const floorVersion = (state ?? codexHomeCatalogState(skillsDir)).floorVersion;

package/bin/lib/snippet-analysis.mjs

@@ -2,16 +2,31 @@
 import { layerForRelativePath } from '../ark-layer-match.mjs';
 import { ANALYSIS_COMPLETENESS } from './analysis-completeness.mjs';
 import { evaluateArkRunEditorSensorsFromSource } from './ark-run-sensors.mjs';
+import { evaluateArkOrderEditorSensors } from './ark-order-sensors.mjs';
+import {
+  buildArkRuleFileHints,
+  evaluateArkRuleSensors,
+  extractClassShapesFromSource,
+} from './arkrules-sensors.mjs';
 import { getDiagnosticCatalogEntry } from './diagnostic-catalog.mjs';
+import { demoteExtraPlaneTeethUnderClassificationFloor } from './extra-merge-teeth.mjs';
 
-function lexicalEvidenceIncompleteMessage(file) {
+/** Hook-only guidance: a hook deny is already the verdict for that write. */
+const HOOK_DENY_PREPARE_CHANGE_NOTE = 'Do not call ark_prepare_change from a hook deny.';
+
+function surfaceNote(context) {
+  return context?.surface === 'hook' ? ` ${HOOK_DENY_PREPARE_CHANGE_NOTE}` : '';
+}
+
+function lexicalEvidenceIncompleteMessage(file, context) {
   const entry = getDiagnosticCatalogEntry('LEXICAL_EVIDENCE_INCOMPLETE');
   const text = [entry?.why, entry?.fix].filter(Boolean).join(' ');
   return {
     code: 'LEXICAL_EVIDENCE_INCOMPLETE',
     message:
-      text ||
-      'This check only saw one file, so it cannot fully prove how the import resolves. The result is provisional — `ark-check` on the project is the authority. Run `npx arkgate-check --root . --config ark.config.json` to confirm. Do not call ark_prepare_change from a hook deny.',
+      (text ||
+        'This check only saw one file, so it cannot fully prove how the import resolves. The result is provisional — `ark-check` on the project is the authority. For a complete verdict, run `npx arkgate-check --root . --config ark.config.json` (or ark_prepare_change over MCP with the full candidate batch).') +
+      surfaceNote(context),
     ...(file ? { file } : {}),
   };
 }
@@ -81,14 +96,132 @@ function arkRunSnippetViolations(source, context = {}) {
     }));
 }
 
+const TS_CLASS_SHAPE_FILE = /\.(tsx?|mts|cts)$/i;
+
+/**
+ * File-local ArkRules structure sensors on the proposed source — the same sensors,
+ * class-shape extraction, and per-file hints ark-check runs, pinned to this one file.
+ * Only enforced (failsStrict) findings block; advisory rules stay CI/doctor warnings.
+ */
+function arkRulesSnippetViolations(source, context = {}) {
+  const arkRules = context.arkRules;
+  const file = context.relFile;
+  if (!arkRules || !(arkRules.structure?.length > 0) || typeof file !== 'string' || !file) {
+    return [];
+  }
+  const layers = Array.isArray(context.layers) ? context.layers : [];
+  const layerForFile = (pathValue) =>
+    pathValue === file && typeof context.layer === 'string'
+      ? context.layer
+      : layerForRelativePath(pathValue, layers);
+  let classShapes = [];
+  if (TS_CLASS_SHAPE_FILE.test(file)) {
+    try {
+      classShapes = extractClassShapesFromSource(file, source);
+    } catch {
+      // Same as the CI resolver: shape extraction never fails the run.
+      classShapes = [];
+    }
+  }
+  const findings = evaluateArkRuleSensors({
+    arkRules,
+    classShapes,
+    files: [file],
+    layerForFile,
+    fileHints: buildArkRuleFileHints({ [file]: source }),
+  });
+  // Same classification floor ark-check applies before merge (teeth only on a classified tree).
+  return demoteExtraPlaneTeethUnderClassificationFloor(findings, context.classification ?? {})
+    .filter((finding) => finding.failsStrict)
+    .map((finding) => ({
+      ...finding,
+      nextAction:
+        getDiagnosticCatalogEntry('ARKRULE_STRUCTURE')?.fix ??
+        'Fix the ArkRules structure finding in this file, then retry the write.',
+      failsStrict: true,
+      severity: 'error',
+    }));
+}
+
+/** ArkOrder editor sensors (generic update, kernel-in-domain, ξ writes) on one source. */
+function arkOrderSnippetViolations(source, context = {}) {
+  const arkOrder = context.arkOrder;
+  const file = context.relFile;
+  if (!arkOrder || typeof file !== 'string' || !file) return [];
+  const layers = Array.isArray(context.layers) ? context.layers : [];
+  const fromLayer =
+    typeof context.layer === 'string' ? context.layer : layerForRelativePath(file, layers);
+  const layerMeta = layers.find((layer) => layer?.name === fromLayer);
+  return evaluateArkOrderEditorSensors({
+    arkOrder,
+    file,
+    source,
+    fromLayer,
+    intentPrefixes: layerMeta?.intentPrefixes ?? [],
+    ...(context.classification ? { classification: context.classification } : {}),
+  })
+    .filter((finding) => finding.failsStrict)
+    .map((finding) => ({
+      ruleId: finding.ruleId,
+      code: finding.ruleId,
+      message: finding.message,
+      file: finding.file,
+      line: finding.line,
+      ...(finding.fromLayer ? { fromLayer: finding.fromLayer } : {}),
+      ...(finding.target ? { target: finding.target } : {}),
+      nextAction: finding.nextAction,
+      failsStrict: true,
+      severity: 'error',
+    }));
+}
+
+/**
+ * The write gate could not load part of its own contract (e.g. a referenced ArkRules
+ * file is missing). CI fails closed on the same input, so the write path does too.
+ */
+function contractLoadViolations(context = {}) {
+  const errors = Array.isArray(context.contractErrors) ? context.contractErrors : [];
+  return errors.map((error) => ({
+    ruleId: 'WRITE_GATE_UNAVAILABLE',
+    code: 'WRITE_GATE_UNAVAILABLE',
+    message: `Invalid Effective Contract: ${
+      typeof error === 'string' ? error : `${error?.path ?? ''}: ${error?.message ?? ''}`.trim()
+    }`,
+    ...(context.relFile ? { file: context.relFile } : {}),
+    nextAction:
+      getDiagnosticCatalogEntry('WRITE_GATE_UNAVAILABLE')?.fix ??
+      'Fix the ArkRules reference in ark.config.json, then retry the write.',
+    failsStrict: true,
+    severity: 'error',
+  }));
+}
+
+/**
+ * Extras (ArkRules structure + ArkOrder) run only on files CI would scan. A file
+ * outside include / excluded is never judged by these planes in CI either.
+ */
+function extraPlaneSnippetViolations(source, context = {}) {
+  if (context.inScope === false) return [];
+  return [
+    ...contractLoadViolations(context),
+    ...arkRulesSnippetViolations(source, context),
+    ...arkOrderSnippetViolations(source, context),
+  ];
+}
+
 export function validateSnippetAnalysis({ gate, ts, source, context = {} }) {
   const observed = gate.validate(source, context);
   const arkRunViolations = arkRunSnippetViolations(source, context);
+  const extraViolations = extraPlaneSnippetViolations(source, context);
   const base = {
-    valid: Boolean(observed.lexicalValid ?? observed.valid) && arkRunViolations.length === 0,
+    valid:
+      Boolean(observed.lexicalValid ?? observed.valid) &&
+      arkRunViolations.length === 0 &&
+      extraViolations.length === 0,
     violations: [
       ...(Array.isArray(observed.violations) ? observed.violations : []),
       ...arkRunViolations,
+      ...extraViolations,
     ],
   };
   const file = context.filePath;
@@ -154,7 +287,8 @@ export function validateSnippetAnalysis({ gate, ts, source, context = {} }) {
               '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.'
+              'Incremental mid-edit parse errors are normal. Finish the source, then re-run `npx arkgate-check` (or the write hook).' +
+                surfaceNote(context)
             ),
             line: first?.line ?? 1,
             column: first?.column ?? 1,
@@ -169,7 +303,7 @@ export function validateSnippetAnalysis({ gate, ts, source, context = {} }) {
       valid: false,
       lexicalValid: base.valid,
       completeness: ANALYSIS_COMPLETENESS.partial,
-      completenessReasons: [lexicalEvidenceIncompleteMessage(file)],
+      completenessReasons: [lexicalEvidenceIncompleteMessage(file, context)],
     };
   } catch {
     return {

package/bin/lib/source-policy.mjs

@@ -25,6 +25,40 @@ export const DEFAULT_INTENT_PREFIXES = Object.freeze([
     { layer: 'SecurityAuditObservability', prefixes: ['Security.', 'Audit.', 'Observability.'] },
     { layer: 'Kernel', prefixes: ['Kernel.'] },
 ]);
+/**
+ * Runtime intent prefixes for one config layer: its declared `intentPrefixes`,
+ * else the built-in prefixes when the layer uses a canonical 11-layer name
+ * (`DomainModel` → `Domain.`, …; the same table the static gate falls back to),
+ * else none. Keeps `ark init` configs, which name canonical layers without
+ * declaring prefixes, resolvable by the ArkRun kernel.
+ */
+export function effectiveIntentPrefixes(layer) {
+    const declared = (layer.intentPrefixes ?? []).filter((prefix) => prefix.trim().length > 0);
+    if (declared.length > 0)
+        return declared;
+    return DEFAULT_INTENT_PREFIXES.find((entry) => entry.layer === layer.name)?.prefixes ?? [];
+}
+/**
+ * Layers named by an `allowed: false` (non-peerIsolation) rule that no intent can map to at runtime
+ * (no declared `intentPrefixes` and not a canonical layer name). Hard observed
+ * layer flow can never fire for such a rule. Sorted, unique.
+ */
+export function unresolvableLayerFlowLayers(config) {
+    const resolvable = new Set(config.layers
+        .filter((layer) => effectiveIntentPrefixes(layer).length > 0)
+        .map((layer) => layer.name));
+    const missing = new Set();
+    for (const rule of config.rules ?? []) {
+        // peerIsolation walls are file-path slice rules; runtime flow never evaluates them.
+        if (rule.allowed !== false || rule.peerIsolation === true)
+            continue;
+        for (const name of [rule.from, rule.to]) {
+            if (!resolvable.has(name))
+                missing.add(name);
+        }
+    }
+    return [...missing].sort();
+}
 /** Longest matching prefix wins; declaration order resolves an identical-prefix tie. */
 export function resolveIntentLayer(intent, layers) {
     const candidates = layers.flatMap((layer, layerIndex) => (layer.prefixes ?? layer.intentPrefixes ?? []).map((prefix) => ({

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

@@ -5,7 +5,10 @@
  * 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';
+import fs from 'node:fs';
+import path from 'node:path';
+import { pinArkgateDevDependency } from './field-install.mjs';
+import { arkPackageRecoveryCommand, packageInstallArgv } from './package-manager.mjs';
 
 const AGE_MARK = /ERR_PNPM_NO_MATURE_MATCHING_VERSION|minimumReleaseAge/i;
 const AGE_EXCLUDE_LINE =
@@ -32,7 +35,7 @@ function hostOutputTail(hostOutput) {
  * @param {string|undefined} installCommand
  * @returns {string|null}
  */
-export function resolveStartInstallPackagePin(packageVersion, installCommand) {
+function resolveStartInstallPackagePin(packageVersion, installCommand) {
   const fromArg = String(packageVersion ?? '')
     .trim()
     .replace(/^arkgate@/i, '')
@@ -154,3 +157,70 @@ export function runStartPackageInstall(command, commandArgs, cwd) {
     stderr: result.stderr ?? '',
   };
 }
+
+// Setup-time arkgate pin shared by `ark start` and `ark init` (kept out of bin/ark.mjs).
+/**
+ * Pin arkgate in package.json (and optionally run the package manager).
+ * start calls this so CI/`npx` is not forced to rely on a stale global install.
+ *
+ * @param {string} root
+ * @param {{ install?: boolean, runPackageManager?: boolean }} [opts]
+ */
+export function ensureProjectArkgateDependency(root, opts = {}) {
+  const install = opts.install !== false;
+  const runPm = opts.runPackageManager === true;
+  if (!install) {
+    return { pinned: { changed: false, reason: 'skipped-no-install' }, installStatus: null };
+  }
+  const pinned = pinArkgateDevDependency(root);
+  let installStatus = null;
+  let hostOutput = '';
+  // Only run the package manager after a successful pin change — avoid surprise
+  // network on every start when arkgate is already listed.
+  if (runPm && pinned.changed) {
+    const [command, commandArgs] = packageInstallArgv(root, pinned.version);
+    const install = runStartPackageInstall(command, commandArgs, root);
+    installStatus = install.status;
+    hostOutput = `${install.stdout}\n${install.stderr}`;
+  }
+  return { pinned, installStatus, hostOutput };
+}
+
+/**
+ * Setup-time pin shared by `ark start` and `ark init`. With the pin, generated CI and host
+ * hooks call the local `ark-check` / `arkgate-mcp` bins through the project runner. Without
+ * it they run `npx -y -p arkgate@<this exact version> <bin>`, because a bare `npx ark-check`
+ * asks npm for a package named `ark-check` (404) or runs a stale global.
+ */
+export function pinArkgateForSetup(root, args, cliVersion) {
+  if (!args.install) {
+    console.log('  Skipping arkgate package pin (--no-install).');
+    return;
+  }
+  if (!fs.existsSync(path.join(root, 'package.json'))) {
+    console.log(
+      `  Warning: no package.json — the generated CI workflow and host hooks run npx -y -p arkgate@${cliVersion()} (downloaded on each run). To run a local install instead, create package.json, add arkgate@^${cliVersion()} to devDependencies, then re-run setup.`
+    );
+    return;
+  }
+  const { pinned, installStatus, hostOutput } = ensureProjectArkgateDependency(root, {
+    install: true,
+    runPackageManager: !args.skipPackageManager,
+  });
+  if (pinned.changed) {
+    console.log(`  Pinned arkgate@${pinned.version} in package.json devDependencies.`);
+    if (installStatus !== null && installStatus !== 0) {
+      const [command, commandArgs] = packageInstallArgv(root, pinned.version);
+      console.error(
+        formatStartPackageInstallFailure({
+          exitStatus: installStatus,
+          installCommand: `${command} ${commandArgs.join(' ')}`,
+          hostOutput,
+          packageVersion: cliVersion(),
+        })
+      );
+    }
+  } else if (pinned.reason === 'already-present') {
+    console.log(`  arkgate already in package.json (${pinned.version}).`);
+  }
+}

package/bin/lib/start-preview.mjs

@@ -20,6 +20,9 @@ import {
   grokHooks,
   grokProjectConfig,
   opencodeProjectConfig,
+  removeAntigravityArkHook,
+  removeClaudeStyleArkHooks,
+  removeCursorArkHook,
 } from './hook-templates.mjs';
 import { codexPrimaryTable, codexProjectMcpIsValid } from './codex-home.mjs';
 import { codexRuntimeActivation } from './enforcement-state.mjs';
@@ -56,6 +59,17 @@ const COMPACT_HOST_TEMPLATES = {
   gemini: (root) => [['GEMINI.md', instructionRule(root)]],
 };
 
+/**
+ * Host hook files the installer merges into (keeping user keys). Removal drops only the
+ * Ark-owned entries, with the same identity as the merge helper.
+ */
+const MERGED_HOOK_FILE_REMOVERS = {
+  '.claude/settings.json': removeClaudeStyleArkHooks,
+  '.codex/hooks.json': removeClaudeStyleArkHooks,
+  '.cursor/hooks.json': removeCursorArkHook,
+  '.agents/hooks.json': removeAntigravityArkHook,
+};
+
 function treeFiles(root) {
   const files = new Map();
   const visit = (dir) => {
@@ -133,7 +147,7 @@ export function setupBudget(changes) {
 }
 
 /** One next write when compact start is the wrong size. `--force` does not unlock. */
-export const START_SETUP_BUDGET_NEXT = 'arkgate-check --init';
+const START_SETUP_BUDGET_NEXT = 'arkgate-check --init';
 
 function formatSetupKb(bytes) {
   return `${Math.max(1, Math.round(Number(bytes) / 1024))} KB`;
@@ -334,6 +348,22 @@ function planHostRemoval(args, helpers) {
       changes.push(change(relativePath, before, after));
       continue;
     }
+    const remover = MERGED_HOOK_FILE_REMOVERS[relativePath];
+    if (remover && before.toString('utf8') !== expected) {
+      const removal = remover(before.toString('utf8'), expected);
+      if (removal.status === 'removed') {
+        changes.push(
+          change(relativePath, before, removal.text == null ? null : Buffer.from(removal.text))
+        );
+      } else if (removal.status === 'customized') {
+        unresolvedDecisions.push(
+          `${relativePath}: the Ark hook entry was customized and was left untouched.`
+        );
+      } else if (removal.status === 'unreadable') {
+        unresolvedDecisions.push(`${relativePath} is not readable JSON and was left untouched.`);
+      }
+      continue;
+    }
     if (before.toString('utf8') !== expected) {
       unresolvedDecisions.push(`${relativePath} was customized and was left untouched.`);
       continue;

package/bin/lib/states-transitions-presence.mjs

@@ -9,7 +9,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 
 /** Product-domain / domain-model homes. Closed list — no tree walk. */
-export const STATES_TRANSITIONS_DOMAIN_HOMES = Object.freeze([
+const STATES_TRANSITIONS_DOMAIN_HOMES = Object.freeze([
   'docs/domain.md',
   'docs/data-model.md',
   'docs/product-domain.md',
@@ -19,7 +19,7 @@ export const STATES_TRANSITIONS_DOMAIN_HOMES = Object.freeze([
 ]);
 
 /** Evolved dedicated homes. Adopt if present; do not force a filename. */
-export const STATES_TRANSITIONS_DEDICATED_HOMES = Object.freeze([
+const STATES_TRANSITIONS_DEDICATED_HOMES = Object.freeze([
   'docs/states.md',
   'docs/transitions.md',
   'docs/states-transitions.md',
@@ -32,7 +32,7 @@ export const STATES_TRANSITIONS_ASK_MISSING =
 export const STATES_TRANSITIONS_ASK_INCOMPLETE =
   'The states heading is there, but it is not a map yet — no table or link.';
 
-export const STATES_TRANSITIONS_NEXT =
+const STATES_TRANSITIONS_NEXT =
   'Add a short table (entity · states · allowed from → to) — or one link — on the domain doc. Names from the code. No flag soup.';
 
 function readMarkdown(abs) {