arkgate 4.1.0 → 4.2.0

package/bin/lib/html-report.mjs

@@ -21,6 +21,11 @@ import {
 } from './html-report-depth.mjs';
 import { FIX_HINTS } from './violations.mjs';
 import { capabilityBadgesFor, renderAdvisorySections } from './html-report-advisories.mjs';
+import { renderEvolutionSection } from './html-report-evolution.mjs';
+import { arkGitignoreAppendDecision } from './ark-gitignore.mjs';
+import { captureGitSnapshot } from './report-snapshot-context.mjs';
+
+export { arkGitignoreAppendDecision, gitignoreCoversArkState, gitignoreHasArkNegationException } from './ark-gitignore.mjs';
 
 export function detectEnforcement(root) {
   const has = (rel) => fs.existsSync(path.join(root, rel));
@@ -158,6 +163,7 @@ export function buildReportSnapshot({
         return path.basename(root);
       }
     })(),
+    git: captureGitSnapshot(root),
     ok: Boolean(ok),
     mode: mode ?? null,
     score: score ?? null,
@@ -336,20 +342,16 @@ export function archiveReportSnapshots(root, { html, snapshot, resetOrigin = fal
     }
   }
 
-  // Ensure .ark/ is gitignored when a .gitignore exists.
+  // EH03: cover .ark reports in .gitignore without defeating ! exceptions.
   const gitignore = path.join(root, '.gitignore');
   if (fs.existsSync(gitignore)) {
     const text = fs.readFileSync(gitignore, 'utf8');
-    const hasArk =
-      text.split('\n').some((line) => {
-        const t = line.trim();
-        return t === '.ark/' || t === '.ark' || t === '/.ark/' || t === '**/.ark/';
-      });
-    if (!hasArk) {
+    const decision = arkGitignoreAppendDecision(text);
+    if (decision.append && decision.rule) {
       const suffix = text.endsWith('\n') || text.length === 0 ? '' : '\n';
       fs.writeFileSync(
         gitignore,
-        `${text}${suffix}\n# Ark generated reports / local state\n.ark/\n`
+        `${text}${suffix}\n# Ark generated reports / local state\n${decision.rule}\n`
       );
     }
   }
@@ -1229,95 +1231,14 @@ export function renderHtmlReport({
     <div class="gates">${enforcementRows}</div>
   </div>
 
-  ${(() => {
-    if (!currentSnapshot) return '';
-    // First report: originSnapshot is null at render time (written to disk just after).
-    if (originJustCreated || !originSnapshot) {
-      return `<div class="section card evolve">
-        <h2>Origin baseline captured</h2>
-        <p class="dim" style="margin:.2rem 0 0;font-size:.9rem">
-          This is the <b>first</b> architecture snapshot for this project
-          (<code>.ark/reports/origin.json</code> + <code>origin.html</code>).
-          Future reports will show deltas against this starting point so you can prove evolution.
-        </p>
-      </div>`;
-    }
-    const rows = [
-      ['Ark score', originSnapshot.score, currentSnapshot.score, ''],
-      ['Governed %', originSnapshot.governedPercent, currentSnapshot.governedPercent, 'pp'],
-      ['Files in scope', originSnapshot.totalFiles, currentSnapshot.totalFiles, ''],
-      ['Classified files', originSnapshot.classifiedFiles, currentSnapshot.classifiedFiles, ''],
-      ['Active violations', originSnapshot.activeViolations, currentSnapshot.activeViolations, ''],
-      ['Value violations', originSnapshot.valueViolations, currentSnapshot.valueViolations, ''],
-      ['Type-only violations', originSnapshot.typeOnlyViolations, currentSnapshot.typeOnlyViolations, ''],
-      ['Layers', originSnapshot.layerCount, currentSnapshot.layerCount, ''],
-      ['Deny rules', originSnapshot.denyRules, currentSnapshot.denyRules, ''],
-      ['Gates configured', originSnapshot.gatesOn, currentSnapshot.gatesOn, ''],
-    ];
-    const originDate = (originSnapshot.generatedAt || '').slice(0, 10) || 'origin';
-    const nowDate = (currentSnapshot.generatedAt || '').slice(0, 10) || 'now';
-    const tr = rows
-      .map(([label, from, to, unit]) => {
-        const d =
-          typeof from === 'number' && typeof to === 'number' ? to - from : null;
-        const good =
-          label.includes('violation') || label.includes('Violation')
-            ? d != null && d <= 0
-            : label.includes('Governed') || label.includes('score') || label.includes('Classified') || label.includes('Gates')
-              ? d != null && d >= 0
-              : null;
-        const cls =
-          d == null || d === 0 ? 'flat' : good === true ? 'up' : good === false ? 'down' : 'flat';
-        const delta =
-          d == null
-            ? '—'
-            : unit === 'pp'
-              ? formatDelta(Math.round(d * 10) / 10, { suffix: ' pp' })
-              : formatDelta(d);
-        return `<tr>
-          <td>${esc(label)}</td>
-          <td class="num">${from ?? '—'}</td>
-          <td class="num">${to ?? '—'}</td>
-          <td class="num delta ${cls}">${esc(delta)}</td>
-        </tr>`;
-      })
-      .join('\n');
-    // Layer file deltas
-    const originLayers = originSnapshot.layerFiles || {};
-    const currentLayers = currentSnapshot.layerFiles || {};
-    const layerKeys = [...new Set([...Object.keys(originLayers), ...Object.keys(currentLayers)])].sort();
-    const layerTr = layerKeys
-      .map((name) => {
-        const from = originLayers[name] || 0;
-        const to = currentLayers[name] || 0;
-        const d = to - from;
-        const cls = d === 0 ? 'flat' : d > 0 ? 'up' : 'down';
-        return `<tr>
-          <td class="ln">${esc(name)}</td>
-          <td class="num">${from}</td>
-          <td class="num">${to}</td>
-          <td class="num delta ${cls}">${esc(formatDelta(d))}</td>
-        </tr>`;
-      })
-      .join('\n');
-    return `<div class="section card evolve">
-      <h2>Evolution vs origin</h2>
-      <p class="dim" style="margin:.15rem 0 .75rem;font-size:.88rem">
-        Origin snapshot <code>${esc(originDate)}</code> → this report <code>${esc(nowDate)}</code>
-        · frozen at <code>.ark/reports/origin.*</code> · reopen origin HTML anytime for the starting picture.
-      </p>
-      <table class="layers">
-        <tr><th>Metric</th><th>Origin</th><th>Now</th><th>Δ</th></tr>
-        ${tr}
-      </table>
-      <h3>Files per layer</h3>
-      <table class="layers">
-        <tr><th>Layer</th><th>Origin</th><th>Now</th><th>Δ</th></tr>
-        ${layerTr || '<tr><td colspan="4" class="dim">No layer file data in snapshots.</td></tr>'}
-      </table>
-      <p class="legend">Green Δ = improvement for that metric (↑ coverage/score/gates, ↓ violations). History JSON under <code>.ark/reports/history/</code> (last ${ARK_REPORT_HISTORY_MAX}).</p>
-    </div>`;
-  })()}
+  ${renderEvolutionSection({
+    originSnapshot,
+    currentSnapshot,
+    originJustCreated,
+    esc,
+    formatDelta,
+    historyMax: ARK_REPORT_HISTORY_MAX,
+  })}
 
   <div class="section card senior">
     <h2>Senior diagnostics</h2>

package/bin/lib/import-resolve.mjs

@@ -35,32 +35,55 @@ export function readTsconfigAliases(ts, root) {
   }
 }
 
+function canonicalPathWithMissingTail(value) {
+  const resolved = path.resolve(value);
+  let current = resolved;
+  const tail = [];
+  while (true) {
+    try {
+      return path.join(fs.realpathSync(current), ...tail.reverse());
+    } catch {
+      const parent = path.dirname(current);
+      if (parent === current) return resolved;
+      tail.push(path.basename(current));
+      current = parent;
+    }
+  }
+}
+
 /**
  * Resolve an import specifier to a repo-relative path.
  * Relative + tsconfig-aliased only; bare packages → undefined.
  */
 export function resolveSpecifierToRel(specifier, fromFilePath, root, tsAliases) {
+  const canonicalRoot = canonicalPathWithMissingTail(root);
   let abs;
   if (specifier.startsWith('./') || specifier.startsWith('../')) {
     if (!fromFilePath) return undefined;
-    const fromAbs = path.isAbsolute(fromFilePath)
-      ? fromFilePath
-      : path.resolve(root, fromFilePath);
-    abs = path.resolve(path.dirname(fromAbs), specifier);
+    const fromAbs = canonicalPathWithMissingTail(
+      path.isAbsolute(fromFilePath) ? fromFilePath : path.resolve(root, fromFilePath)
+    );
+    abs = canonicalPathWithMissingTail(path.resolve(path.dirname(fromAbs), specifier));
   } else {
     const alias = tsAliases.aliases.find((a) => specifier.startsWith(a.from));
     if (!alias) return undefined;
-    abs = path.resolve(tsAliases.baseUrl, `${alias.to}${specifier.slice(alias.from.length)}`);
+    abs = canonicalPathWithMissingTail(
+      path.resolve(tsAliases.baseUrl, `${alias.to}${specifier.slice(alias.from.length)}`)
+    );
   }
-  const rel = path.relative(root, abs).split(path.sep).join('/');
-  return rel.startsWith('..') ? undefined : rel;
+  const relative = path.relative(canonicalRoot, abs);
+  if (path.isAbsolute(relative) || relative.startsWith('..')) return undefined;
+  return relative.split(path.sep).join('/');
 }
 
 function filePathToRel(filePath, root) {
   if (!filePath || typeof filePath !== 'string') return undefined;
-  const abs = path.isAbsolute(filePath) ? filePath : path.resolve(root, filePath);
-  const rel = path.relative(root, abs).split(path.sep).join('/');
-  return rel.startsWith('..') ? undefined : rel;
+  const abs = canonicalPathWithMissingTail(
+    path.isAbsolute(filePath) ? filePath : path.resolve(root, filePath)
+  );
+  const relative = path.relative(canonicalPathWithMissingTail(root), abs);
+  if (path.isAbsolute(relative) || relative.startsWith('..')) return undefined;
+  return relative.split(path.sep).join('/');
 }
 
 function classifyProbe(root, rel, layers) {
@@ -130,4 +153,3 @@ export function createImportTargetResolver(ts, root, config) {
     return undefined;
   };
 }
-

package/bin/lib/install-activation.mjs

@@ -0,0 +1,87 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { arkCommand } from '../ark-shared.mjs';
+import { codexProjectMcpIsValid } from './codex-home.mjs';
+import { codexRuntimeActivation } from './enforcement-state.mjs';
+
+export function inspectCodexInstallActivation(root, enabled) {
+  let configuredOnDisk = false;
+  if (enabled) {
+    try {
+      configuredOnDisk = codexProjectMcpIsValid(
+        fs.readFileSync(path.join(root, '.codex', 'config.toml'), 'utf8'),
+        root
+      );
+    } catch {
+      // Missing/unreadable configuration remains explicitly unverified.
+    }
+  }
+  return {
+    codexProjectConfigured: configuredOnDisk,
+    runtimeActivation: codexRuntimeActivation({
+      configuredOnDisk,
+      restartRequired: configuredOnDisk,
+    }),
+  };
+}
+
+export function reportPartialInstall({
+  root,
+  tools,
+  results,
+  homeResults,
+  earlyWritten,
+  codexMcp,
+  runtimeActivation,
+}) {
+  const failed = [...results, ...homeResults]
+    .filter((result) => result.status === 'failed')
+    .map((result) => ({
+      target: result.relativePath ?? '(unknown template)',
+      reason: 'write failed',
+    }));
+  if (codexMcp?.status === 'failed') {
+    failed.push({
+      target: codexMcp.file,
+      reason: codexMcp.message ?? 'Codex MCP registration failed',
+    });
+  }
+  if (failed.length === 0) return false;
+
+  const written = new Set([
+    ...earlyWritten,
+    ...[...results, ...homeResults]
+      .filter((result) => result.status === 'written' || result.status === 'merged')
+      .map((result) => result.relativePath),
+  ]);
+  console.error('\nINSTALL PARTIAL — some artifacts were written; activation is not complete.');
+  console.error('Written:');
+  if (written.size === 0) console.error('  - (none)');
+  for (const relativePath of written) console.error(`  - ${relativePath}`);
+  console.error('Failed:');
+  for (const failure of failed) console.error(`  - ${failure.target}: ${failure.reason}`);
+  console.error('Recovery:');
+  console.error(
+    `  - Fix the listed path or permission error, then re-run ${arkCommand(root, 'ark-check', `--install-agent-gates${tools.size > 0 ? ` --tools ${[...tools].join(',')}` : ''}`)}.`
+  );
+  console.error('  - Existing customized files were preserved; no destructive rollback was attempted.');
+  if (tools.has('codex')) {
+    console.error(`  - Runtime activation: ${JSON.stringify(runtimeActivation)}`);
+  }
+  return true;
+}
+
+export function printCodexActivationHandoff(root, configuredOnDisk, runtimeActivation) {
+  console.log(
+    configuredOnDisk
+      ? '  CODEX MCP CONFIGURED — RUNTIME NOT VERIFIED'
+      : '  CODEX MCP CONFIGURATION UNRESOLVED — RUNTIME NOT VERIFIED'
+  );
+  console.log(`  Runtime activation: ${JSON.stringify(runtimeActivation)}`);
+  console.log(
+    configuredOnDisk
+      ? `  Restart Codex, then call ark_identity with expectedRoot "${path.resolve(root)}".`
+      : '  Repair `.codex/config.toml`, then restart Codex and call ark_identity.'
+  );
+  console.log('  Do not trust MCP verdicts before the project identity matches.');
+}

package/bin/lib/install-migrate.mjs

@@ -63,12 +63,11 @@ import {
   SKILL_TOOL_TARGETS,
   skillTemplates,
   stampSkill,
-  installedSkillVersion,
-  isVersionOlder,
   detectSkillGaps,
   arkPackageVersion,
   verifyHostSkillCatalog,
 } from './skill-install.mjs';
+import { installRepoSkillFile, installSkillCatalog, skillInstallLine, skillInstallNote } from './skill-write.mjs';
 import { detectDeployPathQuality } from './deploy-path.mjs';
 import {
   stripMcpServerArgs,
@@ -78,6 +77,7 @@ import {
   PREFERRED_CHECK_BIN,
   RUNNER_BEFORE_ARK,
 } from './mcp-adoption.mjs';
+import { inspectCodexInstallActivation, printCodexActivationHandoff, reportPartialInstall } from './install-activation.mjs';
 import {
   hasHardWriteHook,
   validateHardWriteRequest,
@@ -181,7 +181,7 @@ export function buildManagedAssetCatalog({ root, tools, compact = false, skillsO
       compact ? compactAgentInstructions(root, compactHost) : agentInstructions(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
+    // project-bound ark_identity/ark_manifest (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);
@@ -416,9 +416,11 @@ export function runInstallAgentGates(args) {
   // settings.json, CI workflow, rules) are the ones users customize, so a plain
   // `--force` clobbers them — this is the safe way to pick up new skill versions.
   // Do not mutate package.json under --skills-only (typecheck bootstrap is gates/CI).
+  const earlyWritten = new Set();
   if (!args.skillsOnly) {
     // S4.4: always write check:architecture on gate install / start (including compact).
     const checkBootstrap = ensureCheckArchitectureScript(root, { write: true });
+    if (checkBootstrap.changed) earlyWritten.add('package.json');
     if (checkBootstrap.changed && !args.json) {
       console.log(
         `Added package.json script "check:architecture": "${checkBootstrap.script}" (local/CI parity).`
@@ -426,6 +428,7 @@ export function runInstallAgentGates(args) {
     }
     // Bootstrap typecheck before CI template so generated workflow includes the step.
     const typecheckBootstrap = ensureTypecheckScript(root, { write: !args.compact });
+    if (typecheckBootstrap.changed && !args.compact) earlyWritten.add('package.json');
     if (typecheckBootstrap.changed && !args.compact && !args.json) {
       console.log(
         `Added package.json script "typecheck": "${typecheckBootstrap.script}" (tsconfig present; local/CI parity).`
@@ -438,7 +441,7 @@ export function runInstallAgentGates(args) {
     compact: args.compact,
     skillsOnly: args.skillsOnly,
   });
-  const { skills, skillPaths, version } = catalog;
+  const { skills, version } = catalog;
   const assetKindByPath = new Map(
     catalog.assets.map((asset) => [asset.relativePath, asset.kind ?? 'gate'])
   );
@@ -450,7 +453,10 @@ export function runInstallAgentGates(args) {
   if (args.compact && priorCompactHost === 'none' && [...tools][0]) {
     const genericMcp = path.join(root, '.mcp.json');
     try {
-      if (fs.readFileSync(genericMcp, 'utf8') === mcpJson(root)) fs.rmSync(genericMcp);
+      if (fs.readFileSync(genericMcp, 'utf8') === mcpJson(root)) {
+        fs.rmSync(genericMcp);
+        earlyWritten.add('.mcp.json');
+      }
     } catch {
       // Missing or customized user MCP configuration is deliberately retained.
     }
@@ -459,6 +465,9 @@ export function runInstallAgentGates(args) {
   const results = templates.map(([relativePath, content]) => {
     // S4.1: preserve content-identity customized/conflicted managed assets even under --force.
     const kind = assetKindByPath.get(relativePath) ?? 'gate';
+    if (kind === 'skill') {
+      return installRepoSkillFile(root, relativePath, content, version, args.force);
+    }
     if (
       args.force &&
       managedPresent &&
@@ -477,7 +486,14 @@ export function runInstallAgentGates(args) {
       }
       const tableStart = content.indexOf('[mcp_servers.ark]');
       const generatedPrelude = tableStart > 0 ? content.slice(0, tableStart) : '';
-      const mergeBase = generatedPrelude ? existing.replace(generatedPrelude, '') : existing;
+      const mergeBase = generatedPrelude
+        ? existing
+            .replace(generatedPrelude, '')
+            .replace(
+              /^# Generated by ark-check --install-agent-gates \(Codex project scope\)\.\n# Restart Codex after changes; MCP servers are loaded when the project session starts\.\n/m,
+              ''
+            )
+        : existing;
       const merged = upsertCodexMcpTable(mergeBase, 'ark', content);
       if (merged === existing) return { relativePath, status: 'skipped' };
       return writeTemplate(root, relativePath, merged, true);
@@ -527,7 +543,9 @@ export function runInstallAgentGates(args) {
     );
   });
 
-  console.log('Ark agent gate templates:');
+  console.log(
+    `Ark agent gate templates (scope=repo; source=${version ? `arkgate@${version}` : 'arkgate@unknown'}):`
+  );
   let staleSkipped = 0;
   let preservedCustomized = 0;
   for (const result of results) {
@@ -549,13 +567,10 @@ export function runInstallAgentGates(args) {
     if (result.status === 'skipped-customized') {
       preservedCustomized += 1;
       note = '  (customized — content-identity preserved)';
-    } else if (result.status === 'skipped' && skillPaths.has(result.relativePath) && version) {
-      const installed = installedSkillVersion(path.join(root, result.relativePath));
-      if (installed === null || isVersionOlder(installed, version)) {
+    } else if (result.status === 'skipped' && result.skillPlan) {
+      note = `  (${skillInstallNote(result.skillPlan)})`;
+      if (result.skillPlan.reason === 'existing-preserved') {
         staleSkipped += 1;
-        note = `  (stale: ${installed ?? 'no stamp'} < ${version})`;
-      } else {
-        note = '  (up to date)';
       }
     }
     console.log(`  ${marker.padEnd(7)} ${result.relativePath}${note}`);
@@ -581,36 +596,29 @@ export function runInstallAgentGates(args) {
   if (args.codexHome) {
     const dir = codexSkillsDir();
     console.log('');
-    console.log(`Codex home skills (${dir}/<name>/SKILL.md):`);
+    console.log(
+      `Codex home skills (scope=home-shared; source=${version ? `arkgate@${version}` : 'arkgate@unknown'}; target=${dir}/<name>/SKILL.md):`
+    );
+    console.log(
+      '  Compatibility: monotonic downgrade protection requires every shared-catalog writer ' +
+        'to use ArkGate 4.2.0+; pre-4.2 --codex-home ignores this catalog. Upgrade legacy repos first.'
+    );
     try {
       fs.mkdirSync(dir, { recursive: true });
     } catch (error) {
       console.error(`  FAILED to create ${dir} (${error.message})`);
-      homeResults.push({ status: 'failed' });
+      homeResults.push({ relativePath: dir, status: 'failed' });
     }
     if (homeResults.length === 0) {
-      for (const [name, content] of skills) {
-        const skillDir = path.join(dir, name);
-        const file = path.join(skillDir, 'SKILL.md');
-        if (fs.existsSync(file) && !args.force) {
-          const installed = installedSkillVersion(file);
-          const behind = installed === null || (version && isVersionOlder(installed, version));
-          const note = behind
-            ? `  (stale: ${installed ?? 'no stamp'} < ${version}; use --force)`
-            : '  (up to date)';
-          console.log(`  ${'skipped'.padEnd(7)} ${name}/SKILL.md${note}`);
-          homeResults.push({ status: 'skipped' });
-          continue;
-        }
-        try {
-          fs.mkdirSync(skillDir, { recursive: true });
-          fs.writeFileSync(file, content);
-          console.log(`  ${'wrote'.padEnd(7)} ${name}/SKILL.md`);
-          homeResults.push({ status: 'written' });
-        } catch (error) {
-          console.log(`  ${'FAILED'.padEnd(7)} ${name}/SKILL.md (${error.message})`);
-          homeResults.push({ status: 'failed' });
-        }
+      for (const result of installSkillCatalog({
+        directory: dir,
+        skills,
+        packageVersion: version,
+        force: args.force,
+        scope: 'home',
+      })) {
+        console.log(skillInstallLine(result));
+        homeResults.push(result);
       }
     }
   }
@@ -643,26 +651,28 @@ export function runInstallAgentGates(args) {
       const verb = codexMcp.status === 'updated' ? 'updated' : 'wrote';
       console.log(`  ${verb.padEnd(7)} [mcp_servers.ark] with absolute paths`);
       console.log('          RESTART Codex — it does not hot-load MCP servers.');
-      console.log('          Then expect: resource ark://manifest + tools validate_code, ark_check, ark_coverage, ark_place.');
+      console.log(
+        '          Then expect: tools ark_identity, ark_manifest, validate_code, ark_check, ark_coverage, ark_place.'
+      );
     }
   } else if (skipHomeWire) {
     codexMcp = { status: 'skipped', file: codexConfigPath(), reason: 'temp-root' };
   }
 
-  // Repo templates + explicit --codex-home skill writes are hard failures.
-  // Home MCP wire is best-effort: unreadable ~/.codex (sandbox, permissions) must not
-  // mark an otherwise successful repo gate install as failed.
-  const hardFailed = [...results, ...homeResults].filter((result) => result.status === 'failed');
-  if (hardFailed.length > 0) {
-    console.error(`\nFailed to write ${hardFailed.length} template(s).`);
+  const { codexProjectConfigured, runtimeActivation } =
+    inspectCodexInstallActivation(root, tools.has('codex') && !args.skillsOnly);
+  if (reportPartialInstall({
+    root,
+    tools,
+    results,
+    homeResults,
+    earlyWritten,
+    codexMcp,
+    runtimeActivation,
+  })) {
     process.exitCode = 1;
     return;
   }
-  if (codexMcp?.status === 'failed') {
-    console.error(
-      `\nWarning: Codex home MCP registration failed (${codexMcp.message}). Repo gates were written; fix ~/.codex access or re-run with --codex-home --force.`
-    );
-  }
   if (writeRequest.host) {
     if (!hasHardWriteHook(root, writeRequest.host)) {
       console.error(`\nFailed to verify the ${writeRequest.host} hard-write hook after install.`);
@@ -731,8 +741,14 @@ export function runInstallAgentGates(args) {
   }
   if ((tools.has('codex') || args.codexHome)) {
     console.log('');
+    if (tools.has('codex') && !args.skillsOnly) {
+      printCodexActivationHandoff(root, codexProjectConfigured, runtimeActivation);
+    }
     if (codexMcp && codexMcp.status !== 'failed') {
-      console.log(`  Codex: ark MCP registered in ${codexMcp.file} — restart Codex so \`ark://manifest\` loads.`);
+      console.log(
+        `  Codex: ark MCP registered in ${codexMcp.file} — restart Codex, then bind with ` +
+          '`ark_identity` and read the contract with `ark_manifest`.'
+      );
     }
     if (tools.has('codex') && !args.compact) {
       console.log('  Codex write path (honest):');

package/bin/lib/managed-upgrade.mjs

@@ -371,9 +371,9 @@ function summaryFor(assets, manifestChanged) {
   const states = {};
   for (const asset of assets) states[asset.state] = (states[asset.state] ?? 0) + 1;
   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 wouldWrite = applying.length;
+  // Public-summary compatibility: stamp-only writes are no longer scheduled.
+  const metadataRefresh = 0;
   const customizedPreserved = assets.filter((asset) => asset.state === 'customized').length;
   const fileChanges = applying.length;
   return {
@@ -385,7 +385,6 @@ function summaryFor(assets, manifestChanged) {
     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,
   };
@@ -447,12 +446,7 @@ export function planManagedUpgrade(root, options = {}) {
           kind: catalogAsset.kind,
         });
     const accepted = options.acceptConflicts === true;
-    const refreshMetadata =
-      classified.state === 'current' &&
-      catalogAsset.kind === 'skill' &&
-      currentScoped !== desiredScoped;
     const canApply =
-      refreshMetadata ||
       classified.state === 'stale' ||
       (classified.state === 'missing' && (!recorded || accepted)) ||
       (classified.state === 'conflicted' && accepted);
@@ -465,7 +459,7 @@ export function planManagedUpgrade(root, options = {}) {
       scope: catalogAsset.scope,
       ...classified,
       ...(unparsedScope ? { reason: 'unparsed managed TOML scope preserved' } : {}),
-      action: refreshMetadata ? 'refresh-metadata' : canApply ? (currentScoped == null ? 'create' : 'update') : 'none',
+      action: canApply ? (currentScoped == null ? 'create' : 'update') : 'none',
       willApply: canApply,
       blocked,
       beforeHash: hash(currentScoped == null ? null : Buffer.from(currentScoped)),
@@ -615,9 +609,7 @@ export function applyManagedUpgrade(root, plan, expectedPlanDigest) {
   if (resolvedRoot !== plan.root) throw new Error('managed upgrade plan root mismatch');
   if (plan.summary.blocked > 0) return publicPlan(plan, { blocked: true });
   const wouldWrite = plan.summary.wouldWrite ?? 0;
-  const metadataRefresh = plan.summary.metadataRefresh ?? 0;
   // Content already matches: unbound --apply is a no-op (exit success), not a digest error.
-  // Optional stamp-only refresh still requires the preview's exact --plan-digest.
   if (!expectedPlanDigest || expectedPlanDigest !== plan.planDigest) {
     if (wouldWrite === 0 && (plan.summary.blocked ?? 0) === 0 && !expectedPlanDigest) {
       return publicPlan(plan, {
@@ -625,7 +617,6 @@ export function applyManagedUpgrade(root, plan, expectedPlanDigest) {
         applied: false,
         blocked: false,
         nothingToApply: true,
-        optionalStampRefresh: metadataRefresh,
       });
     }
     throw new Error('managed upgrade plan digest mismatch; run a new preview and use its exact nextCommand');
@@ -741,31 +732,18 @@ export function renderManagedUpgrade(plan, options = {}) {
   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}` : '') +
-      '.'
+      `customized preserved: ${customizedPreserved}; blocked conflicts/deletions: ${blocked}.`
   );
   if (plan.applied) {
-    // Distinguish content writes from optional stamp/metadata bookkeeping.
-    if (wouldWrite === 0 && metadataRefresh > 0) {
-      console.log(
-        `Refreshed ${metadataRefresh} version stamp(s)` +
-          (summary.manifestChanged ? ' and managed manifest' : '') +
-          ' (no content body changes).'
-      );
-    } else {
-      console.log(
-        `Applied ${wouldWrite} content write(s)` +
-          (metadataRefresh > 0 ? `, ${metadataRefresh} stamp refresh(es)` : '') +
-          (summary.manifestChanged ? ', managed manifest' : '') +
-          '.'
-      );
-    }
+    console.log(
+      `Applied ${wouldWrite} content write(s)` +
+        (summary.manifestChanged ? ', managed manifest' : '') +
+        '.'
+    );
     return;
   }
   // Content already matches package templates — do not urge --apply as the primary next step.
@@ -775,15 +753,6 @@ export function renderManagedUpgrade(plan, options = {}) {
     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}.`);