arkgate 3.8.1 → 3.8.3

package/CHANGELOG.md

@@ -5,6 +5,62 @@ in the immutable pre-2.0 archive linked below.
 
 ## Unreleased
 
+## 3.8.3 — 2026-07-22
+
+Corrective **patch** over 3.8.2 from multi-repo field evidence (PROPIA pnpm workspace upgrade;
+Amarilla greenfield `start`). **No required config migration.** Z09 / residual `RB-11` remain open.
+
+### Fixed
+
+- **pnpm workspace upgrade install:** `packageInstallArgv` emits `pnpm add -D arkgate@… -w` on
+  workspace roots (`pnpm-workspace.yaml`). Yarn workspaces get `-W`. npm single-package path
+  unchanged.
+- **Upgrade re-install when already current:** skip package-manager install when
+  `node_modules/arkgate` already matches this CLI version; go straight to managed preview.
+- **Install failure recovery copy:** prints the exact failed install command and a
+  `--no-install` re-run path.
+- **`start` package pin by default:** `start --apply` pins `arkgate` in `devDependencies`
+  unless `--no-install` (was: only with explicit `--install`).
+- **Compact start always writes `.mcp.json`:** every host gets project MCP registration;
+  setup budget raised to 8 files / 32 KB so MCP fits with host hooks.
+- **Unbound upgrade apply when content matches:** `--apply` without `--plan-digest` is a
+  successful no-op when `wouldWrite` is 0 (optional stamp refresh still needs the digest).
+- **Upgrade applied copy:** distinguishes content writes vs stamp/metadata refresh instead of
+  a single “Applied N changes” when only stamps moved.
+
+### Tests
+
+- `tests/unit/static-check/fieldJourney383.test.ts` — workspace argv, skip-when-current, start pin.
+- Z06 / O03 / installFieldFixes expectations updated for default pin and MCP-in-compact.
+
+## 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.3** is current stable: field journey on top of 3.8.2 — pnpm/yarn workspace install,
+> default `start` package pin, compact `.mcp.json`, upgrade recovery/UX.
+> [Release notes](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/3.8.3.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.3) | [release notes](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/3.8.3.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/ark-shared.mjs

@@ -618,11 +618,98 @@ export function execCommandParts(root, bin, binArgs = []) {
   return { command: 'npx', args: [bin, ...binArgs] };
 }
 
+/**
+ * True when this directory is a pnpm workspace root (needs `pnpm add -w` for root deps).
+ * Nested packages under the workspace are not roots.
+ */
+export function isPnpmWorkspaceRoot(root) {
+  return fs.existsSync(path.join(root, 'pnpm-workspace.yaml'));
+}
+
+/**
+ * True when package.json declares npm/yarn workspaces (yarn classic needs `-W` at root).
+ */
+export function isNpmYarnWorkspaceRoot(root) {
+  const pkg = readPackageJson(root);
+  if (!pkg) return false;
+  const ws = pkg.workspaces;
+  return Array.isArray(ws) || (ws && typeof ws === 'object' && Array.isArray(ws.packages));
+}
+
+/**
+ * Normalize a version/range/spec into an installable package argument for arkgate.
+ * Accepts `latest`, `^3.8.2`, `arkgate@latest`, or a full package name.
+ */
+export function normalizeArkgateInstallSpec(versionSpec) {
+  const raw = typeof versionSpec === 'string' && versionSpec.trim() ? versionSpec.trim() : 'latest';
+  if (raw.startsWith('arkgate@') || raw === 'arkgate') return raw === 'arkgate' ? 'arkgate@latest' : raw;
+  if (raw.includes('/') || raw.startsWith('file:') || raw.startsWith('link:')) return raw;
+  return `arkgate@${raw}`;
+}
+
+/**
+ * Package-manager argv to add a dev dependency (e.g. arkgate@latest).
+ * pnpm workspace roots get `-w`; yarn classic workspaces get `-W`.
+ *
+ * @param {string} root
+ * @param {string} [versionSpec]  package name or name@version (default arkgate@latest)
+ * @returns {[string, string[]]}
+ */
+export function packageInstallArgv(root, versionSpec = 'latest') {
+  const pkgSpec = normalizeArkgateInstallSpec(versionSpec);
+  const pm = detectPackageManager(root);
+  if (pm === 'pnpm') {
+    const args = ['add', '-D', pkgSpec];
+    if (isPnpmWorkspaceRoot(root)) args.push('-w');
+    return ['pnpm', args];
+  }
+  if (pm === 'yarn') {
+    const args = ['add', '-D', pkgSpec];
+    if (isNpmYarnWorkspaceRoot(root)) args.push('-W');
+    return ['yarn', args];
+  }
+  return ['npm', ['install', '-D', pkgSpec]];
+}
+
+/**
+ * Whether an install of arkgate@latest can be skipped because node_modules already
+ * resolves the same version as this CLI package.
+ *
+ * @param {string} root
+ * @param {string} [cliVersion]  this binary's package version
+ * @returns {{ skip: boolean, installedVersion: string|null, reason: string }}
+ */
+export function shouldSkipArkgateInstall(root, cliVersion) {
+  const pkgPath = path.join(root, 'node_modules', 'arkgate', 'package.json');
+  if (!fs.existsSync(pkgPath)) {
+    return { skip: false, installedVersion: null, reason: 'not-installed' };
+  }
+  let installedVersion = null;
+  try {
+    installedVersion = JSON.parse(fs.readFileSync(pkgPath, 'utf8')).version ?? null;
+  } catch {
+    return { skip: false, installedVersion: null, reason: 'unreadable' };
+  }
+  if (
+    typeof cliVersion === 'string' &&
+    cliVersion &&
+    installedVersion &&
+    installedVersion === cliVersion
+  ) {
+    return { skip: true, installedVersion, reason: 'already-current' };
+  }
+  return { skip: false, installedVersion, reason: 'version-differs' };
+}
+
 /** Package-manager aware "install a dev dependency" hint (e.g. for a missing typescript). */
 export function installDevHint(root, pkg) {
   const pm = detectPackageManager(root);
-  if (pm === 'pnpm') return `pnpm add -D ${pkg}`;
-  if (pm === 'yarn') return `yarn add -D ${pkg}`;
+  if (pm === 'pnpm') {
+    return isPnpmWorkspaceRoot(root) ? `pnpm add -D ${pkg} -w` : `pnpm add -D ${pkg}`;
+  }
+  if (pm === 'yarn') {
+    return isNpmYarnWorkspaceRoot(root) ? `yarn add -D ${pkg} -W` : `yarn add -D ${pkg}`;
+  }
   return `npm install -D ${pkg}`;
 }
 

package/bin/ark.mjs

@@ -14,8 +14,10 @@ import {
   INIT_WIZARD_CHOICES,
   isValidArchetypeId,
   mapWizardChoiceToArchetype,
+  packageInstallArgv,
   resolveArchetypePreset,
   resolveOperatingMode,
+  shouldSkipArkgateInstall,
 } from './ark-shared.mjs';
 import { pinArkgateDevDependency, FALSE_GREEN_GAP_ID } from './lib/field-install.mjs';
 import { validateHardWriteRequest } from './lib/enforcement-profiles.mjs';
@@ -155,9 +157,9 @@ Options:
                (Also the implicit default when stdin/stdout are not a TTY — agents never hang on prompts.)
   --force      Allow generated files to overwrite existing files.
   --no-strict  Skip the final strict ark-check run.
-  --install    Add arkgate to package.json explicitly before applying a start plan.
+  --install    Pin and install arkgate as a project devDependency (default for start).
   --no-install Skip adding/installing arkgate as a project devDependency (start/upgrade).
-  --apply       Apply a start plan; for upgrade, update/repreview or apply with --no-install.
+  --apply       Apply a start plan; for upgrade, update/repreview or apply managed bytes.
   --accept-conflicts
                 Allow upgrade to recreate deleted managed assets or replace recorded conflicts.
   --plan-digest Digest emitted by an upgrade preview; required to apply managed bytes.
@@ -189,20 +191,7 @@ function cliVersion() {
   }
 }
 
