arkgate 4.8.13 → 4.8.15

package/bin/lib/doctor-advisories.mjs

@@ -18,10 +18,19 @@ import {
 } from './reshape-decisions.mjs';
 import { printParseHealthSection, summarizeParseHealth } from './parse-health.mjs';
 import { detectGraphBlindSpots, printGraphBlindSection } from './graph-blind.mjs';
-import { summarizeRulesUnderContract } from './rules-under-contract.mjs';
+import {
+  formatArkRulesDoctorLines,
+  summarizeRulesUnderContract,
+} from './rules-under-contract.mjs';
 import { collectStewardNudge } from './team-parliament-io.mjs';
-import { formatArkRunDoctorLines, summarizeArkRunSection } from './ark-run-doctor.mjs';
 import {
+  ARKRUN_FIRST_CONTACT_NEXT,
+  ARKRUN_ONE_BREATH,
+  formatArkRunDoctorLines,
+  summarizeArkRunSection,
+} from './ark-run-doctor.mjs';
+import {
+  ARKORDER_FIRST_CONTACT_NEXT,
   ARKORDER_ONE_BREATH,
   formatArkOrderDoctorLines,
   summarizeArkOrderSection,
@@ -79,22 +88,77 @@ export function attachExtraDoctorSections(rulesUnderContract, config, classifica
   return { arkRun, arkOrder, mergePlanes };
 }
 
+function arkRulesDoctorMark(section, warn) {
+  if (Array.isArray(section?.loadErrors) && section.loadErrors.length > 0) return warn;
+  if (section?.emptyInvariantCatalog === true) return warn;
+  if ((Number(section?.uncoveredInvariants) || 0) > 0) return warn;
+  return ' ';
+}
+
 export function printCompactExtraDoctorLines(advisories, io) {
+  const owners = advisories?.layerOwners;
+  if (owners?.required && owners.ask) {
+    console.log('');
+    io.line(io.warn, owners.ask);
+    if (owners.nextAction) io.line(' ', `Next: ${owners.nextAction}`);
+  }
+  const adr = advisories?.adrPresence;
+  if (adr?.missing && adr.ask) {
+    console.log('');
+    io.line(io.warn, adr.ask);
+    if (adr.nextAction) io.line(' ', `Next: ${adr.nextAction}`);
+  }
+  const catalog = advisories?.statusTransitionCatalog;
+  if (catalog?.ask) {
+    console.log('');
+    io.line(io.warn, catalog.ask);
+    if (catalog.nextAction) io.line(' ', `Next: ${catalog.nextAction}`);
+  } else {
+    const states = advisories?.statesTransitions;
+    if (states?.ask) {
+      console.log('');
+      io.line(io.warn, states.ask);
+      if (states.nextAction) io.line(' ', `Next: ${states.nextAction}`);
+    }
+  }
+  const noDomain = advisories?.noDomainFrontend;
+  if (noDomain?.ask) {
+    console.log('');
+    io.line(io.warn, noDomain.ask);
+    if (noDomain.nextAction) io.line(' ', `Next: ${noDomain.nextAction}`);
+  }
+  const rulesUnderContract = advisories?.rulesUnderContract;
+  const arkRulesLines = formatArkRulesDoctorLines(rulesUnderContract);
+  if (arkRulesLines.length > 0) {
+    console.log('');
+    const mark = arkRulesDoctorMark(rulesUnderContract, io.warn);
+    for (const text of arkRulesLines) io.line(mark, text);
+  }
   const arkRun = advisories?.arkRun;
   if (arkRun?.active === true && arkRun.notAScore === true) {
     console.log('');
     const residual = Number(arkRun.residual?.count) || 0;
-    io.line(residual > 0 ? io.warn : ' ', `ArkRun: ${arkRun.mode || 'on'} · residual=${residual} · not a score`);
+    const mark = residual > 0 ? io.warn : ' ';
+    io.line(mark, ARKRUN_ONE_BREATH);
+    io.line(mark, `ArkRun: ${arkRun.mode || 'on'} · residual=${residual} · not a score`);
+    if (residual > 0) io.line(mark, ARKRUN_FIRST_CONTACT_NEXT);
   }
   const arkOrder = advisories?.arkOrder;
-  if (arkOrder?.active === true && arkOrder.notAScore === true) {
+  if (arkOrder && arkOrder.notAScore === true) {
     console.log('');
-    const residual = Number(arkOrder.residual?.count) || 0;
-    const keys =
-      Array.isArray(arkOrder.xiKeys) && arkOrder.xiKeys.length > 0 ? arkOrder.xiKeys.join(', ') : 'unnamed';
-    const mark = residual > 0 ? io.warn : ' ';
-    io.line(mark, ARKORDER_ONE_BREATH);
-    io.line(mark, `ArkOrder: ${arkOrder.mode || 'on'} · xiKeys=${keys} · residual=${residual} · not a score`);
+    if (arkOrder.active === true) {
+      const residual = Number(arkOrder.residual?.count) || 0;
+      const keys =
+        Array.isArray(arkOrder.xiKeys) && arkOrder.xiKeys.length > 0
+          ? arkOrder.xiKeys.join(', ')
+          : 'unnamed';
+      const mark = residual > 0 ? io.warn : ' ';
+      io.line(mark, ARKORDER_ONE_BREATH);
+      io.line(mark, `ArkOrder: ${arkOrder.mode || 'on'} · xiKeys=${keys} · residual=${residual} · not a score`);
+    } else {
+      io.line(' ', ARKORDER_ONE_BREATH);
+      io.line(' ', ARKORDER_FIRST_CONTACT_NEXT);
+    }
   }
 }
 
@@ -119,16 +183,36 @@ export function computeDoctorAdvisories(root, config, cov, rules, files, ts, par
     root,
     decisionMemory
   );
-  // Prefer architecture facts paths when available; coverage I/O still walks test roots.
+  // Prefer architecture facts paths when available; still union the doctor walk
+  // so an empty-catalog residual can see Domain files the facts subset missed.
+  const normalizeDoctorFile = (entry) => {
+    const raw =
+      typeof entry === 'string'
+        ? entry
+        : typeof entry?.path === 'string'
+          ? entry.path
+          : '';
+    const path = raw.replace(/\\/g, '/').replace(/^\.\//, '');
+    return path ? { path } : null;
+  };
+  const walkFiles = Array.isArray(files) ? files.map(normalizeDoctorFile).filter(Boolean) : [];
+  const factFiles = Array.isArray(facts?.files)
+    ? facts.files.map(normalizeDoctorFile).filter(Boolean)
+    : [];
+  const seen = new Set();
+  const mergedFiles = [];
+  for (const entry of [...factFiles, ...walkFiles]) {
+    if (seen.has(entry.path)) continue;
+    seen.add(entry.path);
+    mergedFiles.push(entry);
+  }
   const factPaths =
-    facts ??
-    (Array.isArray(files)
+    facts || walkFiles.length > 0
       ? {
-          files: files.map((f) => ({
-            path: typeof f === 'string' ? f.replace(/\\/g, '/').replace(/^\.\//, '') : f?.path,
-          })).filter((f) => f.path),
+          ...(facts && typeof facts === 'object' ? facts : {}),
+          files: mergedFiles,
         }
-      : undefined);
+      : undefined;
   const classification = classificationFromCoverage(cov);
   const rulesUnderContract = summarizeRulesUnderContract(root, config, factPaths, classification);
   const { arkRun, arkOrder } = attachExtraDoctorSections(
@@ -171,6 +255,14 @@ export function printDoctorAdvisories(advisories, io) {
     io.line(io.warn, nudge.ask);
     if (nudge.nextAction) io.line(' ', io.color.dim(`Next: ${nudge.nextAction}`));
   }
+  const rulesUnderContract = advisories.rulesUnderContract;
+  const arkRulesLines = formatArkRulesDoctorLines(rulesUnderContract);
+  if (arkRulesLines.length > 0) {
+    console.log('');
+    console.log(io.color.bold('ArkRules (not a score)'));
+    const mark = arkRulesDoctorMark(rulesUnderContract, io.warn);
+    for (const text of arkRulesLines) io.line(mark, text);
+  }
   const arkRun = advisories.arkRun;
   if (arkRun && arkRun.notAScore === true) {
     console.log('');

package/bin/lib/doctor-human.mjs

@@ -4,7 +4,7 @@
  */
 import path from 'node:path';
 import { arkCommand } from '../ark-shared.mjs';
-import { operatingModeTitle } from './product-copy.mjs';
+import { NORTH_STAR_ONE_LINE, operatingModeTitle } from './product-copy.mjs';
 import { isDoctorHealthyNothingToDo } from './post-green-path.mjs';
 import { printParseHealthSection } from './parse-health.mjs';
 import { printDoctorAdvisories, printCompactExtraDoctorLines } from './doctor-advisories.mjs';
@@ -14,6 +14,7 @@ import { analysisIncompleteStatement } from './analysis-completeness.mjs';
 import { skillGapsForActiveHost, detectCodexHomeGap, codexConcernIsActive } from './agent-gates.mjs';
 import { agentHomeConcernIsActive } from './agent-homes.mjs';
 import { REQUIRED_GATE_WORKFLOW } from './gate-files.mjs';
+import { layerGuidanceLine } from './layer-description.mjs';
 
 function displayedMissingGates(gatesMissing, view) {
   const list = Array.isArray(gatesMissing) ? gatesMissing : [];
@@ -73,6 +74,7 @@ export function printDoctorCompactHuman(view) {
   const skippableCi = ciNotFailClosedNotice(view);
 
   console.log(color.bold(`Ark doctor — ${path.basename(path.resolve(root)) || '.'}`));
+  console.log(color.dim(NORTH_STAR_ONE_LINE));
   if (!analysisComplete) line(warn, analysisIncompleteStatement(completeness));
   printParseHealthSection(doctorAdvisories.parseHealth, { color, warn, line });
 
@@ -138,13 +140,15 @@ export function printDoctorCompactHuman(view) {
         : warn;
   line(govMark, `Governed: ${cov.governed.percent}% (${cov.governed.classifiedFiles}/${cov.governed.totalFiles} files)`);
   for (const row of cov.layers ?? []) {
-    if (row.description) line(' ', `${row.name} — ${row.description}`);
+    const guidance = layerGuidanceLine(row);
+    if (guidance) line(' ', `${row.name} — ${guidance}`);
   }
 
   const hostRed =
     listedMissing.length > 0 ||
     Boolean(writePath.gap) ||
     writePathHonesty?.softWriteHost === true ||
+    writePathHonesty?.nativeFailClosed === false ||
     Boolean(skippableCi);
   if (hostRed) {
     console.log('');
@@ -152,7 +156,9 @@ export function printDoctorCompactHuman(view) {
     if (writePath.activeHost) line(' ', `Active host: ${writePath.activeHost}`);
     if (listedMissing.length > 0) line(bad, `Missing gates: ${listedMissing.join(', ')}`);
     if (skippableCi) line(warn, skippableCi);
-    else if (listedMissing.length === 0 && (writePath.gap || writePathHonesty?.softWriteHost)) {
+    else if (writePathHonesty?.nativeFailClosed === false) {
+      line(warn, writePathHonesty.message || 'Write hook is fail-open — if the checker cannot run, the write still lands.');
+    } else if (listedMissing.length === 0 && (writePath.gap || writePathHonesty?.softWriteHost)) {
       line(warn, 'Local writes are advisory; required CI is the merge boundary.');
     }
   }
@@ -164,7 +170,15 @@ export function printDoctorCompactHuman(view) {
     line(warn, nudge.ask);
   }
 
-  printCompactExtraDoctorLines(doctorAdvisories, { line, warn });
+  printCompactExtraDoctorLines(
+    {
+      ...doctorAdvisories,
+      layerOwners: view.layerOwners,
+      adrPresence: view.adrPresence,
+      statesTransitions: view.statesTransitions, statusTransitionCatalog: view.statusTransitionCatalog, noDomainFrontend: view.noDomainFrontend,
+    },
+    { line, warn }
+  );
 
   if (violations.length === 0) {
     if (!analysisComplete) {
@@ -248,11 +262,11 @@ export function printDoctorDetailsHuman(view) {
     );
   }
   if (cov.suggestions.length === 0 && cov.emptyLayers.length === 0) line(ok, 'Every layer classifies files; no empty layers');
-  const captioned = (cov.layers ?? []).filter((row) => row.description);
+  const captioned = (cov.layers ?? []).filter((row) => layerGuidanceLine(row));
   if (captioned.length > 0) {
     console.log('');
     console.log(color.bold('Layers'));
-    for (const row of captioned) line(' ', `${row.name} — ${row.description}`);
+    for (const row of captioned) line(' ', `${row.name} — ${layerGuidanceLine(row)}`);
   }
 
   if (packageVersionTruth?.dualTruth) {

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

@@ -34,6 +34,9 @@ export function collectDoctorNextActions(ctx) {
   ) {
     actions.push(nudge.nextAction);
   }
+  if (ctx.layerOwners?.required && ctx.layerOwners.nextAction) {
+    actions.push(ctx.layerOwners.nextAction);
+  }
   const enforceEmptyPlan =
     ctx.operatingMode === 'enforce' && planAEmpty && gatesInstalled && !notAdopted;
   if (enforceEmptyPlan) {
@@ -42,6 +45,17 @@ export function collectDoctorNextActions(ctx) {
         '/ark-explore, then one small refactor with /ark-autopilot and your OK'
     );
   }
+  if (ctx.adrPresence?.missing && ctx.adrPresence.nextAction) {
+    actions.push(ctx.adrPresence.nextAction);
+  }
+  if (ctx.statusTransitionCatalog?.nextAction) {
+    actions.push(ctx.statusTransitionCatalog.nextAction);
+  } else if (ctx.statesTransitions?.nextAction) {
+    actions.push(ctx.statesTransitions.nextAction);
+  }
+  if (ctx.noDomainFrontend?.nextAction) {
+    actions.push(ctx.noDomainFrontend.nextAction);
+  }
   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) {

package/bin/lib/doctor-plan.mjs

@@ -15,7 +15,12 @@ import { describePackageVersionDualTruth } from './field-install.mjs';
 import { detectAgentHomeGaps } from './agent-homes.mjs';
 import { collectDoctorNextActions } from './doctor-next-actions.mjs';
 import { printDoctorCompactHuman, printDoctorDetailsHuman } from './doctor-human.mjs';
-import { placementDescriptionFields } from './layer-description.mjs';
+import { collectLayerOwnerResidual, layerGuidanceLine, placementDescriptionFields } from './layer-description.mjs';
+import { collectAdrPresenceResidual, printAdrPresenceHint } from './adr-presence.mjs';
+import { collectStatesTransitionsResidual } from './states-transitions-presence.mjs';
+import { collectStatusTransitionCatalogResidual } from './status-transition-catalog.mjs';
+import { collectNoDomainFrontendResidual } from './no-domain-frontend.mjs';
+export { printAdrPresenceHint };
 export { printDoctorCompactHuman, printDoctorDetailsHuman };
 export { summarizeRulesUnderContract };
 
@@ -173,7 +178,8 @@ export function runCoverage(root, config, files, rules, asJson) {
   console.log(`  ${pad('Layer')}  Files`);
   for (const row of layerRows) {
     const flag = row.files === 0 ? '   (pattern matches nothing)' : '';
-    const caption = row.description ? `  ${row.description}` : '';
+    const guidance = layerGuidanceLine(row);
+    const caption = guidance ? `  ${guidance}` : '';
     console.log(`  ${pad(row.name)}  ${String(row.files).padStart(5)}${flag}${caption}`);
   }
   console.log(`  ${pad('(unclassified)')}  ${String(unclassified.length).padStart(5)}`);
@@ -616,6 +622,7 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
     options.facts ?? options.architectureFacts,
     activeViolations
   );
+  const layerOwners = collectLayerOwnerResidual(config);
   const rulesUnderContract = doctorAdvisories.rulesUnderContract;
   const arkRun = doctorAdvisories.arkRun;
   // Single residual expression (nextPilot || extractionCard) — HTML report uses the same.
@@ -636,6 +643,13 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
     github: githubForBoundary,
     ci: ciMergeBoundary?.ci,
   });
+  const adrPresence = collectAdrPresenceResidual({
+    root,
+    demanded: options.requireGates === true || adopted === 'required-merge',
+  });
+  const statesTransitions = collectStatesTransitionsResidual({ root });
+  const statusTransitionCatalog = collectStatusTransitionCatalogResidual({ root, config, files, statesTransitions });
+  const noDomainFrontend = collectNoDomainFrontendResidual({ config, coverage: cov, designSmells });
   const { coverageHonesty, baselineHonesty, writePathHonesty, productHonesty } =
     computeDoctorEnforcementHonesty({
       governedPercent: cov.governed.percent,
@@ -671,6 +685,8 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
       selfHost:
         packageVersionTruth?.selfHost === true ||
         packageVersionTruth?.code === 'PACKAGE_PIN_SELF_HOST',
+      nativeFailClosed: writePath.nativeFailClosed,
+      nativeFailClosedPolicy: writePath.nativeFailClosedPolicy,
       adopted,
       ciMergeBoundary,
       github: githubForBoundary,
@@ -763,6 +779,10 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
             governed: cov.governed,
             coverageHonesty,
             layers: cov.layers,
+            ...(layerOwners ? { layerOwners } : {}),
+            ...(adrPresence ? { adrPresence } : {}),
+            ...(statesTransitions ? { statesTransitions } : {}),
+            ...(statusTransitionCatalog ? { statusTransitionCatalog } : {}), ...(noDomainFrontend ? { noDomainFrontend } : {}),
             emptyLayers: cov.emptyLayers,
             layersWithoutRules: cov.layersWithoutRules,
             ungovernedDirs: cov.suggestions.length,
@@ -827,6 +847,8 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
               mcpPresent: writePath.mcpPresent,
               evidence: writePath.evidence,
               honesty: writePathHonesty,
+              nativeFailClosed: writePath.nativeFailClosed ?? null,
+              nativeFailClosedPolicy: writePath.nativeFailClosedPolicy ?? 'unsupported',
               ...(writePath.sessionNote ? { sessionNote: writePath.sessionNote } : {}),
               ...(writePath.gap
                 ? {
@@ -902,12 +924,20 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
     operatingMode,
     adopted,
     stewardNudge: doctorAdvisories.stewardNudge,
+    layerOwners,
+    adrPresence,
+    statesTransitions,
+    statusTransitionCatalog, noDomainFrontend,
   });
   const humanView = {
     root,
     analysisComplete,
     completeness,
     doctorAdvisories,
+    layerOwners,
+    adrPresence,
+    statesTransitions,
+    statusTransitionCatalog, noDomainFrontend,
     operatingMode,
     designFitness,
     adopted,

package/bin/lib/enforcement-honesty.mjs

@@ -180,6 +180,8 @@ export function buildBaselineHonesty(input = {}) {
  *   packagePinAbsent?: boolean,
  *   selfHost?: boolean,
  *   motherCli?: boolean,
+ *   nativeFailClosed?: boolean | null,
+ *   nativeFailClosedPolicy?: 'required' | 'unsupported' | 'none',
  * }} [extras]
  */
 export function buildWritePathHonesty(activeHost, hardWriteActive = false, extras = {}) {
@@ -202,7 +204,21 @@ export function buildWritePathHonesty(activeHost, hardWriteActive = false, extra
   const hardAllowed = packageInstalled && !pinAbsentForUser;
   const effectiveHard =
     Boolean(hardWriteActive) && hardCapable && !softWriteHost && hardAllowed;
-  const message = doctorWritePathHonestyMessage(host, effectiveHard);
+  const nativeFailClosedPolicy =
+    extras.nativeFailClosedPolicy === 'required' ||
+    extras.nativeFailClosedPolicy === 'none' ||
+    extras.nativeFailClosedPolicy === 'unsupported'
+      ? extras.nativeFailClosedPolicy
+      : HOST_SUPPORT_MATRIX[host]?.nativeFailClosed ?? (hardCapable ? 'unsupported' : 'none');
+  const nativeFailClosed =
+    extras.nativeFailClosed === true ? true : extras.nativeFailClosed === false ? false : null;
+  const failOpen = nativeFailClosedPolicy === 'required' && nativeFailClosed === false;
+  const honestyMessage = doctorWritePathHonestyMessage(host, effectiveHard);
+  const failOpenMessage =
+    `${HOST_SUPPORT_MATRIX[host]?.label ?? 'This host'}: the write hook is fail-open. ` +
+    'If the checker cannot run, the write still lands. Set failClosed: true on the write hook — ' +
+    'same idea as a file permission: no checker, no write. Required CI is the shared merge line.';
+  const message = failOpen ? failOpenMessage : honestyMessage;
 
   /** @type {Record<string, unknown>} */
   const out = {
@@ -212,6 +228,8 @@ export function buildWritePathHonesty(activeHost, hardWriteActive = false, extra
     hardWriteSupported: hardCapable,
     hardWriteActive: effectiveHard,
     hardWriteUnverified: hardCapable && !effectiveHard,
+    nativeFailClosed,
+    nativeFailClosedPolicy,
     hardMergeBoundary:
       'required-github-status-context (CLI: arkgate-check --strict-merge / ark-check --strict-merge)',
     packageInstalled,
@@ -385,6 +403,16 @@ export function buildProductHonesty(input = {}) {
     });
   }
 
+  if (write?.nativeFailClosed === false && write?.nativeFailClosedPolicy === 'required') {
+    reasons.push({
+      id: 'native-fail-open',
+      bucket: 'environment',
+      message:
+        write.message ||
+        'The write hook is fail-open. If the checker cannot run, the write still lands. Set failClosed: true on the write hook.',
+    });
+  }
+
   const adopted =
     typeof input.adopted === 'string'
       ? input.adopted
@@ -442,7 +470,7 @@ export function buildProductHonesty(input = {}) {
   }
 
   // EH05: environment residual deny-list (future reason ids stay architecture debt by default).
-  const ENVIRONMENT_REASON_IDS = new Set(['soft-write-host']);
+  const ENVIRONMENT_REASON_IDS = new Set(['soft-write-host', 'native-fail-open']);
 
   const environmentResiduals = reasons.filter((r) => ENVIRONMENT_REASON_IDS.has(r.id));
   const architectureReasons = reasons.filter((r) => !ENVIRONMENT_REASON_IDS.has(r.id));
@@ -457,6 +485,8 @@ export function buildProductHonesty(input = {}) {
 
   const softWriteOnly =
     !unfinished && environmentResiduals.some((r) => r.id === 'soft-write-host');
+  const failOpenOnly =
+    !unfinished && environmentResiduals.some((r) => r.id === 'native-fail-open');
   const hostLabel = (() => {
     const h = typeof write?.activeHost === 'string' ? write.activeHost.trim().toLowerCase() : '';
     if (h === 'codex') return 'Codex';
@@ -493,6 +523,10 @@ export function buildProductHonesty(input = {}) {
       'This tree acked advisory-only in .ark/adoption-stance.json. That is not a required GitHub merge status.';
   } else if (softWriteOnly) {
     primaryMessage = `${hostLabel} local writes stay advisory/bypassable; architecture contract on this slice is ready. Hard merge boundary is a required GitHub status context running arkgate-check --strict-merge (alias ark-check --strict-merge).`;
+  } else if (failOpenOnly) {
+    primaryMessage =
+      write?.message ||
+      `${hostLabel} write hook is fail-open — if the checker cannot run, the write still lands. Set failClosed: true. Required CI is the shared merge line.`;
   } else if (wholeTreeGoverned) {
     primaryMessage =
       'No residual honesty blockers on this slice — still not a numeric architecture score; re-doctor after material change.';
@@ -509,6 +543,10 @@ export function buildProductHonesty(input = {}) {
     headline = wholeTreeGoverned
       ? `Architecture contract ready; ${hostLabel} local writes are advisory`
       : `Contract residual clear; ${hostLabel} local writes are advisory`;
+  } else if (!unfinished && failOpenOnly) {
+    headline = wholeTreeGoverned
+      ? `Architecture contract ready; ${hostLabel} write hook is fail-open`
+      : `Contract residual clear; ${hostLabel} write hook is fail-open`;
   } else if (!unfinished && adopted === 'advisory-only-acked') {
     headline = 'Advisory-only adoption — merge status is not required';
   } else if (!unfinished) {
@@ -536,6 +574,9 @@ export function buildProductHonesty(input = {}) {
     primaryNextAction =
       input.stewardNudge?.nextAction ||
       '/ark-adopt (ask, then update stewards[] — do not invent names)';
+  } else if (!primaryNextAction && failOpenOnly) {
+    primaryNextAction =
+      'Set failClosed: true on the write hook, then re-run doctor. Required CI is the shared merge line.';
   } else if (!primaryNextAction && softWriteOnly) {
     primaryNextAction =
       'Confirm the GitHub required status context name runs arkgate-check --strict-merge (or ark-check --strict-merge). Soft-write hosts stay advisory at local write; the required status is the hard merge boundary.';
@@ -613,6 +654,8 @@ export function computeDoctorEnforcementHonesty({
   adoptionStance,
   emptyStewards,
   stewardNudge,
+  nativeFailClosed,
+  nativeFailClosedPolicy,
 } = {}) {
   const coverageHonesty = buildCoverageHonesty({
     percent: governedPercent,
@@ -632,6 +675,8 @@ export function computeDoctorEnforcementHonesty({
     packagePinAbsent: packageVersionTruth?.code === 'PACKAGE_PIN_ABSENT',
     selfHost,
     motherCli,
+    nativeFailClosed,
+    nativeFailClosedPolicy,
   });
   // Prefer explicit blocking count; fall back to activeViolations only when callers
   // already pass blocking-only totals (legacy tests). Type-only must not invent debt.

package/bin/lib/first-run-help.mjs

@@ -2,12 +2,16 @@
  * First-run CLI help (setup + check). Encyclopedia text stays behind --help --all.
  */
 
+import { NORTH_STAR_ONE_LINE } from './product-copy.mjs';
+
 export function setupUsage() {
   return `arkgate (alias ark) — Write. Check. Ship.
 When the agent writes a bad import, the write doesn’t land. Same check fails the PR.
+${NORTH_STAR_ONE_LINE}
 
   arkgate start              preview (no writes)
   arkgate start --apply      write host + CI setup
+                             (refuses weak coverage/shape; lock with --archetype/--preset/--force)
   arkgate-check --doctor     status — one next step
 
 Stuck? Run status (--doctor). Do #1.
@@ -30,6 +34,7 @@ Every flag: arkgate --help --all
 export function setupUsageAll() {
   return `arkgate (alias ark) — Write. Check. Ship.
 When the agent writes a bad import, the write doesn’t land. Same check fails the PR.
+${NORTH_STAR_ONE_LINE}
 
 Usage:
   arkgate start   [--root <project>] [--tools <host>] [--require-write-hook <host>] [--install] [--apply] [--json]
@@ -158,9 +163,13 @@ export async function withSensorsPartialModeHonesty(args, run) {
 
 export function checkUsage() {
   return [
-    'arkgate-check (alias ark-check) — the architecture check.',
+    'arkgate-check (alias ark-check) — Write. Check. Ship.',
+    'When the agent writes a bad import, the write doesn’t land. Same check fails the PR.',
+    NORTH_STAR_ONE_LINE,
     '',
     '  arkgate-check --doctor         where you are: one status light, one next action',
+    '  arkgate-check --local --base <ref>      optional local / multi-worktree cheap check',
+    '  arkgate-check --changed --base <ref>   local / pre-push: checks touched files only',
     '  arkgate-check --strict-merge   CI / merge gate (required GitHub status)',
     '  arkgate-check --sensors        which sensors can ever be enforced (does not run analysis)',
     '',
@@ -170,11 +179,13 @@ export function checkUsage() {
 
 export function checkUsageAll() {
   return [
-    'arkgate-check (alias ark-check) — the architecture check.',
+    'arkgate-check (alias ark-check) — Write. Check. Ship.',
+    'When the agent writes a bad import, the write doesn’t land. Same check fails the PR.',
+    NORTH_STAR_ONE_LINE,
     '',
     'Usage: arkgate-check | ark-check  (identical bins; product name ArkGate)',
     '       arkgate-check --version',
-    '       arkgate-check --root <project> --config <ark.config.json> [--manifest <ark.manifest.json>] [--tsconfig <tsconfig.json>] [--strict-merge | --strict | --strict-config] [--policy-base <file> | --policy-base-ref <git-ref>] [--policy-ack <file>] [--fail-on-new-smells --base-ref <git-ref>] [--contract-diff] [--contract-session] [--changed] [--against <git-ref>] [--base <git-ref>] [--persona touch|contributor|agent|steward] [--author <id>] [--require-gates] [--require-write-hook <host>] [--json] [--baseline [file]] [--report [file.html]] [--no-cache]',
+    '       arkgate-check --root <project> --config <ark.config.json> [--manifest <ark.manifest.json>] [--tsconfig <tsconfig.json>] [--strict-merge | --strict | --strict-config] [--policy-base <file> | --policy-base-ref <git-ref>] [--policy-ack <file>] [--fail-on-new-smells --base-ref <git-ref>] [--contract-diff] [--contract-session] [--local] [--changed] [--against <git-ref>] [--base <git-ref>] [--persona touch|contributor|agent|steward] [--author <id>] [--require-gates] [--require-write-hook <host>] [--json] [--baseline [file]] [--report [file.html]] [--no-cache]',
     '       ark-check --doctor [--json] [--all] [--resident] [--fail-on-new-smells --base-ref <git-ref>]  compact first screen; --all prints Details; resident JSON falls back cold',
     '       ark-check --coverage [--json]          per-layer file counts + full unclassified list (report only, exit 0)',
     '       ark-check --plan [--json]              classified remediation plan (mechanical-safe / judgment / deferred) + goal; report only',
@@ -216,6 +227,9 @@ export function checkUsageAll() {
     '',
     'Team parliament: law files (ark.config / arkrules / .ark-baseline.json) cannot ship in',
     'the same diff as product source. --changed --base <ref> checks touched files only.',
+    '--local (or ARK_CHECK_LOCAL=1) is the same cheap path: it turns on --changed and',
+    'stays per worktree root. It cannot combine with --strict-merge. Write hooks stay',
+    'on the lexical snippet path; they do not run a full-tree check.',
     '--against <ref> ratchets new keys vs that ref\'s baseline. --contract-session is a',
     'steward law-only PR. Loosen / baseline-grow need stewards[] + --author when set.',
     '',
@@ -270,6 +284,8 @@ export function checkUsageAll() {
     '--require-gates implies --strict-config and fails when the Ark contract in AGENTS.md,',
     'the project-rooted Ark server in .mcp.json, or fail-closed CI is missing/invalid.',
     'Included but unclassified source files therefore stay red instead of false-green.',
+    'If gates are required and there is no short decision note yet, it points at docs/adr/',
+    '(or docs/decisions/) — a hint, not a fail. Off without --require-gates.',
     '',
     '--install-agent-gates writes AGENTS.md, .mcp.json, and the CI workflow for every',
     'project, plus tool-specific templates. Known tools: claude, cursor, codex, grok, antigravity',

package/bin/lib/gate-files.mjs

@@ -257,6 +257,42 @@ export function hasArkMcpRegistration(root, relativePath = '.mcp.json') {
   }
 }
 
+/**
+ * Shared MCP JSON destinations written by install-agent-gates (catalog + host copies).
+ * Upsert `mcpServers.ark` without clobbering sibling servers — same contract as
+ * mergeOpencodeArkMcp / mergeCursorArkHook.
+ */
+export const MCP_JSON_GATE_FILES = ['.mcp.json', '.cursor/mcp.json', '.agents/mcp_config.json'];
+
+/**
+ * Upsert mcpServers.ark into an existing MCP JSON document.
+ * Preserves sibling servers and unknown top-level keys. Returns null if unreadable.
+ */
+export function mergeArkMcpJson(existingText, generatedText) {
+  let existing;
+  let generated;
+  try {
+    existing = existingText && existingText.trim() ? JSON.parse(existingText) : {};
+    generated = JSON.parse(generatedText);
+  } catch {
+    return null;
+  }
+  if (!existing || typeof existing !== 'object' || Array.isArray(existing)) return null;
+  if (!generated || typeof generated !== 'object' || Array.isArray(generated)) return null;
+  const generatedArk = generated.mcpServers?.ark;
+  if (!generatedArk || typeof generatedArk !== 'object' || Array.isArray(generatedArk)) {
+    return null;
+  }
+  const servers =
+    existing.mcpServers &&
+    typeof existing.mcpServers === 'object' &&
+    !Array.isArray(existing.mcpServers)
+      ? { ...existing.mcpServers }
+      : {};
+  const next = { ...existing, mcpServers: { ...servers, ark: generatedArk } };
+  return `${JSON.stringify(next, null, 2)}\n`;
+}
+
 function commandArkMcpArgs(command) {
   if (typeof command !== 'string') return null;
   const words = [];
@@ -747,12 +783,13 @@ export function writeTemplate(root, relativePath, content, force) {
       return { relativePath, status: 'skipped-self-hosted' };
     }
     if (existing && !isArkAgentsContent(existing)) {
-      // Never clobber a project-owned AGENTS.md — even with --force.
-      // If Ark section not present yet, merge once; subsequent runs leave it alone.
+      // Never replace a project-owned AGENTS.md — even with --force.
+      // Merge the Ark section once when missing so start / install-agent-gates
+      // leave a contract doctor accepts (issue #210). Subsequent runs leave it.
       const hasArkSection =
         /#\s*Ark(Gate)?\s+Enforcement\b/.test(existing) ||
         /ark\.config\.json is authoritative/i.test(existing);
-      if (force && isArkAgentsContent(content) && !hasArkSection) {
+      if (isArkAgentsContent(content) && !hasArkSection) {
         try {
           const merged = `${existing.replace(/\s*$/, '')}\n\n---\n\n${content}`;
           ensureDirForFile(fullPath);

package/bin/lib/host-support-matrix.mjs

@@ -35,6 +35,11 @@ function hostProfile(label, hookPath, hookSurface, hookOperations, hardWrite, re
       'repair-envelope-emitted': repairEnvelopeEmitted,
       'repair-reinjection-guaranteed': repairReinjectionGuaranteed,
     }),
+    // Host-native "deny when the checker cannot run" flag (FS-permission analog).
+    // required = schema field must be true for hard-write evidence (Cursor failClosed).
+    // unsupported = host has no documented flag; hook-crash behavior is host-owned.
+    // none = advisory host; no local write block.
+    nativeFailClosed: extras.nativeFailClosed ?? (hardWrite ? 'unsupported' : 'none'),
     // EH07 minimum ops matrix (hard=false for soft hosts on every listed op).
     operationCoverage: Object.freeze(
       extras.operationCoverage ||
@@ -83,6 +88,7 @@ export const HOST_SUPPORT_MATRIX = Object.freeze({
     false,
     {
       repairEnvelopeEmitted: true,
+      nativeFailClosed: 'required',
       operationCoverage: {
         Write: true,
         StrReplace: true,
@@ -186,7 +192,9 @@ ${rows}
 **Read the CI column:** for every host, the repository-wide hard guarantee is a **required**
 GitHub **status context** that runs the CLI — not “CI file present,” and not the CLI binary name alone.
 Codex hard write covers only a complete local \`apply_patch\`; Cursor covers only listed
-\`preToolUse\` ops. In both cases the project hook must be installed + trusted, while shell/direct
+\`preToolUse\` ops with \`failClosed: true\`. A Cursor hook without that flag is fail-open
+(if the checker cannot run, the write still lands). In both cases the project hook must be
+installed + trusted, while shell/direct
 filesystem writes, hosted or specialized opt-out paths, and human edits still rely on CI.
 
 This table describes the supported profile **after its files are installed and the host loads/trusts them**. A hard local boundary covers only the listed hook operations; alternate tools, direct filesystem writes, and human edits still rely on CI. MCP validation is advisory because the agent must call it. The CI check blocks a merge only when the repository makes that status required. Repair **envelopes** may be emitted without reinjection being guaranteed; silent auto-apply never happens. Run \`arkgate-check --doctor\` (or \`ark-check --doctor\`) for the evidence actually detected in the current repository.`;