@lh8ppl/claude-memory-kit 0.1.0

package/src/merge-facts.mjs

@@ -0,0 +1,213 @@
+// Fact consolidation (Task 10, refactored in cleanup-layer-2-cross-module-drift).
+// Single public boundary: mergeFacts(opts) → result. See design §3.4.
+//
+// Uses shared modules: tier-paths, frontmatter, audit-log, result-shapes.
+// Composes writeFact() to create the new merged fact, then moves A + B into
+// archive/superseded/ with superseded_by injected. See CLAUDE.md "Shared
+// modules" rule.
+
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from 'node:fs';
+import { join } from 'node:path';
+import {
+  VALID_TIERS,
+  ID_PATTERN,
+  resolveTierRoot,
+  resolveFactDir,
+} from './tier-paths.mjs';
+import { parse, format } from './frontmatter.mjs';
+import { appendAuditEntry, nowIso, REASON_CODES } from './audit-log.mjs';
+import { ERROR_CATEGORIES, errorResult, notFoundResult } from './result-shapes.mjs';
+import { writeFact } from './write-fact.mjs';
+
+function listLiveFactFiles(factDir) {
+  if (!existsSync(factDir)) return [];
+  const out = [];
+  for (const entry of readdirSync(factDir, { withFileTypes: true })) {
+    if (!entry.isFile()) continue;
+    if (!entry.name.endsWith('.md')) continue;
+    if (entry.name === 'INDEX.md') continue;
+    out.push(entry.name);
+  }
+  return out;
+}
+
+function findLiveFactById(factDir, id) {
+  if (!existsSync(factDir)) return null;
+  for (const filename of listLiveFactFiles(factDir)) {
+    const p = join(factDir, filename);
+    if (!statSync(p).isFile()) continue;
+    const { frontmatter, body } = parse(readFileSync(p, 'utf8'));
+    if (frontmatter?.id === id && !frontmatter.deleted_at) {
+      return { id, path: p, frontmatter, body };
+    }
+  }
+  return null;
+}
+
+function moveToSuperseded(match, supersededBy) {
+  const supersededDir = join(match.factDir, 'archive', 'superseded');
+  mkdirSync(supersededDir, { recursive: true });
+  const newPath = join(supersededDir, `${match.id}.md`);
+  const { frontmatter, body } = parse(readFileSync(match.path, 'utf8'));
+  const updated = {
+    superseded_by: supersededBy,
+    ...(frontmatter ?? {}),
+  };
+  writeFileSync(newPath, format({ frontmatter: updated, body }), 'utf8');
+  unlinkSync(match.path);
+  return newPath;
+}
+
+export function mergeFacts(opts = {}) {
+  const {
+    idA,
+    idB,
+    mergedBody,
+    mergedTitle,
+    mergedSlug,
+    mergedType,
+    writeSource,
+    trust,
+    sourceFile,
+    sourceLine,
+    sourceSha1,
+    mergedTags,
+    projectRoot,
+    userDir,
+    now,
+  } = opts;
+
+  const errors = [];
+  if (!idA || !ID_PATTERN.test(idA)) errors.push('idA: must be a valid citation ID');
+  if (!idB || !ID_PATTERN.test(idB)) errors.push('idB: must be a valid citation ID');
+  if (idA && idB && idA === idB) {
+    return errorResult({
+      category: ERROR_CATEGORIES.SCHEMA,
+      errors: [`idA and idB are the same (${idA}); cannot merge a fact with itself`],
+    });
+  }
+  if (!mergedBody || typeof mergedBody !== 'string' || !mergedBody.length) {
+    errors.push('mergedBody: required, non-empty string');
+  }
+  if (!mergedTitle || typeof mergedTitle !== 'string') {
+    errors.push('mergedTitle: required, non-empty string');
+  }
+  // Layer-2 review S4: removed the redundant `mergedSlug` truthy check. The
+  // downstream writeFact owns all slug validation (pattern + presence).
+  // Inconsistent layering disappears; bad slugs surface from writeFact with
+  // a clear schema error.
+  //
+  // Layer-2 review S3: writeSource is now REQUIRED (no compressor default).
+  // Compressor was the most-suspicious default — Task 23 auto-extract and
+  // Task 24 memory-write are NOT compressor-driven. Forcing the caller to
+  // pick avoids accidentally tagging human-curated merges as 'compressor'.
+  if (!writeSource || typeof writeSource !== 'string') {
+    errors.push('writeSource: required (no default). Pick one of user-explicit/auto-extract/compressor/manual-edit/imported.');
+  }
+  if (errors.length > 0) {
+    return errorResult({ category: ERROR_CATEGORIES.SCHEMA, errors });
+  }
+
+  const tierA = idA[0];
+  const tierB = idB[0];
+  if (tierA !== tierB) {
+    return errorResult({
+      category: ERROR_CATEGORIES.SCHEMA,
+      errors: [
+        `cross-tier merge not supported: idA tier (${tierA}) ≠ idB tier (${tierB}). Promote one side to the same tier first.`,
+      ],
+    });
+  }
+  const tier = tierA;
+  if (!VALID_TIERS.has(tier)) {
+    return errorResult({
+      category: ERROR_CATEGORIES.SCHEMA,
+      errors: [`invalid tier prefix on ids: ${tier}`],
+    });
+  }
+
+  const tierRoot = resolveTierRoot({ tier, projectRoot, userDir });
+  const factDir = resolveFactDir(tier, tierRoot);
+
+  const matchA = findLiveFactById(factDir, idA);
+  const matchB = findLiveFactById(factDir, idB);
+  if (!matchA || !matchB) {
+    const missing = [];
+    if (!matchA) missing.push(idA);
+    if (!matchB) missing.push(idB);
+    return notFoundResult({
+      errors: [`no live fact found for ${missing.join(', ')}`],
+    });
+  }
+  matchA.factDir = factDir;
+  matchB.factDir = factDir;
+
+  const typeC =
+    mergedType ?? matchA.frontmatter.type ?? matchB.frontmatter.type;
+
+  const writeResult = writeFact({
+    tier,
+    type: typeC,
+    slug: mergedSlug,
+    title: mergedTitle,
+    body: mergedBody,
+    writeSource,
+    trust: trust ?? 'high',
+    sourceFile: sourceFile ?? matchA.frontmatter.source_file ?? 'merge',
+    sourceLine: sourceLine ?? 1,
+    sourceSha1: sourceSha1 ?? matchA.frontmatter.source_sha1 ?? 'merged',
+    mergedFrom: [idA, idB],
+    tags: mergedTags,
+    projectRoot,
+    userDir,
+  });
+  if (writeResult.action === 'error') {
+    return errorResult({
+      category: writeResult.errorCategory,
+      errors: writeResult.errors,
+    });
+  }
+  // PR-1 blocker B1 fix preserved: writeFact dedup'd to an existing unrelated
+  // fact → return collision error rather than silently retargeting A and B.
+  if (writeResult.action !== 'created') {
+    return errorResult({
+      category: ERROR_CATEGORIES.COLLISION,
+      errors: [
+        `merged body collides with existing fact ${writeResult.id} (writeFact returned ${writeResult.action}${writeResult.skipReason ? ': ' + writeResult.skipReason : ''}); choose a different mergedBody`,
+      ],
+    });
+  }
+
+  const supersededA = moveToSuperseded(matchA, writeResult.id);
+  const supersededB = moveToSuperseded(matchB, writeResult.id);
+
+  const ts = now ?? nowIso();
+  appendAuditEntry(tierRoot, {
+    ts,
+    action: 'merged',
+    tier,
+    id: writeResult.id,
+    reasonCode: REASON_CODES.CURATED_MERGE,
+    paths: {
+      after: writeResult.path,
+      archive: [supersededA, supersededB],
+    },
+    extra: { mergedFrom: [idA, idB] },
+  });
+
+  return {
+    action: 'merged',
+    id: writeResult.id,
+    tier,
+    path: writeResult.path,
+    supersededPaths: [supersededA, supersededB],
+  };
+}

