arkgate 3.8.1 → 3.8.2

package/CHANGELOG.md

@@ -5,6 +5,34 @@ in the immutable pre-2.0 archive linked below.
 
 ## Unreleased
 
+## 3.8.2 — 2026-07-22
+
+Corrective **patch** over 3.8.1 from PREDIAL WEB field evidence. Aligns doctor skill freshness with
+managed upgrade content identity, hardens upgrade preview honesty, clarifies doctor writePath
+inventory vs this-invocation, ships the Y06 pure-layer opt-in advisory, and treats complete-catalog
+Codex leftover prompts as safe-to-delete. **No required config migration.** Z09 / residual `RB-11`
+remain open.
+
+### Fixed
+
+- **Doctor skill “stale” vs managed upgrade (field DX):** skill gap detection now uses the same
+  content-identity rules as `ark upgrade` (stamp-normalized). A skill whose body matches the
+  package template is not stale when only `arkVersion` lags. Stale copy says content-behind-package.
+- **Upgrade preview phantom apply:** summary reports `managedAssets` / `wouldWrite` /
+  `customizedPreserved`; when `wouldWrite` is 0, prints “Nothing to apply” instead of urging
+  `--apply` as the primary next step (optional stamp-only apply remains digest-bound).
+- **Doctor writePath honesty:** with `activeHost: unknown`, a `sessionNote` separates on-disk
+  inventory from this-invocation hardness; package `installed` is independent of host support.
+  Hard still requires runtime proof (Z10).
+- **Codex legacy prompts:** complete `.agents/skills` with leftover `.codex/prompts` is an
+  advisory safe-to-delete signal (CLI, doctor, HTML), not an install-agent-gates gap.
+
+### Added
+
+- **Y06 pure-layer opt-in nudge:** when a golden pattern names pure modules and no layer sets
+  `pure: true`, doctor emits one advisory line (`doctor.pureLayerOptIn`). Never a blocker; never
+  auto-writes `pure: true`. Promoted from field evidence (PREDIAL WEB).
+
 ## 3.8.1 — 2026-07-22
 
 Corrective **patch** over 3.8.0. Closes silent fail-open on peerIsolation incomplete evidence,

package/README.md

@@ -16,9 +16,9 @@ and makes sure a “green” check means something real.
 
 </div>
 
-> **ArkGate 3.8.1** is current stable: 3.8.0 complete analysis / resolved verdict / managed upgrades
-> / design-delta, plus peerIsolation fail-closed and pure-IR require/type-only accuracy.
-> [Release notes](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/3.8.1.md).
+> **ArkGate 3.8.2** is current stable: field DX on top of 3.8.1 — skill stale matches upgrade content
+> identity, honest upgrade preview, doctor session notes, Y06 pure opt-in nudge, Codex legacy advisory.
+> [Release notes](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/3.8.2.md).
 
 > **TypeScript 7 distribution note:** ArkGate prefers a usable project compiler API, then its
 > exact, physically distinct TypeScript 6 analysis host. Analysis reports required
