mason-context 0.9.0 → 0.10.1

package/dist/mason-hook.js

@@ -2,35 +2,141 @@
 
 // src/hook/hook.ts
 import fs5 from "fs/promises";
-import path8 from "path";
+import path10 from "path";
 import os from "os";
 
 // src/decisions/decisions.ts
 import fs3 from "fs/promises";
-import path5 from "path";
+import path7 from "path";
 import { createHash } from "crypto";
 
-// src/snapshot/snapshot.ts
+// src/utils/storage.ts
 import fs2 from "fs/promises";
 import path3 from "path";
-import { execFile as execFile2 } from "child_process";
-import { promisify as promisify2 } from "util";
-import fg3 from "fast-glob";
+import { randomUUID } from "crypto";
 
-// src/mcp/sampler.ts
-import fs from "fs/promises";
+// src/utils/paths.ts
 import path from "path";
+function normalizeRepoPath(value) {
+  const slash = value.replace(/\\/g, "/");
+  if (!slash || slash.includes("\0") || path.posix.isAbsolute(slash) || /^[A-Za-z]:/.test(slash)) return null;
+  if (slash.split("/").includes("..")) return null;
+  const normalized = path.posix.normalize(slash).replace(/\/$/, "");
+  return normalized === "." ? null : normalized;
+}
+function anchorMatches(anchor, file) {
+  const a = normalizeRepoPath(anchor);
+  const f = normalizeRepoPath(file);
+  return a !== null && f !== null && (a === f || f.startsWith(`${a}/`));
+}
+function matchingPaths(anchors, files) {
+  return [...new Set(files)].filter((file) => anchors.some((anchor) => anchorMatches(anchor, file)));
+}
+
+// src/utils/files.ts
+import fs from "fs/promises";
+import { constants } from "fs";
+import path2 from "path";
 import { execFile } from "child_process";
 import { promisify } from "util";
 import fg from "fast-glob";
 var exec = promisify(execFile);
