arkgate 4.1.1 → 4.2.1

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

package/bin/lib/mcp-adoption.mjs

@@ -16,7 +16,7 @@ import { detectWritePathCapabilities } from './write-path-detect.mjs';
 import { detectActiveAgentHost, skillTemplateNames } from './skill-install.mjs';
 import { detectDeployPathQuality } from './deploy-path.mjs';
 import { collectWeakestLinkGaps } from './weakest-link.mjs';
-import { withCiProviderEvidence } from './enforcement-state.mjs';
+import { codexRuntimeActivation, withCiProviderEvidence } from './enforcement-state.mjs';
 
 export { detectDeployPathQuality };
 
@@ -120,7 +120,7 @@ export function brokenMcpGateFiles(root) {
 
 /**
  * Adoption completeness (separate from 0–100 fitness). Pure-ish: filesystem + config.
- * @returns {{ gaps: object[], hosts: object[], mcp: object, codexHome: object|null, coreOptional: object[], originReport: object, baseline: object, layerBalance: object|null, deployPath: object|null, writePath: object }}
+ * @returns {{ gaps: object[], hosts: object[], mcp: object, codexHome: object|null, coreOptional: object[], originReport: object, baseline: object, layerBalance: object|null, deployPath: object|null, writePath: object, runtimeActivation: object }}
  */
 export function collectAdoptionGaps(root, config, coverage) {
   const gaps = [];
@@ -259,7 +259,11 @@ export function collectAdoptionGaps(root, config, coverage) {
       return false;
     }
   })();
