arkgate 4.8.23 → 4.8.25

package/bin/lib/github-enforcement.mjs

@@ -6,6 +6,9 @@ import path from 'node:path';
 /** Kill hung gh instead of stalling CI. */
 export const SPAWN_TIMEOUT_MS = 8000;
 
+/** GitHub Actions app id: a required check bound to it can only be reported by a workflow job. */
+export const GITHUB_ACTIONS_APP_ID = 15368;
+
 function runGh(args, opts = {}) {
   const { run, ...rest } = opts;
   const spawn = typeof run === 'function' ? run : spawnSync;
@@ -18,11 +21,11 @@ function runGh(args, opts = {}) {
 
 const IF_LINE = /^[ \t]*(?:-\s+)?(?:"if"|'if'|if):\s*(.*?)\s*(?:#.*)?$/i;
 const CONTINUE_LINE = /^[ \t]*(?:-\s+)?(?:"continue-on-error"|'continue-on-error'|continue-on-error):\s*(.*?)\s*(?:#.*)?$/i;
-const SAFE_IF = /^(?:['"]?true['"]?|['"]?\$\{\{\s*(?:true|always\(\))\s*\}\}['"]?)$/i;
-const SAFE_NEEDS_IF = /^['"]?\$\{\{\s*always\(\)\s*\}\}['"]?$/i;
+const SAFE_IF = /^(?:['"]?true['"]?|['"]?(?:\$\{\{\s*(?:true|always\(\))\s*\}\}|always\(\))['"]?)$/i;
+const SAFE_NEEDS_IF = /^['"]?(?:\$\{\{\s*always\(\)\s*\}\}|always\(\))['"]?$/i;
 const SAFE_CONTINUE = /^['"]?false['"]?$/i;
 const ENV_PREFIX = /^(?:(?:env\s+)?(?:[A-Za-z_][A-Za-z0-9_]*=(?:"[^"]*"|'[^']*'|\S+)\s+)*)/;
-const DIRECT_ARK = /^(?:(?:npx|yarn)\s+(?:arkgate-check|ark-check)(?=\s|$)|pnpm(?:\s+--\S+)*\s+exec\s+(?:arkgate-check|ark-check)(?=\s|$)|node\s+(?:\S+\/)?bin\/(?:arkgate-check|ark-check)\.mjs(?=\s|$)|(?:arkgate-check|ark-check)(?=\s|$))/;
+const DIRECT_ARK = /^(?:(?:npx(?:\s+(?:-y|--yes))?(?:\s+(?:-p\s+|--package[\s=])arkgate(?:@\S+)?)?|yarn)\s+(?:arkgate-check|ark-check)(?=\s|$)|pnpm(?:\s+--\S+)*\s+exec\s+(?:arkgate-check|ark-check)(?=\s|$)|node\s+(?:\S+\/)?bin\/(?:arkgate-check|ark-check)\.mjs(?=\s|$)|(?:arkgate-check|ark-check)(?=\s|$))/;
 const CHECK_SCRIPT = /^(?:(?:npm|pnpm)\s+run\s+check:architecture(?=\s|$)|yarn(?:\s+run)?\s+check:architecture(?=\s|$))/;
 const FAIL_CLOSED = /(?:^|\s)--(?:strict|strict-merge|require-gates)(?=\s|$)/;
 
@@ -164,7 +167,7 @@ function propertyValue(line, pattern) {
   return line.match(pattern)?.[1]?.trim() ?? null;
 }
 
-function unsafeControl(lines, propertyIndent, needs = false) {
+function controlValues(lines, propertyIndent) {
   const atIndent = lines.filter((line) => {
     const indent = line.match(/^\s*/)?.[0].length ?? 0;
     return indent + (/^\s*-\s+/.test(line) ? 2 : 0) === propertyIndent;
@@ -173,9 +176,13 @@ function unsafeControl(lines, propertyIndent, needs = false) {
   const continuation = atIndent
     .map((line) => propertyValue(line, CONTINUE_LINE))
     .find((value) => value !== null);
+  return { condition, continuation };
+}
+
+function unsafeControl(lines, propertyIndent) {
+  const { condition, continuation } = controlValues(lines, propertyIndent);
   if (condition !== undefined && !SAFE_IF.test(condition)) return true;
-  if (continuation !== undefined && !SAFE_CONTINUE.test(continuation)) return true;
-  return needs && (condition === undefined || !SAFE_NEEDS_IF.test(condition));
+  return continuation !== undefined && !SAFE_CONTINUE.test(continuation);
 }
 
 function stepBounds(lines, runIndex, runIndent, inline) {
@@ -217,7 +224,7 @@ function unquoteRun(value) {
   return trimmed;
 }
 
-export function workflowRunText(text) {
+function workflowRunText(text) {
   const lines = String(text || '').split('\n');
   const commands = [];
   for (let index = 0; index < lines.length; index++) {
@@ -243,14 +250,90 @@ export function workflowRunText(text) {
   return commands.join('\n');
 }
 
-function jobCannotEnforce(job) {
+const NEEDS_LINE = /^\s*(?:"needs"|'needs'|needs):\s*(.*?)\s*(?:#.*)?$/;
+const JOB_ID = /^[A-Za-z0-9_-]+$/;
+
+function unquoteScalar(value) {
+  return String(value).trim().replace(/^(['"])(.*)\1$/, '$2').trim();
+}
+
+/** `needs:` as scalar, flow list, or block list. `valid: false` for expressions/malformed. */
+function jobNeeds(job) {
   const propertyIndent = jobPropertyIndent(job);
   const lines = job.body.split('\n');
-  const needs = lines.some((line) =>
-    (line.match(/^\s*/)?.[0].length ?? 0) === propertyIndent &&
-    /^\s*(?:"needs"|'needs'|needs):/.test(line)
+  const start = lines.findIndex((line) =>
+    (line.match(/^\s*/)?.[0].length ?? 0) === propertyIndent && NEEDS_LINE.test(line)
   );
-  return unsafeControl(lines, propertyIndent, needs);
+  if (start < 0) return { present: false, ids: [], valid: true };
+  const value = unquoteScalar(lines[start].match(NEEDS_LINE)[1]);
+  if (value) {
+    const raw = value.startsWith('[') && value.endsWith(']') ? value.slice(1, -1).split(',') : [value];
+    const ids = raw.map(unquoteScalar).filter((id) => JOB_ID.test(id));
+    return { present: true, ids, valid: ids.length > 0 && ids.length === raw.length };
+  }
+  const ids = [];
+  for (let index = start + 1; index < lines.length; index++) {
+    if (!lines[index].trim() || /^\s*#/.test(lines[index])) continue;
+    if ((lines[index].match(/^\s*/)?.[0].length ?? 0) <= propertyIndent) break;
+    const item = lines[index].match(/^\s*-\s*(['"]?)([A-Za-z0-9_-]+)\1\s*(?:#.*)?$/);
+    if (!item) return { present: true, ids: [], valid: false };
+    ids.push(item[2]);
+  }
+  return { present: true, ids, valid: ids.length > 0 };
+}
+
+/** 'always' | 'default' (absent, `true`, `${{ true }}` = implicit success()) | 'conditional'. */
+function jobConditionKind(job) {
+  const { condition } = controlValues(job.body.split('\n'), jobPropertyIndent(job));
+  if (condition === undefined) return 'default';
+  if (SAFE_NEEDS_IF.test(condition)) return 'always';
+  return SAFE_IF.test(condition) ? 'default' : 'conditional';
+}
+
+function jobIndex(jobs) {
+  return new Map(jobs.map((job) => [job.id, job]));
+}
+
+/**
+ * True when nothing in the `needs:` chain can intentionally skip this job.
+ *
+ * GitHub skips a job whose needed job failed, and a skipped job satisfies a required
+ * status check. An unconditional chain is still fail-closed for the *workflow*: its
+ * only skip path is an upstream failure that fails the same run. Whether that upstream
+ * failure also blocks the merge is a provider question, answered by required-status
+ * correlation over `upstreamJobs`. A conditional `if:` anywhere in the chain (for
+ * example a CI-profile output) is an intentional skip reported as success, so the job
+ * cannot enforce.
+ */
+function needsChainUnconditional(job, byId, seen = new Set()) {
+  const needs = jobNeeds(job);
+  if (!needs.present) return true;
+  if (!needs.valid || seen.has(job.id)) return false;
+  const nextSeen = new Set(seen).add(job.id);
+  return needs.ids.every((id) => {
+    const upstream = byId.get(id);
+    if (!upstream || nextSeen.has(id)) return false;
+    const kind = jobConditionKind(upstream);
+    if (kind === 'conditional') return false;
+    return kind === 'always' || needsChainUnconditional(upstream, byId, nextSeen);
+  });
+}
+
+function jobCannotEnforce(job, byId) {
+  if (unsafeControl(job.body.split('\n'), jobPropertyIndent(job))) return true;
+  if (jobConditionKind(job) === 'always') return false;
+  return !needsChainUnconditional(job, byId);
+}
+
+/** Jobs whose failure skips `job`; stops at `if: always()` upstreams, which still run. */
+function upstreamJobs(job, byId, out = new Map()) {
+  for (const id of jobNeeds(job).ids) {
+    const upstream = byId.get(id);
+    if (!upstream || out.has(id)) continue;
+    out.set(id, upstream);
+    if (jobConditionKind(upstream) !== 'always') upstreamJobs(upstream, byId, out);
+  }
+  return out;
 }
 
 function commandsRunArk(commands, script) {
@@ -261,9 +344,10 @@ function commandsEnforceArk(commands, script) {
   return analyzeCommands(commands, script).some((entry) => entry.enforcing && FAIL_CLOSED.test(entry.text));
 }
 
-export function activeWorkflowRunText(text) {
+function activeWorkflowRunText(text) {
   const jobs = workflowJobs(text);
-  return jobs.filter((job) => !jobCannotEnforce(job)).map((job) => workflowRunText(job.body)).join('\n');
+  const byId = jobIndex(jobs);
+  return jobs.filter((job) => !jobCannotEnforce(job, byId)).map((job) => workflowRunText(job.body)).join('\n');
 }
 
 export function runsArkCheck(text, script = '') {
@@ -322,12 +406,16 @@ function localArkContexts(root) {
   const known = new Set();
   const occurrences = new Map();
   const arkOccurrences = new Map();
+  // context -> contexts whose failure would skip it (null = an upstream has no literal context)
+  const upstream = new Map();
   let dynamic = false;
   for (const workflow of workflowFiles(root)) {
-    for (const job of workflowJobs(workflow.text)) {
+    const jobs = workflowJobs(workflow.text);
+    const byId = jobIndex(jobs);
+    for (const job of jobs) {
       const explicit = jobName(job);
       const matrix = jobHasMatrix(job);
-      const enforcing = !jobCannotEnforce(job) &&
+      const enforcing = !jobCannotEnforce(job, byId) &&
         commandsEnforceArk(workflowRunText(job.body), script);
       if (enforcing) {
         known.add(job.id);
@@ -339,7 +427,15 @@ function localArkContexts(root) {
       }
       const context = explicit.name ?? job.id;
       occurrences.set(context, (occurrences.get(context) ?? 0) + 1);
-      if (enforcing) arkOccurrences.set(context, (arkOccurrences.get(context) ?? 0) + 1);
+      if (enforcing) {
+        arkOccurrences.set(context, (arkOccurrences.get(context) ?? 0) + 1);
+        const skippers = jobConditionKind(job) === 'always' ? [] : [...upstreamJobs(job, byId).values()];
+        const names = skippers.map((needed) => {
+          const neededName = jobName(needed);
+          return neededName.dynamic || jobHasMatrix(needed) ? null : neededName.name ?? needed.id;
+        });
+        upstream.set(context, names.includes(null) ? null : names);
+      }
     }
   }
   const contexts = new Set();
@@ -347,7 +443,19 @@ function localArkContexts(root) {
     if (count === 1 && occurrences.get(context) === 1) contexts.add(context);
     else dynamic = true;
   }
-  return { contexts, known, dynamic };
+  return { contexts, known, dynamic, upstream };
+}
+
+/**
+ * Required-status names that must also be required so an upstream failure (which skips
+ * the Ark job, and a skipped job satisfies branch protection) still blocks the merge.
+ * Returns [] when the chain is closed, otherwise the missing names ('<dynamic>' when an
+ * upstream only has a matrix/expression name that cannot be required exactly).
+ */
+function unrequiredUpstream(local, context, requiredNames) {
+  const names = local.upstream.get(context);
+  if (names === null) return ['<dynamic>'];
+  return (names ?? []).filter((name) => !requiredNames.has(name));
 }
 
 /** Historical name retained; the set also contains literal, non-dynamic job names. */
@@ -357,17 +465,31 @@ export function jobIdsThatRunArkCheck(root) {
 
 export function isArkRequiredStatusCheck(root, requiredNames) {
   if (!Array.isArray(requiredNames) || requiredNames.length === 0) return false;
-  const local = localArkContexts(root).contexts;
-  return requiredNames.some((name) => local.has(String(name)));
+  const local = localArkContexts(root);
+  const required = new Set(requiredNames.map(String));
+  return [...required].some((name) =>
+    local.contexts.has(name) && unrequiredUpstream(local, name, required).length === 0
+  );
 }
 
-function classifyRequired(root, legacyContexts, checks, bindingField) {
-  const local = localArkContexts(root);
+/**
+ * `requiredNames` is every required context across classic protection and rulesets: an
+ * Ark context only counts as required when each job that can skip it is required too.
+ */
+function classifyRequired(local, legacyContexts, checks, bindingField, requiredNames) {
   const exact = (name) => local.contexts.has(String(name));
+  const closed = (name) => unrequiredUpstream(local, String(name), requiredNames).length === 0;
   const matching = checks.filter((check) => exact(check.context));
-  if (matching.some((check) => check[bindingField] == null || check[bindingField] === -1)) return true;
+  // Unbound (any source) or bound to the GitHub Actions app that runs the local workflow job.
+  const satisfiable = matching.filter((check) =>
+    check[bindingField] == null || check[bindingField] === -1 ||
+    check[bindingField] === GITHUB_ACTIONS_APP_ID
+  );
+  if (satisfiable.some((check) => closed(check.context))) return true;
   if (matching.length > 0) return 'unverified';
-  if (legacyContexts.some(exact)) return true;
+  const legacy = legacyContexts.filter(exact);
+  if (legacy.some(closed)) return true;
+  if (legacy.length > 0) return 'unverified';
   return local.dynamic && (legacyContexts.length > 0 || checks.length > 0)
     ? 'unverified'
     : false;
@@ -421,7 +543,7 @@ export function classifyGithubProviderFailure(errorText, opts = {}) {
  * @param {{ name?: string, workflowName?: string, displayTitle?: string }} run
  * @returns {boolean}
  */
-export function isArkishCiRun(run) {
+function isArkishCiRun(run) {
   const blob = `${run?.name || ''} ${run?.workflowName || ''} ${run?.displayTitle || ''}`.toLowerCase();
   if (!blob.trim()) return false;
   // Product tokens with word boundaries (avoid spark, dark, lark false positives).
@@ -558,18 +680,32 @@ export function reportGithubBranchProtection(opts = {}) {
         })).filter((check) => check.context)
     : [];
   const hasWorkflowRule = rulesAvailable && rules.some((rule) => rule?.type === 'workflows');
+  const all = [...new Set([...contexts, ...checks.map((check) => check.context), ...statusRules.map((check) => check.context)])];
+  const requiredNames = new Set(all);
+  const local = localArkContexts(cwd);
   const classicRequired = classicAvailable
-    ? classifyRequired(cwd, contexts, checks, 'app_id')
+    ? classifyRequired(local, contexts, checks, 'app_id', requiredNames)
     : 'unverified';
   const rulesRequired = rulesAvailable
-    ? classifyRequired(cwd, [], statusRules, 'integration_id')
+    ? classifyRequired(local, [], statusRules, 'integration_id', requiredNames)
     : 'unverified';
   const arkCheckRequired = combineRequired(
     classicRequired, rulesRequired, classicAvailable, rulesAvailable, hasWorkflowRule
   );
-  const arkCheckSourceBound = arkCheckRequired === true ? false : 'unverified';
+  // true only when every required Ark check is bound to GitHub Actions; unbound or
+  // legacy-context-only requirements can be satisfied by any status writer.
+  const arkBindings = [
+    ...checks.map((check) => ({ context: check.context, id: check.app_id })),
+    ...statusRules.map((check) => ({ context: check.context, id: check.integration_id })),
+  ].filter((check) => local.contexts.has(check.context));
+  const arkCheckSourceBound = arkCheckRequired !== true
+    ? 'unverified'
+    : arkBindings.length > 0 && arkBindings.every((check) => check.id === GITHUB_ACTIONS_APP_ID);
   const available = arkCheckRequired === true || (classicAvailable && rulesAvailable);
-  const all = [...new Set([...contexts, ...checks.map((check) => check.context), ...statusRules.map((check) => check.context)])];
+  // Required Ark contexts that an unrequired upstream failure could skip (reported as success).
+  const arkCheckUpstreamNotRequired = [...new Set(all
+    .filter((name) => local.contexts.has(name))
+    .flatMap((name) => unrequiredUpstream(local, name, requiredNames)))];
   const error = `${classicResult.stderr || ''}${rulesResult.stderr || ''}`.slice(0, 400);
 
   let reason = available ? 'ok' : 'provider-enforcement-unverified';
@@ -607,6 +743,7 @@ export function reportGithubBranchProtection(opts = {}) {
     enforcesAdmins: classicAvailable ? Boolean(classic.enforcesAdmins) : null,
     arkCheckRequired,
     arkCheckSourceBound,
+    arkCheckUpstreamNotRequired,
     // hard merge remains false when status is not proven required
     hard: arkCheckRequired === true ? undefined : false,
     runtimeObserved: ciRuntime.runtimeObserved === true,

package/bin/lib/golden-pattern.mjs

@@ -10,7 +10,7 @@ import path from 'node:path';
 /** Relative path from project root (stable contract). */
 export const GOLDEN_PATTERN_REL = '.ark/golden-pattern.json';
 
-export const GOLDEN_PATTERN_SCHEMA_VERSION = '1';
+const GOLDEN_PATTERN_SCHEMA_VERSION = '1';
 
 /**
  * @typedef {{

package/bin/lib/hook-templates.mjs

@@ -1,22 +1,24 @@
 // Generated from hook-templates.source.mjs — run npm run generate:packaged-tooling.
-import{execCommandParts as l,execRunner as i}from"../ark-shared.mjs";const s="arkgate-mcp";function h(e){const r=i(e);return`${JSON.stringify({version:1,hooks:{preToolUse:[{command:`${r} ${s} --hook --hook-repair --fail-on-new-smells --root . --root-env CURSOR_PROJECT_DIR --config ark.config.json`,matcher:"Write|StrReplace",failClosed:!0,timeout:30}]}},null,2)}
-`}function y(e){const r=i(e);return`${JSON.stringify({hooks:{SessionStart:[{hooks:[{type:"command",command:`${r} ${s} --session-context --root . --root-env CLAUDE_PROJECT_DIR --config ark.config.json`}]}],PreToolUse:[{matcher:"Write|Edit|MultiEdit",hooks:[{type:"command",command:`${r} ${s} --hook --hook-repair --fail-on-new-smells --root . --root-env CLAUDE_PROJECT_DIR --config ark.config.json`}]}]}},null,2)}
-`}function $(e){const r=i(e);return`${JSON.stringify({hooks:{SessionStart:[{hooks:[{type:"command",timeout:30,command:`${r} ${s} --session-context --root . --root-env CODEX_PROJECT_DIR --config ark.config.json`}]}],PreToolUse:[{matcher:"ApplyPatch|apply_patch|Write|Edit|MultiEdit",hooks:[{type:"command",timeout:30,command:`${r} ${s} --hook --hook-repair --fail-on-new-smells --root . --root-env CODEX_PROJECT_DIR --config ark.config.json`}]}]}},null,2)}
-`}function O(e){const{command:r,args:o}=l(e,s,["--root",".","--config","ark.config.json"]),t=a=>a.replace(/\\/g,"\\\\").replace(/"/g,'\\"'),c=o.map(a=>`"${t(a)}"`).join(", ");return`# Generated by ark-check --install-agent-gates (Codex project scope).
+import{execCommandParts as h,execRunner as d}from"../ark-shared.mjs";const m="arkgate-mcp";function y(t,r){let o,e;try{o=t&&t.trim()?JSON.parse(t):{},e=JSON.parse(r)}catch{return null}return!o||typeof o!="object"||Array.isArray(o)||!e||typeof e!="object"||Array.isArray(e)?null:{existing:o,generated:e}}function x(t){const r=d(t);return`${JSON.stringify({version:1,hooks:{preToolUse:[{command:`${r} ${m} --hook --hook-repair --fail-on-new-smells --root . --root-env CURSOR_PROJECT_DIR --config ark.config.json`,matcher:"Write|StrReplace",failClosed:!0,timeout:30}]}},null,2)}
+`}function _(t){const r=d(t);return`${JSON.stringify({hooks:{SessionStart:[{hooks:[{type:"command",command:`${r} ${m} --session-context --root . --root-env CLAUDE_PROJECT_DIR --config ark.config.json`}]}],PreToolUse:[{matcher:"Write|Edit|MultiEdit",hooks:[{type:"command",command:`${r} ${m} --hook --hook-repair --fail-on-new-smells --root . --root-env CLAUDE_PROJECT_DIR --config ark.config.json`}]}]}},null,2)}
+`}function S(t){const r=d(t);return`${JSON.stringify({hooks:{SessionStart:[{hooks:[{type:"command",timeout:30,command:`${r} ${m} --session-context --root . --root-env CODEX_PROJECT_DIR --config ark.config.json`}]}],PreToolUse:[{matcher:"ApplyPatch|apply_patch|Write|Edit|MultiEdit",hooks:[{type:"command",timeout:30,command:`${r} ${m} --hook --hook-repair --fail-on-new-smells --root . --root-env CODEX_PROJECT_DIR --config ark.config.json`}]}]}},null,2)}
+`}function C(t){const{command:r,args:o}=h(t,m,["--root",".","--config","ark.config.json"]),e=n=>n.replace(/\\/g,"\\\\").replace(/"/g,'\\"'),s=o.map(n=>`"${e(n)}"`).join(", ");return`# Generated by ark-check --install-agent-gates (Codex project scope).
 # CONFIGURED ON DISK \u2014 RUNTIME NOT VERIFIED.
 # Restart Codex, then call ark_identity with expectedRoot before trusting MCP verdicts.
 [mcp_servers.ark]
-command = "${t(r)}"
-args = [${c}]
-`}function R(e){const{command:r,args:o}=l(e,s,["--root",".","--config","ark.config.json"]),t=o.map(c=>`"${c.replace(/\\/g,"\\\\").replace(/"/g,'\\"')}"`).join(", ");return`# Generated by ark-check --install-agent-gates (Grok Build project scope).
+command = "${e(r)}"
+args = [${s}]
+`}function E(t){const{command:r,args:o}=h(t,m,["--root",".","--config","ark.config.json"]),e=o.map(s=>`"${s.replace(/\\/g,"\\\\").replace(/"/g,'\\"')}"`).join(", ");return`# Generated by ark-check --install-agent-gates (Grok Build project scope).
 # Restart Grok (or /mcps \u2192 refresh) after changes. Also loads repo-root .mcp.json.
 [mcp_servers.ark]
 command = "${r.replace(/\\/g,"\\\\").replace(/"/g,'\\"')}"
-args = [${t}]
-`}function _(e){const r=i(e);return`${JSON.stringify({hooks:{SessionStart:[{hooks:[{type:"command",timeout:30,command:`${r} ${s} --session-context --root . --root-env GROK_WORKSPACE_ROOT,CLAUDE_PROJECT_DIR --config ark.config.json`}]}],PreToolUse:[{matcher:"Write|Edit|MultiEdit|write|search_replace",hooks:[{type:"command",timeout:30,command:`${r} ${s} --hook --hook-repair --fail-on-new-smells --root . --root-env GROK_WORKSPACE_ROOT,CLAUDE_PROJECT_DIR --config ark.config.json`}]}]}},null,2)}
-`}function A(e){const r=i(e);return`${JSON.stringify({"ark-write-gate":{PreToolUse:[{matcher:"write_to_file|replace_file_content|multi_replace_file_content",hooks:[{type:"command",timeout:30,command:`${r} ${s} --hook --hook-repair --fail-on-new-smells --root . --config ark.config.json`}]}]}},null,2)}
-`}function j(e){const{command:r,args:o}=l(e,s,["--root",".","--config","ark.config.json"]);return`${JSON.stringify({$schema:"https://opencode.ai/config.json",mcp:{ark:{type:"local",command:[r,...o],enabled:!0}}},null,2)}
-`}function E(e,r){let o,t;try{o=e&&e.trim()?JSON.parse(e):{},t=JSON.parse(r)}catch{return null}if(!o||typeof o!="object"||Array.isArray(o)||!t||typeof t!="object"||Array.isArray(t))return null;const c=t.hooks,p=(Array.isArray(c?.preToolUse)?c.preToolUse:[]).find(n=>n&&typeof n=="object"&&typeof n.command=="string"&&/arkgate-mcp|ark-mcp/.test(n.command)&&/\s--hook(?:\s|$)/.test(` ${n.command} `));if(!p)return null;const m=o.hooks&&typeof o.hooks=="object"&&!Array.isArray(o.hooks)?{...o.hooks}:{},f=Array.isArray(m.preToolUse)?[...m.preToolUse]:[],k=n=>n&&typeof n=="object"&&typeof n.command=="string"&&/arkgate-mcp|ark-mcp/.test(n.command)&&/\s--hook(?:\s|$)/.test(` ${n.command} `)&&(typeof n.matcher!="string"||/Write/.test(n.matcher)||/StrReplace/.test(n.matcher)),g=f.filter(n=>!k(n));m.preToolUse=[...g,p];const u={...o,version:o.version??t.version??1,hooks:m};return`${JSON.stringify(u,null,2)}
-`}function S(e,r){let o,t;try{o=e&&e.trim()?JSON.parse(e):{},t=JSON.parse(r)}catch{return null}if(!o||typeof o!="object"||Array.isArray(o)||!t||typeof t!="object"||Array.isArray(t))return null;const c=t["ark-write-gate"];if(!c||typeof c!="object")return null;const a={...o,"ark-write-gate":c};return`${JSON.stringify(a,null,2)}
-`}function C(e,r){let o,t;try{o=e&&e.trim()?JSON.parse(e):{},t=JSON.parse(r)}catch{return null}if(!o||typeof o!="object"||Array.isArray(o))return null;const c={...o};!c.$schema&&t.$schema&&(c.$schema=t.$schema);const a=o.mcp&&typeof o.mcp=="object"&&!Array.isArray(o.mcp)?{...o.mcp}:{};return a.ark=t.mcp.ark,c.mcp=a,`${JSON.stringify(c,null,2)}
-`}export{s as PREFERRED_MCP_BIN,A as antigravityHooks,y as claudeSettings,$ as codexHooks,O as codexProjectConfig,h as cursorHooks,_ as grokHooks,R as grokProjectConfig,S as mergeAntigravityArkHook,E as mergeCursorArkHook,C as mergeOpencodeArkMcp,j as opencodeProjectConfig};
+args = [${e}]
+`}function v(t){const r=d(t);return`${JSON.stringify({hooks:{SessionStart:[{hooks:[{type:"command",timeout:30,command:`${r} ${m} --session-context --root . --root-env GROK_WORKSPACE_ROOT,CLAUDE_PROJECT_DIR --config ark.config.json`}]}],PreToolUse:[{matcher:"Write|Edit|MultiEdit|write|search_replace",hooks:[{type:"command",timeout:30,command:`${r} ${m} --hook --hook-repair --fail-on-new-smells --root . --root-env GROK_WORKSPACE_ROOT,CLAUDE_PROJECT_DIR --config ark.config.json`}]}]}},null,2)}
+`}function J(t){const r=d(t);return`${JSON.stringify({"ark-write-gate":{PreToolUse:[{matcher:"write_to_file|replace_file_content|multi_replace_file_content",hooks:[{type:"command",timeout:30,command:`${r} ${m} --hook --hook-repair --fail-on-new-smells --root . --config ark.config.json`}]}]}},null,2)}
+`}function P(t){const{command:r,args:o}=h(t,m,["--root",".","--config","ark.config.json"]);return`${JSON.stringify({$schema:"https://opencode.ai/config.json",mcp:{ark:{type:"local",command:[r,...o],enabled:!0}}},null,2)}
+`}function N(t,r){const o=y(t,r);if(!o)return null;const{existing:e,generated:s}=o,n=s.hooks,p=(Array.isArray(n?.preToolUse)?n.preToolUse:[]).find(c=>c&&typeof c=="object"&&typeof c.command=="string"&&/arkgate-mcp|ark-mcp/.test(c.command)&&/\s--hook(?:\s|$)/.test(` ${c.command} `));if(!p)return null;const i=e.hooks&&typeof e.hooks=="object"&&!Array.isArray(e.hooks)?{...e.hooks}:{},l=Array.isArray(i.preToolUse)?[...i.preToolUse]:[],u=c=>c&&typeof c=="object"&&typeof c.command=="string"&&/arkgate-mcp|ark-mcp/.test(c.command)&&/\s--hook(?:\s|$)/.test(` ${c.command} `)&&(typeof c.matcher!="string"||/Write/.test(c.matcher)||/StrReplace/.test(c.matcher)),a=l.filter(c=>!u(c));i.preToolUse=[...a,p];const f={...e,version:e.version??s.version??1,hooks:i};return`${JSON.stringify(f,null,2)}
+`}const $=/(?:^|[\s/])(?:arkgate-mcp|ark-mcp)(?:\.mjs)?(?:\s|$)/,b=/\s--(?:hook|session-context)(?:\s|$)/;function j(t){return!!t&&typeof t=="object"&&typeof t.command=="string"&&$.test(` ${t.command} `)&&b.test(` ${t.command} `)}function T(t,r){const o=y(t,r);if(!o)return null;const{existing:e,generated:s}=o,n=s.hooks;if(!n||typeof n!="object"||e.hooks!==void 0&&(!e.hooks||typeof e.hooks!="object"||Array.isArray(e.hooks)))return null;const k={...e.hooks??{}};for(const[p,i]of Object.entries(n)){if(!Array.isArray(i))continue;const l=k[p];if(l!==void 0&&!Array.isArray(l))return null;const u=[];for(const a of l??[]){if(!a||typeof a!="object"||!Array.isArray(a.hooks)){u.push(a);continue}const f=a.hooks.filter(c=>!j(c));f.length===a.hooks.length?u.push(a):f.length>0&&u.push({...a,hooks:f})}k[p]=[...u,...i]}return`${JSON.stringify({...e,hooks:k},null,2)}
+`}function g(t){const r=o=>typeof o=="string"?o.replace(/arkgate@[^\s"']+/g,"arkgate@*"):Array.isArray(o)?o.map(r):o&&typeof o=="object"?Object.fromEntries(Object.keys(o).sort().map(e=>[e,r(o[e])])):o;return JSON.stringify(r(t))}function A(t,r){try{const o=JSON.parse(t),e=JSON.parse(r);return!o||typeof o!="object"||Array.isArray(o)||!e||typeof e!="object"||Array.isArray(e)?null:{existing:o,generated:e}}catch{return null}}function O(t){return{status:"removed",text:Object.keys(t).length===0?null:`${JSON.stringify(t,null,2)}
+`}}function U(t,r){const o=A(t,r);if(!o)return{status:"unreadable"};const{existing:e,generated:s}=o;if(e.hooks===void 0)return{status:"absent"};if(!e.hooks||typeof e.hooks!="object"||Array.isArray(e.hooks))return{status:"unreadable"};const n={...e.hooks};let k=0;for(const[i,l]of Object.entries(s.hooks??{})){if(!Array.isArray(l)||n[i]===void 0)continue;if(!Array.isArray(n[i]))return{status:"unreadable"};const u=new Set(l.map(g)),a=[];for(const f of n[i]){if(!(f&&typeof f=="object"&&Array.isArray(f.hooks)&&f.hooks.some(j))){a.push(f);continue}if(!u.has(g(f)))return{status:"customized"};k+=1}a.length>0?n[i]=a:delete n[i]}if(k===0)return{status:"absent"};const p={...e,hooks:n};return Object.keys(n).length===0&&delete p.hooks,O(p)}function D(t,r){const o=A(t,r);if(!o)return{status:"unreadable"};const{existing:e,generated:s}=o,n=e.hooks?.preToolUse;if(n===void 0)return{status:"absent"};if(!Array.isArray(n))return{status:"unreadable"};const k=new Set((Array.isArray(s.hooks?.preToolUse)?s.hooks.preToolUse:[]).map(g)),p=[];let i=0;for(const a of n){if(!(a&&typeof a=="object"&&typeof a.command=="string"&&/arkgate-mcp|ark-mcp/.test(a.command)&&/\s--hook(?:\s|$)/.test(` ${a.command} `))){p.push(a);continue}if(!k.has(g(a)))return{status:"customized"};i+=1}if(i===0)return{status:"absent"};const l={...e.hooks};p.length>0?l.preToolUse=p:delete l.preToolUse;const u={...e,hooks:l};return Object.keys(l).length===0&&delete u.hooks,Object.keys(u).length===1&&u.version===(s.version??1)&&delete u.version,O(u)}function H(t,r){const o=A(t,r);if(!o)return{status:"unreadable"};const{existing:e,generated:s}=o;if(!Object.prototype.hasOwnProperty.call(e,"ark-write-gate"))return{status:"absent"};if(g(e["ark-write-gate"])!==g(s["ark-write-gate"]))return{status:"customized"};const n={...e};return delete n["ark-write-gate"],O(n)}function w(t,r){const o=y(t,r);if(!o)return null;const{existing:e,generated:s}=o,n=s["ark-write-gate"];if(!n||typeof n!="object")return null;const k={...e,"ark-write-gate":n};return`${JSON.stringify(k,null,2)}
+`}function I(t,r){let o,e;try{o=t&&t.trim()?JSON.parse(t):{},e=JSON.parse(r)}catch{return null}if(!o||typeof o!="object"||Array.isArray(o))return null;const s={...o};!s.$schema&&e.$schema&&(s.$schema=e.$schema);const n=o.mcp&&typeof o.mcp=="object"&&!Array.isArray(o.mcp)?{...o.mcp}:{};return n.ark=e.mcp.ark,s.mcp=n,`${JSON.stringify(s,null,2)}
+`}export{m as PREFERRED_MCP_BIN,J as antigravityHooks,_ as claudeSettings,S as codexHooks,C as codexProjectConfig,x as cursorHooks,v as grokHooks,E as grokProjectConfig,w as mergeAntigravityArkHook,T as mergeClaudeStyleArkHooks,N as mergeCursorArkHook,I as mergeOpencodeArkMcp,P as opencodeProjectConfig,y as parseJsonMergeInputs,H as removeAntigravityArkHook,U as removeClaudeStyleArkHooks,D as removeCursorArkHook};

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

@@ -37,7 +37,9 @@ function hostProfile(label, hookPath, hookSurface, hookOperations, hardWrite, re
     }),
     // 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.
+    // unsupported = host has no documented flag. ark-mcp --hook fails closed itself
+    // (exit 2 / host deny) when its checker cannot run for a governed source write;
+    // only a crash of node itself before the launcher runs stays 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).

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

@@ -14,6 +14,8 @@ import { formatArkRunHtml } from './ark-run-report.mjs';
 import { formatArkOrderHtml } from './ark-order-report.mjs';
 import { primaryImprovementCompassNextAction } from './improvement-compass.mjs';
 import { flatParentPilotHtml } from './flat-parent-pilot.mjs';
+import { orphanModulesHtml } from './orphan-modules-io.mjs';
+import { crossWallDuplicationHtml } from './duplication-io.mjs';
 
 // htmlEscape is injected by the caller (html-report.mjs) — importing it back
 // would be a dependency cycle, and the repo's own gate blocks that. The
@@ -362,6 +364,8 @@ export function renderAdvisorySections(advisories, escape) {
     physicalCohesionHtml(advisories.physicalCohesion),
     parseHealthHtml(advisories.parseHealth),
     graphBlindSpotsHtml(advisories.graphBlindSpots, esc),
+    orphanModulesHtml(advisories.orphanModules, esc),
+    crossWallDuplicationHtml(advisories.crossWallDuplication, esc),
     rulesUnderContractHtml(advisories.rulesUnderContract),
     formatArkRunHtml(advisories.arkRun, esc),
     formatArkOrderHtml(advisories.arkOrder, esc),

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

@@ -28,7 +28,7 @@ import { buildDeepModuleCoachAdvisory } from './deep-module-coach.mjs';
 import { computePhysicalCohesion } from './physical-cohesion.mjs';
 import { computeReshapeDecisionMemory } from './reshape-decisions.mjs';
 import { POST_GREEN_LEDE, operatingModeTitle } from './product-copy.mjs';
-import { anyChildWallAdvisory, anySliceAlias } from '../ark-layer-match.mjs';
+import { anyChildWallAdvisory, sliceAliasOwesMove } from '../ark-layer-match.mjs';
 
 function esc(value) {
   return String(value)
@@ -176,7 +176,7 @@ export function buildReportDepthPayload(
     primaryNextAction: postGreenPath?.action ?? dualTruthNext,
     activeBlockingViolations: activeBlockingCount,
     physicalCohesionResidual: physicalCohesionResidualRemains(physicalCohesion), childWallAdvisory: anyChildWallAdvisory(config?.rules),
-    sliceAliasDebt: anySliceAlias(config?.rules),
+    sliceAliasDebt: sliceAliasOwesMove(config?.rules),
   });
   // Doctor parity: same physical-cohesion + baseline stale facts as runDoctor.
   const baselineStale =

package/bin/lib/html-report.mjs

@@ -11,7 +11,7 @@ import {
   resolveOperatingMode,
 } from '../ark-shared.mjs';
 import { collectAdoptionGaps, arkCheckCommand } from './agent-gates.mjs';
-import { LEFTOVER_DESIGN_BADGE } from './product-copy.mjs';
+import { LEFTOVER_DESIGN_LABEL } from './product-copy.mjs';
 import { CORE_LAYER_NAMES } from './core-layers.mjs';
 import {
   renderBaselineSignalLegend,
@@ -572,7 +572,7 @@ export function renderHtmlReport({
   const designSmells = Array.isArray(depth.designSmells) ? depth.designSmells : [];
   const designWeakBadge =
     designFitness?.designWeak === true
-      ? ` <span class="badge design" title="Import rules can be green while leftover design work remains. Not a FAIL.">${LEFTOVER_DESIGN_BADGE}</span>`
+      ? ` <span class="badge design" title="Import rules can be green while leftover design work remains. Not a FAIL.">${LEFTOVER_DESIGN_LABEL}</span>`
       : '';
   const designStripHtml =
     renderDesignDepthStrip({

package/bin/lib/import-graph-projection.mjs

@@ -0,0 +1,112 @@
+/**
+ * Compact importer index for doctor and report (ADR 0037 D1).
+ *
+ * The scan releases the resolved facts right after the verdict (memory). This
+ * keeps only what the files-nothing-imports advisory and the flat-parent
+ * suggestion read: governed paths, incoming edge counts, the edge list as
+ * typed-array pairs, and which export names each target is imported by. It is
+ * a projection of facts that already exist — never an input to the verdict.
+ */
+
+/** Unresolved project-looking specifiers kept for `maybe-unresolved` matching. */
+const MAX_UNRESOLVED_SPECIFIERS = 200;
+/** A bare specifier that looks like a project alias rather than a package. */
+const ALIAS_LIKE = /^(?:[@~#$]\/|[~#$])/;
+
+function looksLikeProjectSpecifier(specifier) {
+  return typeof specifier === 'string' && (specifier.startsWith('.') || ALIAS_LIKE.test(specifier));
+}
+
+/**
+ * @param {{ files?: Array<{ path: string, parseStatus?: string }>, dependencies?: Array<object>, completeness?: string }} facts
+ * @returns {{
+ *   files: string[],
+ *   importerCount: Uint32Array,
+ *   edges: Int32Array,
+ *   namedUse: Map<number, Set<string> | '*'>,
+ *   unresolved: Array<{ from: string, specifier: string }>,
+ *   unresolvedTotal: number,
+ *   dynamicSites: number,
+ *   invalidFiles: number,
+ *   completeness: string,
+ * }}
+ */
+export function projectImporterIndex(facts) {
+  const files = [];
+  const indexOf = new Map();
+  let invalidFiles = 0;
+  for (const file of Array.isArray(facts?.files) ? facts.files : []) {
+    if (typeof file?.path !== 'string' || indexOf.has(file.path)) continue;
+    indexOf.set(file.path, files.length);
+    files.push(file.path);
+    if (file.parseStatus === 'invalid') invalidFiles += 1;
+  }
+  const importerCount = new Uint32Array(files.length);
+  const pairs = [];
+  const namedUse = new Map();
+  const unresolved = [];
+  let unresolvedTotal = 0;
+  let dynamicSites = 0;
+  for (const dep of Array.isArray(facts?.dependencies) ? facts.dependencies : []) {
+    if (dep?.resolution === 'dynamic') {
+      dynamicSites += 1;
+      continue;
+    }
+    if (dep?.resolution === 'unresolved') {
+      if (!looksLikeProjectSpecifier(dep.specifier)) continue;
+      unresolvedTotal += 1;
+      if (unresolved.length < MAX_UNRESOLVED_SPECIFIERS) {
+        unresolved.push({ from: dep.from, specifier: dep.specifier });
+      }
+      continue;
+    }
+    if (dep?.resolution !== 'resolved-project') continue;
+    const from = indexOf.get(dep.from);
+    const to = indexOf.get(dep.target);
+    if (from === undefined || to === undefined || from === to) continue;
+    pairs.push(from, to);
+    importerCount[to] += 1;
+    const previous = namedUse.get(to);
+    if (previous === '*') continue;
+    // Default, namespace, side-effect, dynamic, require and `export *` carry no
+    // names: any export may be used through them.
+    const named = Array.isArray(dep.namedBindings) && dep.namedBindings.length > 0 ? dep.namedBindings : null;
+    if (!named) {
+      namedUse.set(to, '*');
+      continue;
+    }
+    const set = previous ?? new Set();
+    for (const name of named) set.add(name);
+    namedUse.set(to, set);
+  }
+  return {
+    files,
+    importerCount,
+    edges: Int32Array.from(pairs),
+    namedUse,
+    unresolved,
+    unresolvedTotal,
+    dynamicSites,
+    invalidFiles,
+    completeness: typeof facts?.completeness === 'string' ? facts.completeness : 'unavailable',
+  };
+}
+
+/**
+ * target path → every governed file that imports it (the flat-parent graph).
+ * @param {ReturnType<typeof projectImporterIndex>} index
+ */
+export function importerGraphFromIndex(index) {
+  const graph = new Map();
+  const { files, edges } = index;
+  for (let i = 0; i + 1 < edges.length; i += 2) {
+    const target = files[edges[i + 1]];
+    let set = graph.get(target);
+    if (!set) {
+      set = new Set();
+      graph.set(target, set);
+    }
+    set.add(files[edges[i]]);
+  }
+  return graph;
+}

package/bin/lib/import-resolve.mjs

@@ -56,7 +56,19 @@ export function readTsconfigAliases(ts, root) {
     if (!configPath) return { baseUrl: root, aliases: [] };
     const read = ts.readConfigFile(configPath, ts.sys.readFile);
     if (read.error) return { baseUrl: root, aliases: [] };
-    const parsed = ts.parseJsonConfigFileContent(read.config, ts.sys, path.dirname(configPath));
+    // Options-only parse: `fileNames` are unused here. With the real `ts.sys` the
+    // parser walked the whole `include` tree on every write-hook call (#205 twin).
+    const optionsOnlyHost = {
+      useCaseSensitiveFileNames: ts.sys.useCaseSensitiveFileNames,
+      readDirectory: () => [],
+      fileExists: (fileName) => ts.sys.fileExists(fileName),
+      readFile: (fileName) => ts.sys.readFile(fileName),
+    };
+    const parsed = ts.parseJsonConfigFileContent(
+      read.config,
+      optionsOnlyHost,
+      path.dirname(configPath)
+    );
     const opts = parsed.options || {};
     const baseUrl = opts.baseUrl || path.dirname(configPath);
     const aliases = [];

package/bin/lib/improvement-compass-doctor.mjs

@@ -2,11 +2,7 @@
  * Doctor adapter for the Domain improvement compass (notAScore projection).
  * Keeps doctor-plan.mjs inside its module budget; pure assembly only.
  */
-import {
-  buildImprovementCompass,
-  formatImprovementCompassDoctorLines,
-  primaryImprovementCompassNextAction,
-} from './improvement-compass.mjs';
+import { buildImprovementCompass } from './improvement-compass.mjs';
 
 /**
  * @param {{
@@ -92,22 +88,3 @@ export function buildDoctorImprovementCompass(input = {}) {
   });
 }
 
-export {
-  formatImprovementCompassDoctorLines,
-  primaryImprovementCompassNextAction,
-};
-
-/**
- * Human doctor section (never a score bar).
- * @param {import('./improvement-compass.mjs').ImprovementCompass} compass
- * @param {{ line: Function, warn: string, ok: string, color: { bold: Function } }} io
- */
-export function printImprovementCompassSection(compass, io) {
-  const { line, warn, ok, color } = io;
-  console.log('');
-  console.log(color.bold('Improvement compass (not a score)'));
-  const mark = compass.topResidual.length > 0 ? warn : ok;
-  for (const text of formatImprovementCompassDoctorLines(compass)) {
-    line(mark, text);
-  }
-}