@geraldmaron/construct 1.0.11 → 1.0.14

package/lib/hooks/session-start.mjs

@@ -6,6 +6,10 @@
  *
  * @p95ms 300
  * @maxBlockingScope SessionStart
+ *
+ * @lifecycle SessionStart
+ * @matcher  *
+ * @exits 0 = pass
  */
 import { readFileSync, existsSync, statSync, writeFileSync } from 'fs';
 import { execSync } from 'child_process';
@@ -321,6 +325,49 @@ try {
   brokerStatusNote = `\n${buildBrokerStatusLine({ env: process.env })}\n`;
 } catch { /* best effort */ }
 
+// Missing-env-vars notice. Reads .env.example from the project root,
+// compares against .env and process.env, lists keys whose example value
+// is a placeholder and whose live value is unset. Empty string when the
+// project has no .env.example or all required keys are populated.
+
+const envCheckNote = buildEnvCheckNote(cwd);
+
+function buildEnvCheckNote(rootDir) {
+  const examplePath = join(rootDir, '.env.example');
+  if (!existsSync(examplePath)) return '';
+  const example = parseEnvFile(examplePath);
+  if (example.size === 0) return '';
+  const envFile = parseEnvFile(join(rootDir, '.env'));
+  const PLACEHOLDER = /^(YOUR_|<|__|\$\{|REPLACE|ADD_|INSERT_|xxx|TODO)/i;
+  const missing = [];
+  for (const [key, exampleVal] of example) {
+    const required = !exampleVal || PLACEHOLDER.test(exampleVal);
+    if (!required) continue;
+    const liveFromEnvFile = envFile.has(key) && envFile.get(key) !== '' && !PLACEHOLDER.test(envFile.get(key));
+    const liveFromProcessEnv = process.env[key] && !PLACEHOLDER.test(process.env[key]);
+    if (!liveFromEnvFile && !liveFromProcessEnv) missing.push(key);
+  }
+  if (missing.length === 0) return '';
+  const noun = missing.length === 1 ? 'variable' : 'variables';
+  const list = missing.map((k) => `  - ${k}`).join('\n');
+  return `\n## Environment check — ${missing.length} required ${noun} not set\n${list}\nAdd these to .env before running the app.\n`;
+}
+
+function parseEnvFile(p) {
+  const map = new Map();
+  if (!existsSync(p)) return map;
+  for (const line of readFileSync(p, 'utf8').split('\n')) {
+    const stripped = line.trim();
+    if (!stripped || stripped.startsWith('#')) continue;
+    const eq = stripped.indexOf('=');
+    if (eq === -1) continue;
+    const key = stripped.slice(0, eq).trim();
+    const val = stripped.slice(eq + 1).trim();
+    if (key) map.set(key, val);
+  }
+  return map;
+}
+
 // Permission posture: surface gaps in ~/.claude/settings.json permissions.allow
 // so the agent can ask the user to close them instead of stumbling into the
 // classifier mid-task. Empty string when no gaps — keeps the banner small.
@@ -331,7 +378,7 @@ try {
   permissionPostureNote = buildPermissionPostureLine({ cwd });
 } catch { /* best effort */ }
 
-process.stdout.write(`${header}\n${body}${stateNote}${efficiencyNote}${observationsNote}${concurrencyNote}${skillScopeNote}${dropNote}${embedStatusNote}${sourcesNote}${selfKnowledgeNote}${rolesNote}${intakeReviewNote}${brokerStatusNote}${permissionPostureNote}\n${footer}${pendingNote}\n`);
+process.stdout.write(`${header}\n${body}${stateNote}${efficiencyNote}${observationsNote}${concurrencyNote}${skillScopeNote}${dropNote}${embedStatusNote}${sourcesNote}${selfKnowledgeNote}${rolesNote}${intakeReviewNote}${brokerStatusNote}${permissionPostureNote}${envCheckNote}\n${footer}${pendingNote}\n`);
 // Auto-bootstrap the policy-engine gate. session-start has just emitted
 // branch + recent commits + prior observations + context-state — that is
 // already grounding; mark the session bootstrapped so the PreToolUse rule

package/lib/hooks/session-tracking-refresh.mjs

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+/**
+ * lib/hooks/session-tracking-refresh.mjs — keep the project's tracking
+ * surfaces current at session end.
+ *
+ * Runs as a Stop hook in parallel with the other Stop-time hooks. Touches
+ * three surfaces:
+ *
+ *   - `.cx/context.md` + `.cx/context.json` — refresh Active Work, Recent
+ *     Decisions, and Architecture Notes from the session's observations,
+ *     commits, and bead state changes.
+ *   - `plan.md` — sync the bead-status table with current `bd show <id>`
+ *     truth; if every referenced bead has closed and the plan has been
+ *     idle for >1h, archive a copy to `.cx/handoffs/<date>-plan-landed.md`
+ *     and reset `plan.md` to the standard template.
+ *
+ * Best-effort. Failures degrade silently. Wall-clock budgeted at 2000 ms
+ * total — bd shells out, and a plan with several bead refs needs one
+ * `bd show` per ref. Exits 0 on any error so the session close path is
+ * never blocked.
+ *
+ * Only runs inside Construct projects (presence of `.cx/`) — same gate as
+ * the other Stop hooks.
+ *
+ * @lifecycle Stop
+ * @matcher  *
+ * @p95ms 2000
+ * @maxBlockingScope none (Stop, non-blocking)
+ * @exits 0 = pass
+ */
+
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { readHookInput } from './_lib/input.mjs';
+import { logHookFailure } from './_lib/log.mjs';
+
+const HARD_BUDGET_MS = 2000;
+const startedAt = Date.now();
+
+const input = readHookInput();
+const cwd = input?.cwd || process.cwd();
+
+// Only run inside Construct projects.
+if (!existsSync(join(cwd, '.cx'))) process.exit(0);
+
+const deadline = setTimeout(() => process.exit(0), HARD_BUDGET_MS);
+deadline.unref();
+
+try {
+  // Order matters. archivePlanIfLanded reads plan.md's mtime to decide
+  // whether the plan has been idle long enough to retire. syncPlanFile
+  // mutates plan.md when bead statuses drift — which bumps mtime and
+  // makes the plan look "recently touched" to the archive check. Run
+  // archive first (true idle mtime), then sync the survivor.
+  const { archivePlanIfLanded, syncPlanFile, refreshContextMd } = await import('../tracking-surfaces.mjs');
+  await archivePlanIfLanded({ rootDir: cwd });
+  await syncPlanFile({ rootDir: cwd });
+  await refreshContextMd({ rootDir: cwd });
+} catch (err) {
+  logHookFailure({ hook: 'session-tracking-refresh', err, phase: 'refresh' });
+}
+
+const elapsed = Date.now() - startedAt;
+if (elapsed > HARD_BUDGET_MS) {
+  try {
+    process.stderr.write(`[session-tracking-refresh] over budget: ${elapsed}ms\n`);
+  } catch { /* stderr closed */ }
+}
+
+process.exit(0);

package/lib/hooks/stop-notify.mjs

@@ -11,8 +11,14 @@
  *
  * @p95ms 500
  * @maxBlockingScope Stop
+ *
+ * @lifecycle Stop
+ * @matcher  *
+ * @exits 0 = pass
  */
-import { readFileSync, writeFileSync, existsSync, appendFileSync, mkdirSync } from 'fs';
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'fs';
+import { appendBounded } from '../logging/rotate.mjs';
+import { resolveProjectScope } from '../project-root.mjs';
 import { execSync } from 'child_process';
 import { homedir } from 'os';
 import { join, dirname } from 'path';
@@ -228,7 +234,12 @@ try {
     if (agentName) entry.agent = agentName;
     if (taskKey) entry.task_key = taskKey;
 
-    try { appendFileSync(costLogPath, JSON.stringify(entry) + '\n'); } catch { /* non-critical */ }
+    // Cross-project ledger — keep at user scope but tag with projectId so a
+    // reader can attribute spend to a specific project.
+
+    const scope = resolveProjectScope();
+    if (scope?.projectId) entry.projectId = scope.projectId;
+    try { appendBounded('session-cost', costLogPath, JSON.stringify(entry) + '\n'); } catch { /* non-critical */ }
 
     totalCostUsd += priced.costUsd;
     turnsLogged += 1;

package/lib/hooks/stop-typecheck.mjs

@@ -6,6 +6,10 @@
  *
  * @p95ms 2000
  * @maxBlockingScope Stop
+ *
+ * @lifecycle Stop
+ * @matcher  *
+ * @exits 0 = pass
  */
 import { readFileSync, writeFileSync, existsSync } from 'fs';
 import { execSync } from 'child_process';

package/lib/hooks/test-watch.mjs

@@ -8,9 +8,13 @@
  *
  * @p95ms 30
  * @maxBlockingScope none (async, non-blocking)
+ *
+ * @lifecycle PostToolUse
+ * @matcher  Bash
+ * @exits 0 = pass
  */
 
-import { readFileSync, existsSync, appendFileSync } from 'node:fs';
+import { readFileSync, existsSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { logHookFailure } from './_lib/log.mjs';
@@ -56,13 +60,13 @@ try {
     }
     state[name] = { failedAt: now };
   }
-  appendFileSync(flakeTrackerPath, '');
   const trimmed = {};
   for (const [k, v] of Object.entries(state)) {
     if ((v.failedAt || v.passedAt || 0) > now - 24 * 60 * 60 * 1000) trimmed[k] = v;
   }
-  const writeFileSync = (await import('node:fs')).writeFileSync;
   writeFileSync(flakeTrackerPath, JSON.stringify(trimmed));
-} catch { /* best effort */ }
+} catch (err) {
+  logHookFailure({ hook: 'test-watch', err, phase: 'flake-track' });
+}
 
 process.exit(0);