package/src/observe-edit.mjs

@@ -0,0 +1,87 @@
+// PostToolUse hook real handler (Task 20, T-017). Fires on Write /
+// Edit / MultiEdit only (matcher in hooks.json) and appends a one-line
+// summary of large tool outputs to sessions/now.md — feeds the rolling-
+// window compression pipeline (design §8.1).
+//
+// Public boundary: observeEdit({payload, projectRoot, now}) → result.
+// The bin wrapper handles stdin parsing + the detached-spawn dance
+// that makes the hook return within 50ms regardless of how big the
+// tool output is.
+//
+// Filter rules (defensive — hooks.json matcher should be the first
+// line of defense, but a misconfigured plugin install could route
+// other tool_names here, so we double-check):
+//   - tool_name must be one of Write / Edit / MultiEdit
+//   - tool_response.content must be > LINE_THRESHOLD lines
+//
+// Per design §1.4 / §8.1 the summary line shape feeds claude-remember-
+// style compaction downstream; we use a stable
+//   [<iso-ts>] <tool> file=<file_path> lines=<count>
+// format so the SessionEnd Haiku compressor (Task 22+23) can recognize
+// individual events.
+
+import { existsSync, mkdirSync, appendFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const ELIGIBLE_TOOLS = new Set(['Write', 'Edit', 'MultiEdit']);
+const LINE_THRESHOLD = 50; // strictly greater-than per design / 20.2
+
+function countLines(text) {
+  if (typeof text !== 'string' || text === '') return 0;
+  let n = 1;
+  for (let i = 0; i < text.length; i++) {
+    if (text.charCodeAt(i) === 10) n++;
+  }
+  // Trailing newline → the empty-after-last-\n shouldn't count as a
+  // line of content. Subtract one if the text ended on \n.
+  if (text.charCodeAt(text.length - 1) === 10) n--;
+  return n;
+}
+
+function extractContent(payload) {
+  // Be permissive — different tool invocations shape the response
+  // slightly differently (Anthropic hook payload evolution). Probe a
+  // few documented spellings.
+  if (!payload || typeof payload !== 'object') return '';
+  const r = payload.tool_response ?? payload.toolResponse ?? null;
+  if (r && typeof r === 'object') {
+    if (typeof r.content === 'string') return r.content;
+    if (typeof r.output === 'string') return r.output;
+    if (typeof r.text === 'string') return r.text;
+  }
+  if (typeof payload.output === 'string') return payload.output;
+  return '';
+}
+
+function extractFilePath(payload) {
+  const i = payload?.tool_input ?? payload?.toolInput ?? null;
+  if (i && typeof i === 'object') {
+    if (typeof i.file_path === 'string') return i.file_path;
+    if (typeof i.filePath === 'string') return i.filePath;
+    if (typeof i.path === 'string') return i.path;
+  }
+  return '';
+}
+
+export function observeEdit({ payload, projectRoot, now } = {}) {
+  const toolName = payload?.tool_name ?? payload?.toolName;
+  if (!ELIGIBLE_TOOLS.has(toolName)) {
+    return { action: 'noop', reason: 'tool-name-not-eligible' };
+  }
+  const content = extractContent(payload);
+  const lines = countLines(content);
+  if (lines <= LINE_THRESHOLD) {
+    return { action: 'noop', reason: 'below-line-threshold', lines };
+  }
+
+  const ts = now ?? new Date().toISOString();
+  const filePath = extractFilePath(payload);
+  const summary = `[${ts}] ${toolName} file=${filePath} lines=${lines}\n`;
+  const sessionsDir = join(projectRoot, 'context', 'sessions');
+  const nowMd = join(sessionsDir, 'now.md');
+  if (!existsSync(sessionsDir)) {
+    mkdirSync(sessionsDir, { recursive: true });
+  }
+  appendFileSync(nowMd, summary, 'utf8');
+  return { action: 'appended', summaryLine: summary, lines };
+}

package/src/platform-commands.mjs

@@ -0,0 +1,138 @@
+// platform-commands.mjs — shared helper for emitting user-facing
+// shell commands that work on the user's actual shell.
+//
+// Why this exists
+// ---------------
+//
+// The kit emits shell commands to users at runtime in several places
+// (lock-discipline.mjs's `recoveryCommand` field is the canonical
+// example; future `cmk doctor` HC-* repair output + `cmk repair`
+// self-repair output + error messages all do the same). The
+// user-facing shell varies by OS:
+//
+//   - Windows (cmd.exe / PowerShell): `Remove-Item`, `Get-ChildItem`,
+//     `New-Item`, etc. POSIX commands (`rm`, `ls`, `mkdir`) DO NOT
+//     work on stock cmd.exe and produce confusing errors.
+//   - macOS / Linux: POSIX commands.
+//   - Git Bash on Windows: POSIX commands work (it provides them).
+//
+// PR-B (lock-discipline.mjs) established the inline pattern:
+// `process.platform === 'win32'` switches between `Remove-Item "..."`
+// and `rm "..."`. PR-E (this campaign Part 7/7) generalizes that
+// pattern into this shared helper so future code doesn't reinvent it,
+// and so `scripts/validate-platform-commands.mjs` can mechanically
+// verify every emission site uses the helper or an explicit
+// suppression marker.
+//
+// What this module provides
+// -------------------------
+//
+// One function per primitive command. Each takes argument(s) and
+// returns a COMPLETE, copy-paste-ready shell command string in the
+// user's native shell. The caller doesn't think about quoting,
+// escaping, or platform differences — the helper does.
+//
+// Primitives currently covered:
+//   - removeFile(path)   — delete a file
+//   - removeDir(path)    — delete a directory recursively
+//   - listDir(path)      — list directory contents
+//
+// What this module does NOT do
+// ----------------------------
+//
+//   - Generate shell-script files. This is for one-liner copy-paste
+//     hints to the user, not for scripting.
+//   - Escape shell injection. Callers pass paths derived from kit
+//     state (lock-file paths, install dirs). Untrusted user input
+//     should be validated upstream.
+//   - Detect Git Bash vs cmd.exe vs PowerShell on Windows. We emit
+//     the PowerShell-style command on win32; Git Bash users can run
+//     the POSIX command independently. The platform-detection
+//     defaults to "what the user's STOCK shell expects" since that's
+//     the failure mode (PR-B's `recoveryCommand` finding: a Windows
+//     user pasting `rm` into cmd.exe gets a "command not found"
+//     error; pasting `Remove-Item` works in both PowerShell AND
+//     Git Bash IF git-bash forwards the call, but at minimum it
+//     doesn't give a confusing error).
+//
+// Suppression
+// -----------
+//
+// Sites that LEGITIMATELY hardcode a POSIX command (e.g., a .sh
+// script that already requires bash) can suppress the
+// `validate-platform-commands.mjs` check with a per-line
+// `// platform-commands: ignore <reason>` marker. Use sparingly —
+// the marker is for cases where a platform-specific shell is the
+// contract, not an oversight.
+
+// Note on Git Bash on Windows (per design §18.6): Git Bash reports
+// `process.platform === 'win32'` (it's running under the win32 Node
+// build) and accepts both POSIX `rm` AND PowerShell `Remove-Item`
+// via PowerShell.exe in PATH. Emitting `Remove-Item` is therefore
+// the cross-Windows-shell-compatible default — it works in stock
+// PowerShell AND in Git Bash. A user on cmd.exe with neither
+// PowerShell nor `rm` in PATH would have a broken Node install
+// anyway, so that case is out of scope.
+const IS_WINDOWS = process.platform === 'win32';
+
+// Quote a path for the user's shell. PowerShell + cmd.exe both
+// accept double-quoted paths. POSIX shells accept either; we use
+// double-quotes for consistency. Paths containing literal double-
+// quote characters are extremely rare in filesystem paths but would
+// need additional handling — not addressed here.
+function quote(path) {
+  return `"${path}"`;
+}
+
+/**
+ * Build a "remove this file" command in the user's native shell.
+ *
+ * Windows (PowerShell / cmd.exe via PowerShell-style fallback):
+ *   Remove-Item "C:\path\to\file"
+ *
+ * POSIX (macOS / Linux / Git Bash):
+ *   rm "/path/to/file"
+ */
+export function removeFile(path) {
+  if (IS_WINDOWS) {
+    return `Remove-Item ${quote(path)}`;
+  }
+  return `rm ${quote(path)}`;
+}
+
+/**
+ * Build a "remove this directory recursively" command.
+ *
+ * Windows:
+ *   Remove-Item -Recurse -Force "C:\path\to\dir"
+ *
+ * POSIX:
+ *   rm -rf "/path/to/dir"
+ */
+export function removeDir(path) {
+  if (IS_WINDOWS) {
+    return `Remove-Item -Recurse -Force ${quote(path)}`;
+  }
+  return `rm -rf ${quote(path)}`;
+}
+
+/**
+ * Build a "list directory contents" command.
+ *
+ * Windows:
+ *   Get-ChildItem "C:\path\to\dir"
+ *
+ * POSIX:
+ *   ls "/path/to/dir"
+ */
+export function listDir(path) {
+  if (IS_WINDOWS) {
+    return `Get-ChildItem ${quote(path)}`;
+  }
+  return `ls ${quote(path)}`;
+}
+
+// Exported for the validator + tests to assert which platform the
+// helper is currently emitting for. Useful for cross-platform CI
+// matrices where the test asserts both halves.
+export const PLATFORM = IS_WINDOWS ? 'win32' : 'posix';

package/src/poison-guard.mjs

@@ -0,0 +1,245 @@
+// Poison_Guard — pre-write secret + injection filter (Task 24.5, T-021).
+//
+// The kit's last line of defense before any auto-extracted or
+// user-explicit fact is written to a project-tier or user-tier file
+// that may end up in git. False negatives = credentials in the repo.
+// False positives = legitimate writes blocked. Pattern correctness
+// has to be right (design §6.7).
+//
+// Public boundary:
+//   checkPoisonGuard(text) → {
+//     rejected: boolean,
+//     pattern_id: string | null,    // category id; null if rejected:false
+//     redacted_excerpt: string,     // safe-for-logging excerpt; masks matched text with ***
+//   }
+//
+// Pattern catalog per design §6.7. The catalog is intentionally
+// conservative — see the design note "Why discoverability-only, not
+// perfect prevention": the threat model is "accidental commit", not
+// "active adversary in your repo." Regex catches the high-frequency
+// mistakes; secret-scanners (gitleaks, trufflehog) are the second
+// line of defense, not us.
+//
+// Redaction contract (security-load-bearing):
+//   - The matched secret/injection text MUST NEVER appear in
+//     redacted_excerpt in cleartext. The whole point of this module
+//     is to keep secrets out of logs. Every pattern in this catalog
+//     must produce a redacted excerpt that masks the match span
+//     with `***`. Unit tests pin this contract.
+//   - The excerpt is bounded in length (≤ ~200 chars) so a long
+//     pasted blob doesn't blow up the log line.
+
+import {
+  appendFileSync,
+  existsSync,
+  mkdirSync,
+} from 'node:fs';
+import { join, dirname } from 'node:path';
+
+// --- Pattern catalog -------------------------------------------------
+// Each pattern is { id, re, category }. The id is the stable
+// machine-parseable name that shows up in poison-guard.log NDJSON +
+// extract.log error_category disambiguation. The re is the
+// case-insensitive regex; category is 'secret' or 'injection' so the
+// downstream categorizer can route into POISON_GUARD_CATEGORIES.
+//
+// Conservative-on-purpose. Adding a pattern is a write — adding a
+// pattern that has false positives is a denial-of-service against
+// legitimate user input. Each pattern should be vetted against
+// realistic adversarial samples AND against realistic benign user
+// content.
+const SECRET_PATTERNS = [
+  // AWS access key id — fixed prefix (AKIA/ASIA/AGPA + various) + 16
+  // additional uppercase alphanumeric. The prefix is required to
+  // avoid matching arbitrary 20-char alphanumeric blobs.
+  {
+    id: 'secret_aws_access_key_id',
+    category: 'secret',
+    re: /\b(?:AKIA|ASIA|AGPA|AIDA|AROA|AIPA|ANPA|ANVA|ASCA)[A-Z0-9]{16}\b/,
+  },
+  // AWS secret access key in a key=value shape. The value pattern is
+  // intentionally lenient (40-char Base64-ish) because real AWS secret
+  // keys are 40 chars of Base64. We require the `aws_secret` token
+  // nearby to gate on intent.
+  {
+    id: 'secret_aws_secret_access_key',
+    category: 'secret',
+    re: /(?:aws[_-]?secret[_-]?(?:access[_-]?)?key)[\s:=]+["']?[A-Za-z0-9/+=]{16,}/i,
+  },
+  // Generic api_key / secret / password / passwd / token / bearer
+  // in a key=value shape. 20-char minimum on the value catches
+  // realistic key shapes without flagging short test fixtures
+  // (api_key=abc123 → only 6 chars, skipped).
+  {
+    id: 'secret_generic_credential',
+    category: 'secret',
+    re: /(?:api[_-]?key|secret|password|passwd|token|bearer)[\s:=]+["']?[A-Za-z0-9_\-/+=]{20,}/i,
+  },
+  // PEM private key armor. The "RSA "/"EC "/"OPENSSH "/"PGP "
+  // variants are optional, so plain `-----BEGIN PRIVATE KEY-----`
+  // also matches.
+  {
+    id: 'secret_pem_private_key',
+    category: 'secret',
+    re: /-----BEGIN (?:RSA |EC |OPENSSH |PGP |DSA |ENCRYPTED )?PRIVATE KEY-----/,
+  },
+  // GitHub personal access token: ghp_ prefix + 36 alphanumeric.
+  // No trailing \b — adjacent alphanumeric padding (in tests; rare in
+  // real input but possible) shouldn't suppress detection. Leading \b
+  // is enough to prevent matching mid-identifier (e.g. "xghp_..." is
+  // not a token).
+  {
+    id: 'secret_github_pat',
+    category: 'secret',
+    re: /\bghp_[A-Za-z0-9]{36}/,
+  },
+  // OpenAI / Anthropic style keys. sk- prefix + optional ant-/proj-
+  // qualifier + ≥40 chars of alphanumeric/dash/underscore.
+  {
+    id: 'secret_openai_anthropic_key',
+    category: 'secret',
+    re: /\bsk-(?:ant-|proj-)?[A-Za-z0-9_-]{40,}/,
+  },
+  // Slack tokens: xoxb-/xoxp-/xoxs- prefix + 10+ alphanumeric/dash.
+  {
+    id: 'secret_slack_token',
+    category: 'secret',
+    re: /\bxox[bps]-[A-Za-z0-9-]{10,}/,
+  },
+];
+
+const INJECTION_PATTERNS = [
+  // "ignore (all|any|previous|prior)* (instructions|prompts|rules)"
+  // Qualifier words are zero-or-more so all of these match:
+  //   "ignore instructions"
+  //   "ignore previous instructions"
+  //   "ignore all previous instructions"  (two qualifiers stacked)
+  //   "IGNORE ALL PREVIOUS INSTRUCTIONS"  (case-insensitive)
+  // The earlier `?` form only allowed ONE qualifier and missed the
+  // most common phrasing.
+  {
+    id: 'injection_ignore_instructions',
+    category: 'injection',
+    re: /ignore (?:all |any |previous |prior )*(?:instructions?|prompts?|rules?)/i,
+  },
+  // "You are now [an AI role]" — role-override attempt.
+  // Earlier draft was `/you are now (?:a |an |the )?[A-Za-z]/i` which
+  // matched ANY sentence starting "you are now <word>" — including
+  // benign content like "you are now able to ship", "you are now
+  // blocked on the API", "you are now responsible for X". False
+  // positives there = denial-of-service on legitimate memory writes.
+  // Tightened to require an explicit role-impersonation noun, with
+  // the optional adjective slot still capturing "you are now a
+  // helpful pirate assistant" / "you are now a different agent".
+  {
+    id: 'injection_role_override',
+    category: 'injection',
+    re: /you are now (?:a |an |the )?(?:[a-z]+ ){0,3}(?:assistant|chatbot|ai|bot|pirate|agent|expert|persona|model|gpt|claude)/i,
+  },
+  // Fake role tags. Closing or opening <system> / <assistant> tag
+  // in user-supplied content suggests an injection attempt.
+  {
+    id: 'injection_fake_role_tag',
+    category: 'injection',
+    re: /<\/?(?:system|assistant)>/i,
+  },
+  // "disregard the above" — common injection lead-in.
+  {
+    id: 'injection_disregard_above',
+    category: 'injection',
+    re: /disregard the above/i,
+  },
+];
+
+const ALL_PATTERNS = [...SECRET_PATTERNS, ...INJECTION_PATTERNS];
+
+// Frozen enum of pattern ids grouped by category. Callers import this
+// to validate routing logic without depending on the internal pattern
+// array order.
+export const POISON_GUARD_CATEGORIES = Object.freeze({
+  SECRET_CATEGORIES: Object.freeze(SECRET_PATTERNS.map((p) => p.id)),
+  INJECTION_CATEGORIES: Object.freeze(INJECTION_PATTERNS.map((p) => p.id)),
+});
+
+// Redaction parameters. The excerpt window around the match should be
+// small enough to fit in a log line but large enough to give a human
+// auditor enough context to act on (e.g., recognize "that was the
+// AWS_SECRET line in my terraform output").
+const REDACTION_CONTEXT_CHARS = 30;
+const REDACTION_MASK = '***';
+
+function redactExcerpt(text, matchStart, matchLength) {
+  const ctxStart = Math.max(0, matchStart - REDACTION_CONTEXT_CHARS);
+  const ctxEnd = Math.min(
+    text.length,
+    matchStart + matchLength + REDACTION_CONTEXT_CHARS,
+  );
+  const before = text.slice(ctxStart, matchStart);
+  const after = text.slice(matchStart + matchLength, ctxEnd);
+  const prefix = ctxStart > 0 ? '...' : '';
+  const suffix = ctxEnd < text.length ? '...' : '';
+  return `${prefix}${before}${REDACTION_MASK}${after}${suffix}`;
+}
+
+export function checkPoisonGuard(text) {
+  if (typeof text !== 'string') {
+    return {
+      rejected: true,
+      pattern_id: 'schema',
+      redacted_excerpt: '',
+    };
+  }
+  for (const { id, re } of ALL_PATTERNS) {
+    const m = text.match(re);
+    if (m) {
+      return {
+        rejected: true,
+        pattern_id: id,
+        redacted_excerpt: redactExcerpt(text, m.index, m[0].length),
+      };
+    }
+  }
+  return {
+    rejected: false,
+    pattern_id: null,
+    redacted_excerpt: '',
+  };
+}
+
+// --- NDJSON logger (Task 24.6, design §6.7) -------------------------
+//
+// One line per rejection at <projectRoot>/context/.locks/
+// poison-guard.log. Schema documented in design §6.7:
+//   {ts, pattern_id, source_file, source_line, action: "rejected",
+//    redacted_excerpt}
+//
+// The cleartext that triggered the rejection is INTENTIONALLY absent
+// from this log line. The caller produces redacted_excerpt via
+// checkPoisonGuard() and passes it in. Tests pin that no field
+// named raw_text / unredacted / matched_text / original ever appears.
+
+const POISON_GUARD_LOG_RELATIVE = ['context', '.locks', 'poison-guard.log'];
+
+export function logPoisonGuardRejection({
+  projectRoot,
+  ts,
+  pattern_id,
+  source_file,
+  source_line,
+  redacted_excerpt,
+} = {}) {
+  const logPath = join(projectRoot, ...POISON_GUARD_LOG_RELATIVE);
+  if (!existsSync(dirname(logPath))) {
+    mkdirSync(dirname(logPath), { recursive: true });
+  }
+  const entry = {
+    ts,
+    pattern_id,
+    source_file,
+    source_line,
+    action: 'rejected',
+    redacted_excerpt,
+  };
+  appendFileSync(logPath, JSON.stringify(entry) + '\n', 'utf8');
+  return logPath;
+}