arkgate 4.8.11 → 4.8.14

package/bin/lib/architecture-scan.mjs

@@ -126,12 +126,18 @@ export function resolveArchitectureSnapshot({
     { ...config, rules: rules ?? config.rules },
     manifest
   );
+  const scoped = fileLocalScope(root, files);
   const facts = resolveCandidateFacts({
     root,
     config: effectiveConfig,
     ts,
     ...(args?.tsconfig ? { tsconfig: args.tsconfig } : {}),
     observeInput,
+    ...(scoped
+      ? { scopeFiles: [...scoped] }
+      : args?.changed
+        ? { scopeFiles: [] }
+        : {}),
   });
   const arkRulesLoad = loadEffectiveArkRulesFromDisk(root, effectiveConfig, {
     observeInput,
@@ -145,7 +151,6 @@ export function resolveArchitectureSnapshot({
     err.issues = arkRulesLoad.errors;
     throw err;
   }
-  const scoped = fileLocalScope(root, files);
   const loadedContract = loadContract(effectiveConfig, configPath, {
     arkRules: arkRulesLoad.arkRules,
   });
@@ -162,7 +167,8 @@ export function resolveArchitectureSnapshot({
         ...coverageOptionsFromConfig(effectiveConfig),
       })
     : undefined;
-  // File-local structure sensors + hint load honor `files`; graph still uses full facts.
+  // File-local sensors honor the touched set. Facts (and graph) use that set plus
+  // its import closure — not the whole include tree. Unbounded `files` stays full-tree.
   const fileHints = loadHintsForScope(
     root,
     facts,

package/bin/lib/ark-order-doctor.mjs

@@ -0,0 +1,160 @@
+/**
+ * GENERATED FILE — do not edit by hand.
+ *
+ * Canonical algorithm: src/domain/arkOrderDoctor.ts
+ * Regenerate: node scripts/generate-cli-pure.mjs
+ * Drift check: node scripts/generate-cli-pure.mjs --check
+ *
+ * Pure CLI helper (bin/lib/ark-order-doctor.mjs). Zero Node I/O.
+ */
+
+import { composeMergePlanesHonesty, extraMergeTeethAllowed, isArkOrderRuleId, } from './extra-merge-teeth.mjs';
+export const ARK_ORDER_DOCTOR_SCHEMA_VERSION = '1.0';
+const RESIDUAL_RULE_CAP = 12;
+export const ARKORDER_ONE_BREATH = 'Layers stop a bad import. ArkOrder stops rewriting a big product choice — like the billing plan — as if it were a seat count. Change those choices through a valve, not a generic update.';
+/** First-contact next step. Reuses the billing gallery + existing doors. */
+export const ARKORDER_FIRST_CONTACT_NEXT = 'Next: examples/arkorder-billing, then /ark-adopt to turn the extra on and /ark-order to wire one candidate.';
+function closedMode(value) {
+    return value === 'enforced' || value === 'advisory' ? value : null;
+}
+function uniqueArkOrderRuleIds(findings) {
+    const seen = new Set();
+    if (!Array.isArray(findings))
+        return [];
+    for (const finding of findings) {
+        const id = finding?.ruleId;
+        if (typeof id !== 'string' || !isArkOrderRuleId(id) || seen.has(id))
+            continue;
+        seen.add(id);
+    }
+    return [...seen].sort((left, right) => (left < right ? -1 : left > right ? 1 : 0));
+}
+function extraFromConfig(arkOrder) {
+    if (!arkOrder || typeof arkOrder !== 'object') {
+        return { present: false, mode: null, roots: 0, layers: 0, xiKeys: [] };
+    }
+    const xiKeys = Array.isArray(arkOrder.xiKeys)
+        ? arkOrder.xiKeys.filter((key) => typeof key === 'string' && key.length > 0)
+        : [];
+    return {
+        present: true,
+        mode: closedMode(arkOrder.mode),
+        roots: Array.isArray(arkOrder.planeRoots) ? arkOrder.planeRoots.length : 0,
+        layers: Array.isArray(arkOrder.managedLayers) ? arkOrder.managedLayers.length : 0,
+        xiKeys,
+    };
+}
+/**
+ * Doctor / HTML ArkOrder advisory. Always emitted; absence is an honest silent row.
+ */
+export function summarizeArkOrderSection(input = {}) {
+    const extra = extraFromConfig(input.arkOrder);
+    const uniqueIds = extra.present ? uniqueArkOrderRuleIds(input.findings) : [];
+    const ruleIds = uniqueIds.slice(0, RESIDUAL_RULE_CAP);
+    const residualCount = uniqueIds.length;
+    const mergePlanes = composeMergePlanesHonesty({
+        classification: input.classification,
+        arkRules: {
+            active: input.arkRules?.active === true,
+            structureEnforced: input.arkRules?.structureEnforced,
+            structureTotal: input.arkRules?.structureTotal,
+            structureAdvisory: input.arkRules?.structureAdvisory,
+            invariantEnforced: input.arkRules?.invariantEnforced,
+            invariantTotal: input.arkRules?.invariantTotal,
+            invariantAdvisory: input.arkRules?.invariantAdvisory,
+            covered: input.arkRules?.covered,
+            uncovered: input.arkRules?.uncovered,
+        },
+        arkRun: {
+            present: input.arkRun?.present === true,
+            mode: input.arkRun?.mode ?? null,
+            residualCount: input.arkRun?.residualCount,
+        },
+        arkOrder: {
+            present: extra.present,
+            mode: extra.mode,
+            residualCount,
+        },
+    });
+    const extraMergeTeeth = extra.present && extra.mode === 'enforced' && extraMergeTeethAllowed(input.classification);
+    let note;
+    if (!extra.present) {
+        note = 'Absence of arkOrder is silent — Layers verdicts unchanged. Not a score.';
+    }
+    else if (extra.mode === 'advisory') {
+        note =
+            'Advisory ArkOrder residual only — never flips valid or --strict-merge. Residual is a finding-id count, never a score.';
+    }
+    else if (extraMergeTeeth) {
+        note =
+            'Enforced ArkOrder is on the extra merge plane. Residual is a finding-id count, never a score.';
+    }
+    else {
+        note =
+            'Enforced ArkOrder extra teeth stay demoted until the layer plane is honestly classified. Residual is a finding-id count, never a score.';
+    }
+    return {
+        schemaVersion: ARK_ORDER_DOCTOR_SCHEMA_VERSION,
+        notAScore: true,
+        active: extra.present,
+        mode: extra.mode,
+        planeRoots: extra.roots,
+        managedLayers: extra.layers,
+        xiKeys: extra.xiKeys,
+        residual: { count: residualCount, ruleIds },
+        extraMergeTeeth,
+        failMergeWhen: mergePlanes.failMergeWhen,
+        note,
+        mergePlanes,
+    };
+}
+/** Thin status slice — counts only; residual null means unknown, not green. */
+export function projectStatusArkOrder(input = {}) {
+    const present = input.present === true;
+    const mode = closedMode(input.mode);
+    const residualRaw = input.residual;
+    let residual = null;
+    if (typeof residualRaw === 'number' && Number.isFinite(residualRaw) && residualRaw >= 0) {
+        residual = Math.floor(residualRaw);
+    }
+    if (!present)
+        residual = residual == null ? 0 : residual;
+    return {
+        notAScore: true,
+        present,
+        mode: present ? mode : null,
+        extraMergeTeeth: present && mode === 'enforced' && input.extraMergeTeeth === true,
+        residual,
+    };
+}
+export function formatArkOrderDoctorLines(section) {
+    if (!section || section.notAScore !== true)
+        return [];
+    if (section.active !== true) {
+        return [
+            ARKORDER_ONE_BREATH,
+            'Off — Layers stay the same (not a score).',
+            ARKORDER_FIRST_CONTACT_NEXT,
+        ];
+    }
+    const mode = section.mode ?? 'unknown';
+    const teeth = section.extraMergeTeeth === true ? 'armed' : 'not armed';
+    const keys = section.xiKeys.length > 0 ? section.xiKeys.join(', ') : '(none named — field-write sensor silent)';
+    const lines = [
+        ARKORDER_ONE_BREATH,
+        `mode: ${mode} · xiKeys: ${keys} · extra merge teeth ${teeth} · not a score`,
+    ];
+    if (section.residual.count > 0) {
+        const shown = section.residual.ruleIds.join(', ');
+        const more = section.residual.count > section.residual.ruleIds.length
+            ? ` (+${section.residual.count - section.residual.ruleIds.length} more)`
+            : '';
+        lines.push(`Residual: ${shown}${more}`);
+    }
+    else {
+        lines.push('Residual: none on this scan (not a score — green extras ≠ a frozen billing plan).');
+    }
+    if (section.failMergeWhen)
+        lines.push(section.failMergeWhen);
+    return lines;
+}

package/bin/lib/ark-order-report.mjs

@@ -0,0 +1,65 @@
+/**
+ * HTML for the doctor ArkOrder advisory (report parity: data-advisory="arkOrder").
+ */
+import { ARKORDER_FIRST_CONTACT_NEXT, ARKORDER_ONE_BREATH } from './ark-order-doctor.mjs';
+
+export function formatArkOrderHtml(section, esc) {
+  if (!section || typeof section !== 'object' || section.notAScore !== true) return '';
+  const escape = typeof esc === 'function' ? esc : (v) => String(v);
+  const note = section.note ? `<p class="muted">${escape(section.note)}</p>` : '';
+  if (section.active !== true) {
+    return `
+  <section class="section card" data-advisory="arkOrder">
+    <h2>ArkOrder <span class="muted">(opt-in extra — not a score)</span></h2>
+    <p class="dim" style="margin:.15rem 0 .55rem;font-size:.88rem">
+      ${ARKORDER_ONE_BREATH}
+      Off until you turn it on — Layers stay the same.
+      ${ARKORDER_FIRST_CONTACT_NEXT}
+    </p>
+    ${note}
+  </section>`;
+  }
+  const residual = section.residual && typeof section.residual === 'object' ? section.residual : { count: 0, ruleIds: [] };
+  const ids = Array.isArray(residual.ruleIds) ? residual.ruleIds : [];
+  const residualHtml =
+    residual.count > 0
+      ? `<p><span class="tag warn">residual</span> ${ids
+          .map((id) => `<code>${escape(id)}</code>`)
+          .join(' · ')}${
+          residual.count > ids.length ? ` <span class="muted">(+${residual.count - ids.length} more)</span>` : ''
+        }</p>`
+      : '<p class="muted">Residual: none on this scan (not a score — green extras ≠ a frozen billing plan).</p>';
+  const teeth = section.extraMergeTeeth === true
+    ? '<span class="tag">extra merge teeth armed</span>'
+    : '<span class="tag warn">extra merge teeth not armed</span>';
+  const mergeSentence =
+    section.mergePlanes && typeof section.mergePlanes.failMergeWhen === 'string'
+      ? section.mergePlanes.failMergeWhen
+      : section.failMergeWhen;
+  const merge =
+    mergeSentence
+      ? `<p class="muted" style="margin:.35rem 0 .55rem;font-size:.86rem"><b>Merge planes:</b> ${escape(mergeSentence)}</p>`
+      : '';
+  const keys = Array.isArray(section.xiKeys) && section.xiKeys.length > 0
+    ? section.xiKeys.map((key) => `<code>${escape(key)}</code>`).join(' · ')
+    : '<span class="muted">(none named — field-write sensor silent)</span>';
+  return `
+  <section class="section card" data-advisory="arkOrder">
+    <h2>ArkOrder <span class="muted">(not a score)</span></h2>
+    <p class="dim" style="margin:.15rem 0 .55rem;font-size:.88rem">
+      <b>[ArkOrder]</b> ${ARKORDER_ONE_BREATH}
+      Separate from <b>[Layer]</b> imports, <b>[ArkRules]</b> shape, and <b>[ArkRun]</b> travel.
+    </p>
+    ${merge}
+    <div class="kpis" style="margin-bottom:.55rem">
+      <div class="kpi"><b>${escape(section.mode || '—')}</b><span>Mode</span></div>
+      <div class="kpi"><b>${Number(residual.count) || 0}</b><span>Residual ids</span></div>
+      <div class="kpi"><b>${Number(section.planeRoots) || 0}</b><span>Plane roots</span></div>
+      <div class="kpi"><b>${Number(section.managedLayers) || 0}</b><span>Managed layers</span></div>
+    </div>
+    <p>${teeth} · <code>notAScore</code></p>
+    <p class="dim" style="margin:.35rem 0 .55rem;font-size:.86rem">xiKeys: ${keys}</p>
+    ${residualHtml}
+    ${note}
+  </section>`;
+}

package/bin/lib/ark-order-sensors.mjs

@@ -219,7 +219,7 @@ export function evaluateArkOrderSensors(input) {
             continue;
         if (!matchesArkOrderAppliesTo(write.file, extra.appliesTo))
             continue;
-        findings.push(finding(extra, 'arkorder-xi-field-write', write.file, write.line, `File writes slow key ${JSON.stringify(write.key)} through a persistence driver; route the field through ingest or a pattern change through proposeRelease.`, { fromLayer, target: write.key }, teethAllowed));
+        findings.push(finding(extra, 'arkorder-xi-field-write', write.file, write.line, `This file writes ${JSON.stringify(write.key)} the same way it would write a seat count. Take the event in, or change that choice through the valve (propose, then apply).`, { fromLayer, target: write.key }, teethAllowed));
     }
     findings.sort((left, right) => left.file.localeCompare(right.file) ||
         left.ruleId.localeCompare(right.ruleId) ||

package/bin/lib/ci-and-commands.mjs

@@ -338,6 +338,8 @@ files; never weaken the gate via subagents.
 
 **Escapes, not a second curriculum.** Do **not** run overlapping skills for the same job.
 Pick **one** primary skill. Prefer doctor top action #1 when unsure.
+Filter: **Contener · Guiar · Ordenar** — contain the write, guide the next step, order leftover mess. Skills never enforce. First-class extras:
+\`/ark-runtime\` (ArkRun) · \`/ark-order\` (ArkOrder).
 
 | When | Invoke | Not this |
 |------|--------|----------|
@@ -352,10 +354,11 @@ Pick **one** primary skill. Prefer doctor top action #1 when unsure.
 | Gate violation on a change (small cluster) | \`/ark-autopilot\` | leftover \`/ark-fix\` |
 | Drive plan **A** to goal.met | \`/ark-autopilot\` | leftover \`/ark-loop\` |
 | Ark **fitness** only (governed%, gates, baseline, install gaps) | \`/ark-coverage\` | leftover design work (use single path above) |
-| One design decision, 2–3 options | \`/ark-think\` | full Shape residual (use single path) |
+| One design decision, 2–3 options | \`/ark-explore\` (one decision) | leftover \`/ark-think\`; apply → autopilot |
 | Explain / HTML report tour | \`/ark-explain\` | explore |
 | Bump arkgate + refresh hosts | \`/ark-upgrade\` | — |
-| Optional runtime kernel evaluate | \`/ark-runtime\` | — |
+| Optional runtime kernel evaluate | \`/ark-runtime\` | leftover \`/ark-run\` (not a skill); order plane → \`/ark-order\` |
+| Optional ArkOrder evaluate / wire | \`/ark-order\` | extra off → \`/ark-adopt\`; skip grind → \`/ark-autopilot\` |
 
 **Post-green door:** when doctor reports ENFORCE · leftover design work, the **primary** next action is the single Shape path above — not a choice among explore / coverage / think. Doctor JSON: \`postGreenPath\` / \`primaryNextAction\`.
 
@@ -405,6 +408,8 @@ ${projectionBlock}
 
 **Primary path (do this):**
 
+Contener · Guiar · Ordenar — contain the write, guide the next step, order leftover mess.
+
 1. Status anytime: \`${doctorCmd}\` — what's wrong and what to do first.
 2. Read the **Improvement compass** section (not a score). Name residual lenses in plain language when present (SoC, DIP, domain, …). Out-of-scope lenses (performance, app security tooling, full resilience) stay honest — do not invent Ark enforcement for them.
 3. CLI-first: if the local CLI already resolved this project root, do not wait on MCP “still connecting”. Identity handshake is optional in that case. When you do trust MCP evidence: call \`ark_identity\` with \`project.expectedRoot\` set to this project's exact absolute root, then reuse that root plus the returned \`projectIdentity.projectId\` on every Ark MCP call. A descendant path is authoritative only with that matching id. Missing tool, non-\`matched\` binding, or wrong root means this is not proven to be the right project: restart the host and use the local CLI meanwhile.

package/bin/lib/design-smells.mjs

@@ -493,6 +493,25 @@ export function summarizeDesignFitness(smells, ctx = {}) {
 /** How many smell ids the green-run pointer names before it counts the rest. */
 export const GREEN_PLAN_POINTER_MAX_IDS = 4;
 
+/** When a smell has no evidence path, say so — do not leave the reader hunting. */
+export const SMELL_UNATTRIBUTED =
+  'no file — leftover design, not a specific line';
+
+/**
+ * One named smell with its first evidence path (or an explicit "no file").
+ * The pointer used to print only the id, so "1 design smell (domain-logic-in-ui)"
+ * could not answer "did my change cause this?"
+ */
+export function formatSmellPointerName(id, smells) {
+  const match = (smells || []).find((smell) => smell?.id === id);
+  const evidence = Array.isArray(match?.evidence)
+    ? match.evidence.filter((entry) => typeof entry === 'string' && entry.trim())
+    : [];
+  if (evidence.length === 0) return `${id} (${SMELL_UNATTRIBUTED})`;
+  const extra = evidence.length - 1;
+  return extra > 0 ? `${id} at ${evidence[0]} (+${extra} more)` : `${id} at ${evidence[0]}`;
+}
+
 /**
  * Name `--plan` on a run that passed.
  *
@@ -528,7 +547,8 @@ export function formatGreenPlanPointer(smells, ctx = {}, planCommand = 'ark-chec
   if (ids.length === 0) return null;
   const shown = ids.slice(0, GREEN_PLAN_POINTER_MAX_IDS);
   const hidden = ids.length - shown.length;
-  const named = hidden > 0 ? `${shown.join(', ')}, +${hidden} more` : shown.join(', ');
+  const namedIds = shown.map((id) => formatSmellPointerName(id, smells));
+  const named = hidden > 0 ? `${namedIds.join(', ')}, +${hidden} more` : namedIds.join(', ');
   const plural = ids.length === 1 ? '' : 's';
   const suppressed = ctx.suppressedCount ?? 0;
   const opening =

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.', '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_IMPORT_VIOLATION', 'layer', 'This import is not allowed', 'This file imported a folder it may not reach. The write doesn’t land. The same check fails the pull request.', '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.'),
@@ -68,14 +68,14 @@ export const DIAGNOSTIC_CATALOG = Object.freeze([
     entry('ARKRUN_TRANSPORT_BYPASS', 'arkrun', 'Homemade broker or emitter import', 'A managed layer imports a closed broker/queue/emitter specifier (EventEmitter, queue clients, …) instead of the ArkRun kernel transport.', 'Send through the ArkRun kernel transport instead of importing that broker or emitter, then preflight again. Never mechanical-safe — homemade buses stay judgment.'),
     entry('ARKORDER_MISSING_PLANE', 'arkorder', 'No createOrderPlane in plane roots', 'The ArkOrder extra is on but no createOrderPlane factory was found in arkOrder.planeRoots, so agents can skip the pattern plane while the write gate stays green.', 'Import createOrderPlane from arkgate/order and call it in a plane root listed in arkOrder.planeRoots, then preflight again. Never mechanical-safe — factory placement is a design decision.'),
     entry('ARKORDER_KERNEL_IN_DOMAIN', 'arkorder', 'Domain-role layer imports the order plane', 'A Domain-role layer imports arkgate/order. Domain stays plane-free; planeRoots own the factory.', 'Move the arkgate/order import out of the Domain-role layer into a plane root or adapter, then preflight again. Never mechanical-safe.'),
-    entry('ARKORDER_GENERIC_UPDATE', 'arkorder', 'Generic update of ξ', 'A call to update/patch/set on the order plane rewrites the slow pattern. Haken slaving forbids generic ξ mutation.', 'Use release() for the first freeze of ξ. Later pattern change is proposeRelease then apply(ProposeResult). Never update/patch/set. Never mechanical-safe.'),
+    entry('ARKORDER_GENERIC_UPDATE', 'arkorder', 'Generic update of a big product choice', 'A call to update/patch/set rewrites a named product choice (like billing plan) as if it were a seat count.', 'Don\'t use a generic update. First freeze with release(). Later, propose the change, then apply it.'),
     entry('ARKORDER_TOO_MANY_PARAMS', 'arkorder', 'Too many slow keys', 'ξ has more keys than arkOrder.maxXiKeys. Haken requires a few slow modes, not a dump of microstate.', 'Cut ξ to the slow keys that actually slave the rest, then preflight again. Never mechanical-safe.'),
     entry('ARKORDER_INGEST_WRITES_XI', 'arkorder', 'ingest assigned into ξ', 'An ingest() result is written into a Release or ξ store. ingest may absorb, escalate_up, or hold; it never mints a pattern.', 'Keep ingest results as absorb/escalate_up/hold only. Change ξ with proposeRelease then apply(ProposeResult). Never mechanical-safe.'),
-    entry('ARKORDER_XI_FIELD_WRITE', 'arkorder', 'Slow key written around the order plane', 'A managed-layer file imports a persistence driver and writes a declared arkOrder.xiKeys name. Field events absorb or escalate; they do not PATCH the slow pattern.', 'Keep invoices, seats, hours, and logs on ingest. Change the slow key with proposeRelease then apply(ProposeResult), then preflight again. Never mechanical-safe.'),
+    entry('ARKORDER_XI_FIELD_WRITE', 'arkorder', 'Big product choice written like a seat count', 'A use-case writes a named product choice (like billing plan) through a database update. Invoices and seats can flow. That choice cannot.', 'Keep invoices and seats as events. Change the choice through the valve (proposeRelease then apply), not a generic update.'),
     entry('ARKORDER_INFORMATION_BUDGET', 'arkorder', 'Projection observes a forbidden kind', 'h(ξ) allowedKinds includes a kind listed in informationBudget.cannotObserve. A scale may not look at what it was told not to see.', 'Cut that kind from the projector or from cannotObserve, then preflight again. Never mechanical-safe.'),
     entry('ARKORDER_XI_TTL', 'arkorder', 'Slow key carries a freshness field', 'ξ named ttl/freshUntil/maxAge. Freshness belongs on σ. A slow parameter that expires per transaction is not slow.', 'Move freshness onto σ (freshUntil) and keep ξ stable, then preflight again. Never mechanical-safe.'),
     entry('ARKORDER_STALE_SIGMA', 'arkorder', 'σ is stale', 'ingest ran after σ.freshUntil (or sigmaMaxAgeMs). ξ does not TTL.', 'Call refreshSigma and ingest again, or proposeRelease then apply(ProposeResult) if the pattern changed. Never mechanical-safe.'),
-    entry('ARKORDER_UNVALVED_RELEASE', 'arkorder', 'Unvalved second freeze of ξ', 'release() ran after a pattern was already frozen and the new ξ differs. First freeze is release(); later pattern change is proposeRelease then apply.', 'Change ξ with proposeRelease then apply(ProposeResult). release() is only the first freeze. Never mechanical-safe.'),
+    entry('ARKORDER_UNVALVED_RELEASE', 'arkorder', 'Second freeze without the valve', 'release() already froze the big choice. A later release() with a different value does not land. First freeze is release(); later change is proposeRelease then apply.', 'Change the choice with proposeRelease then apply. release() is only the first freeze. Never mechanical-safe.'),
     // ── 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.'),

package/bin/lib/doctor-advisories.mjs

@@ -21,6 +21,90 @@ import { detectGraphBlindSpots, printGraphBlindSection } from './graph-blind.mjs
 import { summarizeRulesUnderContract } from './rules-under-contract.mjs';
 import { collectStewardNudge } from './team-parliament-io.mjs';
 import { formatArkRunDoctorLines, summarizeArkRunSection } from './ark-run-doctor.mjs';
+import {
+  ARKORDER_FIRST_CONTACT_NEXT,
+  ARKORDER_ONE_BREATH,
+  formatArkOrderDoctorLines,
+  summarizeArkOrderSection,
+} from './ark-order-doctor.mjs';
+import { composeMergePlanesHonesty } from './extra-merge-teeth.mjs';
+
+export function attachExtraDoctorSections(rulesUnderContract, config, classification, findings) {
+  const arkRulesMerge = {
+    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,
+  };
+  const arkRun = summarizeArkRunSection({
+    arkRun: config?.arkRun,
+    findings,
+    classification,
+    arkRules: arkRulesMerge,
+  });
+  const arkOrder = summarizeArkOrderSection({
+    arkOrder: config?.arkOrder,
+    findings,
+    classification,
+    arkRules: arkRulesMerge,
+    arkRun: {
+      present: arkRun.active === true,
+      mode: arkRun.mode,
+      residualCount: arkRun.residual?.count,
+    },
+  });
+  const mergePlanes = composeMergePlanesHonesty({
+    classification,
+    arkRules: arkRulesMerge,
+    arkRun: {
+      present: arkRun.active === true,
+      mode: arkRun.mode,
+      residualCount: arkRun.residual?.count,
+    },
+    arkOrder: {
+      present: arkOrder.active === true,
+      mode: arkOrder.mode,
+      residualCount: arkOrder.residual?.count,
+    },
+  });
+  if (rulesUnderContract?.mergePlanes) rulesUnderContract.mergePlanes = mergePlanes;
+  arkRun.mergePlanes = mergePlanes;
+  arkRun.failMergeWhen = mergePlanes.failMergeWhen;
+  arkOrder.mergePlanes = mergePlanes;
+  arkOrder.failMergeWhen = mergePlanes.failMergeWhen;
+  return { arkRun, arkOrder, mergePlanes };
+}
+
+export function printCompactExtraDoctorLines(advisories, io) {
+  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 arkOrder = advisories?.arkOrder;
+  if (arkOrder && arkOrder.notAScore === true) {
+    console.log('');
+    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);
+    }
+  }
+}
 
 function classificationFromCoverage(cov) {
   return {
@@ -55,25 +139,12 @@ export function computeDoctorAdvisories(root, config, cov, rules, files, ts, par
       : undefined);
   const classification = classificationFromCoverage(cov);
   const rulesUnderContract = summarizeRulesUnderContract(root, config, factPaths, 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
+  );
   return {
     contractHealth: computeContractHealth(root, config, cov, rules),
     ambientState: computeAmbientState(ts, root, config, files),
@@ -86,6 +157,7 @@ export function computeDoctorAdvisories(root, config, cov, rules, files, ts, par
     stewardNudge: collectStewardNudge(root, config),
     rulesUnderContract,
     arkRun,
+    arkOrder,
   };
 }
 
@@ -116,4 +188,13 @@ export function printDoctorAdvisories(advisories, io) {
       io.line(mark, text);
     }
   }
+  const arkOrder = advisories.arkOrder;
+  if (arkOrder && arkOrder.notAScore === true) {
+    console.log('');
+    console.log(io.color.bold('ArkOrder (not a score)'));
+    const mark = arkOrder.active && arkOrder.residual?.count > 0 ? io.warn : ' ';
+    for (const text of formatArkOrderDoctorLines(arkOrder)) {
+      io.line(mark, text);
+    }
+  }
 }

package/bin/lib/doctor-human.mjs

@@ -4,10 +4,10 @@
  */
 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 } from './doctor-advisories.mjs';
+import { printDoctorAdvisories, printCompactExtraDoctorLines } from './doctor-advisories.mjs';
 import { designDeltaDoctorLines } from './design-delta.mjs';
 import { enforcementDoctorLines } from './enforcement-state.mjs';
 import { analysisIncompleteStatement } from './analysis-completeness.mjs';
@@ -73,6 +73,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 });
 
@@ -164,15 +165,7 @@ export function printDoctorCompactHuman(view) {
     line(warn, nudge.ask);
   }
 
-  const arkRun = doctorAdvisories.arkRun;
-  if (arkRun?.active === true && arkRun.notAScore === true) {
-    console.log('');
-    const residual = Number(arkRun.residual?.count) || 0;
-    line(
-      residual > 0 ? warn : ' ',
-      `ArkRun: ${arkRun.mode || 'on'} · residual=${residual} · not a score`
-    );
-  }
+  printCompactExtraDoctorLines(doctorAdvisories, { line, warn });
 
   if (violations.length === 0) {
     if (!analysisComplete) {

package/bin/lib/doctor-plan.mjs

@@ -658,11 +658,11 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
       pilotTarget: residualPilot?.pilotTarget ?? residualPilot?.pilot ?? null,
       arkRulesMergeHonesty: rulesUnderContract?.mergePlanes
         ? {
-            active: rulesUnderContract.active === true || arkRun?.active === true,
+            active: rulesUnderContract.active === true || arkRun?.active === true || doctorAdvisories.arkOrder?.active === true,
             ...rulesUnderContract.mergePlanes,
           }
-        : rulesUnderContract?.active === true || arkRun?.active === true
-          ? { active: true, extraMergeTeeth: arkRun?.extraMergeTeeth === true }
+        : rulesUnderContract?.active === true || arkRun?.active === true || doctorAdvisories.arkOrder?.active === true
+          ? { active: true, extraMergeTeeth: arkRun?.extraMergeTeeth === true || doctorAdvisories.arkOrder?.extraMergeTeeth === true }
           : null,
       primaryNextAction:
         adopted === 'not-adopted' ? NOT_ADOPTED_NEXT_ACTION : postGreenPath?.action ?? dualTruthNext,
@@ -757,6 +757,7 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
             ...doctorAdvisories,
             rulesUnderContract,
             arkRun,
+            arkOrder: doctorAdvisories.arkOrder,
             // P0-B — single anti-false-green honesty surface (never a score).
             productHonesty,
             governed: cov.governed,