arkgate 4.8.16 → 4.8.18

package/bin/lib/doctor-human.mjs

@@ -11,7 +11,7 @@ import { printDoctorAdvisories, printCompactExtraDoctorLines } from './doctor-ad
 import { designDeltaDoctorLines } from './design-delta.mjs';
 import { enforcementDoctorLines } from './enforcement-state.mjs';
 import { analysisIncompleteStatement } from './analysis-completeness.mjs';
-import { skillGapsForActiveHost, detectCodexHomeGap, codexConcernIsActive } from './agent-gates.mjs';
+import { skillGapsForActiveHost, detectCodexHomeGap, codexConcernIsActive, skillGapToolLabel } from './agent-gates.mjs';
 import { agentHomeConcernIsActive } from './agent-homes.mjs';
 import { layerGuidanceLine } from './layer-description.mjs';
 import {
@@ -467,7 +467,7 @@ export function printDoctorDetailsHuman(view) {
   if (remMiss + remStale > 0) {
     line(
       warn,
-      `${remMiss} missing / ${remStale} content-behind-package /ark-* skill(s) for ${remainingGaps.map((g) => g.tool).join(', ')}`
+      `${remMiss} missing / ${remStale} content-behind-package /ark-* skill(s) for ${remainingGaps.map((g) => skillGapToolLabel(g.tool)).join(', ')}`
     );
   }
   const codexHomeGap = detectCodexHomeGap(root);

package/bin/lib/doctor-next-actions.mjs

@@ -2,7 +2,7 @@
  * Rank doctor next actions from already-computed facts (no I/O).
  * Lets the human printer show light + #1 before honesty/compass sections.
  */
-import { arkCommand } from '../ark-shared.mjs';
+import { arkCommand, globToRegExp } from '../ark-shared.mjs';
 import { skillGapsForActiveHost } from './agent-gates.mjs';
 import { agentHomeConcernIsActive, agentHomeRefreshCommand } from './agent-homes.mjs';
 import { mergePostGreenTopActions } from './post-green-path.mjs';
@@ -17,6 +17,99 @@ function missingGateFiles(ctx) {
   return list;
 }
 
+/** Ignore a handful of expected Next API dual-matches. */
+const DUAL_MATCH_REPAIR_FLOOR = 20;
+/** Absolute pile-up even when the tree is huge. */
+const DUAL_MATCH_REPAIR_ABSOLUTE = 50;
+/** Share of in-scope files that match two+ layers. */
+const DUAL_MATCH_REPAIR_SHARE = 0.1;
+
+function isWildcardPattern(pattern) {
+  return /[*?]/.test(String(pattern ?? ''));
+}
+
+function posixRel(file) {
+  return String(file ?? '').split(/\\/).join('/');
+}
+
+function layerPatterns(cov, layerName) {
+  const rows = Array.isArray(cov?.layers) ? cov.layers : [];
+  const row = rows.find((layer) => layer?.name === layerName);
+  return Array.isArray(row?.patterns) ? row.patterns : [];
+}
+
+function fileMatchesWildcardPatterns(file, patterns) {
+  const rel = posixRel(file);
+  return patterns.some((pattern) => isWildcardPattern(pattern) && globToRegExp(pattern).test(rel));
+}
+
+/**
+ * Domain overlap is a glob leak when Domain matched the sample via a wildcard.
+ * Exact-file Domain listings under another layer glob (mother generated CLI)
+ * are intentional dual-lists, not a repair. No layer patterns → keep the
+ * Domain-sample shortcut so older #269 fixtures still fire.
+ */
+function domainSampleIsGlobLeak(row, cov) {
+  if (!(row?.layers ?? []).includes('DomainModel')) return false;
+  const patterns = layerPatterns(cov, 'DomainModel');
+  if (patterns.length === 0) return true;
+  return fileMatchesWildcardPatterns(row.file, patterns);
+}
+
+/** Overlapping roots from matching Domain wildcards, else sample path prefixes. */
+export function overlappingRootsFromCoverage(cov) {
+  const samples = Array.isArray(cov?.dualMembership?.samples) ? cov.dualMembership.samples : [];
+  const domainPatterns = layerPatterns(cov, 'DomainModel');
+  const fromPatterns = [];
+  for (const row of samples) {
+    const rel = posixRel(row?.file);
+    for (const pattern of domainPatterns) {
+      if (isWildcardPattern(pattern) && globToRegExp(pattern).test(rel)) {
+        fromPatterns.push(pattern);
+      }
+    }
+  }
+  if (fromPatterns.length > 0) {
+    return [...new Set(fromPatterns)].slice(0, 2);
+  }
+  const derived = [];
+  for (const row of samples) {
+    const first = posixRel(row?.file).split('/').filter(Boolean)[0];
+    if (first) derived.push(`${first}/**`);
+  }
+  return [...new Set(derived)].slice(0, 2);
+}
+
+/**
+ * Dual-match is a lying layer map when it is large — especially Domain
+ * overlapping Presentation/Application after over-broad monorepo start globs.
+ * Intentional file+glob dual-lists (exact Domain files under Tooling `bin/**`)
+ * do not steal doctor #1.
+ */
+export function dualMatchNeedsGlobRepair(cov) {
+  const count = Number(cov?.dualMembership?.count) || 0;
+  if (count < DUAL_MATCH_REPAIR_FLOOR) return false;
+  const total = Number(cov?.totalFiles ?? cov?.governed?.totalFiles) || 0;
+  const samples = Array.isArray(cov?.dualMembership?.samples) ? cov.dualMembership.samples : [];
+  const domainOverlap = samples.some((row) => domainSampleIsGlobLeak(row, cov));
+  if (domainOverlap) return true;
+  if (total > 0 && count / total >= DUAL_MATCH_REPAIR_SHARE) return true;
+  return count >= DUAL_MATCH_REPAIR_ABSOLUTE;
+}
+
+export function overlappingGlobNextAction(cov) {
+  const count = Number(cov?.dualMembership?.count) || 0;
+  const sample = Array.isArray(cov?.dualMembership?.samples) ? cov.dualMembership.samples[0] : null;
+  const layers = Array.isArray(sample?.layers) ? sample.layers.filter(Boolean) : [];
+  const example =
+    sample?.file && layers.length > 1
+      ? `${sample.file} matches ${layers.join(' + ')}`
+      : 'the same files match two layer globs';
+  const roots = overlappingRootsFromCoverage(cov);
+  const rootPhrase = roots.length > 0 ? roots.join(', ') : 'the overlapping globs';
+  return `Fix overlapping layer globs — ${count} files match more than one layer (e.g. ${example}). Narrow overlapping roots like ${rootPhrase}. Then /ark-adopt`;
+}
+
 export function collectDoctorNextActions(ctx) {
   const actions = [];
   const missingFiles = missingGateFiles(ctx);
@@ -37,9 +130,26 @@ export function collectDoctorNextActions(ctx) {
   if (ctx.layerOwners?.required && ctx.layerOwners.nextAction) {
     actions.push(ctx.layerOwners.nextAction);
   }
+  const humanSkillGaps = skillGapsForActiveHost(ctx.skillGaps ?? []);
+  const legacyCodex = humanSkillGaps.some((g) => g.tool === 'codex' && g.legacyPromptsOnly);
+  const remainingGaps = humanSkillGaps.filter(
+    (g) => !(g.tool === 'codex' && (g.legacyPromptsOnly || g.legacyAdvisory))
+  );
+  const remMiss = remainingGaps.reduce((s, g) => s + g.missing, 0);
+  const remStale = remainingGaps.reduce((s, g) => s + g.stale, 0);
+  if (legacyCodex) {
+    actions.push('install Codex SKILL.md catalog (--install-agent-gates --skills-only --tools codex --force)');
+  }
+  if (remMiss > 0) {
+    actions.push('install missing /ark-* skills (--install-agent-gates --skills-only --force)');
+  } else if (remStale > 0) {
+    actions.push('refresh stale /ark-* skills (--install-agent-gates --skills-only --force) — gates are installed, catalog is stale');
+  }
   const enforceEmptyPlan =
     ctx.operatingMode === 'enforce' && planAEmpty && gatesInstalled && !notAdopted;
-  if (enforceEmptyPlan) {
+  // Stale/missing doors outrank the Shape nudge — a colleague on an old catalog
+  // must see skills-only refresh as #1, not leftover-design explore.
+  if (enforceEmptyPlan && remMiss === 0 && remStale === 0 && !legacyCodex) {
     actions.push(
       ctx.postGreenPath?.action ||
         '/ark-explore, then one small refactor with /ark-autopilot and your OK'
@@ -70,6 +180,8 @@ export function collectDoctorNextActions(ctx) {
   if (ctx.coverageHonesty.greenIsNotEnforcement && ctx.coverageHonesty.worseThanNoGate) {
     actions.push('raise governed coverage above a minority slice before treating green as enforcement');
   }
+  const overlapAction = dualMatchNeedsGlobRepair(ctx.cov) ? overlappingGlobNextAction(ctx.cov) : null;
+  if (overlapAction) actions.push(overlapAction);
   if (ctx.cov.suggestions.length > 0) actions.push('classify the ungoverned directories (/ark-adopt)');
   if (ctx.packageVersionTruth?.dualTruth) {
     actions.push(
@@ -100,21 +212,6 @@ export function collectDoctorNextActions(ctx) {
           : 'Remove the skippable if:, or write .ark/adoption-stance.json with stance: advisory-only')
     );
   }
-  const humanSkillGaps = skillGapsForActiveHost(ctx.skillGaps);
-  const legacyCodex = humanSkillGaps.some((g) => g.tool === 'codex' && g.legacyPromptsOnly);
-  const remainingGaps = humanSkillGaps.filter(
-    (g) => !(g.tool === 'codex' && (g.legacyPromptsOnly || g.legacyAdvisory))
-  );
-  const remMiss = remainingGaps.reduce((s, g) => s + g.missing, 0);
-  const remStale = remainingGaps.reduce((s, g) => s + g.stale, 0);
-  if (legacyCodex) {
-    actions.push('install Codex SKILL.md catalog (--install-agent-gates --skills-only --tools codex --force)');
-  }
-  if (remMiss > 0) {
-    actions.push('install missing /ark-* skills (--install-agent-gates --skills-only --force)');
-  } else if (remStale > 0) {
-    actions.push('refresh stale /ark-* skills (--install-agent-gates --skills-only --force) — gates are installed, catalog is stale');
-  }
   if (ctx.codexHomeGap && ctx.codexConcernActive && ctx.codexHomeGap.duplicateHome) {
     actions.push(
       'remove duplicate Codex home /ark-* skills (project .agents/skills is enough): --install-agent-gates --skills-only --prune-home-duplicates'
@@ -162,6 +259,9 @@ export function collectDoctorNextActions(ctx) {
   if (ctx.designFitness.designWeak && unique.length === 0 && ctx.postGreenPath) {
     unique.push(ctx.postGreenPath.action);
   }
+  if (overlapAction) {
+    return [overlapAction, ...unique.filter((a) => a !== overlapAction)];
+  }
   if (notAdopted) {
     const next = ctx.notAdoptedNextAction || NOT_ADOPTED_NEXT_ACTION;
     return [next, ...unique.filter((a) => a !== next)];

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

@@ -12,6 +12,7 @@ ${NORTH_STAR_ONE_LINE}
   arkgate start              preview (no writes)
   arkgate start --apply      write host + CI setup
                              (refuses weak coverage/shape; lock with --archetype/--preset/--force)
+                             (refuses a plan too big for compact start; next: arkgate-check --init)
   arkgate-check --doctor     status — one next step
                              (if missing: npx --package=arkgate arkgate-check --doctor)
 
@@ -70,6 +71,7 @@ Options:
   --yes        Non-interactive defaults: create config if needed, install gate templates, run strict check.
                (Also the implicit default when stdin/stdout are not a TTY — agents never hang on prompts.)
   --force      Allow generated files to overwrite existing files.
+               Unlocks weak coverage/shape on start --apply. Does not unlock a plan too big for compact start.
   --no-strict  Skip the final strict ark-check run.
   --install    Pin and install arkgate as a project devDependency (default for start).
   --no-install Skip adding/installing arkgate as a project devDependency (start/upgrade).
@@ -271,7 +273,8 @@ export function checkUsageAll() {
     'This merge profile never depends on an editor/agent hook.',
     'When a Git merge base is available, --strict-merge classifies the ark.config.json',
     'transition. Weakening or judgment-required findings fail unless --policy-ack names',
-    'every finding and is bound to both policy hashes. Use --policy-base/--policy-base-ref',
+    'every finding, is bound to both policy hashes, and adrPath points at a short note',
+    'under docs/adr/ or docs/decisions/. Use --policy-base/--policy-base-ref',
     'for an explicit comparison; ARK_POLICY_BASE_REF is the CI environment equivalent.',
     'The same merge profile blocks new UI business-rule files (domain-logic-in-ui) created',
     'versus that base; leftover design on existing files stays green. Missing base skips',
@@ -302,7 +305,8 @@ export function checkUsageAll() {
     'rule file. Existing files are never overwritten without --force, so re-running',
     'after an update only adds what is missing. --skills-only restricts the write to',
     'just the /ark-* skills (safe to --force-refresh — it leaves a customized AGENTS.md,',
-    'settings, and CI workflow untouched).',
+    'settings, and CI workflow untouched). Doctor / ark-check warn when an already-installed',
+    'catalog is behind this package; that next action is --skills-only --force, not re-adopt.',
     'Pass --tools to pick which tool configs to write; otherwise they are auto-detected',
     'from their config directories (.claude/, .cursor/, .codex/, .grok/, .windsurf/,',
     '.clinerules/, .kiro/, .roo/, .continue/, .gemini/; copilot is explicit-only).',

package/bin/lib/html-report.mjs

@@ -905,7 +905,7 @@ export function renderHtmlReport({
     );
   } else {
     skillsParts.push(
-      `<div class="pill warn">${actionableSkillGaps.length} skill gap(s) — run ark upgrade / --install-agent-gates</div>`
+      `<div class="pill warn">${actionableSkillGaps.length} skill gap(s) — refresh skills only: ark-check --install-agent-gates --skills-only --force</div>`
     );
   }
   if (legacyAdvisoryOnly) {

package/bin/lib/policy-delta-io.mjs

@@ -9,6 +9,7 @@ import {
   loadInvariantCoverageInputs,
 } from './invariant-coverage-io.mjs';
 import { evaluateInvariantCoverage } from './invariant-coverage.mjs';
+import { attachPolicyAdrNote } from './adr-path.mjs';
 
 function readJsonFile(filePath, label) {
   if (!fs.existsSync(filePath)) throw new Error(`${label} not found: ${filePath}`);
@@ -196,14 +197,22 @@ export function analyzePolicyTransition({
     candidateInvariantCoverage = evaluated.coverage;
   }
 
-  return analyzePolicyDelta({
-    baseConfig: base.config,
-    candidateConfig,
-    acknowledgement: readPolicyAcknowledgement(root, acknowledgementPath),
-    baseSource: base.source,
-    candidateSource: path.isAbsolute(configPath) ? configPath : path.join(root, configPath),
-    ...(baseArkRules ? { baseArkRules } : {}),
-    candidateArkRules,
-    ...(candidateInvariantCoverage ? { candidateInvariantCoverage } : {}),
-  });
+  const acknowledgement = readPolicyAcknowledgement(root, acknowledgementPath);
+  return attachPolicyAdrNote(
+    analyzePolicyDelta({
+      baseConfig: base.config,
+      candidateConfig,
+      acknowledgement,
+      baseSource: base.source,
+      candidateSource: path.isAbsolute(configPath) ? configPath : path.join(root, configPath),
+      ...(baseArkRules ? { baseArkRules } : {}),
+      candidateArkRules,
+      ...(candidateInvariantCoverage ? { candidateInvariantCoverage } : {}),
+    }),
+    {
+      root,
+      acknowledgement,
+      failClosed: Boolean(strictMerge || acknowledgementPath),
+    }
+  );
 }

package/bin/lib/presets.mjs

@@ -629,27 +629,21 @@ export const ARCHITECTURE_PRESETS = {
     }
     // Turborepo: apps/ + packages/; Nx enterprise: apps/ + libs/ (+ packages/).
     if (include.length === 0) include = ['packages', 'apps', 'libs'];
-    // Established workspaces often have flat package source roots rather than a
-    // directory named domain/application. The package manifest supplies a real,
-    // reviewable role signal: a published library is a domain surface; an app or
-    // CLI package coordinates work. This is deliberately limited to package roots
-    // Ark already discovered, never a catch-all **/src/** fallback.
-    const packagePatterns = (roles) => {
-      if (!root) return [];
-      return units
-        .filter((unit) => roles.includes(unit.role))
-        .flatMap((unit) => unit.sourceRoots.map((sourceRoot) => {
-          const base = unit.root === '.'
-            ? sourceRoot
-            : sourceRoot === '.'
-              ? unit.root
-              : `${unit.root}/${sourceRoot}`;
-          return base === '.' ? null : `${base}/**`;
-        }))
-        .filter(Boolean);
-    };
-    const librarySourcePatterns = packagePatterns(['library']);
-    const applicationSourcePatterns = packagePatterns(['application', 'cli']);
+    // Library Domain bags stay under packages/ or libs/ — never api/** or client/**.
+    const roleGlobs = (roles, domainScoped) =>
+      !root
+        ? []
+        : units
+            .filter((unit) => roles.includes(unit.role) && !(domainScoped && unit.root === '.'))
+            .flatMap((unit) =>
+              (unit.sourceRoots ?? []).map((sourceRoot) => {
+                const base = unit.root === '.' ? sourceRoot : sourceRoot === '.' ? unit.root : `${unit.root}/${sourceRoot}`;
+                return base === '.' ? null : `${base}/**`;
+              })
+            )
+            .filter((pattern) => pattern && (!domainScoped || /^(packages|libs)\//.test(pattern)));
+    const librarySourcePatterns = roleGlobs(['library'], true);
+    const applicationSourcePatterns = roleGlobs(['application', 'cli'], false);
     return presetWithOverlays(
       {
         include,

package/bin/lib/skill-install.mjs

@@ -261,8 +261,22 @@ export const SKILL_TOOL_TARGETS = {
   windsurf: (name) => `.windsurf/workflows/${name}.md`,
   cline: (name) => `.clinerules/workflows/${name}.md`,
   copilot: (name) => `.github/prompts/${name}.prompt.md`,
+  // Catalog-only gap: `.agents/skills` exists without a host marker that reads it.
+  agents: (name) => canonicalSkillPath(name),
 };
 
+/** Synthetic detectSkillGaps tool when only the canonical catalog is present. */
+export const SKILL_CANONICAL_TOOL = 'agents';
+
+export function skillGapToolLabel(tool) {
+  return tool === SKILL_CANONICAL_TOOL ? SKILL_CANONICAL_DIR : String(tool ?? '');
+}
+
+export function skillTargetIsCanonical(tool) {
+  const target = SKILL_TOOL_TARGETS[tool];
+  return typeof target === 'function' && target('ark-place') === canonicalSkillPath('ark-place');
+}
+
 /** Hosts whose catalog is the project `.agents/skills` tree (write once). */
 export function usesCanonicalSkillCatalog(tool) {
   return (
@@ -1086,10 +1100,32 @@ export function detectSkillGaps(root) {
   if (fs.existsSync(path.join(root, '.cursor'))) detected.push('cursor');
   if (fs.existsSync(path.join(root, '.codex'))) detected.push('codex');
   if (fs.existsSync(path.join(root, '.grok'))) detected.push('grok');
+  // Same markers as resolveTools — Antigravity/OpenCode read or link the catalog.
+  if (
+    fs.existsSync(path.join(root, '.agents', 'hooks.json')) ||
+    fs.existsSync(path.join(root, '.agents', 'mcp_config.json'))
+  ) {
+    detected.push('antigravity');
+  }
+  if (
+    fs.existsSync(path.join(root, 'opencode.json')) ||
+    fs.existsSync(path.join(root, 'opencode.jsonc')) ||
+    fs.existsSync(path.join(root, '.opencode'))
+  ) {
+    detected.push('opencode');
+  }
   if (fs.existsSync(path.join(root, '.windsurf'))) detected.push('windsurf');
   if (fs.statSync(path.join(root, '.clinerules'), { throwIfNoEntry: false })?.isDirectory()) {
     detected.push('cline');
   }
+  // One-catalog trees may have `.agents/skills` and no host marker dir.
+  // Without this, a colleague who `npm install`s a new pin keeps stale doors silently.
+  if (
+    fs.existsSync(path.join(root, SKILL_CANONICAL_DIR)) &&
+    !detected.some((tool) => skillTargetIsCanonical(tool))
+  ) {
+    detected.push(SKILL_CANONICAL_TOOL);
+  }
   const version = arkPackageVersion();
   const gaps = [];
   for (const tool of detected) {
@@ -1150,7 +1186,9 @@ export function detectSkillGaps(root) {
 export function skillGapsForActiveHost(skillGaps, env = process.env) {
   const activeHost = detectActiveAgentHost(env);
   if (!activeHost) return skillGaps ?? [];
-  return (skillGaps ?? []).filter((gap) => gap.tool === activeHost);
+  return (skillGaps ?? []).filter(
+    (gap) => gap.tool === activeHost || gap.tool === SKILL_CANONICAL_TOOL
+  );
 }
 
 /**
@@ -1174,7 +1212,7 @@ export function printSkillAndCodexGapHints(root, opts) {
     );
     const missingTotal = remaining.reduce((sum, gap) => sum + gap.missing, 0);
     const staleTotal = remaining.reduce((sum, gap) => sum + gap.stale, 0);
-    const tools = remaining.map((gap) => gap.tool).join(', ');
+    const tools = remaining.map((gap) => skillGapToolLabel(gap.tool)).join(', ');
     if (legacyCodex) {
       console.log(
         color.yellow(
@@ -1200,9 +1238,9 @@ export function printSkillAndCodexGapHints(root, opts) {
     }
     if (staleTotal > 0) {
       console.log(
-        color.dim(
+        color.yellow(
           `${staleTotal} /ark-* skill(s) content behind this Ark package for ${tools}. ` +
-            `Refresh: ${arkCommand(root, 'ark-check', '--install-agent-gates --skills-only --force')}`
+            `Refresh skills only (do not re-adopt): ${arkCommand(root, 'ark-check', '--install-agent-gates --skills-only --force')}`
         )
       );
     }

package/bin/lib/start-preview.mjs

@@ -122,6 +122,73 @@ export function setupBudget(changes) {
   };
 }
 
+/** One next write when compact start is the wrong size. `--force` does not unlock. */
+export const START_SETUP_BUDGET_NEXT = 'arkgate-check --init';
+
+function formatSetupKb(bytes) {
+  return `${Math.max(1, Math.round(Number(bytes) / 1024))} KB`;
+}
+
+/**
+ * Compact-start size lock. `--force` unlocks coverage/shape only — never this.
+ * @param {object|null|undefined} setupBudget
+ * @param {{ force?: boolean }} [options]
+ */
+export function evaluateStartSetupBudgetGate(setupBudget, { force = false } = {}) {
+  if (!setupBudget || setupBudget.ok) {
+    return { ok: true, forceIgnored: Boolean(force) };
+  }
+  const reasons = [];
+  const maxFiles = setupBudget.maxFiles ?? 8;
+  const maxBytes = setupBudget.maxBytes ?? 32 * 1024;
+  const gateFiles =
+    typeof setupBudget.gateFiles === 'number' ? setupBudget.gateFiles : setupBudget.files;
+  if (typeof gateFiles === 'number' && gateFiles > maxFiles) {
+    reasons.push(`${gateFiles} gate files (max ${maxFiles})`);
+  }
+  if (typeof setupBudget.bytes === 'number' && setupBudget.bytes >= maxBytes) {
+    reasons.push(`${formatSetupKb(setupBudget.bytes)} (max ${formatSetupKb(maxBytes)})`);
+  }
+  if (reasons.length === 0) {
+    reasons.push('the planned write is larger than compact start allows');
+  }
+  return {
+    ok: false,
+    reasons,
+    nextAction: START_SETUP_BUDGET_NEXT,
+    forceBypasses: false,
+    setupBudget,
+  };
+}
+
+/**
+ * Human refuse / preview warning. Avoids the first-run phrase "Compact setup budget".
+ * @param {object|null|undefined} setupBudget
+ * @param {{ applying?: boolean }} [options]
+ */
+export function formatStartSetupBudgetRefuse(setupBudget, { applying = true } = {}) {
+  const gate = evaluateStartSetupBudgetGate(setupBudget);
+  if (gate.ok) return '';
+  const facts = gate.reasons.map((reason) => `  • ${reason}`).join('\n');
+  const next = `--force does not unlock this. Next: ${gate.nextAction}`;
+  if (applying) {
+    return `Refusing ark start --apply: this plan is too big for compact start.\n${facts}\n${next}`;
+  }
+  return `This plan is too big for compact start.\n${facts}\nApply will refuse. ${next}`;
+}
+
+/** Apply-path emit: JSON envelope or human refuse. Call before any “writing…” copy. */
+export function emitStartSetupBudgetRefuse(preview, json) {
+  const gate = evaluateStartSetupBudgetGate(preview.setupBudget);
+  if (json) {
+    console.log(
+      JSON.stringify({ ok: false, error: 'start-setup-budget-gate', ...gate, preview }, null, 2)
+    );
+    return;
+  }
+  console.error(formatStartSetupBudgetRefuse(preview.setupBudget, { applying: true }));
+}
+
 function commands(root, args, helpers) {
   if (args.removeHost) {
     return [`ark start --root ${root} --tools ${args.removeHost} --apply`];
@@ -160,6 +227,7 @@ export function formatStartPackageInstallFailure({ exitStatus, installCommand })
  */
 export function renderStartPreview(preview, options = {}) {
   const applying = options.applying === true;
+  const budgetOk = preview.setupBudget?.ok !== false;
   if (applying) {
     console.log(
       preview.changes.length === 0
@@ -170,7 +238,11 @@ export function renderStartPreview(preview, options = {}) {
     console.log('Ark start preview — no files were changed.');
   }
   if (!applying) {
-    console.log('Apply this plan with: arkgate start --apply');
+    if (budgetOk) {
+      console.log('Apply this plan with: arkgate start --apply');
+    } else {
+      console.log(formatStartSetupBudgetRefuse(preview.setupBudget, { applying: false }));
+    }
   }
   if (preview.analysis) {
     console.log(`Your project looks like: ${preview.analysis.label}.`);
@@ -208,8 +280,8 @@ export function renderStartPreview(preview, options = {}) {
 }
 
 export function applyStartPreview(root, preview) {
-  if (!preview.setupBudget?.ok) {
-    throw new Error('Refusing to apply a start plan that exceeds the compact setup budget.');
+  if (!evaluateStartSetupBudgetGate(preview.setupBudget).ok) {
+    throw new Error(formatStartSetupBudgetRefuse(preview.setupBudget, { applying: true }));
   }
   for (const change of preview.changes) {
     const target = path.join(root, change.path);

package/dist/{diagnosticCatalog-KWvGLI1U.d.ts → diagnosticCatalog-BNxKdcN4.d.ts}

@@ -392,7 +392,7 @@ declare function createAdapterResult(input: {
 }): CurrentAdapterResult;
 
 /** ArkGate library version — single source of truth. */
-declare const version = "4.8.16";
+declare const version = "4.8.18";
 
 /**
  * AI Code Gate (basic).
@@ -1971,6 +1971,12 @@ type PolicyDeltaAcknowledgement = {
     candidatePolicyHash: string;
     findingIds: readonly string[];
     reason: string;
+    /**
+     * Relative decision-note path under a conventional home (`docs/adr/`,
+     * `docs/decisions/`, or the AP01 single-file homes). Tooling checks the file.
+     * Hash matching does not require it.
+     */
+    adrPath?: string;
 };
 type ClassifyArkPolicyDeltaOptions = {
     baseArkRules?: EffectiveArkRules;