@@ -422,7 +422,7 @@ for real systems. Details: [production-hardening.md](https://github.com/pedrokni
 | Security reporting | [SECURITY.md](SECURITY.md) |
 | Demos | [docs/demos/](https://github.com/pedroknigge/arkgate/tree/main/docs/demos) |
 | Examples | [examples/](https://github.com/pedroknigge/arkgate/blob/main/examples/README.md) |
-| Latest release (3.8.1) | [release notes](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/3.8.1.md) · [3.0.0 baseline](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/3.0.0.md) |
+| Latest release (3.8.2) | [release notes](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/3.8.2.md) · [3.0.0 baseline](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/3.0.0.md) |
 | Roadmap and decisions | [ROADMAP.md](https://github.com/pedroknigge/arkgate/blob/main/ROADMAP.md) · [ADRs](https://github.com/pedroknigge/arkgate/tree/main/docs/adr) · [Changelog](CHANGELOG.md) |
 
 ---

package/bin/lib/agent-gates.mjs

@@ -87,8 +87,11 @@ export {
   stampSkill,
   installedSkillVersion,
   isVersionOlder,
+  skillContentIdentity,
+  skillContentMatchesTemplate,
   skillTemplates,
   skillTemplateNames,
+  skillTemplateBodies,
   detectCodexHomeGap,
   detectCodexRepoSkillGap,
   assessCodexSkillParity,

package/bin/lib/doctor-plan.mjs

@@ -36,7 +36,11 @@ import {
   mergePostGreenTopActions,
   isDoctorHealthyNothingToDo,
 } from './post-green-path.mjs';
-import { loadGoldenPattern, summarizeGoldenPattern } from './golden-pattern.mjs';
+import {
+  computePureLayerOptInNudge,
+  loadGoldenPattern,
+  summarizeGoldenPattern,
+} from './golden-pattern.mjs';
 import { summarizePilotLoop } from './pilot-loop.mjs';
 import { computeDoctorAdvisories, printDoctorAdvisories } from './doctor-advisories.mjs';
 import { ANALYSIS_COMPLETENESS, analysisIncompleteStatement, normalizeAnalysisCompleteness } from './analysis-completeness.mjs';
@@ -418,7 +422,10 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
   // Q01 — single post-green door when design-weak (map → B; no skill shopping).
   const postGreenPath = buildPostGreenNextAction(designFitness);
   // Q03 — optional golden pattern for NEW code (advisory; never clears design-weak).
-  const goldenPattern = summarizeGoldenPattern(loadGoldenPattern(root));
+  const goldenLoad = loadGoldenPattern(root);
+  const goldenPattern = summarizeGoldenPattern(goldenLoad);
+  // Y06 — pure-layer opt-in when golden names pure modules but no pure:true layer.
+  const pureLayerOptIn = computePureLayerOptInNudge(config, goldenLoad);
   // Q04 — one next pilot (extraction card) when design-weak.
   const patternBetsForLoop = buildPatternBetsFromSmells(designSmells);
   const pilotLoop = summarizePilotLoop({
@@ -463,6 +470,8 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
               : {}),
             // Q03: advisory golden for new-code placement (absent = no claim).
             goldenPattern,
+            // Y06: advisory pure-layer opt-in (null when not applicable).
+            pureLayerOptIn,
             // Q04: one-pilot loop (extraction card → re-doctor).
             pilotLoop,
             // Advisories, never a verdict: W01 contract health, U05 ambient state,
@@ -507,6 +516,7 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
               hookRepair: writePath.hookRepair,
               mcpPresent: writePath.mcpPresent,
               evidence: writePath.evidence,
+              ...(writePath.sessionNote ? { sessionNote: writePath.sessionNote } : {}),
               ...(writePath.gap
                 ? {
                     gap: {
@@ -655,6 +665,10 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
         'Fix or remove it — absence is fine; a bad file is not guidance.'
     );
   }
+  // Y06 — one-line pure-layer opt-in (U05 voice; never blocker).
+  if (pureLayerOptIn) {
+    line(' ', color.dim(pureLayerOptIn.message));
+  }
 
   printDoctorAdvisories(doctorAdvisories, { line, warn, color }); // advisory sections
 
@@ -756,6 +770,9 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
   line(' ', `Active host: ${writePath.activeHost}`);
   line(' ', `Supported profile: ${writePath.supportSummary}`);
   line(wpMark, `Mode: ${writePath.mode} — ${writePathLabels[writePath.mode] || writePath.mode}`);
+  if (writePath.sessionNote) {
+    line(warn, writePath.sessionNote);
+  }
   const enforcement = writePath.enforcementState;
   for (const row of enforcementDoctorLines(enforcement)) line(row.level === 'ok' ? ok : row.level === 'bad' ? bad : warn, row.text);
   line(
@@ -779,7 +796,12 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
   }
   // Report Codex legacy prompts and other-host missing/stale independently (never exclusive).
   const legacyCodex = skillGaps.some((g) => g.tool === 'codex' && g.legacyPromptsOnly);
-  const remainingGaps = skillGaps.filter((g) => !(g.tool === 'codex' && g.legacyPromptsOnly));
+  const codexLegacySafeDelete = skillGaps.some(
+    (g) => g.tool === 'codex' && g.legacyAdvisory && g.catalogComplete
+  );
+  const remainingGaps = skillGaps.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 (remMiss + remStale === 0 && !legacyCodex) line(ok, '/ark-* skills current for detected tools');
@@ -787,8 +809,19 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
     line(warn, 'Codex: legacy flat .codex/prompts only (not a loadable skill catalog)');
     actions.push('install Codex SKILL.md catalog (--install-agent-gates --skills-only --tools codex --force)');
   }
+  if (codexLegacySafeDelete) {
+    line(
+      ' ',
+      color.dim(
+        'Codex catalog complete — leftover .codex/prompts/ark-*.md are safe to delete (not loadable; not required).'
+      )
+    );
+  }
   if (remMiss + remStale > 0) {
-    line(warn, `${remMiss} missing / ${remStale} outdated /ark-* skill(s) for ${remainingGaps.map((g) => g.tool).join(', ')}`);
+    line(
+      warn,
+      `${remMiss} missing / ${remStale} content-behind-package /ark-* skill(s) for ${remainingGaps.map((g) => g.tool).join(', ')}`
+    );
     actions.push('refresh /ark-* skills (--install-agent-gates --skills-only --force)');
   }
   const codexHomeGap = detectCodexHomeGap(root);
@@ -796,7 +829,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} outdated` : null,
+      codexHomeGap.stale > 0 ? `${codexHomeGap.stale} content-behind-package` : null,
     ].filter(Boolean);
     const deferred = !codexConcernIsActive();
     // Deferred home debt is dim/info (not warn) so non-Codex sessions are not "incomplete".

package/bin/lib/enforcement-state.mjs

@@ -1,2 +1,2 @@
 // Generated from enforcement-state.source.mjs — run npm run generate:packaged-tooling.
-import b from"node:fs";import{createRequire as q}from"node:module";import h from"node:path";const n="unverified";function M(a){const e=h.join(a,"package.json");try{if(JSON.parse(b.readFileSync(e,"utf8"))?.name==="arkgate"&&b.statSync(h.join(a,"bin","ark-check.mjs"),{throwIfNoEntry:!1})?.isFile())return{installed:!0,source:"package.json + bin/ark-check.mjs (self-host)"}}catch{}try{const r=q(e).resolve("arkgate/package.json"),o=h.dirname(r),t=JSON.parse(b.readFileSync(r,"utf8")),l=h.join(o,"bin","ark-check.mjs");if(t?.name==="arkgate"&&b.statSync(l,{throwIfNoEntry:!1})?.isFile())return{installed:!0,source:"arkgate/package.json via project resolver"}}catch{}return{installed:!1,source:"arkgate/package.json unresolved from project"}}function S(a){return a.length>0?a:["filesystem scan (no matching configuration)"]}function g({supported:a,configuredPaths:e,installed:r,active:o,runtimeObserved:t,operation:l,operationCoverage:d,bypassable:u,required:c,hard:i,sources:s}){const p=e.length>0;return{supported:a,analyzed:!0,configured:p,installed:a&&r.installed,active:o,runtimeObserved:t,operation:l,operationCoverage:d,bypassable:u,required:c,hard:i,evidence:[...S(e).map(v=>({field:"configured",source:v,value:p})),{field:"installed",source:r.source,value:a&&r.installed},{field:"active",source:s.active,value:o},{field:"runtimeObserved",source:s.runtimeObserved,value:t},{field:"operationCoverage",source:s.operationCoverage,value:d},{field:"bypassable",source:s.bypassable,value:u},{field:"required",source:s.required,value:c},{field:"hard",source:s.hard,value:i}]}}function w(a,e){const r=M(a),o=!!e.support?.capabilities?.["hard-write"],t=!!e.support?.capabilities?.["advisory-write"],l=e.capabilityEvidence["hard-write"],d=e.capabilityEvidence["advisory-write"],u=e.capabilityEvidence["merge-gate"],c=e.enforcementLadder.localWrite,i=typeof c.operationCovered=="boolean",s=i?c.operationCovered:n,p=i&&s===!0,v=!!(o&&p&&c.hard===!0),m=i?p:o&&l.length>0&&r.installed?n:!1,k=t&&d.length>0&&r.installed?n:!1,f=!!(e.ci?.failClosed&&u.length>0),C=f&&r.installed?n:!1;return{schemaVersion:"1.1",activeHost:e.activeHost,localWrite:g({supported:o,configuredPaths:l,installed:r,active:m,runtimeObserved:i,operation:i?c.operation??null:null,operationCoverage:s,bypassable:v?!1:o&&!i?n:!0,required:n,hard:v,sources:{active:i?"observed PreToolUse attempt":"runtime observation unavailable",runtimeObserved:i?"fresh PreToolUse invocation":"runtime observation unavailable",operationCoverage:i?"active-host operation matcher":"operation not observed",bypassable:v?"observed hard write boundary":"host runtime bypass evidence unavailable",required:"local host policy unavailable",hard:v?"fresh covered active-host invocation":"hardness not proven for this invocation"}}),advisoryMcp:g({supported:t,configuredPaths:d,installed:r,active:k,runtimeObserved:!1,operation:null,operationCoverage:n,bypassable:!0,required:n,hard:!1,sources:{active:"MCP runtime observation unavailable",runtimeObserved:"doctor did not observe an MCP tool invocation",operationCoverage:"advisory MCP is caller-invoked",bypassable:"advisory MCP does not intercept every write",required:"local host policy unavailable",hard:"MCP presence is advisory and never proves a hard boundary"}}),ciMerge:g({supported:!0,configuredPaths:f?u:[],installed:r,active:C,runtimeObserved:!1,operation:"merge",operationCoverage:f?n:!1,bypassable:f?n:!0,required:n,hard:!1,sources:{active:"CI run and provider enforcement not observed",runtimeObserved:"provider evidence unavailable",operationCoverage:"required-status operation coverage unavailable",bypassable:"branch-protection evidence unavailable",required:"branch-protection evidence unavailable",hard:"merge hardness requires fresh provider evidence"}})}}function j(a,e,r,o){return{...a,...o,evidence:[...a.evidence.filter(t=>!e.includes(t.field)),...e.map(t=>({field:t,source:r,value:o[t]}))]}}function x(a,e){if(!e?.available)return a;const r=typeof e.arkCheckRequired=="boolean"?e.arkCheckRequired:n,o=!!(a.enforcementState.ciMerge.configured&&a.enforcementState.ciMerge.installed),t=r===!0?o:r===!1?!1:o?n:!1,l=t===!0?e.arkCheckSourceBound===!1?!0:n:r===!1?!0:o?n:!0,d=`GitHub branch protection (${e.repo??"repository"}:${e.branch??"default"})`,u=!0,c=r,i=t===!0&&l===!1&&c===!0,s=j(a.enforcementState.ciMerge,["active","runtimeObserved","operationCoverage","bypassable","required","hard"],d,{active:t,runtimeObserved:u,operationCoverage:c,bypassable:l,required:r,hard:i});return{...a,enforcementState:{...a.enforcementState,ciMerge:s},enforcementLadder:{...a.enforcementLadder,ciMerge:{...a.enforcementLadder.ciMerge,requiredStatus:r}}}}function y(a,e){const r=o=>o===!0?"yes":o===!1?"no":String(o);return`${a} \u2014 supported: ${r(e.supported)} \xB7 analyzed: ${r(e.analyzed)} \xB7 configured: ${r(e.configured)} \xB7 installed: ${r(e.installed)} \xB7 runtime observed: ${r(e.runtimeObserved)} \xB7 operation: ${e.operation??"none"} \xB7 operation covered: ${r(e.operationCoverage)} \xB7 active: ${r(e.active)} \xB7 bypassable: ${r(e.bypassable)} \xB7 required: ${r(e.required)} \xB7 hard: ${r(e.hard)}`}function L(a){const e=[{level:a.localWrite.active===!0?"ok":"warn",text:y("Local write",a.localWrite)},{level:"warn",text:y("Advisory MCP",a.advisoryMcp)},{level:a.ciMerge.required===!0?"ok":"warn",text:y("CI merge",a.ciMerge)}];return a.localWrite.active===n&&a.localWrite.hard===!1&&e.push({level:"bad",text:"RED FLAG: local hook assets exist, but this active-host operation was not observed at runtime; hard blocking is unverified."}),e}export{w as buildEnforcementState,L as enforcementDoctorLines,x as withCiProviderEvidence};
+import b from"node:fs";import{createRequire as q}from"node:module";import h from"node:path";const n="unverified";function S(a){const e=h.join(a,"package.json");try{if(JSON.parse(b.readFileSync(e,"utf8"))?.name==="arkgate"&&b.statSync(h.join(a,"bin","ark-check.mjs"),{throwIfNoEntry:!1})?.isFile())return{installed:!0,source:"package.json + bin/ark-check.mjs (self-host)"}}catch{}try{const r=q(e).resolve("arkgate/package.json"),o=h.dirname(r),t=JSON.parse(b.readFileSync(r,"utf8")),l=h.join(o,"bin","ark-check.mjs");if(t?.name==="arkgate"&&b.statSync(l,{throwIfNoEntry:!1})?.isFile())return{installed:!0,source:"arkgate/package.json via project resolver"}}catch{}return{installed:!1,source:"arkgate/package.json unresolved from project"}}function M(a){return a.length>0?a:["filesystem scan (no matching configuration)"]}function y({supported:a,configuredPaths:e,installed:r,active:o,runtimeObserved:t,operation:l,operationCoverage:d,bypassable:u,required:c,hard:i,sources:s}){const p=e.length>0,v=!!r.installed;return{supported:a,analyzed:!0,configured:p,installed:v,active:o,runtimeObserved:t,operation:l,operationCoverage:d,bypassable:u,required:c,hard:i,evidence:[...M(e).map(g=>({field:"configured",source:g,value:p})),{field:"installed",source:r.source,value:v},{field:"active",source:s.active,value:o},{field:"runtimeObserved",source:s.runtimeObserved,value:t},{field:"operationCoverage",source:s.operationCoverage,value:d},{field:"bypassable",source:s.bypassable,value:u},{field:"required",source:s.required,value:c},{field:"hard",source:s.hard,value:i}]}}function O(a,e){const r=S(a),o=!!e.support?.capabilities?.["hard-write"],t=!!e.support?.capabilities?.["advisory-write"],l=e.capabilityEvidence["hard-write"],d=e.capabilityEvidence["advisory-write"],u=e.capabilityEvidence["merge-gate"],c=e.enforcementLadder.localWrite,i=typeof c.operationCovered=="boolean",s=i?c.operationCovered:n,p=i&&s===!0,v=!!(o&&p&&c.hard===!0),g=i?p:o&&l.length>0&&r.installed?n:!1,k=t&&d.length>0&&r.installed?n:!1,f=!!(e.ci?.failClosed&&u.length>0),C=f&&r.installed?n:!1;return{schemaVersion:"1.1",activeHost:e.activeHost,localWrite:y({supported:o,configuredPaths:l,installed:r,active:g,runtimeObserved:i,operation:i?c.operation??null:null,operationCoverage:s,bypassable:v?!1:o&&!i?n:!0,required:n,hard:v,sources:{active:i?"observed PreToolUse attempt":"runtime observation unavailable",runtimeObserved:i?"fresh PreToolUse invocation":"runtime observation unavailable",operationCoverage:i?"active-host operation matcher":"operation not observed",bypassable:v?"observed hard write boundary":"host runtime bypass evidence unavailable",required:"local host policy unavailable",hard:v?"fresh covered active-host invocation":"hardness not proven for this invocation"}}),advisoryMcp:y({supported:t,configuredPaths:d,installed:r,active:k,runtimeObserved:!1,operation:null,operationCoverage:n,bypassable:!0,required:n,hard:!1,sources:{active:"MCP runtime observation unavailable",runtimeObserved:"doctor did not observe an MCP tool invocation",operationCoverage:"advisory MCP is caller-invoked",bypassable:"advisory MCP does not intercept every write",required:"local host policy unavailable",hard:"MCP presence is advisory and never proves a hard boundary"}}),ciMerge:y({supported:!0,configuredPaths:f?u:[],installed:r,active:C,runtimeObserved:!1,operation:"merge",operationCoverage:f?n:!1,bypassable:f?n:!0,required:n,hard:!1,sources:{active:"CI run and provider enforcement not observed",runtimeObserved:"provider evidence unavailable",operationCoverage:"required-status operation coverage unavailable",bypassable:"branch-protection evidence unavailable",required:"branch-protection evidence unavailable",hard:"merge hardness requires fresh provider evidence"}})}}function w(a,e,r,o){return{...a,...o,evidence:[...a.evidence.filter(t=>!e.includes(t.field)),...e.map(t=>({field:t,source:r,value:o[t]}))]}}function x(a,e){if(!e?.available)return a;const r=typeof e.arkCheckRequired=="boolean"?e.arkCheckRequired:n,o=!!(a.enforcementState.ciMerge.configured&&a.enforcementState.ciMerge.installed),t=r===!0?o:r===!1?!1:o?n:!1,l=t===!0?e.arkCheckSourceBound===!1?!0:n:r===!1?!0:o?n:!0,d=`GitHub branch protection (${e.repo??"repository"}:${e.branch??"default"})`,u=!0,c=r,i=t===!0&&l===!1&&c===!0,s=w(a.enforcementState.ciMerge,["active","runtimeObserved","operationCoverage","bypassable","required","hard"],d,{active:t,runtimeObserved:u,operationCoverage:c,bypassable:l,required:r,hard:i});return{...a,enforcementState:{...a.enforcementState,ciMerge:s},enforcementLadder:{...a.enforcementLadder,ciMerge:{...a.enforcementLadder.ciMerge,requiredStatus:r}}}}function m(a,e){const r=o=>o===!0?"yes":o===!1?"no":String(o);return`${a} \u2014 supported: ${r(e.supported)} \xB7 analyzed: ${r(e.analyzed)} \xB7 configured: ${r(e.configured)} \xB7 installed: ${r(e.installed)} \xB7 runtime observed: ${r(e.runtimeObserved)} \xB7 operation: ${e.operation??"none"} \xB7 operation covered: ${r(e.operationCoverage)} \xB7 active: ${r(e.active)} \xB7 bypassable: ${r(e.bypassable)} \xB7 required: ${r(e.required)} \xB7 hard: ${r(e.hard)}`}function P(a){const e=[{level:a.localWrite.active===!0?"ok":"warn",text:m("Local write",a.localWrite)},{level:"warn",text:m("Advisory MCP",a.advisoryMcp)},{level:a.ciMerge.required===!0?"ok":"warn",text:m("CI merge",a.ciMerge)}];return a.localWrite.active===n&&a.localWrite.hard===!1&&e.push({level:"bad",text:"RED FLAG: local hook assets exist, but this active-host operation was not observed at runtime; hard blocking is unverified."}),a.activeHost==="unknown"&&e.push({level:"warn",text:"Active host unknown for this invocation \u2014 enforcementState is session projection only. See writePath.inventory for on-disk host hooks; hard write is never claimed without runtime proof."}),e}export{O as buildEnforcementState,P as enforcementDoctorLines,x as withCiProviderEvidence};

package/bin/lib/golden-pattern.mjs

@@ -116,6 +116,33 @@ export function loadGoldenPattern(root) {
   return { ok: true, present: true, path: rel, golden };
 }
 
+/**
+ * Y06 — advisory opt-in nudge when the golden pattern names pure modules but no
+ * layer declares `pure: true`. Never a blocker; never auto-writes pure:true.
+ *
+ * @param {{ layers?: Array<{ pure?: boolean }> }|null|undefined} config
+ * @param {GoldenPatternLoadResult|null|undefined} goldenResult
+ * @returns {null | { id: string, advisory: true, message: string }}
+ */
+export function computePureLayerOptInNudge(config, goldenResult) {
+  const layers = Array.isArray(config?.layers) ? config.layers : [];
+  if (layers.some((layer) => layer?.pure === true)) return null;
+  if (!goldenResult?.present || !goldenResult.golden) return null;
+  const g = goldenResult.golden;
+  const text = [g.name, g.norm, g.newCodeHome, g.examplePath]
+    .filter((part) => typeof part === 'string' && part.trim())
+    .join('\n');
+  // Require explicit purity language in the golden pattern (not mere "Domain").
+  if (!/\bpure\b/i.test(text)) return null;
+  return {
+    id: 'pure-layer-opt-in',
+    advisory: true,
+    message:
+      'Golden pattern references pure modules, but no layer sets pure: true. ' +
+      'Opt in on Domain (or equivalent) to enable ambient-state diagnostics — advisory only; never auto-applied.',
+  };
+}
+
 /**
  * One-line guidance for agents / placement notes.
  * @param {GoldenPatternLoadResult} result

package/bin/lib/html-report.mjs

@@ -809,10 +809,33 @@ export function renderHtmlReport({
     )
     .join('\n');
 
-  const skillsNote =
-    skillGaps.length === 0
-      ? '<div class="pill good">Agent skills current for detected tools</div>'
-      : `<div class="pill warn">${skillGaps.length} skill gap(s) — run ark upgrade / --install-agent-gates</div>`;
+  // Actionable catalog debt only — Codex leftover flat prompts with a complete
+  // .agents/skills catalog (legacyAdvisory) are cleanup advisories, not install gaps.
+  const actionableSkillGaps = skillGaps.filter(
+    (gap) =>
+      (gap?.missing ?? 0) > 0 ||
+      (gap?.stale ?? 0) > 0 ||
+      gap?.legacyPromptsOnly === true
+  );
+  const legacyAdvisoryOnly = skillGaps.some(
+    (gap) => gap?.legacyAdvisory === true && gap?.catalogComplete === true
+  );
+  const skillsParts = [];
+  if (actionableSkillGaps.length === 0) {
+    skillsParts.push(
+      '<div class="pill good">Agent skills current for detected tools</div>'
+    );
+  } else {
+    skillsParts.push(
+      `<div class="pill warn">${actionableSkillGaps.length} skill gap(s) — run ark upgrade / --install-agent-gates</div>`
+    );
+  }
+  if (legacyAdvisoryOnly) {
+    skillsParts.push(
+      '<div class="pill" style="opacity:.85">Codex leftover .codex/prompts are safe to delete (catalog complete; not required)</div>'
+    );
+  }
+  const skillsNote = skillsParts.join('\n');
 
   const meta = [
     version ? `ark-check v${esc(version)}` : '',

package/bin/lib/managed-upgrade.mjs

@@ -6,8 +6,10 @@ import { codexPrimaryTable, upsertCodexMcpTable } from './codex-home.mjs';
 import { buildManagedAssetCatalog } from './install-migrate.mjs';
 import {
   KNOWN_TOOLS,
+  arkPackageVersion,
   detectActiveAgentHost,
   normalizeToolsList,
+  skillContentIdentity,
 } from './skill-install.mjs';
 
 export const MANAGED_MANIFEST_PATH = 'ark.managed.json';
@@ -36,21 +38,17 @@ function hash(content) {
   return `sha256:${createHash('sha256').update(content).digest('hex')}`;
 }
 
-function normalizedIdentityContent(content, kind) {
-  let text = String(content).replace(/\r\n/g, '\n');
-  if (kind !== 'skill') return text;
-  const lines = text.split('\n');
-  if (lines[0] !== '---') return text;
-  const end = lines.indexOf('---', 1);
-  if (end < 0) return text;
-  for (let index = 1; index < end; index += 1) {
-    if (/^arkVersion:/.test(lines[index])) lines[index] = 'arkVersion:<managed>';
-  }
-  return lines.join('\n');
+function normalizedIdentityContent(content) {
+  return String(content).replace(/\r\n/g, '\n');
 }
 
+/**
+ * Content identity for managed assets. Skill kind delegates to skill-install so
+ * doctor stale detection and upgrade classify never drift (single hasher).
+ */
 export function managedContentIdentity(content, kind = 'gate') {
-  return hash(Buffer.from(normalizedIdentityContent(content, kind)));
+  if (kind === 'skill') return skillContentIdentity(content);
+  return hash(Buffer.from(normalizedIdentityContent(content)));
 }
 
 function isSafeRelativePath(relativePath) {
@@ -271,12 +269,22 @@ function serializeManifest(value) {
 function summaryFor(assets, manifestChanged) {
   const states = {};
   for (const asset of assets) states[asset.state] = (states[asset.state] ?? 0) + 1;
-  const fileChanges = assets.filter((asset) => asset.willApply).length;
+  const applying = assets.filter((asset) => asset.willApply);
+  // Content writes (stale/missing/conflicted accepted) — not version-stamp metadata-only.
+  const wouldWrite = applying.filter((asset) => asset.action !== 'refresh-metadata').length;
+  const metadataRefresh = applying.filter((asset) => asset.action === 'refresh-metadata').length;
+  const customizedPreserved = assets.filter((asset) => asset.state === 'customized').length;
+  const fileChanges = applying.length;
   return {
     total: assets.length,
+    managedAssets: assets.length,
     states,
+    wouldWrite,
+    metadataRefresh,
+    customizedPreserved,
     fileChanges,
     manifestChanged,
+    // Full apply count still includes optional stamp refresh + manifest bookkeeping.
     changed: fileChanges + (manifestChanged ? 1 : 0),
     blocked: assets.filter((asset) => asset.blocked).length,
   };
@@ -616,7 +624,41 @@ export function renderManagedUpgrade(plan, options = {}) {
     const consent = asset.requiresConsent ? ' (consent required)' : '';
     console.log(`  ${asset.state.padEnd(10)} ${asset.path}${consent}`);
   }
-  const label = plan.applied ? 'Applied changes' : 'Planned changes';
-  console.log(`${label}: ${plan.summary.changed}; blocked conflicts/deletions: ${plan.summary.blocked}.`);
-  if (!plan.applied) console.log(options.next ?? 'Apply the exact preview with: ark upgrade --apply --no-install');
+  const summary = plan.summary;
+  const managedAssets = summary.managedAssets ?? summary.total ?? plan.assets.length;
+  const wouldWrite = summary.wouldWrite ?? 0;
+  const metadataRefresh = summary.metadataRefresh ?? 0;
+  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}` +
+      (metadataRefresh > 0 ? `; optional stamp refresh: ${metadataRefresh}` : '') +
+      '.'
+  );
+  if (plan.applied) {
+    console.log(`Applied changes: ${summary.changed}.`);
+    return;
+  }
+  // Content already matches package templates — do not urge --apply as the primary next step.
+  if (wouldWrite === 0 && blocked === 0) {
+    const ver = options.packageVersion ?? arkPackageVersion();
+    const verLabel = ver ? `arkgate@${ver}` : 'the installed arkgate package';
+    console.log(
+      `Nothing to apply — managed content matches ${verLabel} (${customizedPreserved} customized preserved).`
+    );
+    if (metadataRefresh > 0) {
+      console.log(
+        `Optional: ${metadataRefresh} skill stamp(s) lag package version while content is already current.`
+      );
+      const stampCmd = options.optionalStampApply ?? options.next;
+      if (stampCmd) {
+        console.log(`Optional stamp-only apply (not required): ${stampCmd}`);
+      }
+    }
+    return;
+  }
+  console.log(`Planned writes: ${wouldWrite}; blocked conflicts/deletions: ${blocked}.`);
+  if (options.next) console.log(options.next);
+  else console.log('Apply the exact preview with: ark upgrade --apply --no-install');
 }

package/bin/lib/skill-install.mjs

@@ -1,6 +1,7 @@
 /**
  * Tool detection, skill templates, stamping, and skill freshness gaps.
  */
+import { createHash } from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import { arkCommand } from '../ark-shared.mjs';
@@ -206,7 +207,12 @@ export function installedSkillVersion(filePath) {
   } catch {
     return null;
   }
-  const match = content.match(/^arkVersion:\s*(.+)$/m);
+  return skillVersionFromContent(content);
+}
+
+function skillVersionFromContent(content) {
+  if (content == null) return null;
+  const match = String(content).match(/^arkVersion:\s*(.+)$/m);
   return match ? match[1].trim() : null;
 }
 
@@ -225,6 +231,63 @@ export function isVersionOlder(a, b) {
   return false;
 }
 
+/**
+ * Content identity for managed skills — arkVersion stamp is normalized so a lagging
+ * header alone never diverges from the package template (matches managed-upgrade).
+ * @param {string|null|undefined} content
+ * @returns {string|null}
+ */
+export function skillContentIdentity(content) {
+  if (content == null) return null;
+  let text = String(content).replace(/\r\n/g, '\n');
+  const lines = text.split('\n');
+  if (lines[0] === '---') {
+    const end = lines.indexOf('---', 1);
+    if (end >= 0) {
+      for (let index = 1; index < end; index += 1) {
+        if (/^arkVersion:/.test(lines[index])) lines[index] = 'arkVersion:<managed>';
+      }
+      text = lines.join('\n');
+    }
+  }
+  return `sha256:${createHash('sha256').update(text).digest('hex')}`;
+}
+
+/**
+ * True when installed skill body matches the package template for that skill
+ * (version stamp ignored). Used so doctor "stale" aligns with managed upgrade.
+ *
+ * Templates ship without arkVersion; installs are stamped. Identity normalizes
+ * the stamp value, so compare against both the raw template and a stamped copy.
+ * @param {string} installedContent
+ * @param {string|undefined|null} templateContent
+ */
+export function skillContentMatchesTemplate(installedContent, templateContent) {
+  if (templateContent == null || installedContent == null) return false;
+  const installedId = skillContentIdentity(installedContent);
+  if (installedId === skillContentIdentity(templateContent)) return true;
+  // Installed skills are stamped; templates are not — stamp with a dummy version
+  // so arkVersion:<managed> lines align under skillContentIdentity.
+  return installedId === skillContentIdentity(stampSkill(templateContent, '0.0.0'));
+}
+
+/** @returns {Record<string, string>} skill name → template body from package */
+export function skillTemplateBodies() {
+  return Object.fromEntries(skillTemplates());
+}
+
+/**
+ * Count a present skill as stale only when content differs from the package
+ * template AND the arkVersion stamp is missing or older than the package.
+ * Content identity match → never stale (even if header lags).
+ */
+function isInstalledSkillStale(installedContent, templateContent, packageVersion) {
+  if (!packageVersion) return false;
+  if (skillContentMatchesTemplate(installedContent, templateContent)) return false;
+  const installed = skillVersionFromContent(installedContent);
+  return installed === null || isVersionOlder(installed, packageVersion);
+}
+
 export function skillTemplates() {
   const dir = path.join(__packageRoot, 'templates', 'skills');
   // A missing/mispackaged templates dir would otherwise install zero skills with
@@ -263,23 +326,31 @@ export function skillTemplateNames() {
 
 /**
  * Count present / stale / legacy-only skill files for one catalog root.
+ * "stale" means content behind the package template (identity mismatch) with a
+ * missing/older arkVersion stamp — not merely a lagging version header when the
+ * body still matches the template (aligned with managed-upgrade classify).
  * @param {string[]} skillNames
  * @param {(name: string) => string} skillFile path builder
  * @param {string|null} packageVersion
- * @param {{ legacyFile?: (name: string) => string }} [opts]
+ * @param {{ legacyFile?: (name: string) => string, templateBodies?: Record<string, string> }} [opts]
  */
 export function assessSkillCatalogParity(skillNames, skillFile, packageVersion, opts = {}) {
   const expectedCount = skillNames.length;
+  const templates = opts.templateBodies ?? skillTemplateBodies();
   const present = [];
   let stale = 0;
   for (const name of skillNames) {
     const file = skillFile(name);
     if (!fs.existsSync(file)) continue;
-    present.push(name);
-    if (packageVersion) {
-      const installed = installedSkillVersion(file);
-      if (installed === null || isVersionOlder(installed, packageVersion)) stale += 1;
+    let content;
+    try {
+      content = fs.readFileSync(file, 'utf8');
+    } catch {
+      // Unreadable path is not a usable install — count as missing (matches detectSkillGaps).
+      continue;
     }
+    present.push(name);
+    if (isInstalledSkillStale(content, templates[name], packageVersion)) stale += 1;
   }
   let legacyCount = 0;
   if (typeof opts.legacyFile === 'function') {
@@ -291,6 +362,7 @@ export function assessSkillCatalogParity(skillNames, skillFile, packageVersion,
   const missing = expectedCount - presentCount;
   const legacyPromptsOnly = presentCount === 0 && legacyCount > 0;
   const hasLegacyPrompts = legacyCount > 0;
+  // Legacy prompts beside a complete modern catalog are not catalog debt.
   const ok = missing === 0 && stale === 0 && !legacyPromptsOnly;
   return {
     ok,
@@ -302,6 +374,7 @@ export function assessSkillCatalogParity(skillNames, skillFile, packageVersion,
     legacyPromptsOnly,
     hasLegacyPrompts,
     legacyCount,
+    catalogComplete: missing === 0 && stale === 0 && presentCount === expectedCount,
   };
 }
 
@@ -490,6 +563,7 @@ export function detectSkillGaps(root) {
   if (fs.existsSync(path.join(root, 'templates', 'skills'))) return [];
   const skillNames = skillTemplateNames();
   if (skillNames.length === 0) return [];
+  const templates = skillTemplateBodies();
   const detected = [];
   if (fs.existsSync(path.join(root, '.claude'))) detected.push('claude');
   if (fs.existsSync(path.join(root, '.cursor'))) detected.push('cursor');
@@ -510,16 +584,21 @@ export function detectSkillGaps(root) {
       const file = path.join(root, target(name));
       if (!fs.existsSync(file)) {
         missing += 1;
-      } else if (version) {
-        // An installed skill with no stamp predates stamping (older Ark), or one
-        // stamped behind the current version is left over from an older install.
-        // Either way the shipped skill has moved on — offer a --force refresh.
-        const installed = installedSkillVersion(file);
-        if (installed === null || isVersionOlder(installed, version)) stale += 1;
+        continue;
+      }
+      let content;
+      try {
+        content = fs.readFileSync(file, 'utf8');
+      } catch {
+        missing += 1;
+        continue;
       }
+      // Content identity match with package template → not stale (version header may lag).
+      if (isInstalledSkillStale(content, templates[name], version)) stale += 1;
     }
     let legacyPromptsOnly = false;
     let hasLegacyPrompts = false;
+    let legacyAdvisory = false;
     if (tool === 'codex') {
       const legacyCount = skillNames.filter((name) =>
         fs.existsSync(path.join(root, '.codex', 'prompts', `${name}.md`))
@@ -527,14 +606,20 @@ export function detectSkillGaps(root) {
       hasLegacyPrompts = legacyCount > 0;
       // Flat prompts without any SKILL.md catalog entries are not loadable.
       legacyPromptsOnly = hasLegacyPrompts && missing === skillNames.length;
+      // Modern catalog complete + leftover flat prompts → advisory only (safe delete).
+      legacyAdvisory =
+        hasLegacyPrompts && !legacyPromptsOnly && missing === 0 && stale === 0;
     }
-    if (missing > 0 || stale > 0 || legacyPromptsOnly) {
+    if (missing > 0 || stale > 0 || legacyPromptsOnly || legacyAdvisory) {
       gaps.push({
         tool,
         missing,
         stale,
         ...(legacyPromptsOnly ? { legacyPromptsOnly: true } : {}),
         ...(hasLegacyPrompts ? { hasLegacyPrompts: true } : {}),
+        ...(legacyAdvisory
+          ? { legacyAdvisory: true, catalogComplete: true }
+          : {}),
       });
     }
   }
@@ -550,8 +635,14 @@ export function printSkillAndCodexGapHints(root, opts) {
   const { skillGaps, codexHomeGap, codexRepoSkillGap, codexSessionActive, color } = opts;
   if (skillGaps?.length > 0) {
     const legacyCodex = skillGaps.some((gap) => gap.tool === 'codex' && gap.legacyPromptsOnly);
+    const legacyAdvisory = skillGaps.some(
+      (gap) => gap.tool === 'codex' && gap.legacyAdvisory && gap.catalogComplete
+    );
     // Report Codex legacy separately; never suppress missing/stale for other hosts.
-    const remaining = skillGaps.filter((gap) => !(gap.tool === 'codex' && gap.legacyPromptsOnly));
+    const remaining = skillGaps.filter(
+      (gap) =>
+        !(gap.tool === 'codex' && (gap.legacyPromptsOnly || gap.legacyAdvisory))
+    );
     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(', ');
@@ -563,6 +654,13 @@ export function printSkillAndCodexGapHints(root, opts) {
         )
       );
     }
+    if (legacyAdvisory) {
+      console.log(
+        color.dim(
+          'Codex .agents/skills catalog is complete; leftover .codex/prompts/ark-*.md are not loadable and safe to delete (not required).'
+        )
+      );
+    }
     if (missingTotal > 0) {
       console.log(
         color.dim(
@@ -574,7 +672,7 @@ export function printSkillAndCodexGapHints(root, opts) {
     if (staleTotal > 0) {
       console.log(
         color.dim(
-          `${staleTotal} /ark-* skill(s) outdated for ${tools} (this Ark ships newer versions). ` +
+          `${staleTotal} /ark-* skill(s) content behind this Ark package for ${tools}. ` +
             `Refresh: ${arkCommand(root, 'ark-check', '--install-agent-gates --skills-only --force')}`
         )
       );
@@ -584,7 +682,7 @@ export function printSkillAndCodexGapHints(root, opts) {
     const parts = [];
     if (codexHomeGap.legacyPromptsOnly) parts.push('legacy-prompts-only');
     if (codexHomeGap.missing > 0) parts.push(`${codexHomeGap.missing} missing`);
-    if (codexHomeGap.stale > 0) parts.push(`${codexHomeGap.stale} outdated`);
+    if (codexHomeGap.stale > 0) parts.push(`${codexHomeGap.stale} content-behind-package`);
     const deferred = !codexSessionActive;
     const deferredNote = deferred
       ? ' Deferred unless you use Codex — not a blocker for Grok/Claude/Cursor. '
@@ -600,7 +698,7 @@ export function printSkillAndCodexGapHints(root, opts) {
     const parts = [];
     if (codexRepoSkillGap.legacyPromptsOnly) parts.push('legacy-prompts-only');
     if (codexRepoSkillGap.missing > 0) parts.push(`${codexRepoSkillGap.missing} missing`);
-    if (codexRepoSkillGap.stale > 0) parts.push(`${codexRepoSkillGap.stale} outdated`);
+    if (codexRepoSkillGap.stale > 0) parts.push(`${codexRepoSkillGap.stale} content-behind-package`);
     console.log(
       color.yellow(
         `Codex repo skill catalog (.agents/skills) needs refresh (${parts.join(', ')}). ` +