-  if (adopted && !isProducer && !codexProjectMcp) {
+  const runtimeActivation = codexRuntimeActivation({
+    configuredOnDisk: codexProjectMcp,
+    restartRequired: codexProjectMcp,
+  });
+  if (adopted && !isProducer) {
     const codexFile = codexConfigPath();
     let toml = '';
     try {
@@ -278,6 +282,8 @@ export function collectAdoptionGaps(root, config, coverage) {
         needsRewrite: assessed.needsRewrite,
         multiProject: assessed.multiProject,
         scopedTable: assessed.scopedTable,
+        projectConfiguredOnDisk: codexProjectMcp,
+        runtimeIdentityVerified: false,
       };
       if (assessed.gap) {
         // Temp/upgrade MCP roots stay urgent (fail-closed). Non-temp Codex-home debt
@@ -288,9 +294,12 @@ export function collectAdoptionGaps(root, config, coverage) {
         const deferred =
           !tempUrgent && activeHost != null && activeHost !== 'codex';
         const severity = deferred ? 'info' : assessed.gap.severity;
+        const localRisk = codexProjectMcp
+          ? 'Project config exists on disk, but the active runtime identity is unverified. '
+          : '';
         const message = deferred
-          ? `Deferred (fix when using Codex): ${assessed.gap.message}`
-          : assessed.gap.message;
+          ? `Deferred (fix when using Codex): ${localRisk}${assessed.gap.message}`
+          : `${localRisk}${assessed.gap.message}`;
         gaps.push({
           id: assessed.gap.id,
           severity,
@@ -526,6 +535,7 @@ export function collectAdoptionGaps(root, config, coverage) {
     deployPath,
     contractFalseGreen,
     writePath,
+    runtimeActivation,
     enforcement: {
       ci: weakest.ci,
       preCommit: weakest.preCommit,

package/bin/lib/physical-cohesion.mjs

@@ -24,7 +24,8 @@ const MAX_FINDINGS = 5;
 const MAX_ANCHORS = 4;
 const MAX_MOVE_SAMPLE = 5;
 
-const FRAMEWORK_FILES = /^(route|page|layout|index|loading|error|template|default|not-found|middleware|actions?|handler)$/i;
+// `proxy` = Next.js 16 network-boundary rename of middleware (still framework-owned).
+const FRAMEWORK_FILES = /^(route|page|layout|index|loading|error|template|default|not-found|middleware|proxy|actions?|handler)$/i;
 const SKIP_SEGMENT = /^(\[.*\]|\(.*\)|src|app|apps|api|lib|libs|pages|packages|modules|components|utils|helpers|hooks|server|client|shared|common|__tests__|tests?|e2e|examples?|dist|build)$/i;
 const NOISE_TOKEN = /^(use|api|get|set|app|lib|the|new)$/;
 /** ADR 0010 D7 — framework-owned anchors never move. */

package/bin/lib/pilot-loop.mjs

@@ -5,7 +5,10 @@
  * extraction-card payload, and compares residual after re-doctor on pilot paths.
  * Judgment only — never mechanical-safe; never multi-pilot batch apply.
  */
-import { buildPatternBetsFromSmells } from './design-smells.mjs';
+import {
+  buildPatternBetsFromSmells,
+  isNonProductionPilotPath,
+} from './design-smells.mjs';
 
 /** Stable product id for JSON / tests. */
 export const PILOT_LOOP_ID = 'one-pilot-redoctor';
@@ -44,14 +47,28 @@ export function fileEvidencePaths(evidence = []) {
   );
 }
 
+function pilotFilesForBet(bet, preferredFiles) {
+  const rawFiles = preferredFiles?.length
+    ? preferredFiles
+    : fileEvidencePaths(bet?.evidence);
+  if (bet?.smellId !== 'god-module') return rawFiles;
+  const files = rawFiles.filter((file) => !isNonProductionPilotPath(file));
+  const excludedPilot =
+    rawFiles.length === 0 &&
+    typeof bet.pilot === 'string' &&
+    isNonProductionPilotPath(bet.pilot);
+  return (rawFiles.length > 0 && files.length === 0) || excludedPilot
+    ? null
+    : files;
+}
+
 /**
  * Score a pattern bet for "do this pilot first".
  * Prefers concrete src/ files and higher-impact smell ids.
  * @param {object} bet
  * @param {number} index
  */
-function scoreBet(bet, index) {
-  const files = fileEvidencePaths(bet?.evidence);
+function scoreBet(bet, index, files = fileEvidencePaths(bet?.evidence)) {
   const smellPri = SMELL_PRIORITY[bet?.smellId] ?? 50;
   // Higher score wins; concrete files dominate; then smell priority; stable by index.
   return files.length * 100 - smellPri * 10 - index;
@@ -64,9 +81,8 @@ function scoreBet(bet, index) {
  */
 export function extractionCardFromBet(bet, preferredFiles) {
   if (!bet || typeof bet !== 'object') return null;
-  const files = preferredFiles?.length
-    ? preferredFiles
-    : fileEvidencePaths(bet.evidence);
+  const files = pilotFilesForBet(bet, preferredFiles);
+  if (files === null) return null;
   const evidence = files.length ? files : (bet.evidence || []).slice(0, 8);
   const pilotTarget =
     files[0] ||
@@ -123,8 +139,9 @@ export function selectNextPilot(patternBets, options = {}) {
     if (!bet || bet.neverMechanicalSafe === false) continue;
     // Skip anything that claims mechanical-safe (honesty).
     if (bet.class === 'mechanical-safe') continue;
-    const files = fileEvidencePaths(bet.evidence);
-    const sc = scoreBet(bet, i);
+    const files = pilotFilesForBet(bet);
+    if (files === null) continue;
+    const sc = scoreBet(bet, i, files);
     if (sc > bestScore) {
       bestScore = sc;
       best = { bet, files };

package/bin/lib/project-identity.mjs

@@ -0,0 +1,103 @@
+/**
+ * GENERATED FILE — do not edit by hand.
+ *
+ * Canonical algorithm: src/domain/projectIdentity.ts
+ * Regenerate: node scripts/generate-cli-pure.mjs
+ * Drift check: node scripts/generate-cli-pure.mjs --check
+ *
+ * Pure CLI helper (bin/lib/project-identity.mjs). Zero Node I/O.
+ */
+
+export const ARK_PROJECT_IDENTITY_SCHEMA_VERSION = '1.0';
+export const ARK_PROJECT_IDENTITY_SCHEMA_URL = 'https://unpkg.com/arkgate@4/schemas/ark.project-identity.schema.json';
+const sha256Pattern = '^sha256:[a-f0-9]{64}$';
+export const PROJECT_EXPECTATION_SCHEMA = {
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+        expectedRoot: {
+            type: 'string',
+            minLength: 1,
+            description: 'Absolute expected workspace/project directory. The initial authoritative handshake ' +
+                'requires the exact project root; descendant calls also require expectedProjectId.',
+        },
+        expectedProjectId: {
+            type: 'string',
+            pattern: sha256Pattern,
+            description: 'Project id previously returned by ark_identity or ark_manifest.',
+        },
+    },
+};
+export const PROJECT_BINDING_SCHEMA = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['status', 'authoritative'],
+    properties: {
+        status: { enum: ['matched', 'unverified', 'mismatch'] },
+        authoritative: { type: 'boolean' },
+        expectedRoot: { type: 'string', minLength: 1 },
+        expectedProjectId: { type: 'string', pattern: sha256Pattern },
+        code: {
+            enum: [
+                'PROJECT_ROOT_MISMATCH',
+                'PROJECT_ID_MISMATCH',
+                'INVALID_PROJECT_EXPECTATION',
+            ],
+        },
+        message: { type: 'string', minLength: 1 },
+    },
+};
+export const ARK_PROJECT_IDENTITY_SCHEMA = {
+    $schema: 'https://json-schema.org/draft/2020-12/schema',
+    $id: ARK_PROJECT_IDENTITY_SCHEMA_URL,
+    title: 'ArkGate MCP project identity',
+    description: 'Stable project binding plus separate runtime and architecture-contract evidence.',
+    type: 'object',
+    additionalProperties: false,
+    required: [
+        'schemaVersion',
+        'projectId',
+        'resolvedRoot',
+        'resolvedConfigPath',
+        'arkgateVersion',
+        'contractHash',
+        'contractSource',
+        'runtimeId',
+        'processStartedAt',
+    ],
+    properties: {
+        schemaVersion: { const: ARK_PROJECT_IDENTITY_SCHEMA_VERSION },
+        projectId: { type: 'string', pattern: sha256Pattern },
+        resolvedRoot: { type: 'string', minLength: 1 },
+        resolvedConfigPath: { type: 'string', minLength: 1 },
+        arkgateVersion: { type: 'string', minLength: 1 },
+        contractHash: { type: 'string', pattern: sha256Pattern },
+        contractSource: { enum: ['project', 'default-profile', 'manifest'] },
+        runtimeId: { type: 'string', minLength: 1 },
+        processStartedAt: { type: 'string', format: 'date-time' },
+    },
+    $defs: {
+        expectation: PROJECT_EXPECTATION_SCHEMA,
+        binding: PROJECT_BINDING_SCHEMA,
+    },
+};
+/**
+ * Stable identity: contract edits and MCP restarts must not change which project
+ * this is. Callers must pass canonical real paths and a SHA-256 hex function.
+ */
+export function createProjectId(resolvedRoot, resolvedConfigPath, sha256Hex) {
+    if (!resolvedRoot || !resolvedConfigPath) {
+        throw new Error('Project identity requires resolvedRoot and resolvedConfigPath.');
+    }
+    const digest = sha256Hex(JSON.stringify({ resolvedRoot, resolvedConfigPath })).toLowerCase();
+    if (!/^[a-f0-9]{64}$/.test(digest)) {
+        throw new Error('Project identity hash adapter must return 64 hexadecimal SHA-256 characters.');
+    }
+    return `sha256:${digest}`;
+}
+export function createProjectIdentity(input) {
+    return {
+        schemaVersion: ARK_PROJECT_IDENTITY_SCHEMA_VERSION,
+        ...input,
+    };
+}

package/bin/lib/report-snapshot-context.mjs

@@ -0,0 +1,28 @@
+import { execFileSync } from 'node:child_process';
+
+/** Best-effort, shell-free Git/worktree evidence for report snapshots. */
+export function captureGitSnapshot(root) {
+  const run = (args) =>
+    execFileSync('git', ['-C', root, ...args], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+  try {
+    const headSha = run(['rev-parse', '--verify', 'HEAD']);
+    let branch = null;
+    try {
+      branch = run(['symbolic-ref', '--quiet', '--short', 'HEAD']) || null;
+    } catch {
+      // Detached HEAD is valid release/report evidence.
+    }
+    let dirty = null;
+    try {
+      dirty = run(['status', '--porcelain=v1', '--untracked-files=normal']).length > 0;
+    } catch {
+      // Keep the commit identity even when worktree state is unavailable.
+    }
+    return { available: true, headSha, branch, dirty };
+  } catch {
+    return { available: false, headSha: null, branch: null, dirty: null };
+  }
+}