arkgate 4.8.11 → 4.8.14

package/bin/lib/extra-merge-teeth.mjs

@@ -80,7 +80,7 @@ export function demoteExtraPlaneTeethUnderClassificationFloor(violations, classi
     return violations;
 }
 /** Stamp for extra-plane honesty: never one architecture score. */
-export const MERGE_PLANES_DUAL_STAMP = 'Structure = heuristics; invariants = catalog+coverage evidence (not business runtime); ArkRun = kernel usage + declarations (not a score); ArkOrder = pattern slaving (not a score). Extra planes never merge into one architecture score. Advisory ArkRules ≠ merge teeth. Advisory ArkRun ≠ merge teeth. Advisory ArkOrder ≠ merge teeth.';
+export const MERGE_PLANES_DUAL_STAMP = 'Structure = heuristics; invariants = catalog+coverage evidence (not business runtime); ArkRun = kernel usage + declarations (not a score); ArkOrder = the few big product choices (not a score). Extra planes never merge into one architecture score. Advisory ArkRules ≠ merge teeth. Advisory ArkRun ≠ merge teeth. Advisory ArkOrder ≠ merge teeth.';
 function countOrZero(value) {
     return typeof value === 'number' && Number.isFinite(value) && value > 0 ? Math.floor(value) : 0;
 }
