phronesis 1.0.0

package/vendor/core/src/search.js

@@ -0,0 +1,534 @@
+// Two-stage retrieval — Stage 1 in-process BM25 + Stage 2 typed link walk
+// (core-0014 / T5.2; specs/compile-retrieve-loop.md §"Two-stage retrieval" + §"The V1
+// retrieval surface contract"; specs/tech-stack.md §"Search stack"; change 0014).
+//
+// Library-first (specs/context-server.md §"V1.0 preparation"): every retrieval
+// primitive lives HERE — the CLI parses and formats only, and the V1.5 context server's
+// `recall()` imports these same functions. The BM25 engine is `lunr` (the spec's
+// "`flexsearch`/`lunr`-class" family): its scoring is actual BM25, it exposes the
+// numeric `score` the surface contract requires, and its stemmer + position metadata
+// drive recall and snippet extraction. Known limits: exact-token + stemmed matching
+// (no fuzzy/prefix by default); the in-memory index is rebuilt from the snapshot at
+// load (lunr indexes are immutable — irrelevant under read-time loading).
+//
+// The persisted machine index (.phronesis/index/objects.json) is a PARSE CACHE —
+// derived, gitignored, export-stripped, rebuildable (change 0008) — never a freshness
+// authority and never source of truth. Freshness is READ-TIME verify-and-repair
+// (change 0014 R1): every load stats the live object file set, re-parses only
+// changed/new files (mtimeMs+ctimeMs+size quick-check — ctime is kernel-set on every
+// write and userspace cannot restore it, so mtime-preserving tools like `rsync -a` /
+// `tar -xp` / `cp -p` still trigger repair; the residual hole is a same-size edit
+// inside one ctime tick, unreachable in practice, and `phronesis index rebuild` is
+// the recovery),
+// drops deleted ones, and persists the repaired snapshot atomically (temp + rename,
+// partial removed on failure). Out-of-band edits — the operator in any editor — are a
+// first-class write path under the plain-files promise; an index refreshed only on
+// `act` commits would go silently stale on exactly the false-negative class the
+// validate-search gate exists to catch. The V1.5 daemon's at-rest watch ADDS
+// push-freshness for long-running consumers; it is not load-bearing for correctness.
+//
+// A search-path persist failure degrades to a stderr-visible warning, never a refusal:
+// the snapshot is a cache, and retrieval must keep working in a read-only checkout
+// (an exported, re-opened installation). An EXPLICIT `phronesis index rebuild` that
+// cannot write its artifact fails loudly — that command's whole job is the artifact.
+//
+// Concurrency: same one-writer-per-installation posture as the event log + audit log.
+// Concurrent loads may race the persist; the atomic rename means readers only ever see
+// a complete snapshot, and the loser's work is re-derived on the next load.
+
+import { join, dirname } from 'node:path';
+import { mkdir, readFile, writeFile, rename, rm, stat } from 'node:fs/promises';
+import { randomBytes } from 'node:crypto';
+import lunr from 'lunr';
+import { listArtifactFiles, readArtifactRecord } from './artifacts.js';
+import { contextFor, listRetrievableObjectFiles, readObjectRecord, walkMarkdown } from './workspace-scan.js';
+import { buildLinkIndexFromRecords } from './link-index.js';
+import { resolveInstall } from './install-root.js';
+import { resolveDomain } from './actions.js';
+
+const SNAPSHOT_VERSION = 1;
+const DEFAULT_LIMIT = 10; // the context-server recall(query, limit = 10) default
+const DEFAULT_HOPS = 1; // the spec's "related decisions, people involved, sources they cite" = the 1-hop neighborhood
+const SNIPPET_BEFORE = 60; // chars of context kept before the first body match
+const SNIPPET_AFTER = 90; // chars kept after it
+
+export function indexDir(installRoot) {
+  return join(installRoot, '.phronesis', 'index');
+}
+
+export function snapshotPath(installRoot) {
+  return join(indexDir(installRoot), 'objects.json');
+}
+
+// --- Snapshot: parse, verify-and-repair, persist ---------------------------------------
+
+// Parse one typed-object file into a snapshot doc — the shared readObjectRecord (ONE
+// file→record parse for the link index and this snapshot; the two-consumers rule) plus
+// the stat fields the freshness quick-check keys on. Returns null for non-objects and
+// unparseable files — the index is best-effort over a possibly-imperfect workspace
+// (the validator flags bad objects; the index routes around them). Null-parses are not
+// recorded, so a persistently broken file is re-attempted each load: correctness over
+// micro-cost, and the validator is the surface that names the problem.
+async function parseDoc(root, rel) {
+  let st;
+  try {
+    st = await stat(join(root, rel));
+  } catch {
+    return null; // vanished mid-scan — the next load sees the final state
+  }
+  const record = await readObjectRecord(root, rel);
+  if (!record) return null;
+  const { ctx, fm, body } = record;
+  return {
+    path: rel,
+    layer: ctx.layer,
+    domain: ctx.domain,
+    codexKind: ctx.codexKind,
+    type: fm.type ?? null,
+    name: fm.name ?? null,
+    title: fm.title ?? null,
+    status: fm.status ?? null,
+    exposure: fm.exposure ?? null,
+    stance: fm.stance ?? null,
+    links: Array.isArray(fm.links) ? fm.links : [],
+    body,
+    mtimeMs: st.mtimeMs,
+    ctimeMs: st.ctimeMs,
+    size: st.size,
+  };
+}
+
+// A cached doc is only trusted if its load-bearing fields hold their contract shape:
+// `path`/`mtimeMs`/`size` drive the freshness quick-check, `body` feeds the BM25 index
+// and snippets, `links` feeds the graph. Envelope-level checks alone (version + "docs
+// is an array") would trust a `null` doc (crash) or a `body: null` whose mtime/size
+// still match disk — a SILENTLY re-persisted stale entry hiding a live file's content,
+// the exact false-negative class this module exists to kill. The gate condition must
+// match the invariant, not a convenient type test (the rules.md null/presence family).
+function isValidDoc(d) {
+  return (
+    d !== null &&
+    typeof d === 'object' &&
+    !Array.isArray(d) &&
+    typeof d.path === 'string' &&
+    typeof d.mtimeMs === 'number' &&
+    typeof d.ctimeMs === 'number' &&
+    typeof d.size === 'number' &&
+    typeof d.body === 'string' &&
+    Array.isArray(d.links)
+  );
+}
+
+// Read the persisted snapshot. Absent, corrupt, version-unknown, or carrying ANY
+// malformed doc all yield null — a cache miss is a full re-parse, never a crash and
+// never a trusted lie (the snapshot is derived state; rebuilding it is always safe).
+async function readSnapshot(root) {
+  let raw;
+  try {
+    raw = await readFile(snapshotPath(root), 'utf8');
+  } catch {
+    return null;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (
+    parsed === null ||
+    typeof parsed !== 'object' ||
+    parsed.schema_version !== SNAPSHOT_VERSION ||
+    !Array.isArray(parsed.docs) ||
+    !parsed.docs.every(isValidDoc)
+  ) {
+    return null;
+  }
+  return parsed;
+}
+
+// The read-time freshness core (S3): reconcile the snapshot against the live object
+// file set. Unchanged files (same mtimeMs + size) keep their cached parse; changed and
+// new files re-parse; files no longer on disk drop. Per-file checks run concurrently
+// (1000 serial stats would put CI's slow disk on the every-search path — the same
+// hardware-bound cost class the perf split exists for). Returns the current doc set
+// plus whether anything differed from the snapshot (deciding whether to re-persist).
+async function verifyAndRepair(root, snapshot) {
+  const cached = new Map((snapshot?.docs ?? []).map((d) => [d.path, d]));
+  // Retrieval set excludes the quarantined seed library (workspace-scan.js): seeds are
+  // discoverable via codex/INDEX.md + lint, never the search index.
+  const files = await listRetrievableObjectFiles(root);
+  let changed = snapshot === null;
+
+  const checked = await Promise.all(
+    files.map(async (rel) => {
+      if (!contextFor(rel)) return null; // not a typed object (codex/INDEX.md)
+      const prior = cached.get(rel);
+      if (prior) {
+        let st;
+        try {
+          st = await stat(join(root, rel));
+        } catch {
+          return { rel, doc: null }; // vanished between listing and stat
+        }
+        if (prior.mtimeMs === st.mtimeMs && prior.ctimeMs === st.ctimeMs && prior.size === st.size) {
+          return { rel, doc: prior, reused: true };
+        }
+      }
+      return { rel, doc: await parseDoc(root, rel) };
+    }),
+  );
+
+  const docs = [];
+  for (const entry of checked) {
+    if (entry === null) continue;
+    cached.delete(entry.rel);
+    if (!entry.reused) changed = true; // new, modified, or newly unparseable
+    if (entry.doc) docs.push(entry.doc);
+  }
+  if (cached.size > 0) changed = true; // deletions
+  docs.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+  return { docs, changed };
+}
+
+// Atomic persist (the core-0003 artifact rule): write a pid+random temp beside the
+// destination, rename only after success, remove the partial on any failure.
+async function persistSnapshot(root, docs) {
+  const file = snapshotPath(root);
+  await mkdir(dirname(file), { recursive: true }); // created on demand — never scaffolded
+  const tmp = `${file}.partial-${process.pid}-${randomBytes(4).toString('hex')}`;
+  try {
+    await writeFile(tmp, JSON.stringify({ schema_version: SNAPSHOT_VERSION, docs }));
+    await rename(tmp, file);
+  } catch (err) {
+    await rm(tmp, { force: true });
+    throw err;
+  }
+}
+
+// --- Stage 1: the BM25 index over snapshot docs -----------------------------------------
+
+// `type` is deliberately NOT an indexed field: it is a returned facet. Indexing it
+// would make every ontology noun ("decision", "project", "person") match every object
+// of that type, flooding results with score-tied noise and making the honest negative
+// (`empty_result: true`) unreachable for exactly the vocabulary operators use most —
+// found by core-0014's adversarial review, pinned by the type-noun test.
+function buildLunrIndex(docs) {
+  return lunr(function () {
+    this.ref('path');
+    this.field('title', { boost: 8 });
+    this.field('name', { boost: 6 });
+    this.field('body');
+    this.metadataWhitelist = ['position'];
+    for (const d of docs) {
+      this.add({
+        path: d.path,
+        title: d.title ?? '',
+        name: d.name ?? '',
+        body: d.body,
+      });
+    }
+  });
+}
+
+// Free-text queries go through lunr.tokenizer + lunr.trimmer + Query.term — NEVER
+// idx.search(raw): the query-string parser assigns syntax to ':'/'~'/'^'/'-', so an
+// ordinary operator question ("what's next: the plan?") would throw QueryParseError.
+// Two pipeline facts decide this shape (both bitten in this packet's own build):
+// Index.query DOES run each clause through the search pipeline (stemmer) — pre-stemming
+// here would double-stem ("decision"→"decis"→"deci", silent recall loss) — but the
+// TRIMMER lives only in the build pipeline, so punctuation must be stripped here or
+// "plan?" never matches the indexed "plan".
+function lunrHits(index, queryStr) {
+  const terms = lunr
+    .tokenizer(String(queryStr ?? ''))
+    .map((token) => lunr.trimmer(token).toString())
+    .filter((term) => term !== '');
+  if (terms.length === 0) return []; // nothing queryable — the honest negative
+  return index.query((q) => {
+    for (const term of terms) q.term(term);
+  });
+}
+
+// Extract a readable snippet around the first body match. Positions refer to the
+// ORIGINAL body string, so the window is cut first and whitespace collapsed after.
+// Title/name-only matches fall back to the body's opening line(s).
+function makeSnippet(body, matchData) {
+  let pos = null;
+  for (const term of Object.keys(matchData?.metadata ?? {})) {
+    const positions = matchData.metadata[term]?.body?.position;
+    if (Array.isArray(positions) && positions.length > 0) {
+      if (pos === null || positions[0][0] < pos[0]) pos = positions[0];
+    }
+  }
+  let raw;
+  let leading = false;
+  let trailing = false;
+  if (pos === null) {
+    raw = body.slice(0, SNIPPET_BEFORE + SNIPPET_AFTER);
+    trailing = body.length > raw.length;
+  } else {
+    const start = Math.max(0, pos[0] - SNIPPET_BEFORE);
+    const end = Math.min(body.length, pos[0] + pos[1] + SNIPPET_AFTER);
+    raw = body.slice(start, end);
+    leading = start > 0;
+    trailing = end < body.length;
+  }
+  const collapsed = raw.replace(/\s+/g, ' ').trim();
+  if (collapsed === '') return '';
+  return `${leading ? '… ' : ''}${collapsed}${trailing ? ' …' : ''}`;
+}
+
+// --- The search index --------------------------------------------------------------------
+
+export class SearchIndex {
+  constructor({ root, scope, docs, scopedDocs, lunrIndex, linkIndex, allPaths, persistError }) {
+    this.root = root;
+    this.scope = scope; // { domains: [slug…], codex: true, all_domains: bool }
+    this.docs = docs; // every typed object in the install (unscoped)
+    this.scopedDocs = scopedDocs;
+    this.lunrIndex = lunrIndex;
+    this.linkIndex = linkIndex; // built over scopedDocs — Stage 2 walks the SCOPED graph
+    this.allPaths = allPaths; // install-wide path set, for the outside-scope relabel
+    this.persistError = persistError; // non-null when the cache write failed (degraded, not fatal)
+    this.byPath = new Map(scopedDocs.map((d) => [d.path, d]));
+  }
+
+  get size() {
+    return this.scopedDocs.length;
+  }
+
+  #result(hit) {
+    const doc = this.byPath.get(hit.ref);
+    return {
+      path: doc.path,
+      layer: doc.layer,
+      domain: doc.domain,
+      type: doc.type,
+      name: doc.name,
+      title: doc.title,
+      score: hit.score,
+      snippet: makeSnippet(doc.body, hit.matchData),
+      exposure: doc.exposure,
+      status: doc.status,
+    };
+  }
+
+  // The library IS the contract surface (S1) — the context server calls these methods
+  // directly, so the semantics live here, not in CLI parse. A bad limit/hops must
+  // refuse: silently clamping limit 0 to an empty result would emit `empty_result:
+  // true` — a machine-checkable claim that "no workspace state matched" — when state
+  // matched (a lying honest negative, found by the adversarial review).
+  #checkLimit(limit) {
+    if (!Number.isInteger(limit) || limit < 1) {
+      throw new Error(`limit must be a positive integer (got ${JSON.stringify(limit)})`);
+    }
+  }
+
+  // Stage 1 — the `phronesis search` surface (S5 envelope).
+  search(queryStr, { limit = DEFAULT_LIMIT } = {}) {
+    this.#checkLimit(limit);
+    const t0 = performance.now();
+    const results = lunrHits(this.lunrIndex, queryStr)
+      .slice(0, limit)
+      .map((hit) => this.#result(hit));
+    return {
+      query: String(queryStr ?? ''),
+      scope: this.scope,
+      results,
+      empty_result: results.length === 0,
+      latency_ms: Math.round(performance.now() - t0),
+    };
+  }
+
+  // Stage 1+2 — the `phronesis query` surface: each BM25 seed expands through typed
+  // links; `sources` are the raw-form leaves of that result's subgraph (the cited raw
+  // sources). An edge to an object that EXISTS outside the scope is relabeled
+  // `outside-scope` (it is real, just not traversed) — distinct from `unresolved`.
+  // Raw leaves are NEVER scope-relabeled, by decision: a raw source is the citing
+  // object's provenance, and the citing object is in scope — hiding a cross-domain
+  // raw citation would hide where an in-scope claim came from.
+  query(queryStr, { limit = DEFAULT_LIMIT, hops = DEFAULT_HOPS } = {}) {
+    this.#checkLimit(limit);
+    if (!Number.isInteger(hops) || hops < 0) {
+      throw new Error(`hops must be a non-negative integer (got ${JSON.stringify(hops)})`);
+    }
+    const t0 = performance.now();
+    const results = lunrHits(this.lunrIndex, queryStr)
+      .slice(0, limit)
+      .map((hit) => {
+        const result = this.#result(hit);
+        const subgraph = this.linkIndex.walk(result.path, { hops, direction: 'both' });
+        for (const node of subgraph.nodes) {
+          if (node.kind === 'unresolved' && this.allPaths.has(node.path)) {
+            node.kind = 'outside-scope';
+          }
+        }
+        result.subgraph = subgraph;
+        result.sources = subgraph.nodes.filter((n) => n.kind === 'raw').map((n) => n.path);
+        return result;
+      });
+    return {
+      query: String(queryStr ?? ''),
+      scope: this.scope,
+      hops,
+      results,
+      empty_result: results.length === 0,
+      latency_ms: Math.round(performance.now() - t0),
+    };
+  }
+}
+
+// --- Loading -----------------------------------------------------------------------------
+
+// Search reads ONLY the registry's `domains` key (scope resolution). Deliberate: the
+// action layer's all-or-nothing registry policy protects a permission lattice; retrieval
+// is read-only and permission-free, so a broken `action_types` section must not take
+// search down with it. But the registry IS domain truth here exactly as it is on the
+// action spine — a registry that does not parse, or parses to a non-object, refuses
+// with the real reason (never a misleading "domain not registered").
+async function readDomainsRegistry(root) {
+  let raw;
+  try {
+    raw = await readFile(join(root, '.phronesis', 'registry.json'), 'utf8');
+  } catch (err) {
+    throw new Error(`cannot read .phronesis/registry.json: ${err.message}`);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error('.phronesis/registry.json is not valid JSON — cannot resolve the domain scope.');
+  }
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error('.phronesis/registry.json is malformed (expected an object) — cannot resolve the domain scope.');
+  }
+  return parsed;
+}
+
+// Both scope shapes filter by the REGISTERED domain list — `--all-domains` widens to
+// every registered domain, never to "whatever directories exist on disk". A stray
+// unregistered domains/{slug}/ tree stays invisible exactly as it is to the action
+// spine; a flag that widens scope widens the LOCATION SET, not the registration check
+// (the core-0006 --dir lesson, applied to scope — found by the adversarial review).
+function filterScope(docs, domains) {
+  return docs.filter((d) => {
+    // The shared layer is always in scope — but only the operator's EARNED codex.
+    // codex/seed/ is quarantined out of retrieval until adopted (compile-retrieve-loop
+    // §"Seed-vs-personal quarantine"): this surface feeds the guard's pre-answer
+    // packets as the operator's own prior state, and unadopted seed surfacing there is
+    // the named folklore-drift failure mode. Seed discoverability belongs to
+    // codex/INDEX.md and the T5.4 lint, not to retrieval; an explicit seed-browse mode
+    // would be its own future contract. Found by the PR codex review (P1).
+    if (d.layer === 'codex') return d.codexKind === 'personal';
+    return domains.includes(d.domain);
+  });
+}
+
+// Load the search index for an installation: resolve the install (marker-checked --dir
+// or walk-up — fail-closed, the core-0006 rule), verify-and-repair the snapshot (S3),
+// scope it (S4), and build the in-memory Stage 1 + Stage 2 indexes.
+export async function loadSearchIndex({
+  dir,
+  installRoot,
+  cwd = process.cwd(),
+  domain,
+  allDomains = false,
+  includeArtifacts = false,
+  persist = true,
+} = {}) {
+  let root = installRoot;
+  if (!root) {
+    const resolved = resolveInstall({ dir, cwd });
+    if (resolved.error) throw new Error(resolved.error);
+    root = resolved.root;
+  }
+
+  // Domain truth resolves BEFORE any snapshot write: a command that refuses on a
+  // corrupt/unresolvable registry must not mutate even derived state on the way out
+  // (the marker-check posture, applied to the cache — PR codex review P3).
+  const registry = await readDomainsRegistry(root);
+  const registered = Array.isArray(registry.domains) ? [...registry.domains].sort() : [];
+  let scope;
+  if (allDomains) {
+    scope = { domains: registered, codex: true, all_domains: true };
+  } else {
+    const slug = resolveDomain({ installRoot: root, registry, domain, cwd });
+    scope = { domains: [slug], codex: true, all_domains: false };
+  }
+
+  const { docs, changed } = await verifyAndRepair(root, await readSnapshot(root));
+
+  let persistError = null;
+  if (persist && changed) {
+    try {
+      await persistSnapshot(root, docs);
+    } catch (err) {
+      persistError = err.message; // degraded cache, working retrieval (read-only checkout)
+    }
+  }
+
+  // Artifacts are excluded from the persisted machine index by contract. An explicit
+  // request reads them directly into this in-memory invocation only, so a normal
+  // search can never accidentally pick up a PRD and a rebuild remains compiled+codex.
+  const artifactDocs = includeArtifacts
+    ? (await Promise.all((await listArtifactFiles(root)).map((rel) => readArtifactRecord(root, rel)))).filter(Boolean)
+    : [];
+  const searchableDocs = [...docs, ...artifactDocs];
+  const scopedDocs = filterScope(searchableDocs, scope.domains);
+  const records = scopedDocs.map((d) => ({
+    rel: d.path,
+    ctx: { layer: d.layer, domain: d.domain, codexKind: d.codexKind, name: d.name, typeDir: null },
+    fm: {
+      type: d.type,
+      name: d.name,
+      title: d.title,
+      status: d.status,
+      exposure: d.exposure,
+      stance: d.stance,
+      links: d.links,
+    },
+  }));
+
+  return new SearchIndex({
+    root,
+    scope,
+    docs: searchableDocs,
+    scopedDocs,
+    lunrIndex: buildLunrIndex(scopedDocs),
+    linkIndex: buildLinkIndexFromRecords(records, root),
+    // The outside-scope relabel universe is REGISTERED domains + codex (seed
+    // included: a link to seed resolves to real install content that retrieval
+    // quarantines — "outside-scope" is the honest label). An unregistered stray tree
+    // is NOT in the universe, so links into it stay "unresolved": the registry is
+    // domain truth here exactly as on the action spine, and leaf labels must not
+    // advertise phantom trees as scoped-out install state (PR codex review P2).
+    // Seeds are quarantined out of searchableDocs (they never enter the search/link
+    // index — workspace-scan listRetrievableObjectFiles), so their paths are added
+    // back into the relabel universe directly: a link INTO a seed is real, immutable,
+    // quarantined content — "outside-scope", never the typo signal "unresolved" (T5.4).
+    allPaths: new Set([
+      ...searchableDocs.filter((d) => d.layer === 'codex' || registered.includes(d.domain)).map((d) => d.path),
+      ...(await walkMarkdown(root, join(root, 'codex', 'seed'))).filter(
+        (rel) => contextFor(rel)?.codexKind === 'seed',
+      ),
+    ]),
+    persistError,
+  });
+}
+
+// `phronesis index rebuild` (change 0008): regenerate the machine index from
+// compiled/ + codex/, ignoring any existing snapshot. Unlike the search-path cache
+// write, a rebuild that cannot persist FAILS — the artifact is this command's job.
+export async function rebuildSearchIndex({ dir, installRoot, cwd = process.cwd() } = {}) {
+  let root = installRoot;
+  if (!root) {
+    const resolved = resolveInstall({ dir, cwd });
+    if (resolved.error) throw new Error(resolved.error);
+    root = resolved.root;
+  }
+  const t0 = performance.now();
+  const { docs } = await verifyAndRepair(root, null);
+  await persistSnapshot(root, docs);
+  return { root, objects: docs.length, ms: Math.round(performance.now() - t0) };
+}

