arkgate 4.8.13 → 4.8.14

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

@@ -12,6 +12,8 @@ import { composeMergePlanesHonesty, extraMergeTeethAllowed, isArkOrderRuleId, }
 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;
 }
@@ -129,7 +131,11 @@ export function formatArkOrderDoctorLines(section) {
     if (!section || section.notAScore !== true)
         return [];
     if (section.active !== true) {
-        return ['ArkOrder extra is off — silent on Layers (not a score).'];
+        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';

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

@@ -1,7 +1,7 @@
 /**
  * HTML for the doctor ArkOrder advisory (report parity: data-advisory="arkOrder").
  */
-import { ARKORDER_ONE_BREATH } from './ark-order-doctor.mjs';
+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 '';
@@ -14,6 +14,7 @@ export function formatArkOrderHtml(section, esc) {
     <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>`;

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.'),
@@ -75,7 +75,7 @@ export const DIAGNOSTIC_CATALOG = Object.freeze([
     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

@@ -22,6 +22,7 @@ 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,
@@ -87,14 +88,21 @@ export function printCompactExtraDoctorLines(advisories, io) {
     io.line(residual > 0 ? io.warn : ' ', `ArkRun: ${arkRun.mode || 'on'} · residual=${residual} · not a score`);
   }
   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);
+    }
   }
 }
 

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';
@@ -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 });
 

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/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

@@ -249,7 +249,7 @@ export function deterministicNextAction(violation) {
                 ? `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.`;
@@ -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:

package/bin/lib/resolved-candidate-facts.mjs

@@ -211,32 +211,67 @@ function canonicalOverlayPath(
   return [...candidates].sort()[0] ?? requested;
 }
 
-function collectCandidateFiles(root, config, changes, observeInput) {
+function discoverScopedFiles(root, config, scopeRelatives, observeInput) {
+  const discovered = [];
+  const seen = new Set();
+  for (const raw of scopeRelatives ?? []) {
+    let relative;
+    try {
+      relative = canonicalProjectPath(
+        String(raw || '')
+          .replace(/\\/g, '/')
+          .replace(/^\.\//, '')
+      );
+    } catch {
+      continue;
+    }
+    if (seen.has(relative) || !isGovernableSourceFile(path.basename(relative))) continue;
+    if (!isIncluded(relative, config.include) || isScanExcludedRelative(relative, config)) {
+      continue;
+    }
+    const absolute = path.join(root, ...relative.split('/'));
+    if (!fs.existsSync(absolute)) continue;
+    seen.add(relative);
+    observeResolvedInput(observeInput, absolute, 'realpath');
+    discovered.push({
+      absolute,
+      real: fs.realpathSync(absolute),
+      relative,
+    });
+  }
+  return discovered.sort((left, right) =>
+    left.relative < right.relative ? -1 : left.relative > right.relative ? 1 : 0
+  );
+}
+
+function collectCandidateFiles(root, config, changes, observeInput, scopeRelatives) {
   const files = new Map();
   const directoryAliases = new Map();
   const expandedAliasDirectories = new Set();
-  const discovered = (config.include ?? [])
-    .flatMap((entry) =>
-      collectGovernedFiles(root, { ...config, include: [entry] }, {
-        observeInput,
-        onDirectory(absolute, real) {
-          let relative = normalize(path.relative(root, absolute));
-          if (relative === '.') relative = '';
-          rememberDirectoryAlias(directoryAliases, real, relative, absolute);
-        },
-      })
-    )
-    .map((absolute) => {
-      observeResolvedInput(observeInput, absolute, 'realpath');
-      return {
-        absolute,
-        real: fs.realpathSync(absolute),
-        relative: canonicalProjectPath(normalize(path.relative(root, absolute))),
-      };
-    })
-    .sort((left, right) =>
-      left.relative < right.relative ? -1 : left.relative > right.relative ? 1 : 0
-    );
+  const discovered = Array.isArray(scopeRelatives)
+    ? discoverScopedFiles(root, config, scopeRelatives, observeInput)
+    : (config.include ?? [])
+        .flatMap((entry) =>
+          collectGovernedFiles(root, { ...config, include: [entry] }, {
+            observeInput,
+            onDirectory(absolute, real) {
+              let relative = normalize(path.relative(root, absolute));
+              if (relative === '.') relative = '';
+              rememberDirectoryAlias(directoryAliases, real, relative, absolute);
+            },
+          })
+        )
+        .map((absolute) => {
+          observeResolvedInput(observeInput, absolute, 'realpath');
+          return {
+            absolute,
+            real: fs.realpathSync(absolute),
+            relative: canonicalProjectPath(normalize(path.relative(root, absolute))),
+          };
+        })
+        .sort((left, right) =>
+          left.relative < right.relative ? -1 : left.relative > right.relative ? 1 : 0
+        );
   const canonicalByRealpath = new Map();
   for (const candidate of discovered) {
     if (!canonicalByRealpath.has(candidate.real)) canonicalByRealpath.set(candidate.real, candidate);
@@ -582,7 +617,8 @@ function compilerContext(ts, root, tsconfig, candidateFiles, observeInput) {
   const optionsByPath = new Map();
   const configInputsByPath = new Map();
   const reasons = [];
-  for (const configPath of configPaths) {
+  const loadConfigOptions = (configPath) => {
+    if (optionsByPath.has(configPath)) return optionsByPath.get(configPath);
     const configContents = new Map();
     const readConfig = (fileName) => {
       observeResolvedInput(observeInput, fileName, 'tsconfig');
@@ -605,15 +641,16 @@ function compilerContext(ts, root, tsconfig, candidateFiles, observeInput) {
       });
       optionsByPath.set(configPath, {});
       configInputsByPath.set(configPath, configContents);
-      continue;
+      return {};
     }
     const parsed = ts.parseJsonConfigFileContent(
       read.config,
       {
         useCaseSensitiveFileNames: ts.sys?.useCaseSensitiveFileNames ?? true,
-        readDirectory(...args) {
-          observeResolvedInput(observeInput, args[0], 'tsconfig-directory');
-          return ts.sys?.readDirectory ? ts.sys.readDirectory(...args) : [];
+        readDirectory(dir) {
+          observeResolvedInput(observeInput, dir, 'tsconfig-directory');
+          // Options-only parse: `fileNames` are unused. Skip the include walk (#205).
+          return [];
         },
         fileExists(fileName) {
           observeResolvedInput(observeInput, fileName, 'tsconfig-exists');
@@ -637,11 +674,19 @@ function compilerContext(ts, root, tsconfig, candidateFiles, observeInput) {
     }
     optionsByPath.set(configPath, parsed.options ?? {});
     configInputsByPath.set(configPath, configContents);
-  }
+    return parsed.options ?? {};
+  };
+  for (const configPath of configPaths) loadConfigOptions(configPath);
 
   const optionsFor = (fileName) => {
-    const configPath = configByFile.get(path.resolve(fileName));
-    return configPath ? optionsByPath.get(configPath) ?? {} : {};
+    const resolved = path.resolve(fileName);
+    let configPath = configByFile.get(resolved);
+    if (!configPath) {
+      configPath = explicitPath
+        ?? nearestTsconfig(root, resolved, nearestConfigByDirectory, observeInput);
+      if (configPath) configByFile.set(resolved, configPath);
+    }
+    return configPath ? loadConfigOptions(configPath) ?? {} : {};
   };
   const configs = configPaths.map((configPath) => ({
     path: configLabel(root, configPath, externalAnchor),
@@ -1036,6 +1081,19 @@ function unavailableFacts(config, ts, reason) {
   });
 }
 
+function loadOneCandidateFile(root, config, relative, observeInput) {
+  const discovered = discoverScopedFiles(root, config, [relative], observeInput);
+  const found = discovered[0];
+  if (!found) return null;
+  observeResolvedInput(observeInput, found.absolute, 'source');
+  return {
+    path: found.relative,
+    absolute: path.resolve(found.absolute),
+    real: path.resolve(found.real),
+    content: fs.readFileSync(found.absolute, 'utf8'),
+  };
+}
+
 /** Resolve one complete candidate tree (base or virtual overlay) into versioned neutral facts. */
 export function resolveCandidateFacts({
   root,
@@ -1044,6 +1102,7 @@ export function resolveCandidateFacts({
   tsconfig,
   changes = [],
   observeInput,
+  scopeFiles,
 }) {
   if (!ts?.createSourceFile || !ts?.resolveModuleName) {
     return unavailableFacts(config, ts, 'No API-compatible TypeScript resolver is available.');
@@ -1053,10 +1112,17 @@ export function resolveCandidateFacts({
   let candidateFiles;
   let canonicalChanges;
   let compiler;
+  const scoped = Array.isArray(scopeFiles);
   try {
     observeResolvedInput(observeInput, root, 'realpath');
     canonicalRoot = fs.realpathSync(root);
-    const candidate = collectCandidateFiles(canonicalRoot, config, changes, observeInput);
+    const candidate = collectCandidateFiles(
+      canonicalRoot,
+      config,
+      changes,
+      observeInput,
+      scoped ? scopeFiles : undefined
+    );
     candidateFiles = candidate.files;
     canonicalChanges = candidate.changes;
     compiler = compilerContext(ts, canonicalRoot, tsconfig, candidateFiles, observeInput);
@@ -1106,7 +1172,8 @@ export function resolveCandidateFacts({
   const compositionRootPatterns = [...(config.arkRun?.compositionRoots ?? [])];
   const planeRootPatterns = [...(config.arkOrder?.planeRoots ?? [])];
 
-  for (const candidate of candidateFiles) {
+  const seedPathSet = new Set(candidateFiles.map((file) => file.path));
+  const ingest = (candidate, fullExtract) => {
     const sourceFile = ts.createSourceFile(
       candidate.absolute,
       candidate.content,
@@ -1158,6 +1225,7 @@ export function resolveCandidateFacts({
         message: `${candidate.path} has ${parseDiagnosticCount} TypeScript parse diagnostic(s).`,
       });
     }
+    if (!fullExtract) return;
     const forbiddenUses = mayContainForbiddenCapability(ts, sourceFile, forbiddenGlobals)
       ? collectForbiddenCapabilityUses(ts, sourceFile, forbiddenGlobals)
       : [];
@@ -1244,10 +1312,50 @@ export function resolveCandidateFacts({
         // Never fail the resolver for ArkOrder release key-count extraction.
       }
     }
+  };
+
+  for (const candidate of candidateFiles) ingest(candidate, true);
+
+  if (scoped) {
+    const loaded = new Set(candidateFiles.map((file) => file.path));
+    let pending = [...candidateFiles];
+    while (pending.length > 0) {
+      const discovered = [];
+      for (const source of pending) {
+        const parsedFile = parsed.get(source.path);
+        if (!parsedFile) continue;
+        for (const dependency of parsedFile.dependencies) {
+          const resolved = resolveDependency(
+            ts,
+            dependency,
+            parsedFile.candidate.absolute,
+            compiler.optionsFor(parsedFile.candidate.absolute),
+            host
+          );
+          if (resolved.resolution !== 'resolved-project' || !resolved.target) continue;
+          if (loaded.has(resolved.target)) continue;
+          const extra = loadOneCandidateFile(
+            canonicalRoot,
+            config,
+            resolved.target,
+            observeInput
+          );
+          if (!extra) continue;
+          loaded.add(extra.path);
+          candidateFiles.push(extra);
+          ingest(extra, false);
+          discovered.push(extra);
+        }
+      }
+      pending = discovered;
+    }
   }
 
+  const extractCandidates = scoped
+    ? candidateFiles.filter((file) => seedPathSet.has(file.path))
+    : candidateFiles;
   const admittedTypeNames = new Set(classShapes.map((shape) => shape.className));
-  for (const candidate of candidateFiles) {
+  for (const candidate of extractCandidates) {
     if (!/\.(tsx?|mts|cts)$/i.test(candidate.path)) continue;
     try {
       arkRunManagedNews.push(
@@ -1264,7 +1372,7 @@ export function resolveCandidateFacts({
 
   if (planeRootPatterns.length > 0) {
     const factoryFiles = new Set(arkOrderPlaneCalls.map((call) => call.file));
-    for (const candidate of candidateFiles) {
+    for (const candidate of extractCandidates) {
       for (const pattern of planeRootPatterns) {
         try {
           if (!globToRegExp(pattern).test(candidate.path)) continue;
@@ -1284,7 +1392,7 @@ export function resolveCandidateFacts({
     const factoryFiles = new Set(
       arkRunKernelCalls.filter((call) => call.kind === 'factory').map((call) => call.file)
     );
-    for (const candidate of candidateFiles) {
+    for (const candidate of extractCandidates) {
       for (const pattern of compositionRootPatterns) {
         try {
           if (!globToRegExp(pattern).test(candidate.path)) continue;