arkgate 4.8.18 → 4.8.20

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/config-contract.mjs

@@ -228,6 +228,7 @@ export const ARK_CONFIG_SCHEMA = {
                         },
                     },
                 },
+                sharedImportsSlice: { type: 'string', enum: ['deny'] },
             },
         },
         safety: {

package/bin/lib/doctor-advisories.mjs

@@ -200,7 +200,8 @@ export function computeDoctorAdvisories(root, config, cov, rules, files, ts, par
     physicalCohesion,
     files,
     root,
-    decisionMemory
+    decisionMemory,
+    { layers: config?.layers, rules: rules ?? config?.rules }
   );
   // Prefer architecture facts paths when available; still union the doctor walk
   // so an empty-catalog residual can see Domain files the facts subset missed.

package/bin/lib/doctor-human.mjs

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

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

@@ -9,6 +9,36 @@ 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) {
@@ -119,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 &&
@@ -259,6 +291,9 @@ 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)];
   }

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';
@@ -59,6 +59,7 @@ import {
 import {
   buildCoverageHonesty,
   computeDoctorEnforcementHonesty,
+  physicalCohesionResidualRemains,
 } from './enforcement-honesty.mjs';
 import {
   computePureLayerOptInNudge,
@@ -653,6 +654,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 +683,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,
@@ -695,6 +694,7 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
       github: githubForBoundary,
       adoptionStance: stanceFile,
       stewardNudge: doctorAdvisories.stewardNudge,
+      physicalCohesionResidual: physicalCohesionResidualRemains(doctorAdvisories.physicalCohesion),
     });
 
   // Improvement compass: projection only — never feeds ok/valid/goal.met.
@@ -752,7 +752,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 +908,7 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
     coverageHonesty,
     cov,
     packageVersionTruth,
-    dualTruthNext,
+    dualTruthNext, packageInstalled, selfHost,
     activeCount,
     writePath,
     gatesMissing,

package/bin/lib/enforcement-honesty.mjs

@@ -288,14 +288,26 @@ export function buildWritePathHonesty(activeHost, hardWriteActive = false, extra
  *   primaryNextAction?: string | null,
  *   operatingMode?: string | null,
  *   activeBlockingViolations?: number | null,
+ *   physicalCohesionResidual?: boolean,
  * }} input
  */
+export function physicalCohesionResidualRemains(cohesion) {
+  const findings = Array.isArray(cohesion?.findings) ? cohesion.findings : [];
+  if (findings.length === 0) return false;
+  const covered = new Set();
+  for (const row of cohesion?.reshapeDecisions?.current ?? []) {
+    if (row?.suppressesPilot === true && typeof row.concept === 'string') covered.add(row.concept);
+  }
+  return findings.some((finding) => !covered.has(finding?.concept));
+}
+
 export function buildProductHonesty(input = {}) {
   const reasons = [];
   const cov = input.coverageHonesty;
   const base = input.baselineHonesty;
   const write = input.writePathHonesty;
   const designWeak = input.designWeak === true;
+  const cohesionResidual = input.physicalCohesionResidual === true;
   const dualTruth = input.packageVersionTruth?.dualTruth === true;
   const pinCode = input.packageVersionTruth?.code || write?.packagePinCode || null;
   const pinAbsent =
@@ -365,6 +377,14 @@ export function buildProductHonesty(input = {}) {
     });
   }
 