package/vendor/core/src/session-hooks.js

@@ -0,0 +1,129 @@
+// Session-boundary hook support (core-0013; change 0010 D4; packet decisions H5/H7/H8).
+//
+// Two deterministic halves of the Tier-1 (Claude Code) session hooks:
+//
+//   due-check (session start) — computes due `review_date`s across every domain's
+//   decisions and emits `outcome.due` per due decision through core appendEvent: the V1
+//   authoritative emitter per the ratified 0010 delta (event-log.md `outcome.due` row;
+//   the daemon's date-watch takes over at V1.5). Re-emission per session start is the
+//   spec's own UX — review surfaces "at next session start" — so there is no dedup.
+//
+//   sweep status (session end/compact) — answers "has this session emitted its capture
+//   sweep marker?". The marker is `session.end` with a `sweep` payload object (H5:
+//   existing vocabulary, no invented type); `sweep.candidates: 0` is the honest
+//   negative. The JUDGMENT half of the sweep ("what should have been stored?") is the
+//   model's, prompted by the scaffolded Stop hook — a shell script cannot judge, so the
+//   deterministic half is exactly this: force the question, verify the marker.
+
+import { join, sep } from 'node:path';
+import { readFile } from 'node:fs/promises';
+import yaml from 'js-yaml';
+import { walkMarkdown, splitFrontmatter } from './workspace-scan.js';
+import { DATE_RE } from './contract.js';
+import { appendEvent, readEvents, localDateStamp } from './event-log.js';
+
+function isPlainObject(v) {
+  return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+
+// Days between two YYYY-MM-DD stamps (UTC date math — both are local-calendar stamps,
+// so the difference is exact whole days).
+function daysBetween(fromStamp, toStamp) {
+  const toUtc = (s) => {
+    const [y, m, d] = s.split('-').map(Number);
+    return Date.UTC(y, m - 1, d);
+  };
+  return Math.round((toUtc(toStamp) - toUtc(fromStamp)) / 86_400_000);
+}
+
+// Every decision whose review obligation is open and due: `review_date <= today` with no
+// `outcome_status` (a recorded outcome ends the obligation). Scans ALL domains — the
+// session-start surface is install-wide. Non-parsing files are skipped: the due-check is
+// a read-only reporter, and `phronesis validate` owns contract enforcement.
+export async function computeDueDecisions({ installRoot, now = new Date() } = {}) {
+  const today = localDateStamp(now);
+  const due = [];
+  const files = (await walkMarkdown(installRoot, join(installRoot, 'domains'))).filter((p) => {
+    const parts = p.split(sep);
+    return parts[2] === 'compiled' && parts[3] === 'decisions';
+  });
+  for (const relPath of files.sort()) {
+    let fm;
+    try {
+      const content = await readFile(join(installRoot, relPath), 'utf8');
+      const yamlSource = splitFrontmatter(content);
+      if (yamlSource === null) continue;
+      fm = yaml.load(yamlSource, { schema: yaml.JSON_SCHEMA });
+    } catch {
+      continue;
+    }
+    if (!isPlainObject(fm)) continue;
+    if (typeof fm.review_date !== 'string' || !DATE_RE.test(fm.review_date)) continue;
+    // Only a RECORDED outcome ends the review obligation: a non-empty string is what
+    // record_outcome writes. `outcome_status: null` (or any junk value) must not
+    // silently kill the obligation — null is present-and-invalid, never "recorded"
+    // (rules.md; the validator owns flagging the junk itself).
+    if (typeof fm.outcome_status === 'string' && fm.outcome_status.trim() !== '') continue;
+    if (fm.review_date > today) continue;
+    due.push({
+      decision_path: relPath,
+      review_date: fm.review_date,
+      days_overdue: daysBetween(fm.review_date, today),
+      title: typeof fm.title === 'string' ? fm.title : fm.name,
+    });
+  }
+  return due;
+}
+
+// Compute + emit: one `outcome.due` per due decision, through the authoritative core
+// path (H3 — the same appendEvent the V1.5 daemon will drive). Returns the due list and
+// the stored events.
+export async function runDueCheck({
+  installRoot,
+  session,
+  actor = 'agent',
+  surface = 'cli',
+  now = new Date(),
+} = {}) {
+  if (typeof session !== 'string' || session === '') {
+    throw new Error('due-check: session is required (a non-empty session id).');
+  }
+  const due = await computeDueDecisions({ installRoot, now });
+  const events = [];
+  for (const d of due) {
+    events.push(
+      await appendEvent({
+        installRoot,
+        type: 'outcome.due',
+        session_id: session,
+        actor,
+        surface,
+        payload: { decision_path: d.decision_path, days_overdue: d.days_overdue },
+        now,
+      }),
+    );
+  }
+  return { due, events };
+}
+
+// Has this session emitted its sweep marker (`session.end` with a `sweep` payload
+// object)? A marker only counts when `sweep.candidates` is a non-negative integer —
+// the count IS the sweep's answer, and `{ sweep: {} }` answering the Stop gate would
+// be an invalid marker satisfying the very check the model is held to (fail closed).
+// Returns the latest marker's count so callers can report the honest negative
+// distinctly from a candidate-bearing sweep.
+export async function sweepStatus({ installRoot, session } = {}) {
+  if (typeof session !== 'string' || session === '') {
+    throw new Error('sweep-status: session is required (a non-empty session id).');
+  }
+  const markers = (await readEvents({ installRoot, type: 'session.end' })).filter(
+    (ev) =>
+      ev.session_id === session &&
+      isPlainObject(ev.payload) &&
+      isPlainObject(ev.payload.sweep) &&
+      Number.isInteger(ev.payload.sweep.candidates) &&
+      ev.payload.sweep.candidates >= 0,
+  );
+  if (!markers.length) return { swept: false };
+  return { swept: true, candidates: markers[markers.length - 1].payload.sweep.candidates };
+}