@geraldmaron/construct 1.0.12 → 1.0.14

package/lib/hooks/audit-trail.mjs

@@ -7,7 +7,9 @@
  * For Bash, only records commands that mutate state (git/npm/docker/cargo etc.
  * write operations, rm, mv, chmod). Read-only commands are skipped.
  *
- * Each record is a single JSONL line written to ~/.cx/audit-trail.jsonl with:
+ * Each record is a single JSONL line written to
+ * <project>/.cx/audit-trail.jsonl (falls back to ~/.cx/audit-trail.jsonl
+ * when the hook fires outside a Construct project) with:
  *   - timestamp ISO
  *   - session_id (from hook input when available)
  *   - tool_name
@@ -21,18 +23,26 @@
  *   - prev_line_hash (chained tamper-evidence — hash of previous JSONL line)
  *
  * The prev_line_hash chain means any after-the-fact reordering or deletion
- * breaks the chain and is detectable by a simple replay.
+ * breaks the chain and is detectable by a simple replay. Bounded via the
+ * `audit-trail` channel registered in lib/logging/rotate.mjs LIMITS.
  *
  * @p95ms 15
  * @maxBlockingScope none (PostToolUse, non-blocking)
+ *
+ * @lifecycle PostToolUse
+ * @matcher  Edit|Write|MultiEdit|NotebookEdit|Bash
+ * @exits 0 = pass
  */
-import { readFileSync, writeFileSync, appendFileSync, existsSync, mkdirSync, statSync } from 'node:fs';
+import { readFileSync, 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 { appendBounded, readLastLineAcrossSegments } from '../logging/rotate.mjs';
+import { resolveProjectScopedPath } from '../project-root.mjs';
+import { logHookFailure } from './_lib/log.mjs';
 
 const CX_DIR = join(homedir(), '.cx');
-const AUDIT_FILE = join(CX_DIR, 'audit-trail.jsonl');
+const AUDIT_FILE = resolveProjectScopedPath('audit-trail.jsonl', { ensureDir: false });
 const LAST_AGENT = join(CX_DIR, 'last-agent.json');
 const MUTATING_TOOLS = new Set(['Edit', 'Write', 'MultiEdit', 'NotebookEdit', 'Bash']);
 
@@ -69,14 +79,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 fs = readFileSync(AUDIT_FILE, 'utf8').slice(readFrom);
-    const lines = fs.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;
   }
@@ -89,7 +94,8 @@ function truncateSnippet(s, limit = 280) {
 }
 
 let input = {};
-try { input = JSON.parse(readFileSync(0, 'utf8')); } catch { process.exit(0); }
+try { input = JSON.parse(readFileSync(0, 'utf8')); }
+catch (err) { logHookFailure({ hook: 'audit-trail', err, phase: 'parse' }); process.exit(0); }
 
 const toolName = input?.tool_name || '';
 if (!MUTATING_TOOLS.has(toolName)) process.exit(0);
@@ -129,7 +135,9 @@ if (toolName !== 'Bash' && target) {
     if (existsSync(absPath)) {
       contentHash = sha256(readFileSync(absPath, 'utf8')).slice(0, 32);
     }
-  } catch { /* best effort */ }
+  } catch (err) {
+    logHookFailure({ hook: 'audit-trail', err, phase: 'hash', input: { target: absPath } });
+  }
 }
 
 const record = {
@@ -146,8 +154,10 @@ const record = {
 };
 
 try {
-  mkdirSync(CX_DIR, { recursive: true });
-  appendFileSync(AUDIT_FILE, JSON.stringify(record) + '\n', 'utf8');
-} catch { /* best effort — audit failure must not block the user's work */ }
+  mkdirSync(dirname(AUDIT_FILE), { recursive: true });
+  appendBounded('audit-trail', AUDIT_FILE, JSON.stringify(record) + '\n');
+} catch (err) {
+  logHookFailure({ hook: 'audit-trail', err, phase: 'append' });
+}
 
 process.exit(0);

package/lib/hooks/bash-output-logger.mjs

@@ -14,10 +14,15 @@
  *
  * @p95ms 20
  * @maxBlockingScope none (PostToolUse, non-blocking)
+ *
+ * @lifecycle PostToolUse
+ * @matcher  Bash
+ * @exits 0 = pass
  */