+var SOURCE_EXTENSIONS = ["ts", "tsx", "js", "jsx", "mts", "cts", "mjs", "cjs", "vue", "svelte", "kt", "kts", "java", "py", "go", "rs", "swift", "rb", "cs", "cpp", "c", "h", "hpp", "dart", "php"];
+var SOURCE_GLOB = `**/*.{${SOURCE_EXTENSIONS.join(",")}}`;
+var MAX_SOURCE_BYTES = 1024 * 1024;
+async function readBoundedFile(file, maxBytes) {
+  const handle = await fs.open(file, constants.O_RDONLY | constants.O_NONBLOCK | constants.O_NOFOLLOW);
+  try {
+    const stat = await handle.stat();
+    if (!stat.isFile() || stat.size > maxBytes) return null;
+    const buffer = Buffer.alloc(Math.min(maxBytes + 1, stat.size + 1));
+    let bytes = 0;
+    while (bytes < buffer.length) {
+      const result = await handle.read(buffer, bytes, buffer.length - bytes, null);
+      if (result.bytesRead === 0) break;
+      bytes += result.bytesRead;
+    }
+    return bytes === buffer.length ? null : buffer.subarray(0, bytes).toString("utf8");
+  } finally {
+    await handle.close();
+  }
+}
+
+// src/utils/storage.ts
+async function storePath(root, relative, createParents = false) {
+  const normalized = normalizeRepoPath(relative);
+  if (!normalized) throw new Error(`Invalid store path: ${relative}`);
+  let current = await fs2.realpath(root);
+  const parts = normalized.split("/");
+  for (let i = 0; i < parts.length; i++) {
+    current = path3.join(current, parts[i]);
+    let stat;
+    try {
+      stat = await fs2.lstat(current);
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+      if (createParents && i < parts.length - 1) {
+        try {
+          await fs2.mkdir(current);
+        } catch (mkdirError) {
+          if (mkdirError.code !== "EEXIST") throw mkdirError;
+        }
+        stat = await fs2.lstat(current);
+      }
+    }
+    if (stat?.isSymbolicLink()) throw new Error(`Symlink in store path: ${relative}`);
+  }
+  return current;
+}
+async function readStoreJson(root, relative) {
+  try {
+    const file = await storePath(root, relative);
+    const raw = await readBoundedFile(file, 10 * 1024 * 1024);
+    if (raw === null) throw new Error("file is not regular or exceeds 10 MiB");
+    const parsed = JSON.parse(raw);
+    if (parsed === null) throw new Error("expected a JSON object, received null");
+    return parsed;
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    throw new Error(`Invalid Mason store ${relative}: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+// src/snapshot/snapshot.ts
+import path5 from "path";
+import { execFile as execFile2 } from "child_process";
+import { promisify as promisify2 } from "util";
+import { z } from "zod";
 
 // src/test-map.ts
-import path2 from "path";
-import fg2 from "fast-glob";
+import path4 from "path";
 
 // src/snapshot/snapshot.ts
 var exec2 = promisify2(execFile2);
+var repoPath = z.string().refine((value) => normalizeRepoPath(value) !== null, "Expected a relative repository path");
+var verificationFields = {
+  refreshedHash: z.string().optional(),
+  verifiedAt: z.string().optional(),
+  verifiedHash: z.string().optional(),
+  verificationFailed: z.boolean().optional(),
+  verificationNote: z.string().optional()
+};
+var featureSchema = z.object({
+  description: z.string(),
+  files: z.array(repoPath),
+  tests: z.array(repoPath).optional(),
+  type: z.enum(["capability", "infrastructure"]).optional(),
+  ...verificationFields
+}).passthrough();
+var flowSchema = z.object({ description: z.string(), chain: z.array(repoPath), ...verificationFields }).passthrough();
+var snapshotSchema = z.object({
+  version: z.literal(2),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+  gitHash: z.string(),
+  features: z.record(featureSchema),
+  flows: z.record(flowSchema)
+}).passthrough();
 async function getCurrentGitHash(rootDir) {
   try {
     const { stdout } = await exec2("git", ["rev-parse", "HEAD"], {
@@ -43,123 +149,279 @@ async function getCurrentGitHash(rootDir) {
 }
 
 // src/context/lexical.ts
-import path4 from "path";
+import path6 from "path";
 
-// src/decisions/decisions.ts
-function decisionsDir(rootDir) {
-  return path5.join(rootDir, ".mason", "decisions");
+// src/decisions/provenance.ts
+import { z as z2 } from "zod";
+
+// src/context/trust.ts
+function assessTrust(entry, freshness) {
+  const verification = entry.verificationFailed ? "failed" : entry.verifiedAt ? "passed" : "unverified";
+  const reasons = [];
+  if (freshness === "unknown") reasons.push("Anchors, history, or working-tree evidence are unavailable; verify before relying on this entry.");
+  if (freshness === "changed") reasons.push("Anchored files changed; verify against current code before relying on this entry.");
+  if (verification === "failed") reasons.push(`Verification failed: ${entry.verificationNote ?? "re-map this entry before relying on it"}`);
+  if (verification === "unverified") reasons.push("No correctness verification has been recorded.");
+  return { freshness, verification, verifiedAt: entry.verifiedAt, verifiedHash: entry.verifiedHash, reasons };
+}
+
+// src/decisions/provenance.ts
+var text = (max) => z2.string().trim().min(1).max(max);
+var decisionSourceSchema = z2.object({
+  kind: z2.enum(["pull_request", "issue", "incident", "discussion", "document", "other"]),
+  reference: text(1e3),
+  note: text(500).optional()
+}).strict();
+var attributionSchema = z2.object({
+  owner: text(200).nullable().optional(),
+  sources: z2.array(decisionSourceSchema).max(20).optional(),
+  actor: text(200).optional()
+});
+var contentSchema = z2.object({
+  title: z2.string().min(1),
+  body: z2.string().min(1),
+  category: z2.enum(["decision", "gotcha", "deprecation", "convention"]),
+  files: z2.array(z2.string().refine((f) => normalizeRepoPath(f) !== null)),
+  owner: text(200).optional(),
+  sources: z2.array(decisionSourceSchema).max(20)
+});
+var approvalSchema = z2.enum(["unreviewed", "proposed", "accepted"]);
+var statusSchema = z2.enum(["active", "superseded", "retired"]);
+var reviewEvidenceSchema = z2.object({
+  baseHash: z2.string(),
+  headHash: z2.string(),
+  historyAvailable: z2.boolean(),
+  changedFiles: z2.array(z2.string()),
+  localChanges: z2.array(z2.string())
+});
+var eventSchema = z2.object({
+  kind: z2.enum(["imported", "created", "revised", "accepted", "reaffirmed", "retired", "superseded"]),
+  at: z2.string().datetime(),
+  actor: text(200).optional(),
+  note: text(1500).optional(),
+  revision: z2.number().int().positive(),
+  content: contentSchema,
+  approval: approvalSchema,
+  status: statusSchema,
+  refreshedHash: z2.string(),
+  evidence: reviewEvidenceSchema.optional()
+});
+var legacySchema = z2.object({
+  version: z2.literal(1),
+  id: z2.string().regex(/^[a-zA-Z0-9_-]+$/),
+  title: z2.string().min(1),
+  body: z2.string().min(1),
+  category: contentSchema.shape.category,
+  files: contentSchema.shape.files,
+  createdAt: z2.string(),
+  updatedAt: z2.string(),
+  refreshedHash: z2.string(),
+  status: z2.enum(["active", "superseded"]),
+  supersededBy: z2.string().optional()
+}).passthrough();
+var currentSchema = legacySchema.extend({
+  version: z2.literal(2),
+  status: statusSchema,
+  approval: approvalSchema,
+  revision: z2.number().int().positive(),
+  owner: text(200).optional(),
+  sources: z2.array(decisionSourceSchema).max(20),
+  history: z2.array(eventSchema).min(1)
+}).superRefine((record, ctx) => {
+  const invalid = (message) => ctx.addIssue({ code: "custom", message });
+  const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+  let previous;
+  for (const event of record.history) {
+    if (!previous) {
+      if (!["created", "imported"].includes(event.kind) || event.revision !== 1) invalid("History must begin with creation or legacy import at revision 1");
+      if (event.approval !== (event.kind === "created" ? "proposed" : "unreviewed")) invalid("Initial records cannot claim acceptance");
+    } else {
+      if (["created", "imported"].includes(event.kind)) invalid("History cannot restart");
+      if (previous.status !== "active") invalid("Archived decisions cannot be changed");
+      if (event.revision !== previous.revision + (event.kind === "revised" ? 1 : 0)) invalid("Invalid revision sequence");
+      if (event.kind !== "revised" && !same(event.content, previous.content)) invalid("A review cannot silently revise decision content");
+      if (event.kind === "reaffirmed" && previous.approval !== "accepted") invalid("Only accepted decisions can be reaffirmed");
+      if (event.kind === "accepted" && previous.approval === "accepted") invalid("Use reaffirmation for an accepted decision");
+      const approval = event.kind === "revised" ? "proposed" : ["accepted", "reaffirmed"].includes(event.kind) ? "accepted" : previous.approval;
+      if (event.approval !== approval) invalid("Approval disagrees with review history");
+      if (!["accepted", "reaffirmed"].includes(event.kind) && event.refreshedHash !== previous.refreshedHash) invalid("Only a review can refresh the evidence baseline");
+    }
+    if (event.kind !== "imported" && event.status !== (event.kind === "retired" ? "retired" : event.kind === "superseded" ? "superseded" : "active")) invalid("Lifecycle disagrees with history");
+    if (["accepted", "reaffirmed", "retired"].includes(event.kind) && (!event.actor || !event.note || !event.evidence)) invalid("Reviews require a named reviewer, reason, and code evidence");
+    if (["accepted", "reaffirmed"].includes(event.kind)) {
+      if (!event.content.owner || !event.content.sources.length) invalid("Accepted decisions require an owner and source");
+      if (!event.evidence || !/^[a-f0-9]{40,64}$/.test(event.evidence.headHash) || event.refreshedHash !== event.evidence.headHash || event.evidence.localChanges.length) invalid("Acceptance requires a committed evidence baseline");
+    }
+    previous = event;
+  }
+  if (!previous || !same(previous.content, decisionContent(record)) || previous.approval !== record.approval || previous.status !== record.status || previous.revision !== record.revision || previous.refreshedHash !== record.refreshedHash) invalid("Decision does not match the final history event");
+});
+var decisionSchema = z2.union([legacySchema, currentSchema]);
+function decisionContent(record) {
+  return {
+    title: record.title,
+    body: record.body,
+    category: record.category,
+    files: record.files,
+    ...typeof record.owner === "string" ? { owner: record.owner } : {},
+    sources: Array.isArray(record.sources) ? record.sources : []
+  };
+}
+function decisionApproval(record) {
+  return record.version === 1 ? "unreviewed" : record.approval;
+}
+function effectiveDecision(record) {
+  if (record.version !== 2 || record.status !== "active" || record.approval !== "proposed") return record;
+  let index = record.history.length - 1;
+  while (index >= 0 && !["accepted", "reaffirmed"].includes(record.history[index].kind)) index--;
+  if (index < 0) return record;
+  const event = record.history[index];
+  return {
+    ...record,
+    ...event.content,
+    owner: event.content.owner,
+    approval: "accepted",
+    revision: event.revision,
+    refreshedHash: event.refreshedHash,
+    updatedAt: event.at,
+    history: record.history.slice(0, index + 1)
+  };
+}
+function decisionAnchors(record) {
+  return [.../* @__PURE__ */ new Set([...effectiveDecision(record).files, ...record.files])];
+}
+function decisionProvenance(record, freshness = "unknown") {
+  const approval = decisionApproval(record);
+  const review = record.version === 2 ? [...record.history].reverse().find((e) => ["accepted", "reaffirmed"].includes(e.kind) && e.revision === record.revision) : void 0;
+  return {
+    approval,
+    revision: record.version === 2 ? record.revision : 0,
+    owner: record.version === 2 ? record.owner ?? null : null,
+    sources: record.version === 2 ? record.sources : [],
+    guidance: record.status !== "active" ? "historical" : approval === "accepted" ? "constraint" : approval === "proposed" ? "proposal" : "unreviewed",
+    reviewRequired: record.status === "active" && (approval !== "accepted" || freshness !== "current"),
+    lastReview: review ? { reviewer: review.actor, at: review.at, note: review.note, gitHash: review.refreshedHash } : null
+  };
+}
+function decisionTrust(record, freshness) {
+  const review = decisionProvenance(record, freshness).lastReview;
+  return assessTrust(review ? { verifiedAt: review.at, verifiedHash: review.gitHash } : {}, freshness);
+}
+function revisionKnowledge(record, freshness) {
+  return { ...decisionContent(record), ...decisionProvenance(record, freshness), trust: decisionTrust(record, freshness) };
+}
+function decisionKnowledge(record, freshness = "unknown", proposalFreshness = "unknown") {
+  const effective = effectiveDecision(record);
+  return {
+    ...revisionKnowledge(effective, freshness),
+    ...effective !== record ? { pendingProposal: revisionKnowledge(record, proposalFreshness) } : {}
+  };
 }
-async function loadDecisions(rootDir) {
+var DECISION_GUIDANCE = "Accepted decisions are recorded team constraints, subject to freshness checks. A pendingProposal is an unaccepted replacement; the accepted revision remains operative until explicit acceptance or retirement. Proposals are suggestions; legacy unreviewed records need confirmation. Use review_decision to inspect provenance and record an authorized review; identities and sources are recorded assertions, not authenticated proof.";
+
+// src/decisions/decisions.ts
+async function loadDecisionStore(rootDir) {
+  const records = [];
+  const diagnostics = [];
   let entries;
   try {
-    entries = await fs3.readdir(decisionsDir(rootDir));
-  } catch {
-    return [];
+    entries = await fs3.readdir(await storePath(rootDir, ".mason/decisions"));
+  } catch (error) {
+    if (error.code !== "ENOENT") diagnostics.push({ path: ".mason/decisions", message: String(error) });
+    return { records, diagnostics };
   }
-  const records = [];
-  for (const entry of entries) {
+  for (const entry of entries.sort()) {
     if (!entry.endsWith(".json")) continue;
+    const relative = `.mason/decisions/${entry}`;
     try {
-      const raw = await fs3.readFile(
-        path5.join(decisionsDir(rootDir), entry),
-        "utf-8"
-      );
-      const parsed = JSON.parse(raw);
-      if (parsed.version !== 1 || !parsed.id || !parsed.title || !parsed.body) {
-        continue;
-      }
-      records.push(parsed);
-    } catch {
-      continue;
+      const record = decisionSchema.parse(await readStoreJson(rootDir, relative));
+      if (entry !== `${record.id}.json`) throw new Error("Record id does not match its filename");
+      records.push(record);
+    } catch (error) {
+      diagnostics.push({ path: relative, message: error instanceof Error ? error.message : String(error) });
     }
   }
-  return records.sort((a, b) => a.id.localeCompare(b.id));
+  return { records, diagnostics };
 }
 
+// src/hook/hook.ts
+import { createHash as createHash2 } from "crypto";
+
 // src/decisions/drift.ts
-import path7 from "path";
+import path9 from "path";
 
 // src/drift/drift.ts
 import fs4 from "fs/promises";
-import path6 from "path";
+import path8 from "path";
 import { execFile as execFile3 } from "child_process";
 import { promisify as promisify3 } from "util";
 var exec3 = promisify3(execFile3);
-async function getChangesWithStatus(resolvedRoot, fromHash) {
-  if (!fromHash || fromHash === "unknown") return null;
+function parseChanges(output) {
+  const fields = output.split("\0");
+  const changes = [];
+  for (let i = 0; i < fields.length && fields[i]; ) {
+    const code = fields[i++];
+    const first = fields[i++];
+    if (!first) break;
+    const second = /^[RC]/.test(code) ? fields[i++] : void 0;
+    const change = second ? code.startsWith("R") ? { status: "renamed", path: second, previousPath: first } : { status: "added", path: second } : { status: code === "A" ? "added" : code === "D" ? "deleted" : "modified", path: first };
+    if (change.path.startsWith(".mason/") && (!change.previousPath || change.previousPath.startsWith(".mason/"))) continue;
+    changes.push(change);
+  }
+  return changes;
+}
+function touchedPaths(changes) {
+  return [...new Set(changes.flatMap((c) => c.previousPath ? [c.previousPath, c.path] : [c.path]))].sort();
+}
+async function getChangesWithStatus(resolvedRoot, fromHash, toHash = "HEAD") {
+  if (!fromHash || fromHash === "unknown" || fromHash.startsWith("-") || !toHash || toHash === "unknown" || toHash.startsWith("-")) return null;
   try {
-    const { stdout } = await exec3(
-      "git",
-      ["diff", "--name-status", "-M", fromHash, "HEAD"],
-      { cwd: resolvedRoot, maxBuffer: 10 * 1024 * 1024 }
-    );
-    const changes = [];
-    for (const line of stdout.split("\n")) {
-      if (!line.trim()) continue;
-      const parts = line.split("	");
-      if (parts.some((p) => p.startsWith(".mason/"))) continue;
-      const code = parts[0];
-      if (code.startsWith("R") && parts.length >= 3) {
-        changes.push({
-          status: "renamed",
-          path: parts[2],
-          previousPath: parts[1]
-        });
-      } else if (code.startsWith("C") && parts.length >= 3) {
-        changes.push({ status: "added", path: parts[2] });
-      } else if (code === "A" && parts.length >= 2) {
-        changes.push({ status: "added", path: parts[1] });
-      } else if (code === "D" && parts.length >= 2) {
-        changes.push({ status: "deleted", path: parts[1] });
-      } else if (parts.length >= 2) {
-        changes.push({ status: "modified", path: parts[1] });
-      }
-    }
-    return changes;
+    const { stdout } = await exec3("git", ["diff", "--name-status", "-z", "-M", fromHash, toHash, "--"], { cwd: resolvedRoot, maxBuffer: 10 * 1024 * 1024 });
+    return parseChanges(stdout);
   } catch {
     return null;
   }
 }
+async function getWorkingTree(resolvedRoot) {
+  try {
+    const [diff, untracked] = await Promise.all([
+      exec3("git", ["diff", "--name-status", "-z", "-M", "HEAD", "--"], { cwd: resolvedRoot, maxBuffer: 10 * 1024 * 1024 }),
+      exec3("git", ["ls-files", "-z", "--others", "--exclude-standard"], { cwd: resolvedRoot, maxBuffer: 10 * 1024 * 1024 })
+    ]);
+    const untrackedFiles = untracked.stdout.split("\0").filter((f) => f && !f.startsWith(".mason/"));
+    return { available: true, changedFiles: [.../* @__PURE__ */ new Set([...touchedPaths(parseChanges(diff.stdout)), ...untrackedFiles])].sort(), untrackedFiles };
+  } catch {
+    return { available: false, changedFiles: [], untrackedFiles: [] };
+  }
+}
 
 // src/decisions/drift.ts
 async function computeDecisionDrift(rootDir, decisions) {
-  const resolvedRoot = path7.resolve(rootDir);
-  const records = decisions ?? await loadDecisions(resolvedRoot);
-  const report = {
-    historyAvailable: true,
-    totalDecisions: records.length,
-    staleDecisions: {}
-  };
-  const head = await getCurrentGitHash(resolvedRoot);
+  const resolvedRoot = path9.resolve(rootDir);
+  const store = decisions ? { records: decisions, diagnostics: [] } : await loadDecisionStore(resolvedRoot);
+  const report = { historyAvailable: true, totalDecisions: store.records.length, staleDecisions: {}, freshness: {}, diagnostics: store.diagnostics };
+  const [head, workingTree] = await Promise.all([getCurrentGitHash(resolvedRoot), getWorkingTree(resolvedRoot)]);
   const changesByHash = /* @__PURE__ */ new Map();
-  for (const record of records) {
-    if (record.status !== "active" || record.files.length === 0) continue;
-    if (record.refreshedHash === head) continue;
+  const inspect = async (record) => {
+    if (record.files.length === 0) return { freshness: "unknown", changedFiles: [] };
     let touched = changesByHash.get(record.refreshedHash);
     if (touched === void 0) {
-      const changes = await getChangesWithStatus(
-        resolvedRoot,
-        record.refreshedHash
-      );
-      if (changes === null) {
-        touched = null;
-      } else {
-        touched = /* @__PURE__ */ new Set();
-        for (const change of changes) {
-          touched.add(change.path);
-          if (change.previousPath) touched.add(change.previousPath);
-        }
-      }
+      const changes = record.refreshedHash === head && head !== "unknown" ? [] : await getChangesWithStatus(resolvedRoot, record.refreshedHash);
+      touched = changes === null ? null : touchedPaths(changes);
       changesByHash.set(record.refreshedHash, touched);
     }
-    if (touched === null) {
-      report.historyAvailable = false;
-      continue;
-    }
-    const hits = record.files.filter((f) => touched.has(f));
-    if (hits.length > 0) {
-      report.staleDecisions[record.id] = hits;
-    }
+    if (touched === null) report.historyAvailable = false;
+    const hits = touched ? matchingPaths(record.files, touched) : [];
+    const localHits = matchingPaths(record.files, workingTree.changedFiles);
+    return { freshness: touched === null || !workingTree.available ? "unknown" : hits.length || localHits.length ? "changed" : "current", changedFiles: hits };
+  };
+  for (const record of store.records) {
+    if (record.status !== "active") continue;
+    const effective = effectiveDecision(record);
+    const state = await inspect(effective);
+    report.freshness[record.id] = state.freshness;
+    if (state.changedFiles.length) report.staleDecisions[record.id] = state.changedFiles;
+    if (effective !== record) (report.pendingProposals ??= {})[record.id] = await inspect(record);
   }
   return report;
 }
@@ -179,22 +441,19 @@ async function exists(p) {
 async function findMasonRoot(startDir) {
   let dir = startDir;
   for (let i = 0; i < MAX_WALK_UP; i++) {
-    if (await exists(path8.join(dir, ".mason", "decisions"))) return dir;
-    if (await exists(path8.join(dir, ".git"))) return null;
-    const parent = path8.dirname(dir);
+    if (await exists(path10.join(dir, ".mason", "decisions"))) return dir;
+    if (await exists(path10.join(dir, ".git"))) return null;
+    const parent = path10.dirname(dir);
     if (parent === dir) return null;
     dir = parent;
   }
   return null;
 }
 function anchorsCover(record, relPath) {
-  return record.files.some((anchor) => {
-    const a = anchor.replace(/\/+$/, "");
-    return a === relPath || relPath.startsWith(`${a}/`);
-  });
+  return decisionAnchors(record).some((anchor) => anchorMatches(anchor, relPath));
 }
 function exactAnchor(record, relPath) {
-  return record.files.some((a) => a.replace(/\/+$/, "") === relPath);
+  return decisionAnchors(record).some((a) => a.replace(/\/+$/, "") === relPath);
 }
 function stateKey(input) {
   const raw = `${input.session_id ?? "nosession"}${input.agent_id ? `-${input.agent_id}` : ""}`;
@@ -208,16 +467,21 @@ async function loadInjected(stateFile) {
     return /* @__PURE__ */ new Set();
   }
 }
-function formatContext(relPath, records, staleIds) {
+function formatContext(relPath, records, drift) {
   const lines = [];
   lines.push(
-    `Mason: recorded team knowledge anchored to ${relPath} \u2014 treat as constraints. Do not modify decision records in .mason/decisions/.`
+    `Mason: decision knowledge relevant to ${relPath} or updated since this session saw it. This replaces earlier guidance for the same decision id. ${DECISION_GUIDANCE} Retired or superseded records are no longer active. Do not modify decision records in .mason/decisions/.`
   );
-  for (const record of records) {
-    const stale = staleIds.has(record.id) ? " [recorded against an older commit \u2013 verify against current code before relying on it]" : "";
+  const append = (id, knowledge, label, freshness) => {
+    const stale = freshness === "current" ? "" : freshness === "changed" ? " [recorded against changed files \u2013 verify against current code before relying on it]" : " [freshness unknown \u2013 verify against current code before relying on it]";
     lines.push(
-      `- [${record.category}] ${record.title}: ${record.body} (anchors: ${record.files.join(", ")})${stale}`
+      `- [${label}] [${knowledge.category}] ${knowledge.title}: ${knowledge.body} (id: ${id}; revision: ${knowledge.revision}; anchors: ${knowledge.files.join(", ")}; owner: ${knowledge.owner ?? "unknown"}; sources: ${knowledge.sources.slice(0, 2).map((s) => s.reference).join(", ") || "unrecorded"})${stale}`
     );
+  };
+  for (const record of records) {
+    const knowledge = decisionKnowledge(record, drift.freshness?.[record.id] ?? "unknown", drift.pendingProposals?.[record.id]?.freshness ?? "unknown");
+    append(record.id, knowledge, record.status === "active" ? knowledge.approval : record.status, knowledge.trust.freshness);
+    if (knowledge.pendingProposal) append(record.id, knowledge.pendingProposal, "proposed", knowledge.pendingProposal.trust.freshness);
   }
   return lines.join("\n");
 }
@@ -228,33 +492,33 @@ async function runHook(stdinText, env = {}) {
   } catch {
     return null;
   }
+  if (!input || typeof input !== "object") return null;
   if (input.tool_name && !SUPPORTED_TOOLS.has(input.tool_name)) return null;
   const filePath = input.tool_input?.file_path;
   if (!filePath || typeof filePath !== "string") return null;
-  const absPath = path8.isAbsolute(filePath) ? filePath : path8.resolve(input.cwd ?? process.cwd(), filePath);
-  const root = await findMasonRoot(path8.dirname(absPath));
+  const absPath = path10.isAbsolute(filePath) ? filePath : path10.resolve(input.cwd ?? process.cwd(), filePath);
+  const root = await findMasonRoot(path10.dirname(absPath));
   if (!root) return null;
-  const relPath = path8.relative(root, absPath).split(path8.sep).join("/");
+  const relPath = path10.relative(root, absPath).split(path10.sep).join("/");
   if (relPath.startsWith("..")) return null;
-  const records = await loadDecisions(root);
-  const matched = records.filter(
-    (r) => r.status === "active" && anchorsCover(r, relPath)
-  );
-  if (matched.length === 0) return null;
+  const { records } = await loadDecisionStore(root);
   const stateDir = env.stateDir ?? os.tmpdir();
-  const stateFile = path8.join(stateDir, `mason-hook-${stateKey(input)}.json`);
+  const stateFile = path10.join(stateDir, `mason-hook-${createHash2("sha256").update(root).digest("hex").slice(0, 12)}-${stateKey(input)}.json`);
   const injected = await loadInjected(stateFile);
-  const fresh = matched.filter((r) => !injected.has(r.id));
+  const recordKey = (record) => `${record.id}:${createHash2("sha256").update(JSON.stringify(record)).digest("hex")}`;
+  const previouslyInjected = (record) => [...injected].some((key) => key === record.id || key.startsWith(`${record.id}:`));
+  const fresh = records.filter((r) => !injected.has(recordKey(r)) && (previouslyInjected(r) || r.status === "active" && anchorsCover(r, relPath)));
   if (fresh.length === 0) return null;
   fresh.sort((a, b) => {
+    const withdrawn = Number(b.status !== "active") - Number(a.status !== "active");
+    if (withdrawn) return withdrawn;
     const exactDiff = Number(exactAnchor(b, relPath)) - Number(exactAnchor(a, relPath));
     if (exactDiff !== 0) return exactDiff;
     return b.updatedAt.localeCompare(a.updatedAt);
   });
   const selected = fresh.slice(0, MAX_INJECTED_DECISIONS);
   const drift = await computeDecisionDrift(root, selected);
-  const staleIds = new Set(Object.keys(drift.staleDecisions));
-  for (const record of selected) injected.add(record.id);
+  for (const record of selected) injected.add(recordKey(record));
   try {
     await fs5.writeFile(stateFile, JSON.stringify([...injected]), "utf-8");
   } catch {
@@ -262,7 +526,7 @@ async function runHook(stdinText, env = {}) {
   return JSON.stringify({
     hookSpecificOutput: {
       hookEventName: "PostToolUse",
-      additionalContext: formatContext(relPath, selected, staleIds)
+      additionalContext: formatContext(relPath, selected, drift)
     }
   });
 }
@@ -297,17 +561,17 @@ var SETTINGS_CONFIG = {
     ]
   }
 };
-async function runHookCli(argv, stdinText, io = {
+async function runHookCli(argv2, stdinText, io = {
   out: (line) => process.stdout.write(`${line}
 `),
   err: (line) => process.stderr.write(`${line}
 `)
 }, env = {}) {
-  if (argv.includes("--help") || argv.includes("-h")) {
+  if (argv2.includes("--help") || argv2.includes("-h")) {
     io.out(USAGE);
     return 0;
   }
-  if (argv.includes("--print-config")) {
+  if (argv2.includes("--print-config")) {
     io.out(JSON.stringify(SETTINGS_CONFIG, null, 2));
     return 0;
   }
@@ -328,5 +592,7 @@ async function readStdin() {
   }
   return Buffer.concat(chunks).toString("utf-8");
 }
-readStdin().then((stdinText) => runHookCli(process.argv.slice(2), stdinText)).then((code) => process.exit(code)).catch(() => process.exit(0));
+var argv = process.argv.slice(2);
+var informational = argv.some((arg) => ["--help", "-h", "--print-config"].includes(arg));
+(informational ? Promise.resolve("") : readStdin()).then((stdinText) => runHookCli(argv, stdinText)).then((code) => process.exit(code)).catch(() => process.exit(0));
 //# sourceMappingURL=mason-hook.js.map