arkgate 4.8.17 → 4.8.19

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

@@ -201,7 +201,7 @@ const AGENT_CONTRACT = {
   ],
   // Cursor-only guidance: the write-time validate_code tool is available in
   // Cursor's runtime but has no equivalent in a plain AGENTS.md read.
-  cursorValidateStep: `Validate the full post-edit file content with the \`validate_code\` tool before writing whenever your runtime supports it.`,
+  cursorValidateStep: `The write gate is the host pre-hook when \`.cursor/hooks.json\` is installed, trusted, and \`failClosed\`. Call \`ark_prepare_write\` / \`validate_code\` only as fallback if that hook is missing or fail-open.`,
 };
 
 /**
@@ -413,7 +413,7 @@ Contener · Guiar · Ordenar — contain the write, guide the next step, order l
 1. Status anytime: \`${doctorCmd}\` — what's wrong and what to do first.
 2. Read the **Improvement compass** section (not a score). Name residual lenses in plain language when present (SoC, DIP, domain, …). Out-of-scope lenses (performance, app security tooling, full resilience) stay honest — do not invent Ark enforcement for them.
 3. CLI-first: if the local CLI already resolved this project root, do not wait on MCP “still connecting”. Identity handshake is optional in that case. When you do trust MCP evidence: call \`ark_identity\` with \`project.expectedRoot\` set to this project's exact absolute root, then reuse that root plus the returned \`projectIdentity.projectId\` on every Ark MCP call. A descendant path is authoritative only with that matching id. Missing tool, non-\`matched\` binding, or wrong root means this is not proven to be the right project: restart the host and use the local CLI meanwhile.
-4. Day to day: call \`ark_manifest\` with the same project expectation (or skip if CLI already bound the root); place new files with \`ark_place\` (filePath required — fail-closed); validate after edits; run \`${checkCmd}\`. The \`ark://manifest\` resource is compatibility-only and always unverified. On a deny, fix the illegal import — do not weaken \`ark.config.json\`.
+4. Day to day: call \`ark_manifest\` with the same project expectation (or skip if CLI already bound the root); place new files with \`ark_place\` (filePath required — fail-closed); run \`${checkCmd}\`. The host pre-hook is the write gate when installed; MCP \`ark_prepare_write\` is fallback if that hook is missing or fail-open. The \`ark://manifest\` resource is compatibility-only and always unverified. On a deny, fix the illegal import — do not weaken \`ark.config.json\`.
 5. If MCP is unavailable: inspect \`ark.config.json\` and run \`${checkCmd}\`. The host-readable projection is AGENTS.md and CLAUDE.md (same schema).
 
 **Single door when residual remains:**

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 {
@@ -147,6 +147,8 @@ export function printDoctorCompactHuman(view) {
     if (skippableCi) line(warn, skippableCi);
     else if (writePathHonesty?.nativeFailClosed === false) {
       line(warn, writePathHonesty.message || 'Write hook is fail-open — if the checker cannot run, the write still lands.');
+    } else if (listedMissing.length === 0 && writePath.gap?.id === 'write-path-mcp-only') {
+      line(warn, writePath.gap.message || 'Fell back to MCP prepare; required CI is the merge boundary.');
     } else if (listedMissing.length === 0 && (writePath.gap || writePathHonesty?.softWriteHost)) {
       line(warn, 'Local writes are advisory; required CI is the merge boundary.');
     }
@@ -467,7 +469,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,13 +2,43 @@
  * 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';
 import { ADOPTED_NOT, NOT_ADOPTED_NEXT_ACTION } from './adoption-stance.mjs';
 import { REQUIRED_GATE_WORKFLOW } from './gate-files.mjs';
 
+/** Package pin may exist; local resolve still failed. Lead with install, not CI. */
+export const PACKAGE_UNRESOLVED_NEXT_ACTION =
+  'Install arkgate in this project first (npx --package=arkgate, or pnpm add -D arkgate -w / yarn add -D arkgate -W at a workspace root), then re-run --doctor';
+
+export function packageUnresolvedNextAction(ctx) {
+  if (ctx?.packageInstalled !== false || ctx?.selfHost === true) return null;
+  const code = ctx?.packageVersionTruth?.code;
+  if (code === 'PACKAGE_PIN_SELF_HOST' || code === 'PACKAGE_PIN_ABSENT') return null;
+  // Failed start --apply: pin is in package.json, node_modules did not resolve.
+  if (code === 'PACKAGE_PIN_MATCHES' || code === 'PACKAGE_PIN_BEHIND_CLI' || ctx?.packagePinned === true) {
+    return PACKAGE_UNRESOLVED_NEXT_ACTION;
+  }
+  return null;
+}
+
+/** Compact doctor JSON #1 — same rank as collectDoctorNextActions when package is missing. */
+export function preferredDoctorPrimaryNextAction({
+  adopted,
+  packageInstalled,
+  selfHost,
+  packageVersionTruth,
+  postGreenPath,
+  dualTruthNext,
+} = {}) {
+  return (
+    packageUnresolvedNextAction({ packageInstalled, selfHost, packageVersionTruth }) ||
+    (adopted === 'not-adopted' ? NOT_ADOPTED_NEXT_ACTION : postGreenPath?.action ?? dualTruthNext ?? null)
+  );
+}
+
 function missingGateFiles(ctx) {
   const list = Array.isArray(ctx.gatesMissing) ? ctx.gatesMissing : [];
   if (ctx.ciNotFailClosed) {
@@ -17,6 +47,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);
@@ -26,6 +149,8 @@ export function collectDoctorNextActions(ctx) {
   if (notAdopted || ctx.adopted === ADOPTED_NOT || ctx.adopted == null) {
     actions.push(ctx.notAdoptedNextAction || NOT_ADOPTED_NEXT_ACTION);
   }
+  const resolvePkg = packageUnresolvedNextAction(ctx);
+  if (resolvePkg) actions.push(resolvePkg);
   const nudge = ctx.stewardNudge;
   if (
     nudge &&
@@ -37,9 +162,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 +212,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 +244,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 +291,12 @@ export function collectDoctorNextActions(ctx) {
   if (ctx.designFitness.designWeak && unique.length === 0 && ctx.postGreenPath) {
     unique.push(ctx.postGreenPath.action);
   }
+  if (resolvePkg) {
+    return [resolvePkg, ...unique.filter((a) => a !== resolvePkg)];
+  }
+  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/doctor-plan.mjs

@@ -13,7 +13,7 @@ import * as arkShared from '../ark-shared.mjs';
 import { summarizeRulesUnderContract } from './rules-under-contract.mjs';
 import { describePackageVersionDualTruth } from './field-install.mjs';
 import { detectAgentHomeGaps } from './agent-homes.mjs';
-import { collectDoctorNextActions } from './doctor-next-actions.mjs';
+import { collectDoctorNextActions, preferredDoctorPrimaryNextAction } from './doctor-next-actions.mjs';
 import { printDoctorCompactHuman, printDoctorDetailsHuman } from './doctor-human.mjs';
 import { collectLayerOwnerResidual, layerGuidanceLine, placementDescriptionFields } from './layer-description.mjs';
 import { collectAdrPresenceResidual, printAdrPresenceHint } from './adr-presence.mjs';
@@ -653,6 +653,7 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
   const statusTransitionCatalog = collectStatusTransitionCatalogResidual({ root, config, files, statesTransitions });
   const noDomainFrontend = collectNoDomainFrontendResidual({ config, coverage: cov, designSmells });
   const { invariantCoverageRoots, invariantTestsPath } = collectInvariantCoverageResiduals({ adopted: isAdopted(adopted) || options.requireGates === true, coverage: config?.coverage, config, root });
+  const selfHost = packageVersionTruth?.selfHost === true || packageVersionTruth?.code === 'PACKAGE_PIN_SELF_HOST';
   const { coverageHonesty, baselineHonesty, writePathHonesty, productHonesty } =
     computeDoctorEnforcementHonesty({
       governedPercent: cov.governed.percent,
@@ -681,13 +682,10 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
         : rulesUnderContract?.active === true || arkRun?.active === true || doctorAdvisories.arkOrder?.active === true
           ? { active: true, extraMergeTeeth: arkRun?.extraMergeTeeth === true || doctorAdvisories.arkOrder?.extraMergeTeeth === true }
           : null,
-      primaryNextAction:
-        adopted === 'not-adopted' ? NOT_ADOPTED_NEXT_ACTION : postGreenPath?.action ?? dualTruthNext,
+      primaryNextAction: preferredDoctorPrimaryNextAction({ adopted, packageInstalled, selfHost, packageVersionTruth, postGreenPath, dualTruthNext }),
       operatingMode,
       packageInstalled,
-      selfHost:
-        packageVersionTruth?.selfHost === true ||
-        packageVersionTruth?.code === 'PACKAGE_PIN_SELF_HOST',
+      selfHost,
       nativeFailClosed: writePath.nativeFailClosed,
       nativeFailClosedPolicy: writePath.nativeFailClosedPolicy,
       adopted,
@@ -752,7 +750,7 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
             adoptionStance: adopted,
             ...(adopted === 'not-adopted'
               ? {
-                  primaryNextAction: NOT_ADOPTED_NEXT_ACTION,
+                  primaryNextAction: productHonesty.primaryNextAction || NOT_ADOPTED_NEXT_ACTION,
                   ...(postGreenPath ? DESIGN_WEAK_HONESTY_FLAGS : {}),
                 }
               : postGreenPath
@@ -908,7 +906,7 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
     coverageHonesty,
     cov,
     packageVersionTruth,
-    dualTruthNext,
+    dualTruthNext, packageInstalled, selfHost,
     activeCount,
     writePath,
     gatesMissing,

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).
@@ -303,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/gate-files.mjs

@@ -152,9 +152,30 @@ export function isCompactRouterAgentsContent(text) {
   return typeof text === 'string' && COMPACT_ROUTER.test(text);
 }
 
+function hasCursorFailClosedHook(root) {
+  try {
+    const parsed = readJson(path.join(root, '.cursor', 'hooks.json'));
+    const entries = Array.isArray(parsed?.hooks?.preToolUse) ? parsed.hooks.preToolUse : [];
+    return entries.some(
+      (entry) =>
+        entry &&
+        typeof entry === 'object' &&
+        entry.failClosed === true &&
+        typeof entry.command === 'string' &&
+        /(?:^|\s)--hook(?:\s|$)/.test(entry.command)
+    );
+  } catch {
+    return false;
+  }
+}
+
+function hasCursorCompactRegistration(root) {
+  return hasArkMcpRegistration(root, '.cursor/mcp.json') && hasCursorFailClosedHook(root);
+}
+
 function hasCompactHostRegistration(root, host) {
   if (host === 'none') return hasArkMcpRegistration(root);
-  if (host === 'cursor') return hasArkMcpRegistration(root, '.cursor/mcp.json');
+  if (host === 'cursor') return hasCursorCompactRegistration(root);
   if (host === 'codex') return hasCodexCompactRegistration(root);
   const files = COMPACT_HOST_FILES[host];
   return Boolean(files) && files.every((relativePath) => fs.existsSync(path.join(root, relativePath)));

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

@@ -197,7 +197,7 @@ Codex hard write covers only a complete local \`apply_patch\`; Cursor covers onl
 installed + trusted, while shell/direct
 filesystem writes, hosted or specialized opt-out paths, and human edits still rely on CI.
 
-This table describes the supported profile **after its files are installed and the host loads/trusts them**. A hard local boundary covers only the listed hook operations; alternate tools, direct filesystem writes, and human edits still rely on CI. MCP validation is advisory because the agent must call it. The CI check blocks a merge only when the repository makes that status required. Repair **envelopes** may be emitted without reinjection being guaranteed; silent auto-apply never happens. Run \`arkgate-check --doctor\` (or \`ark-check --doctor\`) for the evidence actually detected in the current repository.`;
+This table describes the supported profile **after its files are installed and the host loads/trusts them**. A hard local boundary covers only the listed hook operations; alternate tools, direct filesystem writes, and human edits still rely on CI. **Write-gate order:** install and trust the host pre-hook first. MCP prepare is fallback when that path is missing or fail-open. MCP validation is advisory because the agent must call it. The CI check blocks a merge only when the repository makes that status required. Repair **envelopes** may be emitted without reinjection being guaranteed; silent auto-apply never happens. Run \`arkgate-check --doctor\` (or \`ark-check --doctor\`) for the evidence actually detected in the current repository.`;
 }
 
 /**

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

@@ -224,7 +224,7 @@ export function writePathModeHint(mode) {
     case 'reject-only':
       return 'Hard write boundary without repair payload; edits can be blocked without guided re-entry.';
     case 'mcp-only':
-      return 'Advisory MCP only — prepare-write/autoPatch available, no hard PreToolUse for this host.';
+      return 'Fell back to MCP prepare — advisory prepare-write/autoPatch; no hard PreToolUse for this host.';
     case 'none':
       return 'No hard write boundary or advisory MCP for the active host (or host is unknown in this process).';
     default:

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/install-migrate.mjs

@@ -200,10 +200,9 @@ export function buildManagedAssetCatalog({ root, tools, compact = false, skillsO
       })
     );
     if (selectedTools.has('cursor')) {
-      add('.cursor/mcp.json', mcpJson(root));
-      // whole-file for managed upgrade/manifest (json-merge is install-time only via
-      // mergeCursorArkHook below — same pattern as Antigravity hooks).
+      // Write-gate order: pre-hook first, MCP prepare as fallback + identity.
       add('.cursor/hooks.json', cursorHooks(root));
+      add('.cursor/mcp.json', mcpJson(root));
       if (!compact) add('.cursor/rules/ark.mdc', cursorRule(root));
     }
     if (selectedTools.has('claude')) add('.claude/settings.json', claudeSettings(root));
@@ -213,8 +212,8 @@ export function buildManagedAssetCatalog({ root, tools, compact = false, skillsO
       if (!compact) add('docs/ark-codex-config.toml', codexTomlSnippet(root));
     }
     if (selectedTools.has('grok')) {
-      add('.grok/config.toml', grokProjectConfig(root));
       add('.grok/hooks/ark-write-gate.json', grokHooks(root));
+      add('.grok/config.toml', grokProjectConfig(root));
     }
     if (selectedTools.has('antigravity')) {
       add('.agents/hooks.json', antigravityHooks(root));

package/bin/lib/managed-upgrade.mjs

@@ -17,6 +17,7 @@ import {
   arkPackageVersion,
   detectActiveAgentHost,
   normalizeToolsList,
+  planSkillInstall,
   skillContentIdentity,
 } from './skill-install.mjs';
 
@@ -396,8 +397,11 @@ function summaryFor(assets, manifestChanged) {
   for (const asset of assets) states[asset.state] = (states[asset.state] ?? 0) + 1;
   const applying = assets.filter((asset) => asset.willApply);
   const wouldWrite = applying.length;
-  // Public-summary compatibility: stamp-only writes are no longer scheduled.
-  const metadataRefresh = 0;
+  // Same-body stamp drift (arkVersion / description prefix) stays state=current
+  // and is scheduled via planSkillInstall stamp-refresh — not a second pipeline.
+  const metadataRefresh = applying.filter(
+    (asset) => asset.state === 'current' && asset.reason === 'stamp-refresh'
+  ).length;
   const customizedPreserved = assets.filter((asset) => asset.state === 'customized').length;
   const fileChanges = applying.length;
   return {
@@ -477,9 +481,23 @@ export function planManagedUpgrade(root, options = {}) {
       refreshSkills &&
       catalogAsset.kind === 'skill' &&
       classified.state === 'customized';
+    // HS01 / #284: identity-current skill whose arkVersion / description prefix
+    // lagged the package — reuse planSkillInstall stamp-refresh, do not reclassify.
+    const stampRefresh =
+      !unparsedScope &&
+      catalogAsset.kind === 'skill' &&
+      classified.state === 'current' &&
+      currentScoped != null &&
+      planSkillInstall({
+        existingContent: currentScoped,
+        targetContent: desiredScoped,
+        packageVersion: catalog.version ?? arkPackageVersion(),
+        scope: 'repo',
+      }).reason === 'stamp-refresh';
     const canApply =
       classified.state === 'stale' ||
       skillRefresh ||
+      stampRefresh ||
       (classified.state === 'missing' && (!recorded || accepted)) ||
       (classified.state === 'conflicted' && accepted);
     const blocked = classified.requiresConsent && !accepted && !skillRefresh;
@@ -490,7 +508,11 @@ export function planManagedUpgrade(root, options = {}) {
       kind: catalogAsset.kind,
       scope: catalogAsset.scope,
       ...classified,
-      ...(unparsedScope ? { reason: 'unparsed managed TOML scope preserved' } : {}),
+      ...(unparsedScope
+        ? { reason: 'unparsed managed TOML scope preserved' }
+        : stampRefresh
+          ? { reason: 'stamp-refresh' }
+          : {}),
       action: canApply ? (currentScoped == null ? 'create' : 'update') : 'none',
       willApply: canApply,
       blocked,
@@ -970,8 +992,11 @@ export function renderManagedUpgrade(plan, options = {}) {
   const customizedPreserved = summary.customizedPreserved ?? summary.states?.customized ?? 0;
   const blocked = summary.blocked ?? 0;
   console.log(
-    `Managed assets: ${managedAssets}; would write: ${wouldWrite}; ` +
-      `customized preserved: ${customizedPreserved}; blocked conflicts/deletions: ${blocked}.`
+    `Managed assets: ${managedAssets}; would write: ${wouldWrite}` +
+      (summary.metadataRefresh
+        ? `; metadata refresh: ${summary.metadataRefresh}`
+        : '') +
+      `; customized preserved: ${customizedPreserved}; blocked conflicts/deletions: ${blocked}.`
   );
   const honesty =
     plan.selfService ??

package/bin/lib/mcp-adoption.mjs

@@ -191,7 +191,10 @@ export function collectAdoptionGaps(root, config, coverage) {
         host: 'cursor',
         dir: '.cursor',
         skill: (n) => path.join(root, '.cursor', 'commands', `${n}.md`),
-        extras: [['.cursor/mcp.json', 'MCP config']],
+        extras: [
+          ['.cursor/hooks.json', 'write-gate hook'],
+          ['.cursor/mcp.json', 'MCP config (fallback)'],
+        ],
         toolsFlag: 'cursor',
       },
       {

package/bin/lib/presets.mjs

@@ -10,6 +10,7 @@ import {
   DEFAULT_DOMAIN_FORBIDDEN_GLOBALS,
   discoverRepoUnits,
   DEFAULT_INTENT_PREFIXES,
+  monorepoRoleSourceGlobs,
   resolveIncludeRoots,
 } from '../ark-shared.mjs';
 import { withArkConfigMetadata } from './config-contract.mjs';
@@ -629,27 +630,19 @@ 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 librarySourcePatterns = monorepoRoleSourceGlobs(units, ['library'], {
+      root,
+      domainScoped: true,
+    });
+    const applicationSourcePatterns = monorepoRoleSourceGlobs(units, ['application', 'cli'], {
+      root,
+      uiMode: 'not-ui',
+    });
+    const uiApplicationSourcePatterns = monorepoRoleSourceGlobs(units, ['application', 'cli'], {
+      root,
+      uiMode: 'ui',
+    });
     return presetWithOverlays(
       {
         include,
@@ -695,6 +688,7 @@ export const ARCHITECTURE_PRESETS = {
               '**/http/**',
               '**/routes/**',
               '**/hooks/**',
+              ...uiApplicationSourcePatterns,
               // No bare **/lib/** — NEW-ADOPT-LIB-AS-PRESENTATION / NEW-APP-VACUUM-LIB.
             ],
             optional: true,

package/bin/lib/scan-files.mjs

@@ -4,7 +4,9 @@
  */
 import fs from 'node:fs';
 import path from 'node:path';
-import { isScanExcludedRelative } from '../ark-shared.mjs';
+import { isScanExcludedRelative, isSkippedSourceDir } from '../ark-shared.mjs';
+
+export { isSkippedSourceDir };
 
 export const SOURCE_FILE_NAME = /\.[cm]?[tj]sx?$/;
 
@@ -18,31 +20,6 @@ export function isGovernableSourceFile(name) {
   return SOURCE_FILE_NAME.test(name) && !name.endsWith('.d.ts') && !TEST_FILE_NAME.test(name);
 }
 
-export function isSkippedSourceDir(name) {
-  return (
-    name === 'node_modules' ||
-    name === 'dist' ||
-    name === 'coverage' ||
-    name === 'bench' ||
-    name === 'benches' ||
-    name === 'benchmark' ||
-    name === 'benchmarks' ||
-    name === 'docs' ||
-    name === 'documentation' ||
-    name === 'example' ||
-    name === 'examples' ||
-    name === 'fixture' ||
-    name === 'fixtures' ||
-    name === 'playground' ||
-    name === '__tests__' ||
-    name === '__mocks__' ||
-    name === 'e2e' ||
-    // Top-level style Nest/Jest folders (not "testing" helpers inside src)
-    name === 'test' ||
-    name === 'tests'
-  );
-}
-
 function isInsideRoot(root, target) {
   const rel = path.relative(root, target);
   return rel === '' || (!rel.startsWith(`..${path.sep}`) && rel !== '..' && !path.isAbsolute(rel));