-import { readFileSync, writeFileSync, mkdirSync, appendFileSync } from 'node:fs';
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { homedir } from 'node:os';
+import { appendBounded } from '../logging/rotate.mjs';
 
 const SIZE_THRESHOLD_CHARS = 4000;
 const LOG_DIR = join(homedir(), '.cx', 'bash-logs');
@@ -61,7 +66,8 @@ try {
   );
 
   try {
-    appendFileSync(
+    appendBounded(
+      'bash-warn-flags',
       WARN_FLAGS,
       `Bash output ${kb} KB saved to ${logPath} — prefer grepping the log over re-running.\n`,
     );

package/lib/hooks/block-no-verify.mjs

@@ -12,6 +12,10 @@
  *
  * @p95ms 5
  * @maxBlockingScope PreToolUse
+ *
+ * @lifecycle PreToolUse
+ * @matcher  Bash
+ * @exits 0 = pass | 2 = block tool call
  */
 import { readFileSync } from 'node:fs';
 

package/lib/hooks/ci-status-check.mjs

@@ -14,6 +14,10 @@
  *
  * @p95ms 4000
  * @maxBlockingScope none (UserPromptSubmit, non-blocking)
+ *
+ * @lifecycle UserPromptSubmit
+ * @matcher  *
+ * @exits 0 = pass
  */
 
 import { readFileSync, writeFileSync, existsSync, mkdirSync, statSync } from 'node:fs';

package/lib/hooks/comment-lint.mjs

@@ -7,13 +7,17 @@
  * narrative voice, point-in-time notes, noise sentinels. The agent sees the
  * block reason and is expected to fix the comment before continuing.
  *
- * Bypass: set CONSTRUCT_SKIP_COMMENT_LINT=1 in the environment.
+ * No bypass. If the policy fires on a legitimate comment, the policy is wrong
+ * — fix the policy in lib/comment-lint.mjs, not the call site.
  *
  * Input: reads tool_input.file_path from either the legacy TOOL_INPUT_FILE_PATH
  * env var or modern stdin JSON ({ tool_input: { file_path } }).
  *
+ * @lifecycle PostToolUse
+ * @matcher  Write|Edit|MultiEdit
  * @p95ms 60
  * @maxBlockingScope PostToolUse
+ * @exits 0 = pass | 2 = block tool call
  */
 
 import { readFileSync } from 'node:fs';
@@ -21,8 +25,6 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { lintFile, formatResults } from '../comment-lint.mjs';
 
-if (process.env.CONSTRUCT_SKIP_COMMENT_LINT === '1') process.exit(0);
-
 let filePath = process.env.TOOL_INPUT_FILE_PATH;
 if (!filePath) {
   try {
@@ -59,6 +61,6 @@ if (artifactOnly) {
 }
 
 process.stderr.write(
-  '\nComment policy blocked this edit. Remove the violations or set CONSTRUCT_SKIP_COMMENT_LINT=1.\n',
+  '\nComment policy blocked this edit. Remove the violations before continuing.\n',
 );
 process.exit(2);

package/lib/hooks/config-protection.mjs

@@ -16,6 +16,10 @@
  *
  * @p95ms 5
  * @maxBlockingScope PreToolUse
+ *
+ * @lifecycle PreToolUse
+ * @matcher  Write|Edit|MultiEdit
+ * @exits 0 = pass | 2 = block tool call
  */
 import { readFileSync } from 'fs';
 import { logHookFailure } from './_lib/log.mjs';

package/lib/hooks/context-watch.mjs

@@ -26,6 +26,10 @@
  *
  * @p95ms 20
  * @maxBlockingScope UserPromptSubmit
+ *
+ * @lifecycle UserPromptSubmit
+ * @matcher  *
+ * @exits 0 = pass
  */
 import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
 import { join } from 'node:path';

package/lib/hooks/context-window-recovery.mjs

@@ -6,6 +6,10 @@
  *
  * @p95ms 10
  * @maxBlockingScope none (PostToolUse, non-blocking)
+ *
+ * @lifecycle PostToolUseFailure
+ * @matcher  *
+ * @exits 0 = pass
  */
 import { readFileSync, writeFileSync, mkdirSync } from 'fs';
 import { homedir } from 'os';

package/lib/hooks/dep-audit.mjs

@@ -8,11 +8,17 @@
  *
  * @p95ms 5000
  * @maxBlockingScope none (PostToolUse, async, non-blocking)
+ *
+ * @lifecycle PostToolUse
+ * @matcher  Write|Edit
+ * @exits 0 = pass
  */
-import { readFileSync, writeFileSync, existsSync, appendFileSync } from 'fs';
-import { execSync } from 'child_process';
-import { homedir } from 'os';
-import { join, dirname, basename } from 'path';
+import { readFileSync, existsSync } from 'node:fs';
+import { execSync } from 'node:child_process';
+import { homedir } from 'node:os';
+import { join, dirname, basename } from 'node:path';
+import { appendBounded } from '../logging/rotate.mjs';
+import { logHookFailure } from './_lib/log.mjs';
 
 const filePath = process.env.TOOL_INPUT_FILE_PATH || '';
 if (!filePath) process.exit(0);
@@ -28,7 +34,8 @@ const projectDir = dirname(filePath);
 const warnFlagsPath = join(homedir(), '.cx', 'warn-flags.txt');
 
 function appendWarn(msg) {
-  try { appendFileSync(warnFlagsPath, msg + '\n'); } catch { /* best effort */ }
+  try { appendBounded('bash-warn-flags', warnFlagsPath, msg + '\n'); }
+  catch (err) { logHookFailure({ hook: 'dep-audit', err, phase: 'append' }); }
   process.stderr.write(`[dep-audit] ${msg}\n`);
   emitVulnerability(msg);
 }

package/lib/hooks/doc-coupling-check.mjs

@@ -12,6 +12,10 @@
  *
  * @p95ms 15
  * @maxBlockingScope none (PostToolUse, non-blocking)
+ *
+ * @lifecycle PostToolUse
+ * @matcher  Write|Edit|MultiEdit
+ * @exits 0 = pass
  */
 
 import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
@@ -73,7 +77,7 @@ writeState(state);
 
 if (advisory != null) {
   process.stderr.write(
-    `[doc-coupling] ${state.codeEdits} code file edit(s) this session under lib/|bin/|src/|app/; CHANGELOG.md / docs / .cx/context still not touched. Update docs before the next commit (the pre-commit gate will block otherwise; bypass: CONSTRUCT_SKIP_DOCS=1).\n`,
+    `[doc-coupling] ${state.codeEdits} code file edit(s) this session under lib/|bin/|src/|app/; CHANGELOG.md / docs / .cx/context still not touched. Update docs before the next commit (the pre-commit gate will block otherwise).\n`,
   );
 }
 

package/lib/hooks/edit-accumulator.mjs

@@ -1,39 +1,54 @@
 #!/usr/bin/env node
 /**
- * lib/hooks/edit-accumulator.mjs — Edit accumulator hook — batches and summarizes recent file edits for context.
+ * lib/hooks/edit-accumulator.mjs — accumulates edited paths for the next
+ * typecheck batch.
  *
- * Runs as PostToolUse after Edit/Write. Maintains a rolling log of recent edits in ~/.cx/edit-log.json for use by other hooks and efficiency reporting.
+ * Runs as PostToolUse after Edit/Write. Maintains two pieces of session
+ * state at ~/.cx/: a total edit counter for surface-area summaries and a
+ * deduped queue of TS/JS files awaiting typecheck. The typecheck queue is
+ * bounded via the `edit-accumulator` channel in lib/logging/rotate.mjs.
  *
  * @p95ms 10
  * @maxBlockingScope none (PostToolUse, non-blocking)
+ *
+ * @lifecycle PostToolUse
+ * @matcher  Write|Edit|MultiEdit
+ * @exits 0 = pass
  */
-import { appendFileSync, readFileSync, writeFileSync, existsSync } from 'fs';
-import { homedir } from 'os';
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import path from 'node:path';
+import { appendBounded } from '../logging/rotate.mjs';
+import { logHookFailure } from './_lib/log.mjs';
 
 const TS_EXTS = new Set(['.ts','.tsx','.js','.mjs','.jsx','.cjs']);
 const filePath = process.env.TOOL_INPUT_FILE_PATH || '';
 
 if (!filePath) process.exit(0);
 
-const ext = '.' + filePath.split('.').pop();
+const ext = path.extname(filePath);
 const home = homedir();
-const countPath = `${home}/.cx/files-changed-count.txt`;
+const countPath = path.join(home, '.cx', 'files-changed-count.txt');
 
 // Always increment the total files-changed counter for notify
 try {
   const current = existsSync(countPath) ? parseInt(readFileSync(countPath, 'utf8').trim() || '0', 10) : 0;
   writeFileSync(countPath, String(current + 1));
-} catch { /* best effort */ }
+} catch (err) {
+  logHookFailure({ hook: 'edit-accumulator', err, phase: 'count' });
+}
 
 // Only accumulate TS/JS files for typecheck
 if (!TS_EXTS.has(ext)) process.exit(0);
 
-const tcPath = `${home}/.cx/pending-typecheck.txt`;
+const tcPath = path.join(home, '.cx', 'pending-typecheck.txt');
 try {
   const existing = existsSync(tcPath) ? readFileSync(tcPath, 'utf8').split('\n').filter(Boolean) : [];
   if (!existing.includes(filePath)) {
-    appendFileSync(tcPath, filePath + '\n');
+    appendBounded('edit-accumulator', tcPath, filePath + '\n');
   }
-} catch { /* best effort */ }
+} catch (err) {
+  logHookFailure({ hook: 'edit-accumulator', err, phase: 'append' });
+}
 
 process.exit(0);

package/lib/hooks/edit-error-recovery.mjs

@@ -6,6 +6,10 @@
  *
  * @p95ms 10
  * @maxBlockingScope none (PostToolUse, non-blocking)
+ *
+ * @lifecycle PostToolUseFailure
+ * @matcher  *
+ * @exits 0 = pass
  */
 import { readFileSync } from 'fs';
 

package/lib/hooks/edit-guard.mjs

@@ -6,6 +6,10 @@
  *
  * @p95ms 20
  * @maxBlockingScope PreToolUse
+ *
+ * @lifecycle PreToolUse
+ * @matcher  Edit|MultiEdit|Write
+ * @exits 0 = pass | 2 = block tool call
  */
 import { readFileSync, existsSync } from 'fs';
 import { createHash } from 'crypto';

package/lib/hooks/guard-bash.mjs

@@ -6,6 +6,10 @@
  *
  * @p95ms 5
  * @maxBlockingScope PreToolUse
+ *
+ * @lifecycle PreToolUse
+ * @matcher  Bash
+ * @exits 0 = pass | 2 = block tool call
  */
 import { createInterface } from 'readline';
 import { readFileSync, existsSync } from 'fs';

package/lib/hooks/mcp-audit.mjs

@@ -7,6 +7,10 @@
  *
  * @p95ms 10
  * @maxBlockingScope none (PostToolUse, non-blocking)
+ *
+ * @lifecycle PostToolUse
+ * @matcher  mcp__.*
+ * @exits 0 = pass
  */
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
 import { join } from 'path';

package/lib/hooks/mcp-health-check.mjs

@@ -6,6 +6,10 @@
  *
  * @p95ms 51
  * @maxBlockingScope none (PreToolUse, warn-only)
+ *
+ * @lifecycle PreToolUse
+ * @matcher  mcp__.*
+ * @exits 0 = pass | 2 = block tool call
  */
 import { readFileSync, writeFileSync, existsSync } from 'fs';
 import { homedir } from 'os';

package/lib/hooks/model-fallback.mjs

@@ -15,8 +15,12 @@
  *
  * @p95ms 150
  * @maxBlockingScope none (PostToolUse, non-blocking)
+ *
+ * @lifecycle PostToolUseFailure
+ * @matcher  *
+ * @exits 0 = pass
  */
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import { execFileSync } from 'node:child_process';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
@@ -27,20 +31,12 @@ import {
   selectFallbackModel,
   writeProviderCooldown,
 } from '../model-router.mjs';
+import { readHookInput } from './_lib/input.mjs';
 
 const cooldownPath = join(homedir(), '.cx', 'provider-cooldowns.json');
 const envPath = join(process.cwd(), '.env');
 
-function readInput() {
-  try {
-    const raw = readFileSync(0, 'utf8');
-    return raw ? JSON.parse(raw) : {};
-  } catch {
-    return {};
-  }
-}
-
-const input = readInput();
+const input = readHookInput();
 
 const classified = classifyProviderFailure(input);
 if (!classified || !classified.retryable) process.exit(0);

package/lib/hooks/policy-engine.mjs

@@ -15,6 +15,10 @@
  *
  * @p95ms 80
  * @maxBlockingScope PreToolUse, Stop, UserPromptSubmit
+ *
+ * @lifecycle PreToolUse
+ * @matcher  Write|Edit|MultiEdit|NotebookEdit|TodoWrite|Read|Grep|Glob|LS|NotebookRead
+ * @exits 0 = pass | 2 = block tool call
  */
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
 import { execSync } from 'node:child_process';

package/lib/hooks/post-merge-docs-check.mjs

@@ -10,6 +10,10 @@
  *
  * @p95ms 1500
  * @maxBlockingScope none (async, non-blocking)
+ *
+ * @lifecycle PostToolUse
+ * @matcher  Bash
+ * @exits 0 = pass
  */
 
 import { readFileSync } from 'node:fs';

package/lib/hooks/post-merge-tracking.mjs

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+/**
+ * lib/hooks/post-merge-tracking.mjs — close beads referenced by a merged PR.
+ *
+ * Runs as a PostToolUse hook on Bash. Watches for `gh pr merge <N>` (or
+ * `gh pr merge --auto`) invocations that exited successfully; parses the
+ * PR body via `gh pr view <N> --json body`; extracts every `Refs:` /
+ * `Closes:` / `Fixes:` line that names a `construct-XXX` bead; closes each
+ * still-open bead with reason `Merged via PR #N (<sha>)`. Idempotent on
+ * beads already closed.
+ *
+ * The PR-body parse is the source of truth — not the merge commit subject
+ * — because the bundle PR pattern stores the bead refs in the body's
+ * "Beads issue" section and the squash-merge subject often drops them.
+ *
+ * Best-effort. Exits 0 on any parse or shell failure so the surrounding
+ * tool call is never affected. Stderr lines are advisory; the actual
+ * outcome is the `bd close` state, which is what the next Stop hook's
+ * tracking refresh will read.
+ *
+ * @lifecycle PostToolUse
+ * @matcher  Bash
+ * @p95ms 3000
+ * @maxBlockingScope none (PostToolUse, non-blocking)
+ * @exits 0 = pass
+ */
+
+import { spawnSync } from 'node:child_process';
+import { readHookInput } from './_lib/input.mjs';
+import { logHookFailure } from './_lib/log.mjs';
+
+const input = readHookInput();
+const command = input?.tool_input?.command || input?.command || '';
+const exitCode = input?.tool_response?.exit_code ?? input?.tool_response?.exitCode;
+
+const ghPrMergeMatch = /\bgh\s+pr\s+merge\b(?:\s+(\d+))?/.exec(command);
+if (!ghPrMergeMatch) process.exit(0);
+if (exitCode !== undefined && exitCode !== 0) process.exit(0);
+
+const cwd = input?.cwd || process.cwd();
+const prNumber = await resolvePrNumber(ghPrMergeMatch[1], cwd);
+if (!prNumber) process.exit(0);
+
+try {
+  const { closeBeadsFromPrRefs } = await import('../tracking-surfaces.mjs');
+  const mergeCommitSha = readMergeCommitSha(cwd);
+  const result = await closeBeadsFromPrRefs({ prNumber, mergeCommitSha, cwd });
+  if (result?.closed?.length > 0) {
+    process.stderr.write(`[post-merge-tracking] closed beads: ${result.closed.join(', ')}\n`);
+  }
+  if (result?.errors?.length > 0) {
+    process.stderr.write(`[post-merge-tracking] failed to close: ${result.errors.map((e) => e.id).join(', ')}\n`);
+  }
+} catch (err) {
+  logHookFailure({ hook: 'post-merge-tracking', err, phase: 'close' });
+}
+
+process.exit(0);
+
+async function resolvePrNumber(captured, cwd) {
+  if (captured) return captured;
+  // Bare `gh pr merge --auto` / `gh pr merge -s` invocations omit the PR
+  // number. Resolve via the most recent merge commit subject, which `gh`
+  // standardly tails with `(#N)`.
+  try {
+    const lastLog = spawnSync('git', ['log', '-1', '--pretty=format:%s'], { cwd, encoding: 'utf8', timeout: 2000 });
+    if (lastLog.status !== 0) return null;
+    const m = /#(\d+)/.exec(lastLog.stdout);
+    return m ? m[1] : null;
+  } catch {
+    return null;
+  }
+}
+
+function readMergeCommitSha(cwd) {
+  try {
+    const result = spawnSync('git', ['rev-parse', 'HEAD'], { cwd, encoding: 'utf8', timeout: 2000 });
+    return result.status === 0 ? result.stdout.trim() : '';
+  } catch {
+    return '';
+  }
+}

package/lib/hooks/pre-compact.mjs

@@ -11,6 +11,10 @@
  *
  * @p95ms 100
  * @maxBlockingScope PreCompact
+ *
+ * @lifecycle PreCompact
+ * @matcher  *
+ * @exits 0 = pass
  */
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
 import { homedir } from 'os';