@geraldmaron/construct 1.0.12 → 1.0.14

package/lib/embed/inbox.mjs

@@ -33,10 +33,14 @@ import { shouldCreateCx } from '../project-detection.mjs';
 import { ensureCxDir } from '../project-init-shared.mjs';
 import { prepareIntakeForIngestedFile } from '../intake/prepare.mjs';
 import { loadIntakeConfig, INTAKE_DEFAULT_MAX_DEPTH } from '../intake/intake-config.mjs';
+import { loadManifest, recordFile, hasFile, sha256Of, MANIFEST_REL_PATH } from '../intake/manifest.mjs';
+import { gatherAttribution } from '../intake/attribution.mjs';
+import { acquirePollLock, releasePollLock } from '../intake/poll-lock.mjs';
 
 const STATE_FILE = '.cx/runtime/inbox-state.json';
 const DEFAULT_INBOX_SUBDIR = '.cx/inbox';
 const DOCS_INTAKE_SUBDIR = 'docs/intake';
+const ARCHETYPE_INBOX_SUBDIR = 'inbox';
 const MAX_FILE_SIZE_BYTES = 50 * 1024 * 1024; // 50 MB hard cap
 const STALE_STATE_AGE_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
 
@@ -155,6 +159,16 @@ export function resolveInboxDirs(rootDir, env = process.env) {
     if (existsSync(docsIntake)) dirs.push(docsIntake);
   }
 
+  // Archetype inbox is a profile-driven drop zone for raw source files
+  // (capabilities.intake.inbox). Off by default; init flips it on when the
+  // active profile declares the capability so non-archetype projects keep
+  // their pre-Piece-C behavior.
+
+  if (config.includeArchetypeInbox) {
+    const archetypeInbox = join(rootDir, ARCHETYPE_INBOX_SUBDIR);
+    if (existsSync(archetypeInbox)) dirs.push(archetypeInbox);
+  }
+
   for (const candidate of config.parentDirs) {
     if (!candidate) continue;
     if (!existsSync(candidate)) continue;
@@ -298,8 +312,31 @@ export class InboxWatcher {
   /**
    * Scan all inbox dirs, ingest new files, record observations.
    * Returns { processed: [...], skipped: number, errors: [...] }
+   *
+   * @param {object} [opts]
+   * @param {number} [opts.waitMs] - When >0, block up to this many ms for
+   *   the intake poll lock. Default 0 (fail-fast). The CLI sets this when
+   *   the operator opts into waiting; the daemon's tick keeps the default
+   *   so a stuck poll does not stall the next scheduled iteration.
+   * @param {string} [opts.actor] - Stamped onto the lock for diagnostics.
    */
-  async poll() {
+  async poll({ waitMs = 0, actor = 'inbox-watcher' } = {}) {
+    let lockHeld = false;
+    try {
+      await acquirePollLock({
+        rootDir: this.#rootDir,
+        actor,
+        command: 'InboxWatcher.poll',
+        waitMs,
+      });
+      lockHeld = true;
+      return await this.#pollLocked();
+    } finally {
+      if (lockHeld) releasePollLock(this.#rootDir);
+    }
+  }
+
+  async #pollLocked() {
     const config = loadIntakeConfig(this.#rootDir, this.#env);
     const dirs = resolveInboxDirs(this.#rootDir, this.#env);
     const state = readState(this.#rootDir);
@@ -307,6 +344,15 @@ export class InboxWatcher {
     const errors = [];
     let skipped = 0;
 
+    // Capability detection: SHA-256 dedup is enabled when the project's
+    // intake manifest exists (init scaffolds it for the archetype). Hashing
+    // is only paid when the manifest is in use, so non-archetype projects
+    // keep the original fast path.
+
+    const manifestPath = join(this.#rootDir, MANIFEST_REL_PATH);
+    const manifestEnabled = existsSync(manifestPath);
+    const attribution = manifestEnabled ? gatherAttribution({ cwd: this.#rootDir }) : null;
+
     for (const dir of dirs) {
       const candidates = scanDir(dir, config.maxDepth);
       for (const candidate of candidates) {
@@ -319,6 +365,27 @@ export class InboxWatcher {
           continue;
         }
 
+        // Manifest dedup: a file with identical content under any path is
+        // a duplicate. Catches renames, copies, and re-drops the state
+        // check misses. Skipped here without consuming the ingest budget.
+
+        let candidateSha = null;
+        if (manifestEnabled) {
+          try {
+            const bytes = readFileSync(candidate.path);
+            candidateSha = sha256Of(bytes);
+            if (hasFile(this.#rootDir, candidateSha)) {
+              skipped += 1;
+              state[key] = { mtimeMs: candidate.mtimeMs, processedAt: new Date().toISOString(), dedupHash: candidateSha };
+              continue;
+            }
+          } catch (err) {
+            if (this.#env.CONSTRUCT_DEBUG_INTAKE === '1') {
+              process.stderr.write(`[inbox] sha256 hashing failed for ${candidate.path}: ${err.message}\n`);
+            }
+          }
+        }
+
         try {
           const { category, knowledgeSubdir } = inferFileClassification(candidate.path);
           const result = await ingestDocuments([candidate.path], {
@@ -381,7 +448,23 @@ export class InboxWatcher {
             }
 
             state[key] = { mtimeMs: candidate.mtimeMs, processedAt: new Date().toISOString(), outputPath: fileResult.outputPath };
-            processed.push({ path: candidate.path, outputPath: fileResult.outputPath, docsPath, characters: fileResult.characters, knowledgeSubdir, intakeId });
+
+            if (manifestEnabled && candidateSha) {
+              try {
+                recordFile(this.#rootDir, candidateSha, {
+                  sourcePath: candidate.path,
+                  intakeId,
+                  createdBy: attribution?.createdBy ?? null,
+                  createdByAgent: attribution?.createdByAgent ?? null,
+                });
+              } catch (err) {
+                if (this.#env.CONSTRUCT_DEBUG_INTAKE === '1') {
+                  process.stderr.write(`[inbox] manifest record failed for ${candidate.path}: ${err.message}\n`);
+                }
+              }
+            }
+
+            processed.push({ path: candidate.path, outputPath: fileResult.outputPath, docsPath, characters: fileResult.characters, knowledgeSubdir, intakeId, dedupHash: candidateSha });
           }
         } catch (err) {
           // Audio/video files cannot be text-extracted without ASR. Route to

package/lib/embed/recommendation-store.mjs

@@ -18,11 +18,20 @@
  * Prioritization formula:
  *   score = (signalCount * 2) + (customerImpact * 3) + (recencyBonus) + (strategicBonus)
  *   P0: score >= 10, P1: >= 7, P2: >= 4, P3: < 4
+ *
+ * Enrichment state machine: every new record starts with state: 'raw'. The
+ * enrichment loop (subscriber to recommendation.generated, lifecycle event
+ * emitted from createRecommendation on the new-record path only) transitions
+ * raw → enriching → enriched | enrichment_failed and writes enrichedAt /
+ * enrichedBy / framingNotes back to the index. Dedup-update path does not
+ * re-emit so a steady drip of signals against the same recommendation does
+ * not retrigger enrichment.
  */
 
 import { existsSync, readFileSync, writeFileSync, mkdirSync, appendFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { randomUUID } from 'node:crypto';
+import { emitBestEffort } from '../roles/event-bus.mjs';
 import { cxDir } from '../paths.mjs';
 import { hasSqlStore } from '../storage/sql-store.mjs';
 import { createSqlClient } from '../storage/backend.mjs';
@@ -161,6 +170,9 @@ export function createRecommendation({ type, title, reason, signalCount = 1, cus
     supersededAt: null,
     supersededById: null,
     suppressedUntil: null,
+    state: 'raw',
+    enrichedAt: null,
+    enrichedBy: null,
   };
 
   // Append to log
@@ -171,6 +183,23 @@ export function createRecommendation({ type, title, reason, signalCount = 1, cus
   writeIndex(index);
 
   createRecommendationPgBestEffort(rec, project, env);
+
+  // Surfaces the new recommendation as a lifecycle event so the enrichment
+  // loop (and any project-bound subscribers in .cx/specialists/) can route
+  // the matched specialist's contract chain against it.
+
+  emitBestEffort('recommendation.generated', {
+    project: project || '',
+    summary: `${rec.type}: ${rec.title}`,
+    context: {
+      recommendationId: rec.id,
+      dedupKey: key,
+      priority: rec.priority,
+      score: rec.score,
+      artifactType: rec.type,
+    },
+  });
+
   return { id, dedupKey: key, priority: rec.priority, score, existing: false };
 }
 

package/lib/gates-audit.mjs

@@ -41,18 +41,24 @@ const DEFAULT_ROOT_DIR = join(MODULE_DIR, '..');
 const MERGE_AGGREGATOR = 'ci-required';
 
 const GATE_DEFINITIONS = [
-  { ciJob: 'test (ubuntu-latest / node 22)', prePushLabel: 'tests', critical: true, requireMergeVia: MERGE_AGGREGATOR },
-  { ciJob: 'test (macos-latest / node 22)',  prePushLabel: 'tests', critical: true, requireMergeVia: MERGE_AGGREGATOR },
-  { ciJob: 'test (ubuntu-latest / node 20)', prePushLabel: 'tests', critical: true, requireMergeVia: MERGE_AGGREGATOR },
-  { ciJob: 'test (macos-latest / node 20)',  prePushLabel: 'tests', critical: true, requireMergeVia: MERGE_AGGREGATOR },
-  { ciJob: 'retrieval evals',                prePushLabel: 'evals', critical: true, requireMergeVia: MERGE_AGGREGATOR },
-  { ciJob: 'dependency CVE audit',           prePushLabel: 'audit', critical: true, requireMergeVia: MERGE_AGGREGATOR },
-  { ciJob: 'secret scanning',                prePushLabel: null,  preCommitCheck: 'ECC secret scan',               critical: true, note: 'pre-commit ECC scan covers a subset of gitleaks rules' },
-  { ciJob: 'postgres + pgvector integration', prePushLabel: null, preCommitCheck: null,                            critical: false, note: 'CI-only: requires Docker Postgres + pgvector container; not practical locally', localMirror: 'ci-only', requireMergeVia: MERGE_AGGREGATOR },
-  { ciJob: 'docs drift check',               prePushLabel: 'docs', critical: true, requireMergeVia: MERGE_AGGREGATOR },
-  { ciJob: 'comment policy',                 prePushLabel: null,  preCommitCheck: 'Construct comment-lint', critical: true, note: 'pre-commit Construct policy section calls `lint:comments` across the full worktree', requireMergeVia: MERGE_AGGREGATOR },
-  { ciJob: 'template policy',                prePushLabel: null,  preCommitGhPrIntercept: true,                    critical: true, note: 'pre-push-gate intercepts `gh pr create` / `gh pr edit` and lints the body', requireMergeVia: MERGE_AGGREGATOR },
-  { ciJob: MERGE_AGGREGATOR,                 prePushLabel: null,  preCommitCheck: null,                            critical: true, note: 'aggregator: succeeds iff every wrapped conditional job in ci.yml ended in success or skipped', localMirror: 'ci-only' },
+  // Test, build, audit, evals, docs-drift, comment-policy, prose, profiles —
+  // all CI-only. The local pre-push gate was shrunk to claude/* refusal +
+  // SHA-aware red-CI re-push check + PR body lint; CI is the source of
+  // truth for everything else (see CHANGELOG entry "Pre-push hooks shrunk
+  // to local-only signals; CI is the source of truth" and the inverted
+  // contract enforced by tests/ci-parity.test.mjs).
+  { ciJob: 'test (ubuntu-latest / node 22)', prePushLabel: null, critical: true, requireMergeVia: MERGE_AGGREGATOR, localMirror: 'ci-only' },
+  { ciJob: 'test (macos-latest / node 22)',  prePushLabel: null, critical: true, requireMergeVia: MERGE_AGGREGATOR, localMirror: 'ci-only' },
+  { ciJob: 'test (ubuntu-latest / node 20)', prePushLabel: null, critical: true, requireMergeVia: MERGE_AGGREGATOR, localMirror: 'ci-only' },
+  { ciJob: 'test (macos-latest / node 20)',  prePushLabel: null, critical: true, requireMergeVia: MERGE_AGGREGATOR, localMirror: 'ci-only' },
+  { ciJob: 'retrieval evals',                prePushLabel: null, critical: true, requireMergeVia: MERGE_AGGREGATOR, localMirror: 'ci-only' },
+  { ciJob: 'dependency CVE audit',           prePushLabel: null, critical: true, requireMergeVia: MERGE_AGGREGATOR, localMirror: 'ci-only' },
+  { ciJob: 'secret scanning',                prePushLabel: null, preCommitCheck: 'ECC secret scan', critical: true, note: 'pre-commit ECC scan covers a subset of gitleaks rules' },
+  { ciJob: 'postgres + pgvector integration', prePushLabel: null, preCommitCheck: null, critical: false, note: 'CI-only: requires Docker Postgres + pgvector container; not practical locally', localMirror: 'ci-only', requireMergeVia: MERGE_AGGREGATOR },
+  { ciJob: 'docs drift check',               prePushLabel: null, critical: true, requireMergeVia: MERGE_AGGREGATOR, localMirror: 'ci-only' },
+  { ciJob: 'comment policy',                 prePushLabel: null, preCommitCheck: 'Construct comment-lint', critical: true, note: 'pre-commit Construct policy section calls `lint:comments` across the full worktree', requireMergeVia: MERGE_AGGREGATOR },
+  { ciJob: 'template policy',                prePushLabel: null, preCommitGhPrIntercept: true, critical: true, note: 'pre-push-gate intercepts `gh pr create` / `gh pr edit` and lints the body', requireMergeVia: MERGE_AGGREGATOR },
+  { ciJob: MERGE_AGGREGATOR,                 prePushLabel: null, preCommitCheck: null, critical: true, note: 'aggregator: succeeds iff every wrapped conditional job in ci.yml ended in success or skipped', localMirror: 'ci-only' },
 ];
 
 function parseCIJobs(rootDir) {

package/lib/hooks/_lib/input.mjs

@@ -0,0 +1,52 @@
+/**
+ * lib/hooks/_lib/input.mjs — shared hook input parsing.
+ *
+ * Claude Code passes hook input as JSON on stdin. Codex and OpenCode (when
+ * they ship hook support) pass via TOOL_INPUT_FILE_PATH env or argv. This
+ * helper normalizes all three so a hook reads one shape regardless of the
+ * host transport. Hooks should call `readHookInput()` once at startup and
+ * branch on `input.tool_name` from there.
+ *
+ * Returns an object with at minimum `tool_name` and `tool_input` fields,
+ * plus any fields present in the source payload. Empty object on parse
+ * failure (the hook is then free to exit 0 silently if no useful input
+ * landed — matches the existing convention).
+ */
+
+import { readFileSync } from 'node:fs';
+
+export function readHookInput({ env = process.env, argv = process.argv } = {}) {
+  const stdin = tryReadStdin();
+  if (stdin) {
+    const parsed = tryParseJson(stdin);
+    if (parsed && typeof parsed === 'object') return parsed;
+  }
+
+  const envPath = env.TOOL_INPUT_FILE_PATH;
+  if (envPath) {
+    try {
+      const raw = readFileSync(envPath, 'utf8');
+      const parsed = tryParseJson(raw);
+      if (parsed && typeof parsed === 'object') return parsed;
+      return { tool_input: { file_path: envPath } };
+    } catch { /* fall through */ }
+  }
+
+  const argvJsonPos = argv.findIndex((a) => a === '--input-json');
+  if (argvJsonPos >= 0 && argv[argvJsonPos + 1]) {
+    const parsed = tryParseJson(argv[argvJsonPos + 1]);
+    if (parsed && typeof parsed === 'object') return parsed;
+  }
+
+  return {};
+}
+
+function tryReadStdin() {
+  try { return readFileSync(0, 'utf8'); }
+  catch { return null; }
+}
+
+function tryParseJson(s) {
+  try { return JSON.parse(s); }
+  catch { return null; }
+}

package/lib/hooks/adaptive-lint.mjs

@@ -8,6 +8,10 @@
  *
  * @p95ms 800
  * @maxBlockingScope none (PostToolUse, non-blocking)
+ *
+ * @lifecycle PostToolUse
+ * @matcher  Write|Edit
+ * @exits 0 = pass
  */
 import { execSync } from 'child_process';
 import { existsSync, readFileSync } from 'fs';

package/lib/hooks/agent-tracker.mjs

@@ -1,16 +1,34 @@
 #!/usr/bin/env node
 /**
- * lib/hooks/agent-tracker.mjs — Agent task lifecycle hook — tracks task start, completion, and handoffs.
+ * lib/hooks/agent-tracker.mjs — Task tool lifecycle hook: records dispatch +
+ * outcome and enqueues `next:cx-<role>` handoffs.
  *
- * Runs as PostToolUse after Agent tool calls. Records agent invocations and their outcomes to ~/.cx/agent-log.json for telemetry and performance review.
- * Also records observations for learning system to identify patterns/anti-patterns.
+ * Runs as PostToolUse after Task. Writes the agent-log to the project-scoped
+ * .cx/agent-log.jsonl, captures success/failure observations under
+ * .cx/observations/, and enqueues handoffs into ~/.cx/role-pending.jsonl
+ * (kept user-scope because a handoff may legitimately span projects; each
+ * entry carries a projectId tag for attribution).
+ *
+ * Handoffs also emit a `handoff.received` lifecycle event via the role
+ * event-bus for observability. The direct role-pending write stays the
+ * source of truth until the gateway becomes an event-bus consumer; the
+ * emit is the bridge that makes the dispatch observable through the same
+ * surface as every other lifecycle event.
  *
  * @p95ms 10
  * @maxBlockingScope none (PostToolUse, non-blocking)
+ *
+ * @lifecycle PostToolUse
+ * @matcher  Task
+ * @exits 0 = pass
  */
-import { readFileSync, writeFileSync, mkdirSync, existsSync, appendFileSync } from 'fs';
-import { join } from 'path';
-import { homedir } from 'os';
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { appendBounded } from '../logging/rotate.mjs';
+import { resolveProjectScopedPath } from '../project-root.mjs';
+import { emit as emitRoleEvent } from '../roles/event-bus.mjs';
+import { logHookFailure } from './_lib/log.mjs';
 
 let input = {};
 try { input = JSON.parse(readFileSync(0, 'utf8')); } catch { process.exit(0); }
@@ -67,8 +85,11 @@ try {
   const safeName = agentName.replace(/[^a-z0-9._-]/gi, '_');
   writeFileSync(join(cxDir, `last-agent-${safeName}.json`), JSON.stringify(agentEntry));
   
-  // Append to agent log for telemetry
-  const agentLogFile = join(cxDir, 'agent-log.jsonl');
+  // Per-project agent log (was ~/.cx/agent-log.jsonl which mixed every
+  // project's dispatches into one stream). Falls back to ~/.cx/ when the
+  // hook fires outside a Construct project.
+
+  const agentLogFile = resolveProjectScopedPath('agent-log.jsonl', { ensureDir: false });
   const logEntry = {
     timestamp: new Date().toISOString(),
     agent: agentName,
@@ -79,7 +100,7 @@ try {
     toolInputKeys: Object.keys(toolInput).filter(k => !k.includes('secret') && !k.includes('password') && !k.includes('token'))
   };
   
-  appendFileSync(agentLogFile, JSON.stringify(logEntry) + '\n');
+  appendBounded('agent-log', agentLogFile, JSON.stringify(logEntry) + '\n');
   
   // Record observation for pattern learning (only if we have meaningful outcome)
   if (outcome !== 'unknown' && description.length > 10) {
@@ -150,9 +171,8 @@ try {
     }
   }
   
-} catch (error) {
-  // Non-critical - best effort tracking
-  console.error(`Agent tracker error: ${error.message}`);
+} catch (err) {
+  logHookFailure({ hook: 'agent-tracker', err, phase: 'main' });
 }
 
 // Auto-enqueue handoff when a completing persona's result references
@@ -165,12 +185,18 @@ try {
     const unique = [...new Set(matches)];
     if (unique.length > 0) {
       const { isOnboarded, loadManifest } = await import('../roles/manifest.mjs');
+      // role-pending stays at user scope (a handoff might span projects),
+      // but each entry gets a projectId tag so a reader can attribute it.
+
       const pendingPath = join(homedir(), '.cx', 'role-pending.jsonl');
+      const { resolveProjectScope } = await import('../project-root.mjs');
+      const scope = resolveProjectScope();
       const bdMatch = /\b(construct-[a-z0-9]+)\b/i.exec(resultText) || [];
       const bdIssueId = bdMatch[1] || null;
       for (const targetId of unique) {
         if (!isOnboarded(targetId)) continue;
         const manifest = loadManifest(targetId);
+        const summary = `Handoff from ${agentName}${bdIssueId ? ` (re ${bdIssueId})` : ''}`;
         const entry = {
           ts: Date.now(),
           personaId: targetId,
@@ -178,15 +204,33 @@ try {
           bdIssueId,
           fingerprint: `handoff-${agentName}-${targetId}-${Date.now().toString(36)}`,
           eventType: 'handoff.received',
-          summary: `Handoff from ${agentName}${bdIssueId ? ` (re ${bdIssueId})` : ''}`,
+          summary,
           killSwitchEnv: manifest?.killSwitchEnv || '',
           handoffFrom: agentName,
+          ...(scope?.projectId ? { projectId: scope.projectId } : {}),
         };
-        appendFileSync(pendingPath, JSON.stringify(entry) + '\n');
+        appendBounded('role-pending', pendingPath, JSON.stringify(entry) + '\n');
+
+        // Mirror the handoff to the event bus so the dispatch is observable
+        // alongside every other lifecycle event. Best-effort: a bus failure
+        // does not affect the role-pending source of truth above.
+        try {
+          emitRoleEvent('handoff.received', {
+            project: scope?.projectId || '',
+            summary,
+            context: {
+              targetCxId: `cx-${targetId}`,
+              handoffFrom: agentName,
+              bdIssueId,
+            },
+          });
+        } catch { /* swallow */ }
       }
     }
   }
-} catch { /* best effort — handoff enqueue never blocks */ }
+} catch (err) {
+  logHookFailure({ hook: 'agent-tracker', err, phase: 'handoff' });
+}
 
 // Helper functions for learning system
 function extractKeywords(text) {

package/lib/hooks/audit-reads.mjs

@@ -1,41 +1,56 @@
 #!/usr/bin/env node
 /**
- * lib/hooks/audit-reads.mjs — opt-in tamper-evident log of every Read tool call.
+ * lib/hooks/audit-reads.mjs — post-Read state tracker.
  *
- * Symmetric counterpart to audit-trail.mjs (which records mutations). Reads
- * are off by default because they happen much more often than writes; enable
- * with `CONSTRUCT_AUDIT_READS=1`. When enabled, every Read tool call writes
- * a single JSONL line to ~/.cx/audit-reads.jsonl with:
+ * Two responsibilities on every Read tool call:
  *
- *   - timestamp ISO
- *   - session_id (when supplied by the harness)
- *   - tool_name (always Read)
- *   - agent (from ~/.cx/last-agent.json — falls back to "construct")
- *   - cwd
- *   - target (the file_path read)
- *   - bytes (size of the file at read time)
- *   - content_hash (sha256 of the file's first 64KiB at read time, truncated)
- *   - prev_line_hash (chained tamper-evidence — hash of previous JSONL line)
+ *   1. ALWAYS — upsert a file-hash entry in ~/.cx/file-hashes.json keyed by
+ *      absolute path, with the current sha256 + size + iso timestamp.
+ *      Edit-guard reads the store to detect staleness on a subsequent Edit:
+ *      mismatched on-disk content versus the stored hash means the Edit
+ *      target needs a fresh Read. A read-tracker delta is recorded for the
+ *      efficiency snapshot in the same pass.
  *
- * The prev_line_hash chain means any after-the-fact reordering or deletion
- * breaks the chain and is detectable by a simple replay (same approach as
- * the mutation audit).
+ *   2. OPT-IN — when `CONSTRUCT_AUDIT_READS=1`, write a single JSONL line
+ *      to <project>/.cx/audit-reads.jsonl (falls back to ~/.cx/ outside a
+ *      project) with timestamp, session_id, agent, cwd, target, bytes,
+ *      content_hash, and prev_line_hash. The prev_line_hash chain makes
+ *      after-the-fact reordering or deletion detectable by simple replay
+ *      (symmetric counterpart to audit-trail.mjs for mutations). Bounded
+ *      via the `audit-reads` channel.
+ *
+ * Reads happen far more often than writes, so the audit log is opt-in.
+ * The hash store is always-on because edit-guard depends on it for
+ * correctness, not telemetry.
  *
  * @p95ms 8
  * @maxBlockingScope none (PostToolUse, non-blocking)
+ *
+ * @lifecycle PostToolUse
+ * @matcher  Read
+ * @exits 0 = pass
  */
-import { readFileSync, appendFileSync, existsSync, mkdirSync, statSync } from 'node:fs';
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
 import { createHash } from 'node:crypto';
-import { join, resolve } from 'node:path';
+import { join, resolve, dirname } from 'node:path';
 import { homedir } from 'node:os';
 import { logHookFailure } from './_lib/log.mjs';
+import { appendBounded, readLastLineAcrossSegments } from '../logging/rotate.mjs';
+import { resolveProjectScopedPath } from '../project-root.mjs';
+import { flushReadTrackerDeltas, recordReadDelta } from '../read-tracker-store.mjs';
 
 const CX_DIR = join(homedir(), '.cx');
-const AUDIT_FILE = join(CX_DIR, 'audit-reads.jsonl');
+// audit-reads.jsonl is PROJECT-SCOPED — reads happen in a specific project,
+// not across the user's whole machine. resolveProjectScopedPath returns
+// <project>/.cx/audit-reads.jsonl when the hook fires from inside a
+// Construct project, falling back to the legacy ~/.cx path otherwise so
+// existing standalone invocations keep working.
+
+const AUDIT_FILE = resolveProjectScopedPath('audit-reads.jsonl', { ensureDir: false });
+const HASH_STORE = join(CX_DIR, 'file-hashes.json');
 const LAST_AGENT = join(CX_DIR, 'last-agent.json');
 const HASH_PREFIX_BYTES = 64 * 1024;
-
-if (process.env.CONSTRUCT_AUDIT_READS !== '1') process.exit(0);
+const HASH_RETENTION_MS = 2 * 60 * 60 * 1000;
 
 function sha256(input) { return createHash('sha256').update(input).digest('hex'); }
 
@@ -48,14 +63,9 @@ function readLastAgent() {
 
 function readPrevLineHash() {
   try {
-    if (!existsSync(AUDIT_FILE)) return null;
-    const size = statSync(AUDIT_FILE).size;
-    if (size === 0) return null;
-    const readFrom = Math.max(0, size - 2048);
-    const tail = readFileSync(AUDIT_FILE, 'utf8').slice(readFrom);
-    const lines = tail.split('\n').filter(Boolean);
-    if (lines.length === 0) return null;
-    return sha256(lines[lines.length - 1]);
+    const lastLine = readLastLineAcrossSegments(AUDIT_FILE);
+    if (lastLine === null) return null;
+    return sha256(lastLine);
   } catch { return null; }
 }
 
@@ -71,22 +81,53 @@ if (!filePath) process.exit(0);
 
 const absPath = filePath.startsWith('/') ? filePath : resolve(cwd, filePath);
 
+// Stage 1 — always-on hash store update for edit-guard staleness detection.
+
+let fullContent = null;
 let bytes = null;
-let contentHash = null;
+let prefixHash = null;
 try {
   if (existsSync(absPath)) {
-    bytes = statSync(absPath).size;
-    const buf = Buffer.alloc(Math.min(bytes, HASH_PREFIX_BYTES));
-    const fd = await import('node:fs').then((m) => m.openSync(absPath, 'r'));
-    const fsModule = await import('node:fs');
-    fsModule.readSync(fd, buf, 0, buf.length, 0);
-    fsModule.closeSync(fd);
-    contentHash = sha256(buf).slice(0, 32);
+    fullContent = readFileSync(absPath, 'utf8');
+    bytes = Buffer.byteLength(fullContent, 'utf8');
+    const prefix = Buffer.from(fullContent, 'utf8').slice(0, HASH_PREFIX_BYTES);
+    prefixHash = sha256(prefix).slice(0, 32);
+
+    const edgeHash = createHash('sha256').update(fullContent).digest('hex').slice(0, 16);
+    const nowIso = new Date().toISOString();
+    const requestedLimit = Number(input?.tool_input?.limit || 0);
+    const effectiveLimit = requestedLimit > 0 ? requestedLimit : 2000;
+
+    mkdirSync(CX_DIR, { recursive: true });
+    let store = {};
+    try { store = JSON.parse(readFileSync(HASH_STORE, 'utf8')); } catch { /* fresh store */ }
+    store[absPath] = { hash: edgeHash, ts: nowIso, size: fullContent.length };
+
+    const cutoff = Date.now() - HASH_RETENTION_MS;
+    for (const [k, v] of Object.entries(store)) {
+      if (new Date(v.ts).getTime() < cutoff) delete store[k];
+    }
+    writeFileSync(HASH_STORE, JSON.stringify(store, null, 2));
+
+    recordReadDelta({
+      path: absPath,
+      size: fullContent.length,
+      limit: effectiveLimit,
+      ts: nowIso,
+    }, process.env);
+
+    if (process.env.CONSTRUCT_READ_TRACKER_FLUSH === '1') {
+      flushReadTrackerDeltas({ nowIso, env: process.env });
+    }
   }
 } catch (err) {
-  logHookFailure({ hook: 'audit-reads', err, phase: 'hash', input: { filePath: absPath } });
+  logHookFailure({ hook: 'audit-reads', err, phase: 'hash-store', input: { filePath: absPath } });
 }
 
+// Stage 2 — opt-in tamper-evident audit log.
+
+if (process.env.CONSTRUCT_AUDIT_READS !== '1') process.exit(0);
+
 const record = {
   ts: new Date().toISOString(),
   session_id: input?.session_id || null,
@@ -95,13 +136,13 @@ const record = {
   cwd,
   target: filePath,
   bytes,
-  content_hash: contentHash,
+  content_hash: prefixHash,
   prev_line_hash: readPrevLineHash(),
 };
 
 try {
-  mkdirSync(CX_DIR, { recursive: true });
-  appendFileSync(AUDIT_FILE, JSON.stringify(record) + '\n', 'utf8');
+  mkdirSync(dirname(AUDIT_FILE), { recursive: true });
+  appendBounded('audit-reads', AUDIT_FILE, JSON.stringify(record) + '\n');
 } catch (err) {
   logHookFailure({ hook: 'audit-reads', err, phase: 'append' });
 }