arkgate 4.1.1 → 4.2.0

package/bin/lib/agent-gates.mjs

@@ -103,6 +103,7 @@ export {
   assessCodexSkillParity,
   assessSkillCatalogParity,
   detectSkillGaps,
+  skillGapsForActiveHost,
   agentsMdSkillRefs,
   verifyHostSkillCatalog,
   printSkillAndCodexGapHints,

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

@@ -183,9 +183,11 @@ export function ensureCheckArchitectureScript(root, opts = {}) {
 // source so the steps can never drift out of sync between the two files. `steps(checkCommand)`
 // is a builder because the check command's runner prefix varies with the package manager.
 const AGENT_CONTRACT = {
-  manifestResource: 'ark://manifest',
+  manifestTool: 'ark_manifest',
+  compatibilityManifestResource: 'ark://manifest',
   steps: (checkCommand) => [
-    `Read the Ark contract from \`ark://manifest\` when the MCP server is available.`,
+    `Before trusting Ark MCP evidence, call \`ark_identity\` with \`project.expectedRoot\` set to the exact project root's absolute path. Reuse that root plus the returned \`projectIdentity.projectId\` on every Ark MCP call. A descendant path is authoritative only when the matching project id is also supplied. If the tool is missing, the binding is not \`matched\`, or the reported root differs, restart the host and use the local CLI until identity matches.`,
+    `Read the authoritative Ark contract with \`ark_manifest\` using the same project expectation. The \`ark://manifest\` resource is compatibility-only and always unverified/non-authoritative.`,
     `Keep source files inside the layer boundaries declared in \`ark.config.json\`.`,
     `Do not bypass Ark publishers, event contracts, or source metadata for runtime mutations.`,
     `After edits, run \`${checkCommand}\`.`,
@@ -336,7 +338,7 @@ advisory MCP plus CI. The experimental runtime is not required.
 
 /**
  * Compact onboarding uses one project router instead of copied slash-command
- * skills. The package and ark MCP resources remain the canonical capability
+ * skills. The package and ark MCP tools remain the canonical capability
  * source; the marker makes the selected host verifiable by the strict gate.
  */
 export function compactAgentInstructions(root, host = null) {
@@ -358,8 +360,9 @@ export function compactAgentInstructions(root, host = null) {
 **Primary path (do this):**
 
 1. Status anytime: \`${doctorCmd}\` — one status light, one next action (control plane).
-2. Day to day: read \`ark://manifest\` when MCP is available; place new files with \`ark_place\`; validate after edits; run \`${checkCmd}\`. On a gate deny, fix the architecture — do not weaken the contract.
-3. If MCP is unavailable: inspect \`ark.config.json\` and run \`${checkCmd}\`.
+2. Before trusting 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 the process is stale: restart the host and use the local CLI meanwhile.
+3. Day to day: call \`ark_manifest\` with the same project expectation; place new files with \`ark_place\`; validate after edits; run \`${checkCmd}\`. The \`ark://manifest\` resource is compatibility-only and always unverified/non-authoritative. On a gate deny, fix the architecture — do not weaken the contract.
+4. If MCP is unavailable: inspect \`ark.config.json\` and run \`${checkCmd}\`.
 
 The selected host is \`${selectedHost}\`. Host registration and CI are installed with this file.
 This compact router is enough for normal feature work.
@@ -431,8 +434,14 @@ description: Ark architecture contract
 alwaysApply: true
 ---
 
-Before writing or editing TypeScript or JavaScript source files, read the
-\`${AGENT_CONTRACT.manifestResource}\` resource from the \`ark\` MCP server when available.
+Before trusting Ark MCP evidence, call \`ark_identity\` with \`project.expectedRoot\`
+set to the exact project root's absolute path. Reuse that root plus the returned
+\`projectIdentity.projectId\` on every Ark MCP call. A descendant path is authoritative only
+when that matching id is also supplied. If the tool is missing, the binding is not \`matched\`,
+or the root differs, restart the host and use the local CLI until identity matches. Then call
+\`${AGENT_CONTRACT.manifestTool}\` with the same project expectation. The
+\`${AGENT_CONTRACT.compatibilityManifestResource}\` resource is compatibility-only and always
+unverified/non-authoritative.
 
 ${AGENT_CONTRACT.cursorValidateStep} After edits, run:
 

package/bin/lib/codex-home.mjs

@@ -165,22 +165,104 @@ export function codexScopedTableForRoot(tomlText, absRoot) {
   return null;
 }
 
+function extractCodexCommandFromBlock(block) {
+  const matches = [
+    ...String(block || '').matchAll(
+      /^[ \t]*command[ \t]*=[ \t]*("(?:\\.|[^"\\])*"|'[^']*')[ \t]*(?:#.*)?$/gm
+    ),
+  ];
+  if (matches.length !== 1) return null;
+  try {
+    return matches[0][1].startsWith('"')
+      ? JSON.parse(matches[0][1])
+      : matches[0][1].slice(1, -1);
+  } catch {
+    return null;
+  }
+}
+
+function executableName(value) {
+  if (typeof value !== 'string' || value !== value.trim() || value.length === 0) return '';
+  return path.posix
+    .basename(value.replace(/\\/g, '/'))
+    .replace(/\.(?:cmd|exe)$/i, '')
+    .toLowerCase();
+}
+
+function isArkMcpToken(value) {
+  return /^(?:arkgate-mcp|ark-mcp)(?:\.mjs)?$/.test(executableName(value));
+}
+
+function codexArkMcpInvocation(command, args) {
+  if (
+    !command ||
+    !Array.isArray(args) ||
+    [command, ...args].filter(isArkMcpToken).length !== 1
+  ) {
+    return false;
+  }
+  const argv = [command, ...args];
+  if (isArkMcpToken(command)) return { binArgs: argv.slice(1) };
+  const runner = executableName(command);
+  if ((runner === 'npx' || runner === 'yarn') && isArkMcpToken(args[0])) {
+    return { binArgs: argv.slice(2) };
+  }
+  if (runner === 'node') {
+    const script = args[0]?.replace(/\\/g, '/');
+    return isArkMcpToken(script) && /(?:^|\/)bin\/ark-mcp\.mjs$/.test(script)
+      ? { binArgs: argv.slice(2) }
+      : false;
+  }
+  if (runner !== 'pnpm') return false;
+  const binIndex =
+    args[0] === 'exec'
+      ? 1
+      : args[0] === '--config.verify-deps-before-run=false' && args[1] === 'exec'
+        ? 2
+        : -1;
+  return binIndex >= 0 && isArkMcpToken(args[binIndex])
+    ? { binArgs: argv.slice(binIndex + 2) }
+    : false;
+}
+
+function singleOptionValue(args, option) {
+  const indexes = args.flatMap((value, index) => (value === option ? [index] : []));
+  return indexes.length === 1 ? args[indexes[0] + 1] ?? null : null;
+}
+
+function projectPathFlavor(projectRoot) {
+  const windows = /^(?:[A-Za-z]:[\\/]|\\\\)/.test(projectRoot);
+  return {
+    api: windows ? path.win32 : path,
+    comparable: (value) => (windows ? value.toLowerCase() : value),
+  };
+}
+
+function blockHasWorkingDirectoryOverride(block) {
+  return /^[ \t]*(?:cwd|"cwd"|'cwd')[ \t]*=/m.test(String(block || ''));
+}
+
 /** True when project TOML owns the primary Ark MCP binding for that project. */
 export function codexProjectMcpIsValid(tomlText, projectRoot) {
-  const resolvedRoot = path.resolve(projectRoot);
   if (listCodexArkServerTables(tomlText).filter((entry) => entry.table === 'ark').length !== 1) {
     return false;
   }
   const primary = codexPrimaryTable(tomlText);
   const args = extractCodexArgsFromBlock(primary?.block);
-  if (!primary?.root || !args?.some((value) => /^(ark|arkgate)-mcp$/.test(value))) return false;
-  const configIndex = args.indexOf('--config');
-  const config = configIndex >= 0 ? args[configIndex + 1] : null;
-  if (!config) return false;
+  const command = extractCodexCommandFromBlock(primary?.block);
+  const invocation = args && codexArkMcpInvocation(command, args);
+  if (!invocation || blockHasWorkingDirectoryOverride(primary?.block)) return false;
+  const rootArg = singleOptionValue(invocation.binArgs, '--root');
+  const configArg = singleOptionValue(invocation.binArgs, '--config');
+  if (!rootArg || !configArg || invocation.binArgs.length !== 4) return false;
   try {
+    const { api, comparable } = projectPathFlavor(projectRoot);
+    const resolvedRoot = api.resolve(projectRoot);
+    const requestedRoot = api.resolve(resolvedRoot, rootArg);
+    const requestedConfig = api.resolve(resolvedRoot, configArg);
     return (
-      path.resolve(resolvedRoot, primary.root) === resolvedRoot &&
-      path.resolve(resolvedRoot, config) === path.join(resolvedRoot, 'ark.config.json')
+      comparable(requestedRoot) === comparable(resolvedRoot) &&
+      comparable(requestedConfig) === comparable(api.join(resolvedRoot, 'ark.config.json'))
     );
   } catch {
     return false;
@@ -281,7 +363,7 @@ export function assessCodexHomeMcp(tomlText, absRoot) {
       message: scopedTable
         ? `Codex primary [mcp_servers.ark] is bound to another project (${rootArg}); ` +
           `this project is registered as [mcp_servers.${scopedTable}]. ` +
-          `Install the project-scoped binding so this repo owns ark://manifest when active.`
+          `Install the project-scoped binding so ark_identity and ark_manifest match this repo when active.`
         : `Codex home primary MCP --root is another permanent project ` +
           `(${rootArg || 'missing'} ≠ ${resolvedRoot}). ` +
           `Install the project-scoped binding for this repo; the global primary can remain unchanged.`,

package/bin/lib/design-smells.mjs

@@ -33,7 +33,7 @@ export const DESIGN_SMELL_OUTCOMES = Object.freeze({
   'god-module':
     'A few huge files own too many responsibilities — the AI cannot safely edit one concern without breaking others. Split the pilot file by job (one export surface per concern).',
   'domain-logic-in-ui':
-    'Business rules (can*/calculate*/policy) sit in UI components — the AI will duplicate them in pages. Move pure rules into Domain (or a pure domain module) and import from the UI.',
+    'Business rules (can*/calculate*/policy) sit in UI components — the AI will duplicate them in pages. Move the pure rule into Domain, expose it through Application, and keep UI imports on that Application boundary.',
   'facade-sql-in-routes':
     'Routes/controllers import the ORM or SQL client — the AI will keep growing “smart controllers.” Keep queries in a repository/adapter; routes only call that port.',
   'mixed-pattern-cluster':
@@ -76,8 +76,13 @@ const ROUTE_DEFINITION_CALL_RE =
   /\bdefineRoute\s*(?:<[\s\S]{1,512}?>)?\s*\(/;
 const ROUTE_DEFINITION_DECLARATION_RE =
   /\b(?:export\s+)?(?:declare\s+)?(?:async\s+)?function\s+defineRoute\s*(?:<[\s\S]{1,512}?>)?\s*\(/g;
-const DOMAIN_LOGIC_UI_RE =
-  /\b(?:export\s+)?(?:async\s+)?function\s+(?:can|calculate|compute|should)[A-Z]\w*|\b(?:export\s+)?const\s+(?:can|calculate|compute|should)[A-Z]\w*\s*=/;
+const DOMAIN_LOGIC_UI_DECL_RE =
+  /\b(?:export\s+)?(?:(?:async\s+)?function\s+((?:can|calculate|compute|should)[A-Z]\w*)|const\s+((?:can|calculate|compute|should)[A-Z]\w*)\s*=)/g;
+const UI_PERMISSION_OR_LOCAL_STATE_RE =
+  /\b(?:permissions?|roles?|acl|session|currentUser|isOwner|readOnly|useState|useMemo|useContext|localState|uiState|selected(?:Id|Row|Tab)?|is(?:Open|Closed|Expanded|Collapsed|Selected|Loading|Pending|Hovered|Focused|Disabled))\b(?:\s*\.\s*\w+|\s*\[[^\]]+\])*/gi;
+const STRING_LITERAL_RE = /'(?:\\.|[^'\\])*'|"(?:\\.|[^"\\])*"/g;
+const BUSINESS_RULE_CONTEXT_RE =
+  /\b(?:amount|total|price|tax|discount|balance|quantity|inventory|order|cart|invoice|credit|policy|threshold|limit|status)\b/i;
 const EXPORT_RE =
   /\bexport\s+(?:async\s+)?(?:function|class|const|let|var|type|interface|enum|default)\b|\bexport\s*\{/g;
 
@@ -93,6 +98,19 @@ const MAX_SCAN_FILES = 800;
 const GOD_LOC = 400;
 const GOD_EXPORTS = 12;
 
+/** Files that may be intentionally broad or generated are not extraction pilots. */
+export function isNonProductionPilotPath(filePath) {
+  const rel = String(filePath || '').replace(/\\/g, '/');
+  return (
+    /(?:^|\/)(?:tests?|__tests__|fixtures?|testdata|mocks?|stubs?|examples?|samples?|seeds?|seeders?|migrations?|demos?|generated|codegen)(?:\/|$)/i.test(
+      rel
+    ) ||
+    /(?:^|\/)(?:(?:fixture|seed|seeder|migration|demo|generated)|[^/]*(?:\.generated|\.gen|[-_.](?:fixture|seed|seeder|migration|demo|generated)))\.(?:ts|tsx|js|jsx|mts|cts)$/i.test(
+      rel
+    )
+  );
+}
+
 function normalizeRel(root, filePath) {
   const abs = path.isAbsolute(filePath) ? filePath : path.join(root, filePath);
   let rel = path.relative(root, abs).split(path.sep).join('/');
@@ -175,6 +193,38 @@ function hasHollowPersistenceShape(source) {
   );
 }
 
+function hasGeneratedSourceBanner(source) {
+  return /(?:@generated|GENERATED FILE|generated by|do not edit)/i.test(source.slice(0, 400));
+}
+
+function hasDomainLogicInUi(source) {
+  for (const match of source.matchAll(DOMAIN_LOGIC_UI_DECL_RE)) {
+    const name = match[1] || match[2] || '';
+    const start = match.index ?? 0;
+    const statementEnd = source.indexOf(';', start);
+    const end =
+      statementEnd >= start && statementEnd <= start + 800
+        ? statementEnd + 1
+        : Math.min(source.length, start + 800);
+    const declaration = source.slice(start, end);
+    const uiDecisionName =
+      /^(?:can(?:Edit|Delete|View|Manage|Select|Open|Close)|should(?:Show|Render|Display|Open|Close|Disable|Enable))/i.test(
+        name
+      );
+    // canEdit/shouldShow are common local UI or permission decisions. Require
+    // business evidence outside the helper name before treating them as domain logic.
+    const ruleContext = declaration
+      .replace(name, '')
+      .replace(STRING_LITERAL_RE, '')
+      .replace(UI_PERMISSION_OR_LOCAL_STATE_RE, '');
+    if (uiDecisionName && !BUSINESS_RULE_CONTEXT_RE.test(ruleContext)) {
+      continue;
+    }
+    return true;
+  }
+  return false;
+}
+
 /**
  * @typedef {object} DesignSmell
  * @property {string} id
@@ -277,11 +327,16 @@ export function detectDesignSmells(root, config, files = [], coverage = null) {
     const loc = countLines(source);
     const exportsCount = countExports(source);
 
-    if (loc >= GOD_LOC && exportsCount >= GOD_EXPORTS) {
+    if (
+      loc >= GOD_LOC &&
+      exportsCount >= GOD_EXPORTS &&
+      !isNonProductionPilotPath(rel) &&
+      !hasGeneratedSourceBanner(source)
+    ) {
       godEvidence.push(rel);
     }
 
-    if ((UI_PATH_RE.test(rel) || isPresentationLayer(layer)) && DOMAIN_LOGIC_UI_RE.test(source)) {
+    if ((UI_PATH_RE.test(rel) || isPresentationLayer(layer)) && hasDomainLogicInUi(source)) {
       domainInUi.push(rel);
     }
 
@@ -353,7 +408,7 @@ export function detectDesignSmells(root, config, files = [], coverage = null) {
         severity: 'warn',
         message: `Business-style can*/calculate*/compute* helpers live under UI/presentation paths (${domainInUi.length} file(s)).`,
         evidence: domainInUi.slice(0, 12),
-        fix: 'Move pure rules into Domain (or shared pure module under Domain globs) and import from UI.',
+        fix: 'Move the pure rule into Domain, expose it through Application, and have UI import the Application boundary (never Presentation → Domain directly).',
       })
     );
   }
@@ -399,7 +454,7 @@ export function detectDesignSmells(root, config, files = [], coverage = null) {
 }
 
 /**
- * Whether edge-clean ENFORCE should still report design-weak residual.
+ * Whether edge-clean analysis should still report design-weak residual.
  *
  * @param {DesignSmell[]} smells
  * @param {{ activeViolations?: number, governedPercent?: number|null, totalFiles?: number|null }} ctx
@@ -416,16 +471,23 @@ export function isDesignWeak(smells, ctx = {}) {
 
 /**
  * Design fitness summary for doctor JSON / human.
+ * @param {DesignSmell[]} smells
+ * @param {{ activeViolations?: number, governedPercent?: number|null, totalFiles?: number|null, operatingMode?: string }} ctx
  */
 export function summarizeDesignFitness(smells, ctx = {}) {
   const designWeak = isDesignWeak(smells, ctx);
+  const mode =
+    typeof ctx.operatingMode === 'string' &&
+    /^(?:suggest|adapt|enforce)$/.test(ctx.operatingMode)
+      ? ctx.operatingMode.toUpperCase()
+      : null;
   return {
     status: designWeak ? 'design-weak' : smells.length > 0 ? 'smells-with-open-edges' : 'ok',
     designWeak,
     smellCount: Array.isArray(smells) ? smells.length : 0,
     ids: (smells || []).map((s) => s.id),
     label: designWeak
-      ? 'ENFORCE · design-weak — edges clean; Shape residual remains (see designSmells / plan B)'
+      ? `${mode ? `${mode} · ` : ''}design-weak — edges clean; Shape residual remains (see designSmells / plan B)`
       : smells.length > 0
         ? 'Design smells present alongside open edge debt'
         : 'No deterministic design smells detected',
@@ -471,7 +533,7 @@ function successSignalFor(id) {
     case 'god-module':
       return 'Pilot god module split; fan-in and export surface reduced without new edge violations';
     case 'domain-logic-in-ui':
-      return 'can*/calculate* pure rules live under Domain; UI imports them only';
+      return 'can*/calculate* pure rules live under Domain; Application exposes them; UI imports Application only';
     case 'facade-sql-in-routes':
       return '0 route/controller files import ORM/SQL clients; queries in adapters';
     case 'mixed-pattern-cluster':

package/bin/lib/doctor-plan.mjs

@@ -22,6 +22,7 @@ const matchingLayersForRelativePath =
 import {
   collectAdoptionGaps,
   detectSkillGaps,
+  skillGapsForActiveHost,
   detectCodexHomeGap,
   codexConcernIsActive,
   detectWritePathCapabilities,
@@ -331,7 +332,7 @@ export function buildRemediationPlan(
             : 'No active violations — the architecture already meets its contract.';
   if (designWeak) {
     statement =
-      'No active edge violations — contract edges are clean, but design smells remain (ENFORCE · design-weak). Shape residual is plan B only; not healthy finished.';
+      'No active edge violations — contract edges are clean, but design smells remain (design-weak). Shape residual is plan B only; not healthy finished.';
   }
   if (completeness !== ANALYSIS_COMPLETENESS.complete) statement = analysisIncompleteStatement(completeness);
 
@@ -361,7 +362,7 @@ export function buildRemediationPlan(
       ...(designWeak
         ? {
             designWeakLabel:
-              'ENFORCE · design-weak — use patternBets / dual-plan B; never auto-apply as mechanical-safe',
+              'Design-weak — use patternBets / dual-plan B; never auto-apply as mechanical-safe',
             ...DESIGN_WEAK_HONESTY_FLAGS,
           }
         : {}),
@@ -422,7 +423,7 @@ export function runPlan(
   if (plan.goal.designWeak) {
     console.log(
       color.yellow(
-        `  ENFORCE · design-weak — ${plan.patternBets?.length ?? 0} pattern bet(s) (never auto-apply)`
+        `  Design-weak — ${plan.patternBets?.length ?? 0} pattern bet(s) (never auto-apply)`
       )
     );
   }
@@ -536,11 +537,32 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
     if (!baseline.exists) return true;
     return !baseline.keys.has(occurrenceKeys[index]);
   }).length;
+  const emptyScopeEarly = cov.emptyScope === true || cov.governed.totalFiles === 0;
+  const presentationRowEarly = cov.layers.find((r) => r.name === 'PresentationAdapters');
+  const totalFilesEarly = cov.governed.totalFiles || 0;
+  const operatingMode = resolveOperatingMode({
+    governedPercent: emptyScopeEarly ? 0 : cov.governed.percent,
+    // planMet uses blocking only; type-only placement debt alone must not force ADAPT.
+    planMet:
+      analysisComplete &&
+      blockingActive === 0 &&
+      !emptyScopeEarly &&
+      cov.governed.percent >= 50,
+    mature: cov.governed.totalFiles >= 150,
+    totalFiles: cov.governed.totalFiles,
+    emptyLayers: cov.emptyLayers,
+    coreOptionalWithFiles: adoption.coreOptional?.length ?? 0,
+    presentationShare:
+      totalFilesEarly > 0 && presentationRowEarly
+        ? presentationRowEarly.files / totalFilesEarly
+        : null,
+  });
   const designSmells = detectDesignSmells(root, config, files, cov);
   const observedDesignFitness = summarizeDesignFitness(designSmells, {
     activeViolations: blockingActive,
     governedPercent: cov.governed.percent,
     totalFiles: cov.governed.totalFiles,
+    operatingMode,
   });
   const designFitness = analysisComplete ? observedDesignFitness : {
     ...observedDesignFitness, status: 'analysis-incomplete', designWeak: false, label: 'Design fitness not verified — analysis is incomplete; observed smells remain advisory.',
@@ -576,27 +598,6 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
   );
   // Single residual expression (nextPilot || extractionCard) — HTML report uses the same.
   const residualPilot = pilotLoop?.nextPilot || pilotLoop?.extractionCard || null;
-  const emptyScopeEarly = cov.emptyScope === true || cov.governed.totalFiles === 0;
-  const presentationRowEarly = cov.layers.find((r) => r.name === 'PresentationAdapters');
-  const totalFilesEarly = cov.governed.totalFiles || 0;
-  const operatingMode = resolveOperatingMode({
-    governedPercent: emptyScopeEarly ? 0 : cov.governed.percent,
-    // planMet uses blocking (failsStrict !== false) only — type-only placement debt alone
-    // must not force adapt via unmet plan (parity with merge/exit and productHonesty).
-    planMet:
-      analysisComplete &&
-      blockingActive === 0 &&
-      !emptyScopeEarly &&
-      cov.governed.percent >= 50,
-    mature: cov.governed.totalFiles >= 150,
-    totalFiles: cov.governed.totalFiles,
-    emptyLayers: cov.emptyLayers,
-    coreOptionalWithFiles: adoption.coreOptional?.length ?? 0,
-    presentationShare:
-      totalFilesEarly > 0 && presentationRowEarly
-        ? presentationRowEarly.files / totalFilesEarly
-        : null,
-  });
   // Evidence-backed hard only (never capabilities-from-hook-files alone).
   const hardWriteActive = writePath.enforcementState?.localWrite?.hard === true;
   const packageInstalled = writePath.enforcementState?.localWrite?.installed === true;
@@ -796,7 +797,6 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
     mode === 'enforce' && !designFitness.designWeak
       ? ok
       : warn;
-  // Status lights are detected states, not user-picked settings (see docs/product-voice.md).
   // modeTitle alone names the light — bodies must not re-prefix Suggest/Adapt/Enforce.
   const modeHelp = {
     suggest:
@@ -807,8 +807,8 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
       'honest coverage and clean checked edges. You arrived here; you never turn Enforce on. Next: keep the host write path and CI check; only NEW violations should fail.',
   };
   const modeTitle =
-    mode === 'enforce' && designFitness.designWeak
-      ? 'ENFORCE · design-weak'
+    designFitness.designWeak
+      ? `${mode.toUpperCase()} · design-weak`
       : mode.toUpperCase();
   line(
     modeMark,
@@ -999,7 +999,7 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
         'No active violations — coverage is still thin, so green is not yet honest enforcement'
       );
     } else if (designFitness.designWeak) {
-      line(warn, 'None on checked edges — edges match the contract; design residual remains (ENFORCE · design-weak). Not healthy finished.');
+      line(warn, `None on checked edges — edges match the contract; design residual remains (${modeTitle}). Not healthy finished.`);
     } else {
       line(ok, 'None — the code matches the contract on checked edges');
     }
@@ -1067,17 +1067,17 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
 
   console.log('');
   console.log(color.bold('Gates & skills'));
-  if (gatesMissing.length === 0) line(ok, 'Shared gate files present (AGENTS.md, .mcp.json, CI)');
+  if (gatesMissing.length === 0) line(ok, 'Shared gate artifacts found on disk (AGENTS.md, .mcp.json, CI); runtime activation is reported separately');
   else {
     line(bad, `Missing gates: ${gatesMissing.join(', ')}`);
     actions.push(`install gates (${arkCommand(root, 'ark-check', '--install-agent-gates')})`);
   }
-  // Report Codex legacy prompts and other-host missing/stale independently (never exclusive).
-  const legacyCodex = skillGaps.some((g) => g.tool === 'codex' && g.legacyPromptsOnly);
-  const codexLegacySafeDelete = skillGaps.some(
+  const humanSkillGaps = skillGapsForActiveHost(skillGaps);
+  const legacyCodex = humanSkillGaps.some((g) => g.tool === 'codex' && g.legacyPromptsOnly);
+  const codexLegacySafeDelete = humanSkillGaps.some(
     (g) => g.tool === 'codex' && g.legacyAdvisory && g.catalogComplete
   );
-  const remainingGaps = skillGaps.filter(
+  const remainingGaps = humanSkillGaps.filter(
     (g) => !(g.tool === 'codex' && (g.legacyPromptsOnly || g.legacyAdvisory))
   );
   const remMiss = remainingGaps.reduce((s, g) => s + g.missing, 0);
@@ -1107,7 +1107,7 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
     const parts = [
       codexHomeGap.legacyPromptsOnly ? 'legacy-prompts-only' : null,
       codexHomeGap.missing > 0 ? `${codexHomeGap.missing} missing` : null,
-      codexHomeGap.stale > 0 ? `${codexHomeGap.stale} content-behind-package` : null,
+      codexHomeGap.stale > 0 ? `${codexHomeGap.stale} content-behind-package` : null, codexHomeGap.catalogStateReason,
     ].filter(Boolean);
     const deferred = !codexConcernIsActive();
     // Deferred home debt is dim/info (not warn) so non-Codex sessions are not "incomplete".
@@ -1115,7 +1115,7 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
       line(color.dim('·'), color.dim(`Codex home skills ${parts.join(', ')} (deferred — not on Codex session)`));
     } else {
       line(warn, `Codex home skills ${parts.join(', ')}`);
-      actions.push('refresh Codex home skills (--install-agent-gates --skills-only --codex-home --force)');
+      actions.push(codexHomeGap.catalogMetadataInvalid ? 'repair invalid Codex home catalog metadata after verifying the newest installed version' : 'refresh Codex home skills (--install-agent-gates --skills-only --codex-home --force)');
     }
   }
 
@@ -1229,7 +1229,7 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
     if (postGreenPath) {
       console.log(
         color.dim(
-          '  Shape residual is the primary door under ENFORCE · design-weak — do not skill-shop explore vs coverage vs think.'
+          `  Shape residual is the primary door under ${modeTitle} — do not skill-shop explore vs coverage vs think.`
         )
       );
     } else {

package/bin/lib/effective-contract-load.mjs

@@ -10,6 +10,35 @@ import {
   loadArkRulesContract,
 } from './arkrules-contract.mjs';
 
+function normalizeProjectRelativePath(value) {
+  const normalized = value.replace(/\\/g, '/');
+  if (
+    !normalized ||
+    normalized.startsWith('/') ||
+    /^[A-Za-z]:/.test(normalized) ||
+    normalized.includes('\0')
+  ) {
+    return undefined;
+  }
+  const segments = [];
+  for (const segment of normalized.split('/')) {
+    if (!segment || segment === '.') continue;
+    if (segment === '..') return undefined;
+    segments.push(segment);
+  }
+  return segments.length > 0 ? segments.join('/') : undefined;
+}
+
+function isWithinRoot(root, candidate) {
+  const relative = path.relative(root, candidate);
+  return (
+    relative === '' ||
+    (!relative.startsWith(`..${path.sep}`) &&
+      relative !== '..' &&
+      !path.isAbsolute(relative))
+  );
+}
+
 /**
  * @param {string} root
  * @param {Record<string, unknown>} config loaded ark.config.json object
@@ -29,6 +58,7 @@ export function loadEffectiveArkRulesFromDisk(root, config, opts = {}) {
   const warnings = [];
   const parts = [];
   const referenced = new Set();
+  const canonicalRoot = fs.realpathSync(root);
 
   for (const layer of Object.keys(refs).sort()) {
     const relRaw = refs[layer];
@@ -37,10 +67,12 @@ export function loadEffectiveArkRulesFromDisk(root, config, opts = {}) {
       errors.push({ path: pathKey, message: 'must be a non-empty relative path string' });
       continue;
     }
-    if (relRaw.startsWith('/') || /^[A-Za-z]:[\\/]/.test(relRaw)) {
+    const rel = normalizeProjectRelativePath(relRaw);
+    if (!rel) {
       errors.push({
         path: pathKey,
-        message: 'must be a project-relative path (absolute paths are not allowed)',
+        message:
+          'must be a project-relative path without absolute roots or parent-directory traversal',
       });
       continue;
     }
@@ -52,17 +84,42 @@ export function loadEffectiveArkRulesFromDisk(root, config, opts = {}) {
       continue;
     }
 
-    const rel = relRaw.replace(/\\/g, '/').replace(/^\.\//, '');
     referenced.add(rel);
-    const absolute = path.resolve(root, rel);
-    opts.observeInput?.(absolute, 'arkrules');
-    if (!fs.existsSync(absolute)) {
+    const lexicalTarget = path.resolve(canonicalRoot, ...rel.split('/'));
+    if (!isWithinRoot(canonicalRoot, lexicalTarget)) {
+      errors.push({
+        path: pathKey,
+        message: `referenced ArkRules path ${JSON.stringify(rel)} resolves outside the project root`,
+      });
+      continue;
+    }
+    if (!fs.existsSync(lexicalTarget)) {
       errors.push({
         path: pathKey,
         message: `referenced ArkRules file ${JSON.stringify(rel)} is missing`,
       });
       continue;
     }
+    let absolute;
+    try {
+      absolute = fs.realpathSync(lexicalTarget);
+    } catch (error) {
+      errors.push({
+        path: pathKey,
+        message: `referenced ArkRules file ${JSON.stringify(rel)} could not be resolved: ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+      });
+      continue;
+    }
+    if (!isWithinRoot(canonicalRoot, absolute)) {
+      errors.push({
+        path: pathKey,
+        message: `referenced ArkRules path ${JSON.stringify(rel)} resolves outside the project root`,
+      });
+      continue;
+    }
+    opts.observeInput?.(absolute, 'arkrules');
     let content;
     try {
       content = fs.readFileSync(absolute, 'utf8');
@@ -90,9 +147,16 @@ export function loadEffectiveArkRulesFromDisk(root, config, opts = {}) {
   }
 
   // Drift: unreferenced files under arkrules/
-  const arkrulesDir = path.join(root, 'arkrules');
-  if (fs.existsSync(arkrulesDir) && fs.statSync(arkrulesDir).isDirectory()) {
-    for (const name of fs.readdirSync(arkrulesDir).sort()) {
+  const arkrulesDir = path.join(canonicalRoot, 'arkrules');
+  const resolvedArkRulesDir = fs.existsSync(arkrulesDir)
+    ? fs.realpathSync(arkrulesDir)
+    : undefined;
+  if (
+    resolvedArkRulesDir &&
+    isWithinRoot(canonicalRoot, resolvedArkRulesDir) &&
+    fs.statSync(resolvedArkRulesDir).isDirectory()
+  ) {
+    for (const name of fs.readdirSync(resolvedArkRulesDir).sort()) {
       if (!name.endsWith('.json')) continue;
       const rel = `arkrules/${name}`;
       if (!referenced.has(rel)) {