@@ -112,7 +112,14 @@ export function composeMergePlanesHonesty(input = {}) {
     const arkRunResidual = countOrZero(input.arkRun?.residualCount);
     const arkRunHasEnforced = arkRunPresent && arkRunMode === 'enforced';
     const arkRunTeeth = arkRunHasEnforced && classificationAllowsTeeth;
-    const hasEnforcedTeeth = arkRulesHasEnforced || arkRunHasEnforced;
+    const arkOrderPresent = input.arkOrder?.present === true;
+    const arkOrderMode = input.arkOrder?.mode === 'enforced' || input.arkOrder?.mode === 'advisory'
+        ? input.arkOrder.mode
+        : null;
+    const arkOrderResidual = countOrZero(input.arkOrder?.residualCount);
+    const arkOrderHasEnforced = arkOrderPresent && arkOrderMode === 'enforced';
+    const arkOrderTeeth = arkOrderHasEnforced && classificationAllowsTeeth;
+    const hasEnforcedTeeth = arkRulesHasEnforced || arkRunHasEnforced || arkOrderHasEnforced;
     const extraMergeTeeth = hasEnforcedTeeth && classificationAllowsTeeth;
     const teethDeferredForClassification = hasEnforcedTeeth && classificationKnown && !classificationAllowsTeeth;
     let failMergeWhen;
@@ -122,12 +129,15 @@ export function composeMergePlanesHonesty(input = {}) {
             extras.push('enforced structure/invariant findings');
         if (arkRunHasEnforced)
             extras.push('enforced ArkRun skip findings');
+        if (arkOrderHasEnforced)
+            extras.push('enforced ArkOrder skip findings');
         failMergeWhen = `Layer graph failures plus ${extras.join(' and ')} (advisory extras never fail merge alone).`;
     }
     else if (teethDeferredForClassification) {
         const which = [
             arkRulesHasEnforced ? 'ArkRules structure/invariant' : null,
             arkRunHasEnforced ? 'ArkRun' : null,
+            arkOrderHasEnforced ? 'ArkOrder' : null,
         ]
             .filter((part) => Boolean(part))
             .join(' and ');
@@ -139,15 +149,21 @@ export function composeMergePlanesHonesty(input = {}) {
             : arkRunMode === 'advisory'
                 ? ' Advisory ArkRun never merge-blocks.'
                 : ' ArkRun extra is present but does not arm merge teeth.';
+        const arkOrderBit = !arkOrderPresent
+            ? ' Absence of arkOrder is silent.'
+            : arkOrderMode === 'advisory'
+                ? ' Advisory ArkOrder never merge-blocks.'
+                : ' ArkOrder extra is present but does not arm merge teeth.';
         failMergeWhen =
             'Layer graph only — no enforced ArkRules structure/invariant teeth on this tree. Advisory packs do not arm merge teeth.' +
-                arkRunBit;
+                arkRunBit +
+                arkOrderBit;
     }
     const out = {
         layers: {
             role: 'inter-layer-edges',
             alwaysOnGate: true,
-            note: 'Import/export layer graph — the default merge plane. Absent arkRules or arkRun changes nothing here.',
+            note: 'Import/export layer graph — the default merge plane. Absent extras change nothing here.',
         },
         structureSensors: {
             role: 'intra-layer-heuristics',
@@ -177,6 +193,18 @@ export function composeMergePlanesHonesty(input = {}) {
                     : 'Advisory ArkRun never adds merge teeth and never flips valid. Residual is a count, never a score.'
                 : 'Absence of arkRun is silent — Layers and ArkRules verdicts unchanged. The extra never becomes a score.',
         },
+        arkOrder: {
+            role: 'pattern-slaving',
+            present: arkOrderPresent,
+            mode: arkOrderMode,
+            residualCount: arkOrderResidual,
+            extraMergeTeeth: arkOrderTeeth,
+            note: arkOrderPresent
+                ? arkOrderMode === 'enforced'
+                    ? 'Enforced ArkOrder arms extra merge teeth only when the layer plane is classified. Residual is a count, never a score.'
+                    : 'Advisory ArkOrder never adds merge teeth and never flips valid. Residual is a count, never a score.'
+                : 'Absence of arkOrder is silent — Layers verdicts unchanged. The extra never becomes a score.',
+        },
         extraMergeTeeth,
         dualPlaneStamp: MERGE_PLANES_DUAL_STAMP,
         failMergeWhen,

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

@@ -2,9 +2,12 @@
  * 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
@@ -30,6 +33,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 +162,12 @@ 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 --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,7 +177,9 @@ 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',

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/html-report-advisories.mjs

@@ -11,6 +11,7 @@ import { effectiveCapabilityDeny } from './analysis-engine.mjs';
 import { graphBlindSpotsHtml } from './graph-blind.mjs';
 import { formatRulesUnderContractHtml } from './rules-under-contract.mjs';
 import { formatArkRunHtml } from './ark-run-report.mjs';
+import { formatArkOrderHtml } from './ark-order-report.mjs';
 import { primaryImprovementCompassNextAction } from './improvement-compass.mjs';
 
 // htmlEscape is injected by the caller (html-report.mjs) — importing it back
@@ -353,6 +354,7 @@ export function renderAdvisorySections(advisories, escape) {
     graphBlindSpotsHtml(advisories.graphBlindSpots, esc),
     rulesUnderContractHtml(advisories.rulesUnderContract),
     formatArkRunHtml(advisories.arkRun, esc),
+    formatArkOrderHtml(advisories.arkOrder, esc),
   ]
     .filter(Boolean)
     .join('\n');

package/bin/lib/html-report-depth.mjs

@@ -19,7 +19,7 @@ import {
   buildProductHonesty,
 } from './enforcement-honesty.mjs';
 import { summarizeRulesUnderContract } from './rules-under-contract.mjs';
-import { summarizeArkRunSection } from './ark-run-doctor.mjs';
+import { attachExtraDoctorSections } from './doctor-advisories.mjs';
 import { readBaseline, baselineOccurrenceKeys } from './violations.mjs';
 import { describePackageVersionDualTruth } from './field-install.mjs';
 import { buildDoctorImprovementCompass } from './improvement-compass-doctor.mjs';
@@ -136,23 +136,12 @@ export function buildReportDepthPayload(
     classifiedFiles: coverage?.governed?.classifiedFiles ?? null,
   };
   const rulesUnderContract = summarizeRulesUnderContract(root, config, undefined, classification);
-  const arkRun = summarizeArkRunSection({
-    arkRun: config?.arkRun,
-    findings: activeViolations,
+  const { arkRun, arkOrder } = attachExtraDoctorSections(
+    rulesUnderContract,
+    config,
     classification,
-    arkRules: {
-      active: rulesUnderContract?.active === true,
-      structureEnforced: rulesUnderContract?.mergePlanes?.structureSensors?.enforced,
-      structureTotal: rulesUnderContract?.mergePlanes?.structureSensors?.total,
-      structureAdvisory: rulesUnderContract?.mergePlanes?.structureSensors?.advisory,
-      invariantEnforced: rulesUnderContract?.mergePlanes?.invariants?.enforced,
-      invariantTotal: rulesUnderContract?.mergePlanes?.invariants?.total,
-      invariantAdvisory: rulesUnderContract?.mergePlanes?.invariants?.advisory,
-      covered: rulesUnderContract?.mergePlanes?.invariants?.covered,
-      uncovered: rulesUnderContract?.mergePlanes?.invariants?.uncovered,
-    },
-  });
-  if (rulesUnderContract?.mergePlanes) rulesUnderContract.mergePlanes = arkRun.mergePlanes;
+    activeViolations
+  );
   // Single residual expression (parity with doctor): nextPilot || extractionCard.
   const residualPilot =
     pilotLoop?.nextPilot || pilotLoop?.extractionCard || null;
@@ -174,7 +163,7 @@ export function buildReportDepthPayload(
     residualPilots: Boolean(residualPilot) && designFitness.designWeak === true,
     pilotTarget: residualPilot?.pilotTarget ?? residualPilot?.pilot ?? null,
     arkRulesMergeHonesty: rulesUnderContract?.mergePlanes
-      ? { active: rulesUnderContract.active === true || arkRun?.active === true, ...rulesUnderContract.mergePlanes }
+      ? { active: rulesUnderContract.active === true || arkRun?.active === true || arkOrder?.active === true, ...rulesUnderContract.mergePlanes }
       : null,
     primaryNextAction: postGreenPath?.action ?? dualTruthNext,
     activeBlockingViolations: activeBlockingCount,
@@ -218,6 +207,7 @@ export function buildReportDepthPayload(
       productHonesty,
       mergePlanes: rulesUnderContract?.mergePlanes ?? null,
       arkRun,
+      arkOrder,
       improvementCompass,
       deepModuleCoach,
     },

package/bin/lib/html-report.mjs

@@ -152,6 +152,8 @@ export function buildReportSnapshot({
   improvementCompass = null,
   /** RN08 — thin status ArkRun slice (notAScore; residual count, never a score). */
   arkRun = null,
+  /** Thin status ArkOrder slice (notAScore; residual count, never a score). */
+  arkOrder = null,
 }) {
   const layers = Array.isArray(config?.layers) ? config.layers : [];
   const rules = Array.isArray(config?.rules) ? config.rules : [];
@@ -213,6 +215,20 @@ export function buildReportSnapshot({
             : null,
     };
   }
+  if (arkOrder && typeof arkOrder === 'object' && arkOrder.notAScore === true) {
+    snapshot.arkOrder = {
+      notAScore: true,
+      present: arkOrder.active === true || arkOrder.present === true,
+      mode: arkOrder.mode === 'enforced' || arkOrder.mode === 'advisory' ? arkOrder.mode : null,
+      extraMergeTeeth: arkOrder.extraMergeTeeth === true,
+      residual:
+        typeof arkOrder.residual === 'number'
+          ? arkOrder.residual
+          : typeof arkOrder.residual?.count === 'number'
+            ? arkOrder.residual.count
+            : null,
+    };
+  }
   return snapshot;
 }
 

package/bin/lib/install-migrate.mjs

@@ -37,6 +37,8 @@ import {
   hasCheckArchitectureScript,
   ensureTypecheckScript,
   compactRouterHost,
+  mergeArkMcpJson,
+  MCP_JSON_GATE_FILES,
   writeTemplate,
 } from './gate-files.mjs';
 import {
@@ -573,6 +575,27 @@ export function runInstallAgentGates(args) {
       // Upsert ark-write-gate without requiring --force; never wipe sibling named hooks.
       return writeTemplate(root, relativePath, merged, true);
     }
+    if (MCP_JSON_GATE_FILES.includes(relativePath)) {
+      const fullPath = path.join(root, relativePath);
+      let existing = '';
+      try {
+        existing = fs.readFileSync(fullPath, 'utf8');
+      } catch {
+        // Missing MCP JSON → write generated ark server.
+      }
+      if (!existing) {
+        return writeTemplate(root, relativePath, content, true);
+      }
+      const merged = mergeArkMcpJson(existing, content);
+      if (merged == null) {
+        return args.force
+          ? writeTemplate(root, relativePath, content, true)
+          : { relativePath, status: 'skipped-non-ark' };
+      }
+      if (merged === existing) return { relativePath, status: 'skipped' };
+      // Upsert mcpServers.ark without requiring --force; never wipe sibling servers.
+      return writeTemplate(root, relativePath, merged, true);
+    }
     return writeTemplate(
       root,
       relativePath,

package/bin/lib/mcp-hook-payload.mjs

@@ -314,7 +314,7 @@ export function emitHostAllow(output, { antigravityStyle, cursorStyle }) {
  */
 export function formatWriteGateDeny({ file, reason, ruleId, nextAction, extraLines = [] }) {
   const target = file || 'this write';
-  const why = String(reason || 'this change breaks the architecture layers').replace(/\s+/g, ' ').trim();
+  const why = String(reason || 'a bad import — the write doesn’t land').replace(/\s+/g, ' ').trim();
   const next =
     nextAction && /place|move|import|port/i.test(nextAction)
       ? nextAction

package/bin/lib/product-copy.mjs

@@ -6,6 +6,10 @@
  * common software words. See docs/product-voice.md.
  */
 
+/** First-contact north star. Ordinary English. Spanish names once. */
+export const NORTH_STAR_ONE_LINE =
+  'Contener · Guiar · Ordenar — contain the write, guide the next step, order leftover mess.';
+
 /** Status-light leftover-design qualifier (was “design-weak”). */
 export const LEFTOVER_DESIGN_LABEL = 'leftover design work';
 

package/bin/lib/remediation.mjs

@@ -239,17 +239,17 @@ export function deterministicNextAction(violation) {
         case 'ARKORDER_KERNEL_IN_DOMAIN':
             return 'Move the arkgate/order import out of the Domain-role layer into a plane root or adapter, then preflight again. Never mechanical-safe.';
         case 'ARKORDER_GENERIC_UPDATE':
-            return 'Use release() for the first freeze of ξ. Later pattern change is proposeRelease then apply(ProposeResult). Never update/patch/set. Never mechanical-safe.';
+            return 'Don\'t use a generic update. First freeze with release(). Later, propose the change, then apply it.';
         case 'ARKORDER_TOO_MANY_PARAMS':
             return 'Cut ξ to the slow keys that actually slave the rest, then preflight again. Never mechanical-safe.';
         case 'ARKORDER_INGEST_WRITES_XI':
             return 'Keep ingest results as absorb/escalate_up/hold only. Change ξ with proposeRelease then apply(ProposeResult). Never mechanical-safe.';
         case 'ARKORDER_XI_FIELD_WRITE':
             return typeof violation.target === 'string' && violation.target.length > 0
-                ? `Do not persist slow key ${violation.target} from a use-case. Absorb the field with ingest() or change the pattern with proposeRelease then apply, then preflight again.`
-                : 'Do not persist a declared slow key from a use-case. Absorb the field with ingest() or change the pattern with proposeRelease then apply, then preflight again. Never mechanical-safe.';
+                ? `Don't write ${violation.target} from a use-case. Take the event in, or change that choice through the valve (proposeRelease then apply), not a generic update.`
+                : "Don't write a named product choice from a use-case. Take the event in, or change that choice through the valve (proposeRelease then apply), not a generic update.";
         case 'ARKORDER_UNVALVED_RELEASE':
-            return 'Change ξ with proposeRelease then apply(ProposeResult). release() is only the first freeze. Never mechanical-safe.';
+            return 'Change the choice with proposeRelease then apply. release() is only the first freeze. Never mechanical-safe.';
         default:
             if (typeof violation.ruleId === 'string' && violation.ruleId.startsWith('ARKRULE_')) {
                 return `Fix the ArkRule ${typeof violation.arkruleId === 'string' ? violation.arkruleId : violation.ruleId}, then preflight again.`;
@@ -528,7 +528,7 @@ export function enrichViolationWithFixClass(violation) {
             enriched.effort = 'medium';
             enriched.enthusiastHint =
                 violation.ruleId === 'ARKORDER_GENERIC_UPDATE'
-                    ? 'Do not PATCH the slow pattern. Freeze ξ with release() or propose a pattern change that lists what dies.'
+                    ? 'Don\'t PATCH the billing plan. First freeze with release(), or propose the change then apply it.'
                     : violation.ruleId === 'ARKORDER_KERNEL_IN_DOMAIN'
                         ? 'Domain stays plane-free. Import arkgate/order only from a listed plane root.'
                         : violation.ruleId === 'ARKORDER_TOO_MANY_PARAMS'
@@ -536,7 +536,7 @@ export function enrichViolationWithFixClass(violation) {
                             : violation.ruleId === 'ARKORDER_INGEST_WRITES_XI'
                                 ? 'ingest can absorb or escalate. It never writes a new house.'
                                 : violation.ruleId === 'ARKORDER_XI_FIELD_WRITE'
-                                    ? 'Name the slow keys in arkOrder.xiKeys. Invoices and seats still flow; changing the plan is a new release, not prisma.update.'
+                                    ? 'Name the few big choices in arkOrder.xiKeys. Invoices and seats still flow; changing the plan goes through the valve, not a generic update.'
                                     : violation.ruleId === 'ARKORDER_INFORMATION_BUDGET'
                                         ? 'A scale may not observe a denied kind. Cut it from the projector or from cannotObserve.'
                                         : violation.ruleId === 'ARKORDER_XI_TTL'
@@ -544,7 +544,7 @@ export function enrichViolationWithFixClass(violation) {
                                             : violation.ruleId === 'ARKORDER_STALE_SIGMA'
                                                 ? 'Refresh σ. ξ does not expire.'
                                                 : violation.ruleId === 'ARKORDER_UNVALVED_RELEASE'
-                                                    ? 'The pattern is frozen. proposeRelease then apply — do not call release() again with a different ξ.'
+                                                    ? 'The choice is already frozen. proposeRelease then apply — do not call release() again with a different value.'
                                                     : 'Call createOrderPlane from arkgate/order in a listed plane root so the app actually freezes a pattern.';
             break;
         default: