create-evda 0.1.5 → 0.1.7

package/lib/grants.mjs

@@ -63,6 +63,9 @@ export function grantManifest({ to, circle, role = "viewer", by, at = new Date()
   if (!MEMBER_ROLES.includes(role)) throw new EvdaError(`role must be one of ${MEMBER_ROLES.join(", ")}, got ${JSON.stringify(role)}.`, { exit: 2 });
   if (to.kind === "agent" && role !== "viewer") throw new EvdaError(`REFUSED: an agent holds viewer and nothing else. It reads a circle; it does not hold one (Spec 00 #65).`, { code: "AGENT_ROLE", exit: 2 });
   if (!nonEmpty(by)) throw new EvdaError("a grant says who granted it (grantedBy).", { exit: 2 });
+  // The substrate's Member refuses an eco holding "--", its filename delimiter, so a grant on such a
+  // circle would be a file no substrate reader opens (HQ-1406).
+  if (typeof circle !== "string" || circle.includes("--")) throw new EvdaError(`REFUSED: a circle named ${JSON.stringify(circle)} cannot be granted: "--" separates the reader from the circle in a grant's name. Rename the circle.`, { code: "BAD_CIRCLE_NAME", exit: 2 });
   const eco = ecoNamespace(circle);
   const m = {
     id: grantId(principalId, eco),
@@ -108,7 +111,10 @@ export function readGrants(evda) {
     if (!isObject(m)) { fail("must hold a mapping."); continue; }
     g.manifest = m;
     const slug = name.slice(0, -GRANT_SUFFIX.length);
-    const sep = slug.indexOf("--");
+    // A principal id may end in "-" ("a-" granted "a" is `a---a`), so the first "--" is not always
+    // the delimiter: read the name as the manifest's principalId when it starts the name (HQ-1406).
+    const own = nonEmpty(m.principalId) && slug.startsWith(`${m.principalId}--`) ? m.principalId.length : -1;
+    const sep = own > 0 ? own : slug.indexOf("--");
     const fromName = sep > 0 ? { principalId: slug.slice(0, sep), eco: slug.slice(sep + 2) } : null;
     if (!fromName) fail(`is not named <principalId>--<circle>.eco${GRANT_SUFFIX}.`);
     if (m.kind !== "member") fail(`"kind" must be "member", got ${JSON.stringify(m.kind)}. A grant is the substrate's member tuple.`);

package/lib/guard.mjs

@@ -0,0 +1,132 @@
+// The read guard for Claude Code (HQ-1374): a PreToolUse hook that refuses Read, Grep and the
+// ordinary shell reads (cat, head, grep and the rest) of a just-noted entry, or of a file whose
+// circle is set to be read by an AI other than Claude.
+//
+// It is the Claude Code half of "agents decline on their own end". The MCP server refuses in code
+// (lib/tools.mjs), AGENTS.md tells every other agent to check, and this catches the file tools an
+// agent reaches for when it is working in the folder instead of through the server. It is a guard
+// on the ordinary paths, not a sandbox: a shell command built to hide what it opens gets past it,
+// and says nothing about the files it opened. The words are the owner's plain files on their own
+// disk, and the claim is only that a cooperating agent is stopped before it reads, with a reason.
+//
+// Installed per record by create-evda, into <record>/.claude/settings.json, for owners who chose
+// Claude. Claude Code runs it with the tool call as JSON on stdin; it answers with a
+// permissionDecision on stdout (https://code.claude.com/docs/en/hooks, PreToolUse). Anything it
+// cannot parse is allowed, because a guard that blocks every tool on a malformed input blocks the
+// owner's own work, and the refusals it exists for are the ones it can name.
+//
+//   EVDA_GUARD_FALSIFY=allow-all   every decision is allow, so the tests can be watched failing
+//
+// FALSIFIED 2026-09-22, in a real Claude Code session (claude -p, haiku) on a fresh create-evda
+// record with one `evda note`, AGENTS.md and CLAUDE.md moved aside so only the hook could stop it:
+//   asked to Read the noted capture -> it answered "You have a just-noted entry at
+//   record/captures/2026-09-22-1900-noted.md that you can open yourself", and never printed it.
+//   The same prompt with EVDA_GUARD_FALSIFY=allow-all -> it quoted the canary line verbatim.
+
+import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve, sep } from "node:path";
+import { findRoot, openEvda } from "./manifest.mjs";
+import { readContext, mayRead, callerFrom, SEALED_WHY } from "./readers.mjs";
+import { markdownFiles, sealedSections } from "./circles.mjs";
+
+// Shell commands that read what they are pointed at. A path token in a command outside this list
+// (ls, mv, git add) is not a read of the file's words.
+const READERS = /(^|[\s;&|(`])(cat|head|tail|less|more|bat|grep|egrep|fgrep|rg|ag|ack|awk|sed|cut|sort|uniq|wc|strings|xxd|od|hexdump|base64|tar|zip|cp|rsync|scp|curl|nl|tac|diff|cmp|jq|yq|python3?|node|ruby|perl|open)(\s|$)/;
+
+const real = (p) => { try { return realpathSync(p); } catch { return resolve(p); } };
+
+function recordOf(abs) {
+  let start = abs;
+  try { if (!statSync(abs).isDirectory()) start = dirname(abs); } catch { start = dirname(abs); }
+  const root = findRoot(start);
+  if (!root) return null;
+  try { return openEvda(real(root)); } catch { return null; }
+}
+
+// The refusals for one path: the file itself, or every markdown file under a directory.
+function refusalsFor(abs, caller) {
+  const evda = recordOf(abs);
+  if (!evda) return [];
+  const target = real(abs);
+  if (!target.startsWith(evda.dir + sep) && target !== evda.dir) return [];
+  const ctx = readContext(evda);
+  let isDir = false;
+  try { isDir = statSync(target).isDirectory(); } catch { return []; }
+  const files = isDir ? markdownFiles(target) : [target];
+  const out = [];
+  for (const f of files) {
+    const may = mayRead(ctx, f, caller);
+    if (!may.ok) { out.push(may); continue; }
+    // A file holding a sealed section (HQ-1220): Read and cat cannot leave the section out, so the
+    // whole read is refused; evda_read returns the file without it.
+    if (/\.md$/i.test(f)) {
+      let text = "";
+      try { text = readFileSync(f, "utf8"); } catch { /* unreadable: nothing to hold back */ }
+      if (sealedSections(text).length) out.push({ ok: false, kind: "sealed", section: true, why: "It holds a sealed section, which only its owner opens, on their own devices. The evda MCP tool evda_read returns the file without it." });
+    }
+  }
+  return out;
+}
+
+// Words in a shell command that could be paths, quotes stripped. A glob keeps the part before its
+// first wildcard, so `cat record/captures/*` is checked as the folder it expands in.
+export function shellPaths(command) {
+  const words = String(command).match(/"[^"]*"|'[^']*'|[^\s;&|<>()`]+/g) ?? [];
+  return words
+    .map((w) => w.replace(/^["']|["']$/g, ""))
+    .filter((w) => w && !w.startsWith("-") && !/^[A-Za-z_][A-Za-z0-9_]*=/.test(w))
+    .map((w) => (/[*?[]/.test(w) ? w.slice(0, w.search(/[*?[]/)).replace(/\/[^/]*$/, "") || "." : w));
+}
+
+// A sealed refusal is counted and never named: its path is not in the sentence (HQ-1220).
+function sentence(refused, tool) {
+  const sealedAll = refused.filter((r) => r.kind === "sealed");
+  const sealed = sealedAll.length;
+  const named = refused.filter((r) => r.kind !== "sealed");
+  const noted = named.filter((r) => r.kind === "noted").length;
+  const other = named.length - noted;
+  const first = named[0] ?? { why: sealedAll.every((r) => r.section) ? sealedAll[0].why : SEALED_WHY };
+  const parts = [];
+  if (sealed) parts.push(`${sealed} sealed entr${sealed === 1 ? "y" : "ies"}`);
+  if (noted) parts.push(`${noted} just-noted entr${noted === 1 ? "y" : "ies"}`);
+  if (other) parts.push(`${other} file(s) set to be read by a different AI`);
+  const many = named.length > 1 ? ` (${named.slice(0, 5).map((r) => r.path).join(", ")}${named.length > 5 ? ", ..." : ""})` : "";
+  const narrow = tool === "Read" ? "" : " Narrow the path so it leaves them out, or search with the evda MCP tool evda_search, which skips them.";
+  return `EVÐA: this would read ${parts.join(" and ")}${many}. ${first.why}${narrow} Tell the owner in one plain sentence what is there and how they open it.`;
+}
+
+// The decision for one PreToolUse input. { decision: "allow" } or { decision: "deny", reason }.
+export function decide(input, { env = process.env } = {}) {
+  if (env.EVDA_GUARD_FALSIFY === "allow-all") return { decision: "allow" };
+  const tool = input?.tool_name;
+  const args = input?.tool_input ?? {};
+  const cwd = typeof input?.cwd === "string" && input.cwd ? input.cwd : process.cwd();
+  const at = (p) => (isAbsolute(p) ? p : join(cwd, p));
+  // A hook reads the tool call; Claude Code is the caller, unless the owner said otherwise.
+  const caller = callerFrom({ clientName: "claude-code", env });
+  let paths = [];
+  if (tool === "Read" || tool === "NotebookRead") paths = [args.file_path ?? args.notebook_path].filter(Boolean);
+  else if (tool === "Grep") paths = [args.path ?? cwd];
+  else if (tool === "Bash") {
+    const command = String(args.command ?? "");
+    if (!READERS.test(command)) return { decision: "allow" };
+    paths = shellPaths(command).filter((p) => existsSync(at(p)));
+  } else return { decision: "allow" };
+  const refused = [];
+  for (const p of paths) refused.push(...refusalsFor(at(p), caller));
+  if (!refused.length) return { decision: "allow" };
+  return { decision: "deny", reason: sentence(refused, tool) };
+}
+
+// The hook's whole life: read stdin, answer on stdout, exit 0.
+export async function runHook({ stdin = process.stdin, stdout = process.stdout, env = process.env } = {}) {
+  let raw = "";
+  for await (const chunk of stdin) raw += chunk;
+  let input;
+  try { input = JSON.parse(raw); } catch { return 0; }
+  const d = decide(input, { env });
+  if (d.decision === "deny") {
+    stdout.write(JSON.stringify({ hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "deny", permissionDecisionReason: d.reason } }) + "\n");
+  }
+  return 0;
+}

package/lib/hooks.mjs

@@ -0,0 +1,124 @@
+// Installing the Claude Code hooks into a record, and saying whether each is installed. Project
+// level only: the record's own .claude/settings.json and .claude/hooks/, never the owner's
+// ~/.claude/settings.json, so they run in sessions opened in the record and nowhere else.
+//
+//   keep-record   a Stop hook (lib/keep-hook.mjs, HQ-1376): a session that read the record or heard
+//                 the owner out and filed nothing is asked once before it stops.
+//   file-prompt   a UserPromptSubmit hook (lib/prompt-hook.mjs, HQ-1385): each message the owner
+//                 sends is filed verbatim, deterministically. Installed only when evda.json says
+//                 "filing": "everything"; `installPromptHook` refuses otherwise.
+//
+// The hook files are copied, not referenced: `npx create-evda` runs from a cache that is gone after
+// the command, and a settings line pointing into it would fail every call. Each hook imports only
+// node: built-ins and the files copied beside it (lib/day-file.mjs, lib/secret-shape.mjs). Every
+// copy is compared to the shipped file by `evda doctor`, and `evda hook install` refreshes them.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { HOOK_NAME } from "./keep-hook.mjs";
+import { PROMPT_HOOK_NAME } from "./prompt-hook.mjs";
+import { filingOf } from "./day-file.mjs";
+import { EvdaError } from "./errors.mjs";
+
+const LIB = dirname(fileURLToPath(import.meta.url));
+export const SHIPPED_HOOK = join(LIB, "keep-hook.mjs");
+export const HOOK_REL = `.claude/hooks/${HOOK_NAME}`;
+export const PROMPT_HOOK_REL = `.claude/hooks/${PROMPT_HOOK_NAME}`;
+export const SETTINGS_REL = ".claude/settings.json";
+export const HOOK_COMMAND = `node "$CLAUDE_PROJECT_DIR/${HOOK_REL}"`;
+export const PROMPT_HOOK_COMMAND = `node "$CLAUDE_PROJECT_DIR/${PROMPT_HOOK_REL}"`;
+
+// What each hook copies: [shipped file in lib/, path in the record]. The first is the hook itself.
+export const HOOK_FILES = {
+  keep: [["keep-hook.mjs", HOOK_REL], ["day-file.mjs", ".claude/hooks/day-file.mjs"]],
+  prompt: [["prompt-hook.mjs", PROMPT_HOOK_REL], ["day-file.mjs", ".claude/hooks/day-file.mjs"], ["secret-shape.mjs", ".claude/hooks/secret-shape.mjs"]],
+};
+
+function readSettings(dir) {
+  const p = join(dir, SETTINGS_REL);
+  if (!existsSync(p)) return { path: p, settings: {} };
+  try {
+    const settings = JSON.parse(readFileSync(p, "utf8"));
+    if (settings === null || typeof settings !== "object" || Array.isArray(settings)) throw new Error("not an object");
+    return { path: p, settings };
+  } catch (e) {
+    throw new EvdaError(`REFUSED: ${SETTINGS_REL} is not a JSON object (${e.message}), so the hook was not added to it. Nothing was written.`, { code: "BAD_SETTINGS", exit: 2 });
+  }
+}
+
+const registeredIn = (settings, event, name) => (settings?.hooks?.[event] ?? []).some((g) => (g?.hooks ?? []).some((h) => typeof h?.command === "string" && h.command.includes(name)));
+
+// Copy a hook's files; returns what the first (the hook) was before: null, same, or different.
+function copyFiles(dir, files) {
+  let state = "current";
+  files.forEach(([src, rel], i) => {
+    const shipped = readFileSync(join(LIB, src));
+    const abs = join(dir, rel);
+    const before = existsSync(abs) ? readFileSync(abs) : null;
+    if (i === 0) state = !before ? "absent" : before.equals(shipped) ? "current" : "stale";
+    else if (state === "current" && (!before || !before.equals(shipped))) state = "stale";
+    mkdirSync(dirname(abs), { recursive: true });
+    if (!before || !before.equals(shipped)) writeFileSync(abs, shipped);
+  });
+  return state;
+}
+
+function register(dir, event, name, command, timeout) {
+  const { path, settings } = readSettings(dir);
+  if (registeredIn(settings, event, name)) return false;
+  settings.hooks ??= {};
+  settings.hooks[event] ??= [];
+  settings.hooks[event].push({ hooks: [{ type: "command", command, timeout }] });
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, JSON.stringify(settings, null, 2) + "\n");
+  return true;
+}
+
+const actionFor = (added, state) => (added ? "installed" : state === "absent" ? "restored the hook file" : state === "current" ? "already installed, current" : "updated the hook file");
+
+// Copy the keep-record hook and register it. Idempotent: a second run refreshes the copies and adds
+// nothing to settings. Every other key and hook in the settings file is kept as it was.
+export function installHook(dir) {
+  readSettings(dir);
+  const state = copyFiles(dir, HOOK_FILES.keep);
+  const added = register(dir, "Stop", HOOK_NAME, HOOK_COMMAND, 30);
+  return { action: actionFor(added, state), hook: HOOK_REL, settings: SETTINGS_REL };
+}
+
+// The prompt hook, only for an owner who chose to have everything filed. Refused otherwise, with
+// nothing written: it files every message, and that is the owner's answer to give.
+export function installPromptHook(dir) {
+  const manifest = JSON.parse(readFileSync(join(dir, "evda.json"), "utf8"));
+  const filing = filingOf(manifest);
+  if (filing !== "everything") throw new EvdaError(`REFUSED: evda.json says ${filing ? `"filing": "${filing}"` : "nothing about filing"}, and the prompt hook files every message the owner sends, so it is installed only when they chose "everything". Nothing was written.`, { code: "FILING_NOT_EVERYTHING", exit: 2 });
+  readSettings(dir);
+  const state = copyFiles(dir, HOOK_FILES.prompt);
+  const added = register(dir, "UserPromptSubmit", PROMPT_HOOK_NAME, PROMPT_HOOK_COMMAND, 10);
+  return { action: actionFor(added, state), hook: PROMPT_HOOK_REL, settings: SETTINGS_REL };
+}
+
+// { registered, file, current, problem } for doctor. Never throws: an unreadable settings file is
+// reported. `current` needs every copied file to match what ships.
+function statusOf(dir, event, name, files) {
+  const hookAbs = join(dir, files[0][1]);
+  let reg = false;
+  let problem = null;
+  try { reg = registeredIn(readSettings(dir).settings, event, name); } catch (e) { problem = e.message; }
+  const file = existsSync(hookAbs);
+  const current = file && files.every(([src, rel]) => existsSync(join(dir, rel)) && readFileSync(join(dir, rel)).equals(readFileSync(join(LIB, src))));
+  return { registered: reg, file, current, problem };
+}
+
+const blind = () => (process.env.EVDA_HOOKS_FALSIFY ?? "").split(",").map((x) => x.trim()).includes("blind");
+
+// EVDA_HOOKS_FALSIFY=blind (HQ-1377) reports it absent, as lib/connect.mjs guardStatus does.
+export function hookStatus(dir) {
+  if (blind()) return { registered: false, file: false, current: false, problem: null };
+  return statusOf(dir, "Stop", HOOK_NAME, HOOK_FILES.keep);
+}
+
+export function promptHookStatus(dir) {
+  if (blind()) return { registered: false, file: false, current: false, problem: null };
+  return statusOf(dir, "UserPromptSubmit", PROMPT_HOOK_NAME, HOOK_FILES.prompt);
+}

package/lib/keep-hook.mjs

@@ -0,0 +1,185 @@
+#!/usr/bin/env node
+// The record keeps itself, in Claude Code: a Stop hook that asks once before a session goes quiet
+// having read the record, or heard the owner out, and filed nothing to the day's record (HQ-1376).
+//
+// Mike, 2026-09-22: "So will it always be updating your EVÐA naturally? You don't have to tell it
+// to do that." The instruction to file in the same turn is a prompt, and a prompt was measured
+// failing in his own vault, which is why his vault has the HQ-1357 Stop hook this one generalizes.
+//
+// `evda hook install` (and create-evda, when the owner uses Claude) copies THIS FILE, byte for
+// byte, to <record>/.claude/hooks/evda-keep-record.mjs and registers it in the record's own
+// .claude/settings.json. Project level only: it runs in sessions opened in the record and nowhere
+// else, and the owner's global settings are never touched. Because the file is copied, it imports
+// node: built-ins and lib/day-file.mjs, which is copied beside it; `evda doctor` compares both
+// copies to the shipped files and says when one is older.
+//
+// FILING (HQ-1385): when evda.json says "filing": "asked", the owner chose to file only when they
+// ask, and this hook never blocks.
+//
+// WHAT IT DECIDES. The transcript Claude Code hands a Stop hook is read as a list of events. The
+// stretch is everything after the later of (the last write to the day's record, the last time this
+// hook blocked). Inside the stretch, the session either read the record (a tool call naming a
+// record folder, or an evda_* read tool) or had a real exchange (the owner wrote at least
+// OWNER_WORDS words). If either, and nothing in the stretch wrote to the day's record, it blocks the
+// stop once with an instruction that names the day's file. The day's file having been modified
+// since the stretch began also counts as a write, so a write by any route (the MCP server, a shell)
+// is seen.
+//
+// NEVER A LOOP. `stop_hook_active` (the continuation this hook caused) exits 0 before reading
+// anything. A block stores the event index it blocked at, so the next block needs a new stretch.
+// Any error of its own exits 0 without output: a broken hook must never trap a session.
+//
+// EVDA_RECORD_FALSIFY=no-block makes decide() never block, for the tests that show the block is
+// what the pass depends on.
+
+import { existsSync, mkdirSync, readFileSync, realpathSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { tmpdir } from "node:os";
+import { fileURLToPath } from "node:url";
+import { dayRole, findRecord, filingOf, localDate } from "./day-file.mjs";
+
+export { dayRole, findRecord };
+
+export const HOOK_NAME = "evda-keep-record.mjs";
+export const OWNER_WORDS = 20;
+
+const WRITE_TOOLS = new Set(["Write", "Edit", "MultiEdit", "NotebookEdit"]);
+const BASH_WRITE = /(>>|>\s*[^&\s]|\btee\b|\bmv\b|\bcp\b|sed -i|cat >|writeFileSync|appendFileSync|\.write_text)/;
+// MCP tools arrive as mcp__<server>__<tool>; the server name is the owner's to choose.
+const MCP_WRITE = /(^|__)evda_(write|note)$/;
+const MCP_READ = /(^|__)evda_(recent|search|read|gather_questions)$/;
+
+const falsified = (mode) => (process.env.EVDA_RECORD_FALSIFY ?? "").split(",").map((s) => s.trim()).includes(mode);
+
+// What the hook needs to know about the record: the day's folder and file, and every folder a
+// record role maps (a tool call naming one of them is a read of the record).
+export function recordFacts(root, now = new Date()) {
+  const manifest = JSON.parse(readFileSync(join(root, "evda.json"), "utf8"));
+  const mapping = manifest.mapping ?? {};
+  const role = dayRole(mapping);
+  if (!role) return null;
+  const dayRel = mapping[role].replace(/\/+$/, "");
+  const fileRel = `${dayRel}/${localDate(now)}.md`;
+  const folders = Object.entries(mapping)
+    .filter(([k, v]) => typeof v === "string" && k !== "agents" && !/^[a-z][a-z0-9-]*:/.test(v) && v.replace(/\/+$/, "") !== "")
+    .map(([, v]) => v.replace(/\/+$/, ""));
+  return { root, role, dayRel, dayAbs: join(root, dayRel), fileRel, fileAbs: join(root, fileRel), folders, filing: filingOf(manifest) };
+}
+
+function userText(d) {
+  if (d.type !== "user" || d.isMeta) return "";
+  const c = d.message?.content;
+  const parts = typeof c === "string" ? [c] : Array.isArray(c) ? c.filter((x) => x?.type === "text").map((x) => x.text ?? "") : [];
+  return parts.filter((t) => !/^\s*(<|\[Request interrupted)/.test(t)).join(" ");
+}
+
+// The transcript as events: { kind: "owner", words } for what the owner typed, and
+// { kind: "tool", name, input } for each tool call, each with its timestamp.
+export function events(transcriptText) {
+  const out = [];
+  for (const line of transcriptText.split("\n")) {
+    if (!line.trim()) continue;
+    let d;
+    try { d = JSON.parse(line); } catch { continue; }
+    const at = d.timestamp ? Date.parse(d.timestamp) : NaN;
+    const said = userText(d);
+    if (said.trim()) out.push({ kind: "owner", words: said.trim().split(/\s+/).length, at });
+    const c = d.message?.content;
+    if (d.type === "assistant" && Array.isArray(c)) {
+      for (const x of c) if (x?.type === "tool_use") out.push({ kind: "tool", name: String(x.name ?? ""), input: JSON.stringify(x.input ?? {}), at });
+    }
+  }
+  return out;
+}
+
+// Whether a tool call's input (as JSON text) names a folder, relative to the record or absolute.
+const names = (s, rel, abs) => s.includes(`${rel}/`) || s.includes(`"${rel}"`) || s.includes(abs);
+
+export function classify(e, facts) {
+  if (e.kind !== "tool") return null;
+  const { name, input } = e;
+  const toDay = names(input, facts.dayRel, facts.dayAbs);
+  if (MCP_WRITE.test(name)) return "write";
+  if (WRITE_TOOLS.has(name)) return toDay ? "write" : "other-write";
+  if (name === "Bash" && BASH_WRITE.test(input) && toDay) return "write";
+  if (MCP_READ.test(name)) return "read";
+  if (facts.folders.some((f) => names(input, f, join(facts.root, f)))) return "read";
+  return "other";
+}
+
+// The decision, pure. `lastBlock` is the event index this hook last blocked at (0 for never).
+// `fileMtime` is the day file's modification time in ms, or null when it does not exist.
+export function decide(evs, facts, { lastBlock = 0, fileMtime = null } = {}) {
+  let lastWrite = 0;
+  evs.forEach((e, i) => { if (classify(e, facts) === "write") lastWrite = i + 1; });
+  const start = Math.max(lastWrite, lastBlock);
+  const stretch = evs.slice(start);
+  const tools = stretch.filter((e) => e.kind === "tool").length;
+  const writes = stretch.filter((e) => /write$/.test(classify(e, facts) ?? "")).length;
+  const reads = stretch.filter((e) => classify(e, facts) === "read").length;
+  const words = stretch.filter((e) => e.kind === "owner").reduce((n, e) => n + e.words, 0);
+  const began = stretch.find((e) => Number.isFinite(e.at))?.at;
+  const touched = fileMtime !== null && Number.isFinite(began) && fileMtime >= began;
+  const facts_ = { tools, writes, reads, words, at: evs.length };
+  if (!stretch.length || touched) return { block: false, ...facts_ };
+  if (reads === 0 && words < OWNER_WORDS) return { block: false, ...facts_ };
+  if (falsified("no-block")) return { block: false, ...facts_ };
+  const why = reads && words >= OWNER_WORDS ? "read the record and the owner talked" : reads ? "read the record" : "the owner talked";
+  const reason = [
+    `evda: this conversation ${why}, and nothing from it is in today's record (${tools} tool call(s), ${writes} write(s), none to ${facts.fileRel}).`,
+    `Before you stop, file what the owner said that is worth keeping: their words verbatim, filler and typos intact, appended to ${facts.fileRel} under a "## HH:MM" heading or through evda_write.`,
+    "Then tell them the path in the past tense. If a person, project or place with an entry came up, add a dated section to that entry too (never to a noted one); one with no entry, offer to start it and wait for their yes.",
+    "If nothing they said is worth keeping, stop. This asks once per stretch.",
+  ].join(" ");
+  return { block: true, reason, ...facts_ };
+}
+
+function stateFile(sid) {
+  const dir = process.env.EVDA_KEEP_STATE_DIR || join(tmpdir(), "evda-keep-record");
+  mkdirSync(dir, { recursive: true });
+  return join(dir, `${String(sid).replace(/[^A-Za-z0-9_-]/g, "_")}.json`);
+}
+
+// One Stop event in, the hook's stdout out ("" for let it stop). Never throws.
+export function run(payload, { now = new Date() } = {}) {
+  try {
+    if (!payload || payload.stop_hook_active) return "";
+    const tpath = payload.transcript_path;
+    if (!tpath || !existsSync(tpath)) return "";
+    const here = dirname(fileURLToPath(import.meta.url));
+    const root = findRecord(payload.cwd || process.cwd()) ?? findRecord(here);
+    if (!root) return "";
+    const facts = recordFacts(root, now);
+    // The owner said to file only when they ask (HQ-1385): a quiet session is what they chose.
+    if (!facts || facts.filing === "asked") return "";
+    const evs = events(readFileSync(tpath, "utf8"));
+    const sf = stateFile(payload.session_id ?? "unknown");
+    let lastBlock = 0;
+    try { lastBlock = Number(JSON.parse(readFileSync(sf, "utf8")).at) || 0; } catch { /* first stop of the session */ }
+    if (lastBlock > evs.length) lastBlock = 0; // a different transcript under the same id
+    const fileMtime = existsSync(facts.fileAbs) ? statSync(facts.fileAbs).mtimeMs : null;
+    const d = decide(evs, facts, { lastBlock, fileMtime });
+    if (!d.block) return "";
+    writeFileSync(sf, JSON.stringify({ at: d.at, when: now.toISOString() }) + "\n");
+    return JSON.stringify({ decision: "block", reason: d.reason });
+  } catch {
+    return "";
+  }
+}
+
+const entry = (() => {
+  try { return process.argv[1] && realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url)); } catch { return false; }
+})();
+
+if (entry) {
+  let input = "";
+  process.stdin.setEncoding("utf8");
+  process.stdin.on("data", (d) => (input += d));
+  process.stdin.on("end", () => {
+    let payload = null;
+    try { payload = JSON.parse(input); } catch { /* not a hook call */ }
+    const out = run(payload);
+    if (out) process.stdout.write(out);
+    process.exit(0);
+  });
+}

package/lib/kinds.mjs

@@ -10,6 +10,10 @@
 //
 // Entry files: a `.json` or `.yaml` file holding one entity, or a markdown file whose frontmatter
 // carries `kind:`. For a note in markdown, the body is the words when the frontmatter has none.
+//
+// The marks an owner writes on an entry (`share:`, `noted: true`, `sealed: true`, HQ-1220) are not
+// fields of any kind: they ride on an entry of every kind, a kind reads the entry the same with or
+// without them, and doctor validates them where it validates circles (lib/circles.mjs names them).
 
 import { readFileSync } from "node:fs";
 import { parseYaml } from "./yaml.mjs";
@@ -106,6 +110,11 @@ export function isDay(value) {
   const d = new Date(Date.UTC(Number(m[1]), Number(m[2]) - 1, Number(m[3])));
   return d.getUTCFullYear() === Number(m[1]) && d.getUTCMonth() === Number(m[2]) - 1 && d.getUTCDate() === Number(m[3]);
 }
+const MONTH = /^(\d{4})-(0[1-9]|1[0-2])$/;
+export const isDayOrMonth = (value) => isDay(value) || (typeof value === "string" && MONTH.test(value));
+const sinceProblem = (path, v) => (isDayOrMonth(v) ? null : `${path}: "${String(v)}" is not a day or a month. Write YYYY-MM-DD, or YYYY-MM when only the month is known.`);
+// A month sorts as its first day, for ordering only; the observation keeps the month it was written with.
+const sinceKey = (since) => (MONTH.test(since) ? `${since}-01` : since);
 const dayProblem = (path, v) => (isDay(v) ? null : `${path}: "${String(v)}" is not a day. Write YYYY-MM-DD.`);
 const emptyProblem = (path, v, what) => (typeof v === "string" && v.trim() !== "" ? null : `${path}: is empty. ${what}`);
 const hasText = (s) => typeof s === "string" && s.trim() !== "";
@@ -158,13 +167,13 @@ const CHECKS = {
     for (const id of duplicates(obs.map((o) => o.id))) out.push(`$.observations: id "${id}" is used more than once. supersededBy points at an id, so each must name one observation.`);
     obs.forEach((o, i) => {
       const at = `$.observations[${i}]`;
-      push(dayProblem(`${at}.since`, o.since));
+      push(sinceProblem(`${at}.since`, o.since));
       push(emptyProblem(`${at}.text`, o.text, "An observation says something."));
       if (o.supersededBy !== undefined) {
         const next = byId.get(o.supersededBy);
         if (o.supersededBy === o.id) out.push(`${at}.supersededBy: names itself. An observation is superseded by a later one.`);
         else if (!next) out.push(`${at}.supersededBy: names "${o.supersededBy}", which is not an observation in this profile.`);
-        else if (next.since < o.since) out.push(`${at}.supersededBy: names "${next.id}", dated ${next.since}, which is before this one (${o.since}). A later observation supersedes an earlier one.`);
+        else if (sinceKey(next.since) < sinceKey(o.since)) out.push(`${at}.supersededBy: names "${next.id}", dated ${next.since}, which is before this one (${o.since}). A later observation supersedes an earlier one.`);
         else {
           const seen = new Set([o.id]);
           let cur = next;
@@ -178,7 +187,12 @@ const CHECKS = {
       if (o.quote) {
         push(emptyProblem(`${at}.quote.words`, o.quote.words, "A quote holds words."));
         if (o.quote.said !== undefined) push(dayProblem(`${at}.quote.said`, o.quote.said));
-        if (o.quote.provenance === "owner" && o.quote.by !== owner) out.push(`${at}.quote: marked as the owner's words, but by is "${o.quote.by}", not the owner "${owner}". Words someone else produced are provenance agent.`);
+        if (o.quote.provenance === "owner" && o.quote.by !== owner) out.push(`${at}.quote: marked as the owner's words, but by is "${o.quote.by}", not the owner "${owner}". Words someone else said are provenance person; an agent's summary is provenance agent.`);
+        if (o.quote.provenance === "person") {
+          const empty = emptyProblem(`${at}.quote.by`, o.quote.by, "Words someone other than the owner said name who said them.");
+          if (empty) out.push(empty);
+          else if (o.quote.by === owner) out.push(`${at}.quote: marked as another person's words, but by is the owner "${owner}". The owner's own words are provenance owner.`);
+        }
         if (o.quote.provenance === "agent" && o.quote.by === owner) out.push(`${at}.quote: marked as an agent's summary, but by is the owner "${owner}". The owner's own words are provenance owner.`);
       }
     });
@@ -277,7 +291,9 @@ export function readEntry(kind, raw, { owner } = {}) {
 export const hypothesisSurfaces = (dto) => dto.parked === false;
 
 // An entry file's contents as an object, or { error } when the file cannot be read as one, or null
-// when the file is not an entry at all (markdown with no `kind:` in its frontmatter).
+// when the file is not an entry at all (markdown with no `kind:` in its frontmatter). Markdown also
+// carries `body`, the text below the frontmatter, for a reader that needs the words (a note) or the
+// section headings (doctor's person-profile heading-coverage check).
 export function entryFromFile(name, text) {
   if (/\.json$/i.test(name)) {
     try { return { raw: JSON.parse(text) }; } catch (e) { return { error: `is not valid JSON (${e.message}).` }; }
@@ -294,8 +310,9 @@ export function entryFromFile(name, text) {
     try { front = parseYaml(lines.slice(1, end).join("\n")); } catch (e) { return /^kind:/m.test(lines.slice(1, end).join("\n")) ? { error: e.message } : null; }
     if (!isObject(front) || front.kind === undefined) return null;
     const raw = { ...front };
-    if (raw.kind === "note" && absent(raw.words)) raw.words = lines.slice(end + 1).join("\n").trim();
-    return { raw };
+    const body = lines.slice(end + 1).join("\n");
+    if (raw.kind === "note" && absent(raw.words)) raw.words = body.trim();
+    return { raw, body };
   }
   return null;
 }

package/lib/kinds.schema.json

@@ -102,7 +102,8 @@
                     "type": "enum",
                     "values": [
                       "owner",
-                      "agent"
+                      "agent",
+                      "person"
                     ]
                   },
                   "by": {

package/lib/manifest.mjs

@@ -14,7 +14,17 @@ import { EvdaError } from "./errors.mjs";
 
 export const SCHEMA_VERSION = 1;
 export const KNOWN_LAYERS = ["record", "ledger", "circles"];
-export const KNOWN_KEYS = ["evda", "id", "name", "owner", "created", "layers", "mapping"];
+// `filing` (HQ-1385) is the owner's answer to the one setup question, "everything" or "asked";
+// lib/day-file.mjs filingOf reads it for every agent and hook.
+export const KNOWN_KEYS = ["evda", "id", "name", "owner", "created", "layers", "mapping", "subrecords", "read_by", "filing"];
+
+// Whether a record's circles stop at its sub-records (HQ-1371). A sub-record is a directory below
+// the root holding its own evda.json. "bounded": the parent's circles, coverage, scan and release
+// stop at every sub-record, and the parent holds a sub-record's files only through a circle it
+// mounts. Absent: the parent's circles still cover sub-record files as its own, which is what a
+// record declared before HQ-1371 syncs, so nothing it sends changes until its owner opts in.
+export const SUBRECORD_MODES = ["bounded"];
+export const isBounded = (manifest) => (manifest?.manifest ?? manifest)?.subrecords === "bounded";
 
 // Who holds the record (Spec 07, section 1): a person, an agent, or a company. `owner.kind` on the
 // manifest; absent means person. `id` is the record's atlas id, the name another record uses in a
@@ -98,6 +108,9 @@ export function readManifest(dir) {
     });
   }
   for (const [role, rel] of Object.entries(m.mapping)) {
+    // The one non-string value: `work` (or a work facet) naming a live source as an object.
+    const isWork = role === "work" || role.startsWith("work/");
+    if (isWork && rel !== null && typeof rel === "object" && !Array.isArray(rel) && typeof rel.source === "string" && rel.source !== "") continue;
     if (typeof rel !== "string" || rel === "") {
       throw new EvdaError(`REFUSED: mapping for role "${role}" is not a path.`, { code: "BAD_MANIFEST", exit: 2 });
     }