package/lib/init-unified.mjs

@@ -812,12 +812,28 @@ async function main() {
     const { findProjectConfigPath, loadProjectConfig, writeProjectConfig, PROJECT_CONFIG_FILENAME } = await import('./config/project-config.mjs');
     const found = findProjectConfigPath(target);
     const cfgPath = found || path.join(target, PROJECT_CONFIG_FILENAME);
-    const cfg = found ? (loadProjectConfig(target) || { version: 1 }) : { version: 1 };
+
+    // loadProjectConfig returns a wrapper { path, raw, config, source, errors }.
+    // Persist .raw (the on-disk JSON) so user customizations survive and
+    // defaults are not silently materialized into the file.
+
+    const loaded = found ? loadProjectConfig(target) : null;
+    const cfg = loaded?.raw ? { ...loaded.raw } : { version: 1 };
     cfg.profile = profileId;
     writeProjectConfig(cfgPath, cfg, { validate: true });
     if (!quiet) console.log(`Profile set to ${profileId}.`);
   }
-  
+
+  // Resolve active profile to drive capability-gated scaffolding (intake
+  // archetype, attribution stamping). Falls back to rnd when no profile is
+  // configured — matches resolveActiveProfile semantics elsewhere.
+
+  const { resolveActiveProfile } = await import('./profiles/loader.mjs');
+  const activeProfile = resolveActiveProfile(target, profileId) ?? null;
+  const intakeCap = activeProfile?.capabilities?.intake ?? null;
+  const { gatherAttribution } = await import('./intake/attribution.mjs');
+  const attribution = intakeCap?.attribution ? gatherAttribution() : null;
+
   // Always create core Construct files
   writeStampedIfMissing({
     targetRoot: target,
@@ -826,8 +842,9 @@ async function main() {
     filePath: path.join(target, "AGENTS.md"),
     content: buildAgentsGuide(projectName),
     generator: "construct/init",
+    attribution,
   });
-  
+
   writeStampedIfMissing({
     targetRoot: target,
     created,
@@ -835,17 +852,18 @@ async function main() {
     filePath: path.join(target, "plan.md"),
     content: buildPlanTemplate(),
     generator: "construct/init",
+    attribution,
   });
-  
+
   writeStampedIfMissing({
     targetRoot: target,
     created,
     skipped,
     filePath: path.join(target, ".cx", "context.json"),
-    content: buildContextJson(projectName),
+    content: buildContextJson(projectName, { attribution }),
     generator: "construct/init",
   });
-  
+
   writeStampedIfMissing({
     targetRoot: target,
     created,
@@ -853,6 +871,7 @@ async function main() {
     filePath: path.join(target, ".cx", "context.md"),
     content: buildContextMarkdown(),
     generator: "construct/init",
+    attribution,
   });
   
   writeStampedIfMissing({
@@ -888,6 +907,56 @@ async function main() {
     });
   }
 
+  // Intake-archetype scaffolding. When the active profile declares
+  // capabilities.intake.inbox, scaffold a project-root inbox/ drop zone
+  // (with a .gitignore so raw drops never enter source) and seed the
+  // dedup manifest. The existing-structure detection already opted us
+  // out of clobbering a user's pipeline above.
+
+  if (intakeCap?.inbox && !inboxDecision.skip) {
+    const projectInbox = path.join(target, 'inbox');
+    if (!fs.existsSync(projectInbox)) {
+      fs.mkdirSync(projectInbox, { recursive: true });
+      created.push('inbox/');
+    }
+    const inboxGitignore = path.join(projectInbox, '.gitignore');
+    if (!fs.existsSync(inboxGitignore)) {
+      fs.writeFileSync(inboxGitignore, '*\n!.gitignore\n', 'utf8');
+      created.push('inbox/.gitignore');
+    }
+
+    if (intakeCap.dedup === 'sha256') {
+      const { saveManifest, loadManifest, MANIFEST_REL_PATH } = await import('./intake/manifest.mjs');
+      const manifestExists = fs.existsSync(path.join(target, MANIFEST_REL_PATH));
+      if (!manifestExists) {
+        saveManifest(target, loadManifest(target));
+        created.push(MANIFEST_REL_PATH);
+      }
+    }
+  }
+
+  // Ensure `.cx/` is in project .gitignore. .cx/ is runtime state — observations,
+  // sessions, vector index, and traces (with daily JSONL files that can exceed
+  // GitHub's 100 MB file-size limit). Idempotent: if `.cx/` (or a broader
+  // pattern like `.cx` / `*` / `**`) already matches, leave the file alone.
+
+  try {
+    const gitignorePath = path.join(target, '.gitignore');
+    const existing = fs.existsSync(gitignorePath) ? fs.readFileSync(gitignorePath, 'utf8') : '';
+    const lines = existing.split('\n').map((l) => l.trim());
+    const alreadyIgnored = lines.some((l) =>
+      l === '.cx' || l === '.cx/' || l === '.cx/**' || l === '*' || l === '**'
+    );
+    if (!alreadyIgnored) {
+      const prefix = existing.length === 0 || existing.endsWith('\n') ? '' : '\n';
+      const block = `${prefix}\n# Construct runtime state — local-only, never source\n.cx/\n`;
+      fs.writeFileSync(gitignorePath, existing + block, 'utf8');
+      created.push(existing.length === 0 ? '.gitignore (added .cx/)' : '.gitignore (appended .cx/)');
+    }
+  } catch (err) {
+    console.warn(`⚠️  Could not update .gitignore: ${err.message}`);
+  }
+
   // Stage .construct/ launcher + sync .claude/ adapters so init produces the
   // same project shape as a fresh `npm install` of the package as a dep.
 
@@ -911,23 +980,12 @@ async function main() {
       created.push('.claude/ (agents + settings)');
     }
 
-    // Also sync home-level adapters for all 6 host surfaces (Copilot, OpenCode,
-    // Codex, VS Code, Cursor, plus Claude home) so the user's environment is
-    // fully wired after init. Project-local Claude adapters were written above.
-    const syncScript = path.join(ROOT_DIR, 'scripts', 'sync-specialists.mjs');
-    if (fs.existsSync(syncScript)) {
-      const { spawnSync } = await import('node:child_process');
-      const homeResult = spawnSync(process.execPath, [syncScript], {
-        cwd: target,
-        stdio: 'pipe',
-        env: { ...process.env, CONSTRUCT_PROJECT_ROOT: target },
-        timeout: 120000,
-      });
-      if (homeResult.status !== 0) {
-        const errMsg = homeResult.stderr.toString().substring(0, 200);
-        console.warn(`⚠️  Home adapter sync had issues (exit ${homeResult.status}): ${errMsg}`);
-      }
-    }
+    // construct init writes project scope only. Global wiring (the `construct`
+    // front-door agent in `~/.claude/agents/`, `~/.codex/agents/`, etc.) is
+    // installed once by `construct sync --global` or the npm postinstall.
+    // Specialists, slash commands, and skills live with the repo per each
+    // host's documented best-practice scope.
+
   } catch (err) {
     console.warn(`⚠️  Adapter staging failed: ${err.message}`);
   }
@@ -987,6 +1045,15 @@ async function main() {
   // pipeline. User can opt in later via `construct config intake.includeProjectInbox=true`.
 
   if (inboxDecision.skip) intakeConfig.includeProjectInbox = false;
+
+  // Archetype: flip includeArchetypeInbox on so resolveInboxDirs picks up
+  // the project-root inbox/ drop zone alongside .cx/inbox/. Mirrors the
+  // existing includeProjectInbox / includeDocsIntake toggles rather than
+  // polluting parentDirs (which is reserved for user-explicit dirs).
+
+  if (intakeCap?.inbox) {
+    intakeConfig.includeArchetypeInbox = true;
+  }
   const { saveIntakeConfig } = await import('./intake/intake-config.mjs');
   try {
     saveIntakeConfig(target, intakeConfig);

package/lib/intake/attribution.mjs

@@ -0,0 +1,77 @@
+/**
+ * lib/intake/attribution.mjs — provenance metadata for intake-archetype artifacts.
+ *
+ * Two-field attribution. Human identity comes from `git config user.name` +
+ * `user.email`; agent identity comes from CONSTRUCT_AGENT_ID (set by hosts
+ * like Claude Code, Codex, Copilot before they invoke the binary). Both are
+ * captured because either can be the proximate cause of a write and the
+ * audit reader needs to know which.
+ *
+ * Pure, side-effect free. No git/cli call when the env var
+ * CONSTRUCT_ATTRIBUTION_DISABLE=1 — useful for deterministic tests and for
+ * privacy-sensitive setups that prefer no identity capture.
+ */
+
+import { spawnSync } from 'node:child_process';
+
+function gitConfigValue(key, cwd) {
+  const result = spawnSync('git', ['config', '--get', key], {
+    cwd,
+    encoding: 'utf8',
+    timeout: 2000,
+  });
+  if (result.status !== 0) return null;
+  const value = (result.stdout || '').trim();
+  return value || null;
+}
+
+function humanIdentity(cwd) {
+  const name = gitConfigValue('user.name', cwd);
+  const email = gitConfigValue('user.email', cwd);
+  if (!name && !email) return null;
+  if (name && email) return `${name} <${email}>`;
+  return name || email;
+}
+
+function agentIdentity() {
+  return (
+    process.env.CONSTRUCT_AGENT_ID
+    || process.env.CLAUDE_AGENT_ID
+    || null
+  );
+}
+
+export function gatherAttribution({ now = new Date(), cwd } = {}) {
+  if (process.env.CONSTRUCT_ATTRIBUTION_DISABLE === '1') {
+    return {
+      createdBy: null,
+      createdByAgent: null,
+      createdAt: now.toISOString(),
+    };
+  }
+  return {
+    createdBy: humanIdentity(cwd),
+    createdByAgent: agentIdentity(),
+    createdAt: now.toISOString(),
+  };
+}
+
+export function stampAttribution(record, attribution = gatherAttribution()) {
+  if (!record || typeof record !== 'object') return record;
+  return {
+    ...record,
+    createdBy: attribution.createdBy,
+    createdByAgent: attribution.createdByAgent,
+    createdAt: attribution.createdAt,
+  };
+}
+
+export function touchAttribution(record, attribution = gatherAttribution()) {
+  if (!record || typeof record !== 'object') return record;
+  return {
+    ...record,
+    lastModifiedBy: attribution.createdBy,
+    lastModifiedByAgent: attribution.createdByAgent,
+    lastModifiedAt: attribution.createdAt,
+  };
+}

package/lib/intake/intake-config.mjs

@@ -44,6 +44,7 @@ export const DEFAULT_INTAKE_CONFIG = Object.freeze({
   maxDepth: INTAKE_DEFAULT_MAX_DEPTH,
   includeProjectInbox: true,
   includeDocsIntake: true,
+  includeArchetypeInbox: false,
 });
 
 export function intakeConfigPath(rootDir) {
@@ -98,6 +99,7 @@ export function loadIntakeConfig(rootDir, env = process.env) {
     maxDepth,
     includeProjectInbox: stored.includeProjectInbox !== false,
     includeDocsIntake: stored.includeDocsIntake !== false,
+    includeArchetypeInbox: stored.includeArchetypeInbox === true,
   };
 }
 
@@ -113,6 +115,7 @@ export function saveIntakeConfig(rootDir, patch = {}) {
     maxDepth: clampDepth(patch.maxDepth ?? current.maxDepth),
     includeProjectInbox: patch.includeProjectInbox !== undefined ? Boolean(patch.includeProjectInbox) : current.includeProjectInbox,
     includeDocsIntake: patch.includeDocsIntake !== undefined ? Boolean(patch.includeDocsIntake) : current.includeDocsIntake,
+    includeArchetypeInbox: patch.includeArchetypeInbox !== undefined ? Boolean(patch.includeArchetypeInbox) : current.includeArchetypeInbox,
   };
 
   const file = intakeConfigPath(rootDir);

package/lib/intake/manifest.mjs

@@ -0,0 +1,107 @@
+/**
+ * lib/intake/manifest.mjs — SHA-256 dedup manifest for intake-archetype projects.
+ *
+ * Projects that scaffold the intake archetype (profile.capabilities.intake)
+ * drop raw source files into `inbox/`. The manifest records which source
+ * files have already been processed (by content hash, not path) so the
+ * intake runtime can refuse to reprocess an unchanged file and so a moved
+ * or renamed file still dedups correctly.
+ *
+ * Storage: <projectRoot>/.cx/intake/manifest.json
+ *
+ * Shape:
+ *   {
+ *     "version": 1,
+ *     "files": {
+ *       "<sha256>": {
+ *         "sourcePath": "inbox/notes-2026-05-29.md",
+ *         "processedAt": "2026-05-29T19:00:00.000Z",
+ *         "intakeId": "intake-1779164832122-onxe",
+ *         "createdBy": "Gerald Dagher <gerald@example.com>",
+ *         "createdByAgent": "claude-opus-4-7"
+ *       }
+ *     }
+ *   }
+ *
+ * Pure functions over the JSON. Callers own the rootDir; no implicit cwd.
+ * Atomic writes go through write-rename so a crash mid-write cannot leave
+ * the manifest half-written.
+ */
+
+import { createHash } from 'node:crypto';
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  writeFileSync,
+} from 'node:fs';
+import { join } from 'node:path';
+
+export const MANIFEST_REL_PATH = '.cx/intake/manifest.json';
+export const MANIFEST_VERSION = 1;
+
+function manifestPath(rootDir) {
+  return join(rootDir, MANIFEST_REL_PATH);
+}
+
+function emptyManifest() {
+  return { version: MANIFEST_VERSION, files: {} };
+}
+
+export function loadManifest(rootDir) {
+  const p = manifestPath(rootDir);
+  if (!existsSync(p)) return emptyManifest();
+  try {
+    const raw = JSON.parse(readFileSync(p, 'utf8'));
+    if (!raw || typeof raw !== 'object' || typeof raw.files !== 'object') {
+      return emptyManifest();
+    }
+    return raw;
+  } catch {
+    return emptyManifest();
+  }
+}
+
+export function saveManifest(rootDir, manifest) {
+  const p = manifestPath(rootDir);
+  const dir = join(rootDir, '.cx', 'intake');
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  const payload = JSON.stringify(manifest, null, 2) + '\n';
+  const tmp = `${p}.tmp`;
+  writeFileSync(tmp, payload, 'utf8');
+  renameSync(tmp, p);
+}
+
+export function sha256Of(buffer) {
+  return createHash('sha256').update(buffer).digest('hex');
+}
+
+export function hasFile(rootDir, sha) {
+  if (!sha) return false;
+  const manifest = loadManifest(rootDir);
+  return Boolean(manifest.files[sha]);
+}
+
+export function recordFile(rootDir, sha, entry) {
+  if (!sha) throw new Error('recordFile: sha is required');
+  const manifest = loadManifest(rootDir);
+  manifest.files[sha] = {
+    sourcePath: entry?.sourcePath ?? null,
+    processedAt: entry?.processedAt ?? new Date().toISOString(),
+    intakeId: entry?.intakeId ?? null,
+    createdBy: entry?.createdBy ?? null,
+    createdByAgent: entry?.createdByAgent ?? null,
+  };
+  saveManifest(rootDir, manifest);
+  return manifest.files[sha];
+}
+
+export function manifestStats(rootDir) {
+  const manifest = loadManifest(rootDir);
+  const entries = Object.values(manifest.files);
+  return {
+    total: entries.length,
+    version: manifest.version,
+  };
+}