+  if (cohesionResidual) {
+    reasons.push({
+      id: 'physical-cohesion-residual',
+      message:
+        'Physical cohesion residual remains — the gate verdict and exit code are unchanged, and the reshape card is one judgment, not a queue to empty.',
+    });
+  }
+
   if (dualTruth) {
     reasons.push({
       id: 'package-version-dual-truth',
@@ -551,6 +571,12 @@ export function buildProductHonesty(input = {}) {
     headline = 'Advisory-only adoption — merge status is not required';
   } else if (!unfinished) {
     headline = 'Honesty clear on residual signals';
+  } else if (
+    wholeTreeGoverned &&
+    architectureReasons.length === 1 &&
+    architectureReasons[0].id === 'physical-cohesion-residual'
+  ) {
+    headline = 'Residual remaining';
   } else if (coverageIncomplete) {
     headline = 'Not finished / not whole-tree guarantee';
   } else {
@@ -592,8 +618,8 @@ export function buildProductHonesty(input = {}) {
         : 'unknown';
 
   return {
-    finished: !unfinished && wholeTreeGoverned && !designWeak && activeBlocking === 0,
-    elegant: !designWeak && !base?.dirtyBaselineRisk && !designSmellsOpenEdges && activeBlocking === 0,
+    finished: !unfinished && wholeTreeGoverned && !designWeak && !cohesionResidual && activeBlocking === 0,
+    elegant: !designWeak && !cohesionResidual && !base?.dirtyBaselineRisk && !designSmellsOpenEdges && activeBlocking === 0,
     wholeTreeGuarantee:
       wholeTreeGoverned &&
       !designWeak &&
@@ -656,6 +682,7 @@ export function computeDoctorEnforcementHonesty({
   stewardNudge,
   nativeFailClosed,
   nativeFailClosedPolicy,
+  physicalCohesionResidual,
 } = {}) {
   const coverageHonesty = buildCoverageHonesty({
     percent: governedPercent,
@@ -713,6 +740,7 @@ export function computeDoctorEnforcementHonesty({
     considerMergeBoundary: true,
     emptyStewards,
     stewardNudge,
+    physicalCohesionResidual,
   });
   return {
     coverageHonesty,

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

@@ -17,6 +17,7 @@ import {
   buildBaselineHonesty,
   buildWritePathHonesty,
   buildProductHonesty,
+  physicalCohesionResidualRemains,
 } from './enforcement-honesty.mjs';
 import { summarizeRulesUnderContract } from './rules-under-contract.mjs';
 import { attachExtraDoctorSections } from './doctor-advisories.mjs';
@@ -25,6 +26,7 @@ import { describePackageVersionDualTruth } from './field-install.mjs';
 import { buildDoctorImprovementCompass } from './improvement-compass-doctor.mjs';
 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';
 
 function esc(value) {
@@ -153,6 +155,8 @@ export function buildReportDepthPayload(
       : packageVersionTruth?.code === 'PACKAGE_PIN_ABSENT'
         ? 'Add arkgate to package.json and install so CI/npx resolve this CLI (PACKAGE_PIN_ABSENT)'
         : null;
+  const physicalCohesion = computePhysicalCohesion(root, files);
+  physicalCohesion.reshapeDecisions = computeReshapeDecisionMemory(root, files).summary;
   const productHonesty = buildProductHonesty({
     coverageHonesty,
     baselineHonesty,
@@ -169,9 +173,9 @@ export function buildReportDepthPayload(
       : null,
     primaryNextAction: postGreenPath?.action ?? dualTruthNext,
     activeBlockingViolations: activeBlockingCount,
+    physicalCohesionResidual: physicalCohesionResidualRemains(physicalCohesion),
   });
   // Doctor parity: same physical-cohesion + baseline stale facts as runDoctor.
-  const physicalCohesion = computePhysicalCohesion(root, files);
   const baselineStale =
     typeof baselineSplit.baselineStale === 'number' ? baselineSplit.baselineStale : null;
   // Improvement compass — same projection as doctor; notAScore; never a gate input.
@@ -224,7 +228,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/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/invariant-coverage.mjs

@@ -19,7 +19,7 @@ export const INVARIANT_COVERAGE_ROOTS_MESSAGE = 'A domain invariant is enforced,
  * `omitBudget` drops the budget clause and the load totals for messages whose
  * own text already carries them — the same number twice reads as two facts.
  */
-function formatCoverageDiscards(stats, omitBudget = false) {
+export function formatCoverageDiscards(stats, omitBudget = false) {
     if (!stats)
         return '';
     const d = stats.discarded;
@@ -62,22 +62,50 @@ function titleMatchesInvariant(content, id) {
     const re = new RegExp(`(?:describe|it|test|context)\\s*\\(\\s*['"\`][^'"\`]*${escaped}[^'"\`]*['"\`]`, 'i');
     return re.test(content) || content.includes(id);
 }
-function symbolPresent(fileContents, symbol) {
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * True when `name` is declared here. Imports and calls do not count.
+ * `export const name =` is the same binding shape sensors already treat as a
+ * declaration (arrow or function). The last segment of `Aggregate.method` is
+ * the name that must be declared.
+ */
+function declaresIdentifier(content, name) {
+    const n = escapeRegExp(name);
+    const functionDecl = new RegExp(`(?:^|[\\s;{}])(?:export\\s+(?:default\\s+)?)?(?:declare\\s+)?(?:async\\s+)?function\\s*\\*?\\s*${n}\\s*[(<]`);
+    const classDecl = new RegExp(`(?:^|[\\s;{}])(?:export\\s+(?:default\\s+)?)?(?:abstract\\s+)?class\\s+${n}\\b`);
+    const constDecl = new RegExp(`(?:^|[\\s;{}])export\\s+(?:const|let|var)\\s+${n}\\s*=`);
+    const methodDecl = new RegExp(`(?:^|[\\n;{}])\\s*(?:(?:public|private|protected|static|async|readonly|override|abstract|get|set|declare)\\s+)*${n}\\s*(?:<[^>\\n]*>)?\\s*\\([^;{}]*\\)\\s*(?::\\s*[^;{]+)?\\s*\\{`);
+    return (functionDecl.test(content) ||
+        classDecl.test(content) ||
+        constDecl.test(content) ||
+        methodDecl.test(content));
+}
+/** Witness path, or undefined when no non-test file declares `symbol`. */
+function symbolPresent(fileContents, testFiles, symbol) {
     if (!symbol)
-        return false;
-    // Support Aggregate.method or bare method name.
+        return undefined;
     const parts = symbol.split('.');
-    const needle = parts[parts.length - 1];
+    const needle = parts[parts.length - 1] ?? '';
+    if (!needle)
+        return undefined;
     const className = parts.length > 1 ? parts[0] : null;
-    for (const content of Object.values(fileContents)) {
+    const tests = new Set(testFiles.map((file) => file.replace(/\\/g, '/').replace(/^\.\//, '')));
+    const files = Object.keys(fileContents).sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+    for (const file of files) {
+        const normalized = file.replace(/\\/g, '/').replace(/^\.\//, '');
+        if (tests.has(normalized))
+            continue;
+        const content = fileContents[file];
+        if (!content)
+            continue;
         if (className && !content.includes(className))
             continue;
-        if (new RegExp(`(?:function\\s+|\\b)${needle.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\s*[(<]`).test(content) ||
-            content.includes(symbol)) {
-            return true;
-        }
+        if (declaresIdentifier(content, needle))
+            return file;
     }
-    return false;
+    return undefined;
 }
 export function evaluateInvariantCoverage(input) {
     const invariants = input.arkRules.invariants ?? [];
@@ -131,9 +159,11 @@ export function evaluateInvariantCoverage(input) {
             if (testEvidenceFile !== undefined)
                 evidence.push('test-title');
         }
-        if (symbol && symbolPresent(input.fileContents, symbol)) {
+        const symbolEvidenceFile = symbol
+            ? symbolPresent(input.fileContents, testFiles, symbol)
+            : undefined;
+        if (symbolEvidenceFile)
             evidence.push('symbol');
-        }
         // Covered if any requested evidence is present.
         // When coverage declares neither test nor symbol, require at least description-only advisory presence = not covered.
         const requiresEvidence = inv.coverage?.test === true || Boolean(symbol) || inv.coverage === undefined;
@@ -154,6 +184,7 @@ export function evaluateInvariantCoverage(input) {
             partial,
             description: inv.description,
             ...(testEvidenceFile !== undefined ? { testEvidenceFile } : {}),
+            ...(symbolEvidenceFile !== undefined ? { symbolEvidenceFile } : {}),
             ...(outsideDeclaredRoots !== undefined ? { outsideDeclaredRoots } : {}),
             coverageRootsDeclared: rootsDeclared,
         });

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/package-manager.mjs

@@ -94,9 +94,12 @@ export function arkCommand(root, bin, argsStr = '') {
 /**
  * Run an Ark binary from package `arkgate` when local bins may be missing.
  * Bare `npx arkgate-check` 404s — npx treats that bin name as its own package.
+ * Pass `packageSpec` (e.g. `arkgate@4.8.19`) when Age blocked a local add.
  */
-export function arkPackageRecoveryCommand(bin, argsStr = '') {
-  return `npx --package=arkgate ${bin}${argsStr ? ` ${argsStr}` : ''}`;
+export function arkPackageRecoveryCommand(bin, argsStr = '', packageSpec) {
+  const spec =
+    typeof packageSpec === 'string' && packageSpec.trim() ? packageSpec.trim() : 'arkgate';
+  return `npx --package=${spec} ${bin}${argsStr ? ` ${argsStr}` : ''}`;
 }
 
 /**