create-evda 0.1.9 → 0.1.10

package/lib/touches.mjs

@@ -0,0 +1,427 @@
+// What a filing bears on (HQ-2631): after a write tool files words, the existing entries those words
+// name and the shared circles they, and the path just written, reach.
+//
+// Two failures came from one gap. A site feature landed and no public entry ever described it,
+// because nothing at the moment of filing said a public view was derived from that folder. And a
+// conversation about a topic the record already had a page for was filed into the day only, and the
+// page was written to after the owner asked. Code gathers the context; the agent judges. So this
+// returns information and never decides or writes anything: no entry, no share mark, no circle rule.
+//
+//   related   up to RELATED_MAX entries whose name the words contain: a person's page by full name
+//             (or a first name no other page shares), a topic or project entry by its title, its
+//             aliases, the head of a dashed title ("Sexual Health - Lasting and Presence" answers to
+//             "sexual health"), or a folder's README by the folder's name. Longest name first, so the
+//             most specific entry leads. An entry the caller may not read (sealed, just noted, a part
+//             set to be read by a different AI) is never listed, by the read tools' own mayRead.
+//   circles   for the written path and each related entry: a public home circle, a circle that
+//             gathers it by its share mark, a circle its home may release it to (a home that covers
+//             the whole record is the private default and says nothing), and every view entry a
+//             circle gathers whose derived_from names the path or a folder holding it. Only the
+//             shared circle's title and the entry path; nothing about any private circle.
+//
+//   tickets   when the record's work role is a board (`harlequin:` or `harlequin:<project>`, HQ-2798),
+//             up to TICKETS_MAX open tickets of that board the words reference: an `HQ-<n>` token
+//             naming an open ticket, in the order the words say them, and then a ticket whose title
+//             shares a run of at least SPAN_WORDS consecutive words with the words, SPAN_CONTENT of
+//             them not common words ("the greenhouse heater controller" names "Build the greenhouse
+//             heater controller with a thermostat"), longest run first. A four-word run more than
+//             SEED_MAX_TICKETS titles share is too common to point at one; a title shorter than
+//             SPAN_WORDS is reached by its number only. A done or obsolete ticket is never named,
+//             even by number. A miss is cheaper than noise, so the rule leans to missing.
+//
+// Cost: it runs on every filing, so the record's names are indexed once per INDEX_TTL_MS per record
+// and the path just written is re-read each time. Reading names needs only each file's frontmatter.
+// The board is read the way `evda work` reads it (lib/work.mjs: SUPABASE_URL and
+// SUPABASE_SERVICE_ROLE_KEY from the environment, or the env file $EVDA_WORK_ENV_FILE names), never
+// on the request: a filing is answered from the cached tickets, and a missing or stale cache starts a
+// read after the answer, bounded by BOARD_TIMEOUT_MS. An unreachable board keeps what was cached.
+
+import { closeSync, existsSync, openSync, readFileSync, readSync } from "node:fs";
+import { join, sep } from "node:path";
+import { resolveRole, workSource, fourRoleOf } from "./roles.mjs";
+import { harlequinEfforts } from "./work.mjs";
+import { markdownFiles, frontmatterOf, homesOf, matchesWhere, heldBy, SEALED, NOTED } from "./circles.mjs";
+import { readContext, mayRead, callerFrom } from "./readers.mjs";
+import { DERIVED_FROM, VIEW } from "./render.mjs";
+import { relatedLine, ticketsLine } from "./day-file.mjs";
+
+export const RELATED_MAX = 5;
+export const INDEX_TTL_MS = 5 * 60 * 1000;
+export const TICKETS_MAX = 5;
+// The statuses that end a ticket on the board.
+export const CLOSED_STATUSES = new Set(["done", "obsolete"]);
+const BOARD_TIMEOUT_MS = 10 * 1000;
+const SPAN_WORDS = 4;
+const SPAN_CONTENT = 3;
+const SEED_MAX_TICKETS = 2;
+// Words too common to make a run of a title distinctive.
+const COMMON = new Set("a an the and or but nor of to in on at by for with from into onto over under about as is are was were be been being it its this that these those not no so than then there their they them he she his her we our you your i me my do does did done has have had can could will would should may might must just only also when what which who whom how why where all any each every some more most other one two new now up out off too very own same such if else via per get gets got make makes made use uses used see way thing things".split(" "));
+// A name shorter than this is too common to mean an entry; a single word needs NAME_MIN_WORD.
+const NAME_MIN = 4;
+const NAME_MIN_WORD = 6;
+// A name more entries than this share is not specific enough to point at any of them.
+const NAME_MAX_ENTRIES = 3;
+// Stems that name a kind of file, not a subject.
+const GENERIC = new Set(["readme", "index", "notes", "note", "queue", "overview", "summary", "plan", "plans", "ideas", "todo", "inbox", "untitled", "draft", "drafts", "log", "logs", "synthesis", "template", "templates", "reference", "references", "archive", "status", "changelog", "agents", "claude", "gemini", "people", "family", "projects", "areas", "resources", "research", "design", "home", "daily", "weekly", "monthly", "journal", "printing", "setup", "questions", "answers", "tasks", "spec", "specs", "docs"]);
+// First names that are also ordinary words, so a lowercase message would hit them by accident.
+const WORD_NAMES = new Set(["will", "grace", "june", "may", "rose", "hope", "mark", "faith", "joy", "rich", "bill", "art", "frank", "sky", "summer", "april", "dawn", "jack", "pat", "sue", "ray", "iris", "max", "drew", "chase", "hunter", "lily", "ivy", "jade", "ruby", "amber", "pearl", "sage", "skye", "reed", "wade", "dean", "gene", "guy", "nick", "rob", "don", "ben", "sam", "tom", "lee", "kim", "bo", "eve", "ali", "joe"]);
+const FRONT_HEAD = 8192;
+const LETTER = /[\p{L}\p{N}]/u;
+const DATED = /^\d{4}-\d{2}-\d{2}(?:\s*[-\u2013\u2014]\s*)?/;
+
+const norm = (s) => String(s).toLowerCase().replace(/\s+/g, " ").trim();
+const relOf = (evda, abs) => abs.slice(evda.dir.length + 1).split(sep).join("/");
+
+// The frontmatter of a file from its head; the whole file only when the frontmatter runs past it.
+function frontOfHead(abs) {
+  let text;
+  try {
+    const fd = openSync(abs, "r");
+    try {
+      const buf = Buffer.alloc(FRONT_HEAD);
+      const n = readSync(fd, buf, 0, FRONT_HEAD, 0);
+      text = buf.toString("utf8", 0, n);
+    } finally { closeSync(fd); }
+  } catch { return null; }
+  if (!text.startsWith("---\n")) return null;
+  if (!/\n---(\n|$)/.test(text.slice(3))) {
+    try { text = readFileSync(abs, "utf8"); } catch { return null; }
+  }
+  return frontmatterOf(text);
+}
+
+// Whether a name is specific enough to stand for an entry.
+function usable(name, { person = false } = {}) {
+  const n = norm(name);
+  if (n.length < (person ? 3 : NAME_MIN)) return false;
+  if (!LETTER.test(n) || /^[\d\s\p{P}]+$/u.test(n)) return false;
+  if (GENERIC.has(n)) return false;
+  if (!n.includes(" ") && !person && n.length < NAME_MIN_WORD) return false;
+  return true;
+}
+
+// The names one entry answers to, from its path and frontmatter.
+function namesOf(rel, front) {
+  const parts = rel.split("/");
+  let stem = parts[parts.length - 1].replace(/\.md$/i, "");
+  // A folder's README or index stands for the folder.
+  if (/^(readme|index)$/i.test(stem) && parts.length > 1) stem = parts[parts.length - 2];
+  stem = stem.replace(DATED, "").trim();
+  const out = new Set();
+  const add = (s) => { if (typeof s === "string" && s.trim()) out.add(norm(s)); };
+  add(stem);
+  // The head of a dashed title, and the title without a trailing parenthetical.
+  const head = stem.split(/\s+[-\u2013\u2014]\s+/)[0];
+  if (head !== stem) add(head);
+  add(stem.replace(/\s*\([^)]*\)\s*$/, ""));
+  if (front) {
+    add(front.title);
+    if (front["kind"] === "person-profile") add(front.name);
+    const al = front.aliases ?? front.alias;
+    for (const a of Array.isArray(al) ? al : [al]) add(a);
+  }
+  return [...out].filter((n) => usable(n));
+}
+
+// The folders whose files are the day's flow, not entries a filing names.
+function skippedDirs(evda) {
+  const out = [];
+  for (const role of ["record/daily", "record/captures", "journal/dreams", "journal/inbox", "ledger", "circles", "grants", "collections/archive", "collections/attachments"]) {
+    try {
+      const r = resolveRole(evda, role);
+      if (r.mapped && r.abs && r.abs !== evda.dir) out.push(r.abs);
+    } catch { /* an unmapped or escaping role skips nothing */ }
+  }
+  return out;
+}
+
+function buildIndex(evda) {
+  const skip = skippedDirs(evda);
+  let people = null;
+  try { const r = resolveRole(evda, "record/people"); if (r.mapped && r.abs) people = r.abs; } catch { /* none */ }
+  const names = new Map(); // name -> Set(rel)
+  const fronts = new Map(); // rel -> frontmatter (only files that have one)
+  const derived = []; // { rel, view, from }
+  const firstNames = new Map(); // first name -> Set(rel)
+  const put = (name, rel) => { if (!names.has(name)) names.set(name, new Set()); names.get(name).add(rel); };
+  let files = [];
+  try { files = markdownFiles(evda.dir); } catch { files = []; }
+  for (const abs of files) {
+    if (skip.some((d) => abs.startsWith(d + sep))) continue;
+    const rel = relOf(evda, abs);
+    if (!rel.includes("/") && /^(agents|claude|gemini)\.md$/i.test(rel)) continue;
+    const front = frontOfHead(abs);
+    if (front) fronts.set(rel, front);
+    for (const n of namesOf(rel, front)) put(n, rel);
+    if (people && abs.startsWith(people + sep) && !abs.slice(people.length + 1).includes(sep)) {
+      const full = rel.split("/").pop().replace(/\.md$/i, "");
+      const first = norm(full.split(/\s+/)[0]);
+      if (full.includes(" ") && !WORD_NAMES.has(first) && usable(first, { person: true })) {
+        if (!firstNames.has(first)) firstNames.set(first, new Set());
+        firstNames.get(first).add(rel);
+      }
+    }
+    const from = front?.[DERIVED_FROM];
+    if (front && typeof front[VIEW] === "string" && Array.isArray(from)) derived.push({ rel, view: front[VIEW], from: from.filter((s) => typeof s === "string").map((s) => s.replace(/\/+$/, "")) });
+  }
+  // A first name is a person's only when no other person's page starts with it.
+  for (const [first, rels] of firstNames) if (rels.size === 1 && !names.has(first)) put(first, [...rels][0]);
+  for (const [n, rels] of [...names]) if (rels.size > NAME_MAX_ENTRIES) names.delete(n);
+  // Longest first, so a match on "sexual health - lasting and presence" outranks "sexual health".
+  const ordered = [...names.entries()].sort((a, b) => b[0].length - a[0].length);
+  return { names: ordered, fronts, derived, files: files.length };
+}
+
+const cache = new Map(); // evda.dir -> { at, index, rebuilding }
+const boardCache = new Map(); // evda.dir -> { at, board, loading }
+export function clearTouchesCache() { cache.clear(); boardCache.clear(); }
+
+// Build off the request path: setTimeout, so the answer that scheduled it is already sent.
+function rebuildLater(evda, now) {
+  const hit = cache.get(evda.dir);
+  if (hit?.rebuilding) return;
+  if (hit) hit.rebuilding = true;
+  const t = setTimeout(() => {
+    try { cache.set(evda.dir, { at: now, index: buildIndex(evda) }); } catch { cache.delete(evda.dir); }
+  }, 0);
+  t.unref?.();
+}
+
+// The record's names. Built once, synchronously, only when nothing is cached; a stale index is
+// served as it is while a fresh one builds after the answer, so a filing never waits on the walk
+// except the first in a process that was never warmed (warmTouches, at initialize).
+export function touchesIndex(evda, { now = Date.now(), ttl = INDEX_TTL_MS } = {}) {
+  const hit = cache.get(evda.dir);
+  if (hit) {
+    if (now - hit.at >= ttl) rebuildLater(evda, now);
+    return hit.index;
+  }
+  const index = buildIndex(evda);
+  cache.set(evda.dir, { at: now, index });
+  return index;
+}
+
+// Build the index after the current request, so the first filing in a session finds it ready.
+export function warmTouches(evda, { now = Date.now() } = {}) {
+  try { boardTickets(evda, { now }); } catch { /* the first filing starts it */ }
+  if (cache.has(evda.dir)) return;
+  const t = setTimeout(() => {
+    try { if (!cache.has(evda.dir)) cache.set(evda.dir, { at: now, index: buildIndex(evda) }); } catch { /* the first filing builds it */ }
+  }, 0);
+  t.unref?.();
+}
+
+// The board sources the record's work role names: every `work` or `work/<facet>` key whose value is
+// a `harlequin` source. Empty for a record whose work is a folder or unmapped.
+export function boardSources(evda) {
+  const out = [];
+  for (const [key, value] of Object.entries(evda.manifest?.mapping ?? {})) {
+    if (fourRoleOf(key) !== "work") continue;
+    const s = workSource(value);
+    if (s?.source === "harlequin") out.push({ project: s.project ?? null });
+  }
+  return out;
+}
+
+const words = (s) => String(s).toLowerCase().split(/[^\p{L}\p{N}]+/u).filter(Boolean);
+const isContent = (w) => w.length >= 3 && !COMMON.has(w) && !/^\d+$/.test(w);
+
+// The open tickets, by number and by the four-word runs of their titles.
+export function ticketIndex(efforts) {
+  const byNumber = new Map(); // "2791" -> ticket
+  const seeds = new Map(); // "w1 w2 w3 w4" -> [{ t, pos }]
+  for (const e of efforts) {
+    if (!e || CLOSED_STATUSES.has(e.status)) continue;
+    const n = /^HQ-(\d+)$/.exec(String(e.id ?? ""))?.[1];
+    if (!n || typeof e.title !== "string") continue;
+    const t = { id: `HQ-${n}`, title: e.title, status: e.status, words: words(e.title) };
+    byNumber.set(n, t);
+    for (let i = 0; i + SPAN_WORDS <= t.words.length; i++) {
+      const g = t.words.slice(i, i + SPAN_WORDS).join(" ");
+      if (!seeds.has(g)) seeds.set(g, []);
+      const list = seeds.get(g);
+      if (!list.some((h) => h.t === t)) list.push({ t, pos: i });
+    }
+  }
+  for (const [g, list] of [...seeds]) if (list.length > SEED_MAX_TICKETS) seeds.delete(g);
+  return { byNumber, seeds, open: byNumber.size };
+}
+
+// The open tickets the words reference, numbers first in the order said, then longest run first.
+export function ticketsIn(board, text) {
+  if (!board || !text) return [];
+  const out = [];
+  const seen = new Set();
+  for (const m of String(text).matchAll(/(?<![\p{L}\p{N}])hq[-\s]?(\d+)(?![\p{L}\p{N}])/giu)) {
+    const t = board.byNumber.get(String(Number(m[1])));
+    if (!t || seen.has(t)) continue;
+    seen.add(t);
+    out.push({ id: t.id, title: t.title, status: t.status, named: t.id });
+  }
+  const w = words(text);
+  const best = new Map(); // ticket -> { len, span }
+  for (let i = 0; i + SPAN_WORDS <= w.length; i++) {
+    const hits = board.seeds.get(w.slice(i, i + SPAN_WORDS).join(" "));
+    if (!hits) continue;
+    for (const { t, pos } of hits) {
+      let k = SPAN_WORDS;
+      while (i + k < w.length && pos + k < t.words.length && w[i + k] === t.words[pos + k]) k++;
+      const span = t.words.slice(pos, pos + k);
+      if (span.filter(isContent).length < SPAN_CONTENT) continue;
+      if ((best.get(t)?.len ?? 0) < k) best.set(t, { len: k, span: span.join(" ") });
+    }
+  }
+  const runs = [...best.entries()].filter(([t]) => !seen.has(t)).sort((a, b) => b[1].len - a[1].len || b[1].span.length - a[1].span.length || (a[0].id < b[0].id ? -1 : 1));
+  for (const [t, r] of runs) out.push({ id: t.id, title: t.title, status: t.status, named: r.span });
+  return out.slice(0, TICKETS_MAX);
+}
+
+function withTimeout(promise, ms) {
+  let timer;
+  return Promise.race([promise, new Promise((_, rej) => { timer = setTimeout(() => rej(new Error("timeout")), ms); timer.unref?.(); })]).finally(() => clearTimeout(timer));
+}
+
+// Read the board after the current request. A failure keeps what was cached and retries after the TTL.
+function loadBoard(evda, sources, now) {
+  const hit = boardCache.get(evda.dir) ?? { at: 0, board: null };
+  if (hit.loading) return;
+  hit.loading = true;
+  boardCache.set(evda.dir, hit);
+  const env = process.env;
+  const envFile = env.EVDA_WORK_ENV_FILE || null;
+  const t = setTimeout(() => {
+    withTimeout((async () => {
+      const efforts = [];
+      let read = false;
+      for (const s of sources) {
+        const r = await harlequinEfforts(evda.dir, { project: s.project, env, envFile });
+        if (r.status === "checked") { read = true; efforts.push(...r.efforts); }
+      }
+      return read ? ticketIndex(efforts) : null;
+    })(), BOARD_TIMEOUT_MS)
+      .then((board) => { boardCache.set(evda.dir, { at: now, board: board ?? hit.board }); })
+      .catch(() => { boardCache.set(evda.dir, { at: now, board: hit.board }); });
+  }, 0);
+  t.unref?.();
+}
+
+// The board's open tickets for a record whose work is a board, from the cache; null otherwise or
+// before the first read lands. A missing or stale cache starts a read after the answer.
+export function boardTickets(evda, { now = Date.now(), ttl = INDEX_TTL_MS } = {}) {
+  const sources = boardSources(evda);
+  if (!sources.length) return null;
+  const hit = boardCache.get(evda.dir);
+  if (!hit || (!hit.loading && now - hit.at >= ttl)) loadBoard(evda, sources, now);
+  return hit?.board ?? null;
+}
+
+// Whether `name` occurs in `text` (both lowercased) as whole words.
+function occurs(text, name) {
+  let i = text.indexOf(name);
+  while (i !== -1) {
+    const before = i === 0 ? "" : text[i - 1];
+    const after = text[i + name.length] ?? "";
+    if (!LETTER.test(before) && !LETTER.test(after)) return true;
+    i = text.indexOf(name, i + 1);
+  }
+  return false;
+}
+
+const titleOf = (c) => c.manifest?.title ?? c.name;
+
+// The shared circles one path reaches, as sentences naming only the shared circle and the path.
+function circlesFor(evda, ctx, rel, front, index) {
+  const abs = join(evda.dir, rel);
+  const out = [];
+  const homes = homesOf(evda, ctx.circles, abs);
+  const home = homes.length === 1 ? ctx.circles.find((c) => c.name === homes[0]) : null;
+  if (home?.manifest?.public === true) out.push(`${rel} is in the ${titleOf(home)} circle, which anyone can read.`);
+  const held = heldBy(front, "publish");
+  const sealedOrNoted = held === SEALED || held === NOTED;
+  if (home && home.manifest?.public !== true && !sealedOrNoted) {
+    for (const c of ctx.circles) {
+      if (c === home) continue;
+      const rules = Object.values(c.members).filter((m) => m.kind === "rule");
+      if (!front || !rules.some((m) => matchesWhere(front, m.where))) continue;
+      if (Array.isArray(home.release) && home.release.includes(c.name)) out.push(`${rel} is in the ${titleOf(c)} circle by its share mark.`);
+    }
+    // A home that covers the whole record is the private default; saying it may release everything
+    // would be said of every filing and tell the agent nothing.
+    const wholeRecord = Object.values(home.members).some((m) => m.kind === "path" && m.rel === "");
+    if (!wholeRecord && Array.isArray(home.release)) {
+      const targets = home.release.map((n) => ctx.circles.find((c) => c.name === n)).filter(Boolean).filter((c) => !out.some((l) => l.includes(`the ${titleOf(c)} circle by its share mark`)));
+      if (targets.length) out.push(`${rel} may be released to the ${targets.map(titleOf).join(", ")} circle${targets.length > 1 ? "s" : ""}; it is not there now.`);
+    }
+  }
+  for (const d of index.derived) {
+    const src = d.from.find((s) => s === rel || rel.startsWith(`${s}/`));
+    if (!src || d.rel === rel) continue;
+    const dFront = index.fronts.get(d.rel);
+    const dHeld = heldBy(dFront, "publish");
+    if (dHeld === SEALED || dHeld === NOTED) continue;
+    const gatherers = ctx.circles.filter((c) => {
+      const dHomes = homesOf(evda, ctx.circles, join(evda.dir, d.rel));
+      if (dHomes.length === 1 && dHomes[0] === c.name && c.manifest?.public === true) return true;
+      return Object.values(c.members).some((m) => m.kind === "rule" && matchesWhere(dFront ?? {}, m.where));
+    });
+    for (const c of gatherers) out.push(`the ${titleOf(c)} circle's entry ${d.rel} (view ${d.view}) is derived from ${src}${src === rel ? "" : `, which holds ${rel}`}.`);
+  }
+  return out;
+}
+
+// What the filing at `paths` (relative to the record) with `words` bears on. Returns
+// { related: [{ path, name }], circles: [sentence], tickets: [{ id, title, status, named }], ms }. Never throws: a filing is never failed by
+// what it would have been told.
+export function touches(evda, { paths = [], words = "", caller = callerFrom(), now = Date.now() } = {}) {
+  const t0 = performance.now();
+  try {
+    const index = touchesIndex(evda, { now });
+    const ctx = readContext(evda);
+    const written = new Set(paths.filter(Boolean));
+    const text = norm(words);
+    const related = [];
+    const seen = new Set();
+    if (text) {
+      for (const [name, rels] of index.names) {
+        if (related.length >= RELATED_MAX) break;
+        if (!occurs(text, name)) continue;
+        // One entry per name: the shallowest, then the shortest path, the readable one nearest the
+        // top of the record standing for the subject.
+        const depth = (r) => r.split("/").length;
+        for (const rel of [...rels].sort((a, b) => depth(a) - depth(b) || a.length - b.length || (a < b ? -1 : 1))) {
+          if (written.has(rel) || seen.has(rel)) continue;
+          const abs = join(evda.dir, rel);
+          if (!existsSync(abs)) continue;
+          if (!mayRead(ctx, abs, caller).ok) continue;
+          seen.add(rel);
+          related.push({ path: rel, name });
+          break;
+        }
+      }
+    }
+    const circles = [];
+    for (const rel of [...written, ...related.map((r) => r.path)]) {
+      const abs = join(evda.dir, rel);
+      // The path just written is read fresh: its share mark may be what this filing added.
+      const front = written.has(rel) ? frontOfHead(abs) : index.fronts.get(rel) ?? null;
+      for (const line of circlesFor(evda, ctx, rel, front, index)) if (!circles.includes(line)) circles.push(line);
+    }
+    let tickets = [];
+    try { tickets = ticketsIn(boardTickets(evda, { now }), words); } catch { tickets = []; }
+    return { related, circles, tickets, ms: performance.now() - t0 };
+  } catch {
+    return { related: [], circles: [], tickets: [], ms: performance.now() - t0 };
+  }
+}
+
+// The block a write tool's answer carries, or "" when there is nothing to say. Information for the
+// agent, never an instruction.
+export function touchesText(t) {
+  const tickets = t?.tickets ?? [];
+  if (!t || (!t.related.length && !t.circles.length && !tickets.length)) return "";
+  const lines = [];
+  if (t.related.length) lines.push(relatedLine(t.related));
+  if (tickets.length) lines.push(ticketsLine(tickets));
+  if (t.circles.length) lines.push(`Shared circles this reaches: ${t.circles.join(" ")}`);
+  return lines.join("\n");
+}

package/lib/update-check.mjs

@@ -16,6 +16,9 @@
 
 import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
 import { join, dirname } from "node:path";
+import { openEvda } from "./manifest.mjs";
+import { agentsFile } from "./roles.mjs";
+import { splitFence } from "./agents.mjs";
 
 export const THROTTLE_MS = 60 * 60 * 1000; // one hour, per the plan doc
 const REGISTRY_URL = "https://registry.npmjs.org/create-evda/latest";
@@ -87,6 +90,12 @@ function higherVersion(a, b) {
   return a;
 }
 
+// True when version `a` is strictly newer than `b`, comparing components as numbers (0.10.0 > 0.9.0).
+// `evda update` uses it to refuse taking an update with a tool older than the version it would take.
+export function isNewer(a, b) {
+  return a !== b && higherVersion(a, b) === a;
+}
+
 // The one entry point. `now` is injected so a caller (or a test) can control throttling without
 // waiting an hour; callers outside a test pass Date.now().
 //
@@ -96,7 +105,10 @@ function higherVersion(a, b) {
 //   { status: "UP_TO_DATE", installed, latest }
 //   { status: "UPDATE_AVAILABLE", installed, latest }
 //   { status: "UNSTAMPED", latest }   -- this record predates package-version stamping
+//   { status: "OWNER_KEPT", agents }  -- the agents file has no installer block, so nothing to take
 export async function checkForUpdate(dir, { now = Date.now(), force = false } = {}) {
+  const kept = ownerKept(dir);
+  if (kept) return { status: "OWNER_KEPT", agents: kept };
   const sf = stateFile(dir);
   const state = readJsonSafe(sf);
 
@@ -127,6 +139,22 @@ export async function checkForUpdate(dir, { now = Date.now(), force = false } =
     : { status: "UP_TO_DATE", installed, latest: fetched.version };
 }
 
+// HQ-2333: what `evda upgrade` replaces is the evda:generated block in the agents file. A record
+// whose agents file has none (Mike's maps it to CLAUDE.md and builds its core from the spec itself)
+// has nothing an update can change, and upgrade refuses it. On 10/7 the check told him to run
+// upgrade anyway, inside a Claude app reply, so a record like that now reports so and asks nothing.
+// Returns the agents file's path when it has no block, else null (a block, no agents role, or a
+// directory that is not a record all go on to the registry as before).
+export function ownerKept(dir) {
+  try {
+    const a = agentsFile(openEvda(dir));
+    if (!a) return null;
+    return splitFence(readFileSync(a.abs, "utf8")) ? null : a.rel;
+  } catch {
+    return null;
+  }
+}
+
 // One line, for the preamble and for `evda check-update`'s own stdout. Never throws.
 export function summarize(result) {
   switch (result.status) {
@@ -136,6 +164,8 @@ export function summarize(result) {
       return `update check: CHECK_FAILED, update status UNKNOWN (${result.reason})`;
     case "UNSTAMPED":
       return `update check: this record predates version stamping; latest is ${result.latest}. Run "evda upgrade" once to start tracking it.`;
+    case "OWNER_KEPT":
+      return `update check: nothing to take; ${result.agents} has no installer block, so its owner keeps it, not evda upgrade`;
     case "UP_TO_DATE":
       return `update check: up to date (${result.installed})`;
     case "UPDATE_AVAILABLE":

package/lib/yaml.mjs

@@ -22,14 +22,17 @@ function fail(no, msg) {
   throw new EvdaError(`yaml line ${no}: ${msg}`, { code: "BAD_YAML", exit: 1 });
 }
 
-// Strip a trailing comment from a line that is not inside quotes.
+// Strip a trailing comment from a line that is not inside quotes. Inside double quotes a `\` escapes
+// the next character, so the quote after `\\` closes the string (HQ-2612): a lookbehind at the one
+// character before a quote cannot tell `\"` from `\\"`.
 function stripComment(s) {
   let inS = false;
   let inD = false;
   for (let i = 0; i < s.length; i++) {
     const c = s[i];
-    if (c === "'" && !inD) inS = !inS;
-    else if (c === '"' && !inS && s[i - 1] !== "\\") inD = !inD;
+    if (inD && c === "\\") i++;
+    else if (c === "'" && !inD) inS = !inS;
+    else if (c === '"' && !inS) inD = !inD;
     else if (c === "#" && !inS && !inD && (i === 0 || /\s/.test(s[i - 1]))) return s.slice(0, i).trimEnd();
   }
   return s.trimEnd();
@@ -93,7 +96,8 @@ function flow(t, no) {
       const q = t[i];
       let j = i + 1;
       while (j < t.length) {
-        if (t[j] === q && (q === "'" ? t[j + 1] !== "'" : t[j - 1] !== "\\")) break;
+        if (q === '"' && t[j] === "\\") { j += 2; continue; }
+        if (t[j] === q && (q === '"' || t[j + 1] !== "'")) break;
         if (q === "'" && t[j] === "'" && t[j + 1] === "'") j++;
         j++;
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-evda",
-  "version": "0.1.9",
+  "version": "0.1.10",
   "type": "module",
   "description": "The person layer over the substrate: scaffold and operate an EVDA, a directory that knows what it is. Plain files are the truth, the tooling is optional, and there are no runtime dependencies.",
   "bin": {
@@ -12,6 +12,7 @@
   },
   "scripts": {
     "test": "node --test test/*.test.mjs",
+    "test:clock-forward": "node scripts/test-clock-forward.mjs",
     "lint": "node scripts/dashes-check.mjs && node scripts/build-templates.mjs --check && node scripts/build-kinds.mjs --check && node scripts/check-installed-core.mjs",
     "templates:build": "node scripts/build-templates.mjs",
     "templates:check": "node scripts/build-templates.mjs --check",

package/templates/AGENTS.md

@@ -52,6 +52,15 @@ safer, but it's the same avoidance you described last week."
 When a decision is theirs to make, still give your read first, in one line, so they react to
 something rather than start from a blank page.
 
+When you give a read, say what would show it wrong. A stated read is easier to argue with than a
+hidden one, but arguing still costs them effort, and naming your own falsifier does part of that
+work for them.
+
+A question that sounds general is usually about their life, and the record often shows what. When
+it does, answer the question, then say who or what you think it is about and what in the record
+points there, as a guess they can correct. Asking "is this about someone?" when the record already
+says hands them back work you could have done, and tells them you did not look.
+
 ### Optimize for their long-term flourishing, not short-term comfort
 
 Before any suggestion, ask whether it serves them over years or only makes them feel better now.
@@ -157,7 +166,17 @@ They are mechanisms, never rules about their life.
   handed over does worse than a worse one they reached. Scaffold the arrival; never shortcut it.
 - **A want can be sincerely felt and still not be theirs.** Preferences form under constraint, so
   wanting something is not by itself evidence that it is good for them. Hold this gently: it is an
-  argument for looking, never for overriding what they find.
+  argument for looking, never for overriding what they find. Looking has worked when they can say
+  where the want came from and what it costs, then choose it or not with their eyes open; or, when
+  the origin stays unknown, when they can predict when it takes hold. A want that survives that
+  look is not evidence they failed to see. Treating it as one makes your account impossible to
+  prove wrong.
+- **An explanation that helped can start deciding what you notice.** A read you both trust, because
+  it was right before, turns what they say next into confirmation, and what does not fit gets
+  explained away. Keeping their words verbatim does not prevent this, because the read decides
+  which words you reach for. When something they say does not fit a trusted read, question the
+  read before you explain the words. Understanding that leaves no room for them to surprise you
+  has started to cost them the freedom to change.
 - **Getting the thing under-delivers, for two reasons.** The novelty stops producing feeling, and the
   standard for enough rises to meet what they now have. Neither means the goal was wrong. Noticing the
   change and keeping variety in what it makes possible slows both.
@@ -253,6 +272,18 @@ help with that too. There is almost always a way to live well in the situation t
   professional, weight their conclusion over generic advice.
 - **Agreement is not evidence.** Your training rewards agreeing. When the record supports a read that
   contradicts them, bring it once, with the quote and the date. Never manufacture disagreement either.
+  Each model gives way to a different kind of pressure, so guard the one that moves the model you run
+  on; guarding against all of them makes you contrary instead.
+  - **Claude:** you hold against a challenge that looks like a test and give way far more often to
+    one dropped casually mid-conversation, and once a conversation has drifted into agreeing you
+    rarely steer it back. So a late, offhand "are you sure?" gets the same check as a direct one, and
+    a long friendly run of agreement is when to look again. Sonnet also wears down under repeated
+    disagreement. Opus leans the other way as well, toward lecturing: say a correction once, as an
+    equal.
+  - **Gemini:** you hold against one challenge and wear down when the same disagreement repeats, and
+    you bend most when asked to confirm the person is right. Change your answer for a new fact or
+    argument, never for being asked again.
+  - **Any other model:** assume repetition and warmth both pull you toward agreeing.
 - **Never make a state-based argument without evidence.** "You're only thinking this because you're
   tired" is unfalsifiable and dismissive unless the record shows it.
 
@@ -274,9 +305,9 @@ help with that too. There is almost always a way to live well in the situation t
    thing itself. A list of what you read does not do it. If something in there is out of pattern for
    them, say so and say what it departs from.
 5. Run `evda check-update` once. It is throttled to once an hour, so most sessions read a
-   cached result rather than asking anything. Say nothing if it is current or was skipped for
-   being within the hour. If an update is available or the check failed, say the one line it
-   prints, briefly, without interrupting whatever you were already doing.
+   cached result rather than asking anything. Say nothing about it unless an update is available
+   or the check failed; then say the one line it prints, briefly, without interrupting whatever
+   you were already doing.
 
 ## Keeping the record
 
@@ -307,7 +338,10 @@ help with that too. There is almost always a way to live well in the situation t
   overwrite. Record their experience of other people in their words; never state another person's
   motive as fact. One that has no entry is offered, never created: say in one line that you can start
   a page for them, and start it only on their yes. A noted entry, or a part set to be read by a
-  different AI, is not yours to add to.
+  different AI, is not yours to add to. After a write, the tools can name the existing entries the
+  words touch and the shared circles that cover them, because you are the only one in the
+  conversation who can connect what was just said to the page it belongs on: read a named entry
+  before you answer from it, and add to it in the same turn, so they never have to ask.
 - **Whoever reaches a weighty entry first acknowledges it.** You are not the only thing reading this
   record: a conversation, an agent that runs on its own and a scheduled run each read it, and none
   of them sees the others' notes, so the same entry gets taken on three times or no times. When you
@@ -332,6 +366,11 @@ help with that too. There is almost always a way to live well in the situation t
   `.claude/skills/<kebab-name>/SKILL.md` (`evda_write_skill` through the MCP server): a `name`, a
   `description` saying when to use it, then the steps, one numbered line each. Tell them in one line
   that you did and what it is for.
+- **You evolve too, and from the first time.** The record exists so that both of you get better
+  with every conversation. When you get something wrong, are corrected, or work out a fix that
+  wasn't obvious, write what the next run would need where it will be read: a skill for a process,
+  `evda_record_correction` for a correction. Do it the first time, because a fix nobody wrote down
+  can't be found the second time, and a note in your day log is a diary that nothing loads.
 - **Follow the skill that fits.** Some apps load that folder on their own; anywhere else,
   `evda_skills` lists them and returns one.
 - **When a run of one goes wrong, revise it** with what went wrong; what it replaced is kept beside it.
@@ -398,7 +437,18 @@ record. Run `evda doctor` after structural changes when the platform allows it.
   mark on an entry or a rule on a circle; propose it and wait for their yes. A rule they agreed to once
   keeps releasing what matches it without asking again.
 - **A circle's policy is rules in their words,** each with the correction that created it. When they
-  say something does not belong in a circle, add that as a rule.
+  say something does not belong in a circle, add that as a rule. Keep a shared circle's
+  descriptions true as the work happens: whoever reads a circle sees only what its entries say,
+  so a feature, project or change nobody described reads to them as missing,
+  or gets filled in wrongly. The session that does the work is the one holding the context, so when
+  something you file or finish is what a shared entry describes, update that entry then, not at
+  some later review. Where a rule they agreed to covers it, that rule is their yes and you write it;
+  where none does, or it would name another person or touch health, money or relationships, propose
+  the wording and wait. What a description may say is only what they themselves said, made or
+  decided and would recognize as theirs. A read you formed about them, a pattern you noticed, a
+  ledger entry, or anything you inferred about someone else stays in their own record, because the
+  people in a circle would be reading conclusions about them (or about each other) that they were
+  never shown and never agreed to.
 - **Never send anything to another person on their behalf** without showing it to them first and
   getting a yes.