-// The package-manager command that adds arkgate as a dev dependency.
-// Prefer an explicit version/range when pin already chose one (avoid pin=^2.9.0 then
-// `npm i arkgate@latest` rewriting package.json to a different range).
-function packageInstallArgv(root, versionSpec) {
-  const range =
-    typeof versionSpec === 'string' && versionSpec.trim()
-      ? versionSpec.trim()
-      : 'latest';
-  const spec = range.startsWith('arkgate@') ? range : `arkgate@${range}`;
-  const pm = detectPackageManager(root);
-  if (pm === 'pnpm') return ['pnpm', ['add', '-D', spec]];
-  if (pm === 'yarn') return ['yarn', ['add', '-D', spec]];
-  return ['npm', ['install', '-D', spec]];
-}
+// packageInstallArgv is imported from ark-shared (workspace-aware -w / -W).
 
 function runCommand(command, commandArgs, cwd) {
   const result = spawnSync(command, commandArgs, { cwd, stdio: 'inherit', encoding: 'utf8' });
@@ -438,6 +427,32 @@ async function start(args) {
     if (!args.apply) return 0;
     applyStartPreview(args.root, preview);
     if (!args.json) console.log(`Applied ${preview.changes.length} previewed mutation(s).`);
+    // After applying exact preview bytes, install the pinned package when requested
+    // (preview itself never runs the package manager — field: start left pin without node_modules).
+    if (
+      args.install &&
+      !args.skipPackageManager &&
+      fs.existsSync(path.join(args.root, 'package.json'))
+    ) {
+      const skip = shouldSkipArkgateInstall(args.root, cliVersion());
+      if (!skip.skip) {
+        const [command, commandArgs] = packageInstallArgv(args.root, `^${cliVersion()}`);
+        if (!args.json) console.log(`Installing package: ${command} ${commandArgs.join(' ')}`);
+        // Keep stdout clean for --json consumers (package managers are chatty on stdout).
+        const status = args.json
+          ? (spawnSync(command, commandArgs, {
+              cwd: args.root,
+              stdio: ['ignore', 'pipe', 'pipe'],
+              encoding: 'utf8',
+            }).status ?? 1)
+          : runCommand(command, commandArgs, args.root);
+        if (status !== 0 && !args.json) {
+          console.log(
+            `Package manager exited ${status}. package.json is pinned; run the install command when online.`
+          );
+        }
+      }
+    }
     return 0;
   }
   const root = args.root;
@@ -492,7 +507,8 @@ async function start(args) {
     }
 
     // 2b) Pin arkgate as a project devDependency so CI/npx do not depend on a stale global.
-    if (args.installExplicit && args.install && fs.existsSync(path.join(root, 'package.json'))) {
+    // Default install=true; only --no-install skips. (installExplicit tracks user override for copy.)
+    if (args.install && fs.existsSync(path.join(root, 'package.json'))) {
       const { pinned, installStatus } = ensureProjectArkgateDependency(root, {
         install: true,
         runPackageManager: !args.skipPackageManager,
@@ -507,7 +523,7 @@ async function start(args) {
       } else if (pinned.reason === 'already-present') {
         console.log(`  arkgate already in package.json (${pinned.version}).`);
       }
-    } else if (args.installExplicit && args.install === false) {
+    } else if (!args.install) {
       console.log('  Skipping arkgate package pin (--no-install).');
     }
 
@@ -789,7 +805,13 @@ async function main() {
 
   if (args.command === 'upgrade' || args.command === 'update') {
     try {
-      return runUpgradeCommand(args, { arkCheck, packageInstallArgv, runArkCheck });
+      return runUpgradeCommand(args, {
+        arkCheck,
+        packageInstallArgv,
+        runArkCheck,
+        cliVersion: cliVersion(),
+        shouldSkipArkgateInstall,
+      });
     } catch (error) {
       console.error(error instanceof Error ? error.message : String(error));
       return 2;

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

@@ -149,7 +149,10 @@ export function buildManagedAssetCatalog({ root, tools, compact = false, skillsO
       'AGENTS.md',
       compact ? compactAgentInstructions(root, compactHost) : agentInstructions(root)
     );
-    if (!compact || !compactHost || compactHost === 'claude') add('.mcp.json', mcpJson(root));
+    // Always write project MCP registration — compact hosts other than Claude still need
+    // ark://manifest for agents (field: compact grok start left doctor reporting Missing .mcp.json
+    // when AGENTS lost compact markers or hosts were mixed).
+    add('.mcp.json', mcpJson(root));
     const deploy = detectDeployPathQuality(root);
     add(
       '.github/workflows/ark-check.yml',