create-evda 0.1.5 → 0.1.7

package/lib/skills.mjs

@@ -0,0 +1,266 @@
+// Skills the agent writes for itself (HQ-1377): a process it found itself repeating, written down
+// once so the next run follows it instead of rediscovering it.
+//
+// A skill lives in the record at `.claude/skills/<name>/SKILL.md`, the Anthropic skill format (a
+// `name` and a `description` saying when to use it, in frontmatter, then the steps). Claude Code
+// loads that folder on its own when a session opens in the record; every other app reads the same
+// files through the MCP server's evda_skills tool. The folder is a dot folder, so it is never a
+// record entry, yet it syncs with the record, so a skill travels to every device the record does.
+//
+// Two refusals, each with a test in test/skills.test.mjs:
+//   1. Nothing outside `.claude/skills/<name>/`. The tool takes a name, never a path, and a name
+//      that is not kebab-case (which is how `..` and `/` would get in) is refused.
+//   2. Nothing that is a rule about the owner's life. A skill is how the agent works. A threshold,
+//      count or streak about a person is never a skill, whoever asks (Mike, 2026-09-16: the mean is
+//      relative to the person, and a rule with a number in it about their life is the wrong shape).
+//
+// Revising: a skill that went wrong on a run is rewritten with revise: true and what went wrong; the
+// previous text is appended to REVISIONS.md beside it, so a revision never loses what it replaced.
+//
+// EVDA_SKILLS_FALSIFY=<mode,...>, for the tests: outside skips the path check, owner-rules skips the
+// life-rule check, frontmatter makes doctor accept any frontmatter, no-hint turns the repeated-
+// process line in the MCP server off.
+
+import { appendFileSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { join, resolve, sep } from "node:path";
+import { frontmatterOf } from "./circles.mjs";
+import { EvdaError } from "./errors.mjs";
+
+export const SKILLS_REL = ".claude/skills";
+export const SKILL_FILE = "SKILL.md";
+export const REVISIONS_FILE = "REVISIONS.md";
+export const NAME_MAX = 64;
+export const DESCRIPTION_MAX = 1024;
+export const SKILLS_FALSIFY_MODES = ["outside", "owner-rules", "frontmatter", "no-hint"];
+export const skillsFalsified = (mode, env = process.env) => (env.EVDA_SKILLS_FALSIFY ?? "").split(",").map((s) => s.trim()).includes(mode);
+
+const KEBAB = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const STEP = /^\s*(?:\d+[.)]|[-*])\s+\S/m;
+const SAYS_WHEN = /\b(?:use|when|whenever|before|after)\b/i;
+
+const pad = (n) => String(n).padStart(2, "0");
+const localDate = (d) => `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
+
+function refuse(message, code) {
+  return new EvdaError(`REFUSED: ${message} Nothing was written.`, { code, exit: 2 });
+}
+
+// ---- what counts as a rule about the owner's life ----
+
+// Words that point at the owner rather than at the agent. "you" is left out on purpose: a skill
+// talks to the agent as "you".
+const OWNER_WORDS = /\b(?:the owner|owner's|they|them|their|theirs|he|him|his|she|her|hers)\b/i;
+// A quota over a period with a unit of living: "8 hours a night", "3 drinks per week".
+const QUOTA = /\b\d+(?:\.\d+)?\s*(?:x\s*)?(?:times?|hours?|hrs?|minutes?|mins?|days?|nights?|drinks?|cups?|glasses|meals?|snacks?|calories|kcal|steps|grams?|g|kg|lbs?|pounds|reps?|sets|miles|km|servings?|pages|sessions?|workouts?)\s+(?:a|an|per|each|every)\s+(?:day|week|month|night|morning|evening|weekend)\b/i;
+// A streak is the word itself, or a run counted in days: "five days in a row", "consecutive nights".
+// "twice in a row" about a correction is how the agent notices a process, and is not one.
+const STREAK = /\bstreaks?\b|\bchain unbroken\b|\b(?:days?|nights?|weeks?|mornings?)\s+(?:in a row|straight)\b|\bconsecutive\s+(?:days?|nights?|weeks?|mornings?)\b/i;
+const EVERY = /\b(?:every|each)\s+(?:single\s+)?(?:day|night|morning|evening|week)\b|\bdaily\b|\bnightly\b/i;
+const MUST = /\b(?:must|should|has to|have to|needs? to|required|make sure|never miss|no exceptions)\b/i;
+const THRESHOLD = /\b(?:at least|at most|no more than|fewer than|less than|more than|under|over|up to|max(?:imum)?|min(?:imum)?|limit(?:ed)? (?:to|of)|cap(?:ped)? at|target of|goal of|quota of)\s+\$?\d/i;
+const LIFE = /\b(?:sleep|slept|bed|bedtime|wake|woke|eat|ate|eating|food|meals?|snacks?|drink|drinks|drinking|alcohol|sugar|calories|carbs|protein|weight|weigh|exercise|workouts?|gym|run|running|steps|screen time|phone|scroll|spend|spent|spending|money|budget|meditat\w*|water|caffeine|coffee|study|studied|read|journal\w*|smok\w*|vap\w*|weed|thc|sex|porn|social media)\b/i;
+
+// The line and the reason when a text reads as a rule about the owner's life, or null.
+export function ownerRule(text, { owner = "", env = process.env } = {}) {
+  if (skillsFalsified("owner-rules", env)) return null;
+  const first = String(owner ?? "").trim().split(/\s+/)[0] ?? "";
+  const named = first.length >= 2 ? new RegExp(`\\b${first.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`, "i") : null;
+  const lines = String(text).split("\n");
+  for (let i = 0; i < lines.length; i++) {
+    const l = lines[i];
+    const aboutOwner = OWNER_WORDS.test(l) || (named ? named.test(l) : false);
+    let why = null;
+    if (QUOTA.test(l)) why = "a quota over a period";
+    else if (aboutOwner && STREAK.test(l)) why = "a streak";
+    else if (aboutOwner && EVERY.test(l) && MUST.test(l)) why = "something they must do every day";
+    else if (aboutOwner && THRESHOLD.test(l) && LIFE.test(l)) why = "a threshold on how they live";
+    if (why) return { line: i + 1, text: l.trim(), why };
+  }
+  return null;
+}
+
+// ---- reading and checking ----
+
+// The record's skills folder, absolute, or null when it would resolve outside the record (a
+// symlinked .claude pointing elsewhere). Existence is not required.
+export function skillsDir(evda) {
+  const abs = join(evda.dir, SKILLS_REL);
+  if (skillsFalsified("outside")) return abs;
+  let p = evda.dir;
+  for (const part of SKILLS_REL.split("/")) {
+    p = join(p, part);
+    if (!existsSync(p)) break;
+    if (lstatSync(p).isSymbolicLink()) {
+      const real = realpathSync(p);
+      const root = realpathSync(evda.dir);
+      if (real !== root && !real.startsWith(root + sep)) return null;
+    }
+  }
+  return abs;
+}
+
+// The problems with one skill's text, as sentences, and what it parsed to. `folder` is the name of
+// the directory it sits in, which the frontmatter name must match.
+export function checkSkill(text, { folder = null, owner = "", env = process.env } = {}) {
+  const problems = [];
+  const warnings = [];
+  // What the skill format requires (a parseable name and description) fails; what makes a skill
+  // useful (it says when, it has steps) is required of one the agent writes, and only warned about
+  // in one written by hand, which may be prose (Mike's vault skills are, and they load fine).
+  const advisories = [];
+  const front = frontmatterOf(text);
+  const loose = skillsFalsified("frontmatter", env);
+  const name = front?.name;
+  const description = front?.description;
+  if (!loose) {
+    if (!front) problems.push(`has no frontmatter: it starts with a --- block holding name and description.`);
+    else {
+      if (typeof name !== "string" || !KEBAB.test(name)) problems.push(`name ${JSON.stringify(name ?? null)} is not kebab-case (lowercase letters, digits and single hyphens).`);
+      else if (name.length > NAME_MAX) problems.push(`name is ${name.length} characters; at most ${NAME_MAX}.`);
+      else if (folder !== null && name !== folder) problems.push(`name ${JSON.stringify(name)} differs from its folder ${JSON.stringify(folder)}.`);
+      if (typeof description !== "string" || description.trim() === "") problems.push(`has no description. The description is what tells an agent when to use it.`);
+      else if (description.length > DESCRIPTION_MAX) problems.push(`description is ${description.length} characters; at most ${DESCRIPTION_MAX}.`);
+      else if (!SAYS_WHEN.test(description)) advisories.push(`description does not say when to use it (no "use", "when", "before" or "after" in it).`);
+    }
+    const body = bodyOf(text);
+    if (!STEP.test(body)) advisories.push(`has no steps: the body holds no numbered or bulleted step.`);
+  }
+  const rule = ownerRule(bodyOf(text) + "\n" + (typeof description === "string" ? description : ""), { owner, env });
+  if (rule) warnings.push(`line ${rule.line} reads as a rule about the owner's life (${rule.why}): "${rule.text}". A skill is how the agent works, never a threshold, count or streak about a person.`);
+  return { name: typeof name === "string" ? name : folder, description: typeof description === "string" ? description : null, problems, advisories, warnings: [...advisories, ...warnings] };
+}
+
+function bodyOf(text) {
+  const lines = String(text).split("\n");
+  if (lines[0] !== "---") return text;
+  const end = lines.indexOf("---", 1);
+  return end === -1 ? text : lines.slice(end + 1).join("\n");
+}
+
+// Every skill in the record, sorted by folder name: { name, folder, path, description, problems,
+// warnings }. A folder with no SKILL.md is reported as a problem, not skipped.
+export function listSkills(evda, { env = process.env } = {}) {
+  const dir = skillsDir(evda);
+  if (dir === null) return { dir: SKILLS_REL, outside: true, skills: [] };
+  if (!existsSync(dir)) return { dir: SKILLS_REL, skills: [] };
+  const owner = evda.manifest?.owner?.name ?? "";
+  const skills = [];
+  for (const folder of readdirSync(dir).sort()) {
+    if (folder.startsWith(".")) continue;
+    const abs = join(dir, folder);
+    if (!lstatSync(abs).isDirectory()) continue;
+    const path = `${SKILLS_REL}/${folder}/${SKILL_FILE}`;
+    const file = join(abs, SKILL_FILE);
+    if (!existsSync(file)) { skills.push({ name: folder, folder, path, description: null, problems: [`${folder}/ holds no ${SKILL_FILE}.`], advisories: [], warnings: [] }); continue; }
+    const r = checkSkill(readFileSync(file, "utf8"), { folder, owner, env });
+    skills.push({ folder, path, ...r });
+  }
+  return { dir: SKILLS_REL, skills };
+}
+
+// One skill's whole text by name.
+export function getSkill(evda, name) {
+  if (typeof name !== "string" || !KEBAB.test(name)) throw new EvdaError(`REFUSED: evda_skills: ${JSON.stringify(name ?? null)} is not a skill name (kebab-case), so it names nothing in ${SKILLS_REL}.`, { code: "BAD_SKILL_NAME", exit: 2 });
+  const dir = skillsDir(evda);
+  const file = dir && join(dir, name, SKILL_FILE);
+  if (!file || !existsSync(file)) {
+    const have = listSkills(evda).skills.map((s) => s.folder);
+    throw new EvdaError(`No skill named ${JSON.stringify(name)} in ${SKILLS_REL}. ${have.length ? `There are: ${have.join(", ")}.` : "There are none yet."}`, { code: "NO_SKILL", exit: 2 });
+  }
+  return { name, path: `${SKILLS_REL}/${name}/${SKILL_FILE}`, text: readFileSync(file, "utf8") };
+}
+
+// ---- writing ----
+
+const yamlString = (s) => (/^[\w(][^:#\n]*$/.test(s) && !/^(?:true|false|null|yes|no|~)$/i.test(s) && !/\s$/.test(s) ? s : JSON.stringify(s));
+const titleOf = (name) => name.split("-").map((w, i) => (i === 0 ? w[0].toUpperCase() + w.slice(1) : w)).join(" ");
+
+export function renderSkill({ name, description, steps }) {
+  return `---\nname: ${name}\ndescription: ${yamlString(description.replace(/\s*\n\s*/g, " ").trim())}\n---\n\n# ${titleOf(name)}\n\n${steps.trim()}\n`;
+}
+
+// Write a new skill, or revise one with revise: true and `why` (what went wrong on the run).
+export function writeSkill(evda, args = {}, { now = new Date(), env = process.env } = {}) {
+  const allowed = ["name", "description", "steps", "revise", "why"];
+  const extra = Object.keys(args).filter((k) => !allowed.includes(k));
+  if (extra.length) throw refuse(`evda_write_skill does not take ${extra.map((k) => JSON.stringify(k)).join(", ")}. It takes a name, never a path: a skill is always ${SKILLS_REL}/<name>/${SKILL_FILE}.`, "UNKNOWN_ARGUMENT");
+  const { name, description, steps } = args;
+  if (typeof name !== "string" || !KEBAB.test(name) || name.length > NAME_MAX) {
+    if (!(skillsFalsified("outside", env) && typeof name === "string" && name)) {
+      throw refuse(`evda_write_skill: the name ${JSON.stringify(name ?? null)} is not kebab-case of at most ${NAME_MAX} characters, so it could land outside ${SKILLS_REL}/. A skill is only ever written at ${SKILLS_REL}/<name>/${SKILL_FILE}.`, "OUTSIDE_SKILLS");
+    }
+  }
+  if (typeof description !== "string" || description.trim() === "") throw refuse(`evda_write_skill needs "description": when to use it, starting "Use when".`, "NO_DESCRIPTION");
+  if (typeof steps !== "string" || steps.trim() === "") throw refuse(`evda_write_skill needs "steps": the steps, one numbered line each.`, "NO_STEPS");
+  const dir = skillsDir(evda);
+  if (dir === null) throw refuse(`${SKILLS_REL} resolves outside the record (a symlink), so no skill is written there.`, "OUTSIDE_SKILLS");
+  const folder = resolve(dir, name);
+  if (!skillsFalsified("outside", env) && !folder.startsWith(dir + sep)) throw refuse(`${name} resolves outside ${SKILLS_REL}/.`, "OUTSIDE_SKILLS");
+  const text = renderSkill({ name, description, steps });
+  const check = checkSkill(text, { folder: skillsFalsified("outside", env) ? null : name, env });
+  const bad = [...check.problems, ...check.advisories];
+  if (bad.length) throw refuse(`evda_write_skill: the skill ${bad.join(" ")}`, "BAD_SKILL");
+  const rule = ownerRule(`${description}\n${steps}`, { owner: evda.manifest?.owner?.name ?? "", env });
+  if (rule) throw refuse(`evda_write_skill: line ${rule.line} reads as a rule about the owner's life (${rule.why}): "${rule.text}". A skill is how you work (the steps of a process you repeat), never a threshold, count or streak about a person. Write the process without it.`, "OWNER_RULE");
+  const file = join(folder, SKILL_FILE);
+  const rel = `${SKILLS_REL}/${name}/${SKILL_FILE}`;
+  const exists = existsSync(file);
+  if (exists && args.revise !== true) throw refuse(`a skill named ${name} already exists at ${rel}. To change it after a run went wrong, pass revise: true and "why", what went wrong; read it first with evda_skills.`, "SKILL_EXISTS");
+  if (!exists && args.revise === true) throw refuse(`there is no skill named ${name} to revise. Write it without revise.`, "NO_SKILL");
+  if (args.revise === true && (typeof args.why !== "string" || args.why.trim() === "")) throw refuse(`a revision needs "why": what went wrong on the run that made it need one.`, "NO_WHY");
+  mkdirSync(folder, { recursive: true });
+  let revisions = null;
+  if (exists) {
+    const before = readFileSync(file, "utf8");
+    if (before === text) return { path: rel, action: "unchanged", name };
+    revisions = `${SKILLS_REL}/${name}/${REVISIONS_FILE}`;
+    const head = existsSync(join(folder, REVISIONS_FILE)) ? "" : `# Revisions of ${name}\n\nWhat each revision replaced, and why. Newest last.\n`;
+    appendFileSync(join(folder, REVISIONS_FILE), `${head}\n## ${localDate(now)}\n\n${args.why.trim()}\n\nThe text it replaced:\n\n\`\`\`\`markdown\n${before.trimEnd()}\n\`\`\`\`\n`);
+  }
+  writeFileSync(file, text);
+  return { path: rel, action: exists ? "revised" : "written", name, revisions };
+}
+
+// ---- noticing a repeated process ----
+
+// Tools that are how a session starts or keeps itself, never a step of a process the owner asked
+// for. And the plain read-and-file loop: search, read, write is the record's ordinary use, not a
+// process worth a skill, so a run made only of those is never pointed at.
+const META = new Set(["evda_operating_layer", "evda_skills", "evda_write_skill", "evda_check_update"]);
+const ORDINARY = new Set(["evda_recent", "evda_search", "evda_read", "evda_write", "evda_note", "evda_circles", "evda_presets"]);
+export const MIN_STEPS = 3;
+export const MAX_STEPS = 8;
+
+// Given the session's step list (tool names, oldest first) after a call, the repeated run it now
+// ends with, as a list of tool names, or null. A run is MIN_STEPS to MAX_STEPS calls long, holds at
+// least two different tools and one that is not ordinary, and ran before, ending before this one
+// started. The longest such run wins.
+export function repeatedRun(steps) {
+  const s = steps.filter((n) => !META.has(n));
+  const n = s.length;
+  for (let len = Math.min(MAX_STEPS, Math.floor(n / 2)); len >= MIN_STEPS; len--) {
+    const tail = s.slice(n - len);
+    if (new Set(tail).size < 2 || tail.every((t) => ORDINARY.has(t))) continue;
+    for (let start = n - 2 * len; start >= 0; start--) {
+      if (tail.every((t, i) => s[start + i] === t)) return tail;
+    }
+  }
+  return null;
+}
+
+export function repeatHint(run) {
+  return `These steps have now run twice in this conversation: ${run.join(", ")}. If that is one process, write it down once as a skill with evda_write_skill (a kebab-case name, a description saying when to use it, the steps), and tell the owner in one line that you did. If it is not a process, ignore this.`;
+}
+
+// Count one call for the hint. At most one hint per distinct run per session; never with no-hint.
+export function noticeRepeat(session, name, { env = process.env } = {}) {
+  (session.steps ??= []).push(name);
+  (session.hinted ??= new Set());
+  if (skillsFalsified("no-hint", env)) return null;
+  const run = repeatedRun(session.steps);
+  if (!run) return null;
+  const key = run.join(">");
+  if (session.hinted.has(key)) return null;
+  session.hinted.add(key);
+  return repeatHint(run);
+}

package/lib/subrecord.mjs

@@ -0,0 +1,121 @@
+// Making a record inside a record from a conversation (HQ-1377, the HQ-1371 shape): the owner asks
+// for a sub-EVÐA for a project, a company or an agent, and their AI makes it through the MCP server.
+//
+// What it makes, at a path inside the record: an evda.json with the four roles (journal from
+// record/daily and record/captures, work from work/, collections from record/people, knowledge from
+// the ledger), an AGENTS.md whose owner section carries what it is for, and everything else a new
+// record gets from create-evda. It is made by the same scaffold, so a sub-record is never a second
+// shape of record.
+//
+// The parent stays as it is. Its evda.json changes only when the owner opts into "subrecords":
+// "bounded" (the parent's circles stop at the sub-record), which changes what the parent syncs and
+// so waits for confirmed: true. Doctor runs on the parent before and after, walking the new
+// sub-record as its own record; when the parent was clean before and is not after, everything this
+// call made is removed again and the report says why.
+
+import { existsSync, readdirSync, readFileSync, rmSync, writeFileSync, mkdirSync } from "node:fs";
+import { isAbsolute, join, normalize, resolve, sep } from "node:path";
+import { parseArgs, scaffold, slug } from "../create-evda.mjs";
+import { readManifest, isBounded } from "./manifest.mjs";
+import { subRecords } from "./records.mjs";
+import { doctor } from "./doctor.mjs";
+import { EvdaError } from "./errors.mjs";
+
+export const WORK_DIR = "work";
+
+// EVDA_SUBRECORD_FALSIFY=<mode,...>, for the tests: no-doctor returns without running doctor after,
+// keep-broken leaves what it made in place when doctor fails on it.
+export const SUBRECORD_FALSIFY_MODES = ["no-doctor", "keep-broken"];
+const falsified = (mode) => (process.env.EVDA_SUBRECORD_FALSIFY ?? "").split(",").map((x) => x.trim()).includes(mode);
+
+function refuse(message, code) {
+  return new EvdaError(`REFUSED: ${message} Nothing was written.`, { code, exit: 2 });
+}
+
+function runDoctor(dir) {
+  const lines = [];
+  const r = doctor(dir, { out: (l) => lines.push(l) });
+  return { exit: r.exit, text: lines.join("\n") };
+}
+
+// Where the new record may go, as a relative path, or a refusal naming why not.
+export function placeFor(evda, path) {
+  if (typeof path !== "string" || path.trim() === "") throw refuse(`evda_create_subrecord needs "path": where in the record the new EVÐA goes, such as Projects/Garden.`, "NO_PATH");
+  if (isAbsolute(path)) throw refuse(`"path" ${JSON.stringify(path)} is absolute; it is relative to the record.`, "BAD_PATH");
+  const rel = normalize(path).split(sep).join("/").replace(/\/+$/, "");
+  const abs = resolve(evda.dir, rel);
+  if (abs === evda.dir || !abs.startsWith(evda.dir + sep)) throw refuse(`"path" ${JSON.stringify(path)} is not inside the record.`, "BAD_PATH");
+  if (rel.split("/").some((part) => part.startsWith("."))) throw refuse(`"path" ${JSON.stringify(path)} goes through a dot folder, which is the tooling's, not the record's.`, "BAD_PATH");
+  const inside = subRecords(evda.dir).find((s) => rel === s || rel.startsWith(`${s}/`));
+  if (inside !== undefined) throw refuse(`${rel} is inside the sub-record at ${inside}, which is a record of its own. Make it from that record's server.`, "INSIDE_SUBRECORD");
+  for (const [key, value] of Object.entries(evda.manifest.mapping)) {
+    if (typeof value !== "string" || /^[a-z][a-z0-9-]*:/.test(value)) continue;
+    const mapped = value.replace(/\/+$/, "");
+    if (mapped === rel || mapped.startsWith(`${rel}/`)) throw refuse(`${rel} would hold ${mapped}, which this record maps as "${key}". A parent's own folders never go inside a sub-record.`, "HOLDS_ROLE");
+    if (key === "agents" && rel.startsWith(`${mapped}/`)) throw refuse(`${rel} is under ${mapped}, a file.`, "BAD_PATH");
+  }
+  if (existsSync(abs) && readdirSync(abs).length) throw refuse(`${rel} already exists and is not empty. A sub-EVÐA starts in a new or empty folder; to make an existing folder a record of its own, ask the owner and run create-evda there with --force.`, "NOT_EMPTY");
+  return { rel, abs };
+}
+
+export function createSubrecord(evda, args = {}) {
+  const allowed = ["path", "name", "purpose", "kind", "bounded", "confirmed"];
+  const extra = Object.keys(args).filter((k) => !allowed.includes(k));
+  if (extra.length) throw refuse(`evda_create_subrecord does not take ${extra.map((k) => JSON.stringify(k)).join(", ")}.`, "UNKNOWN_ARGUMENT");
+  if (args.bounded === true && args.confirmed !== true) {
+    throw refuse(`bounded: true changes this record's evda.json so its circles stop at the new sub-record, which changes what it syncs. Pass confirmed: true only when the owner said yes to that in this conversation. Without bounded, the sub-EVÐA is made and the parent is left as it is.`, "NOT_CONFIRMED");
+  }
+  const { rel, abs } = placeFor(evda, args.path);
+  const name = typeof args.name === "string" && args.name.trim() ? args.name.trim() : rel.split("/").pop();
+  const kind = args.kind ?? "person";
+  const parentId = typeof evda.manifest.id === "string" && evda.manifest.id ? evda.manifest.id : "atlas";
+  const id = `${slug(name)}.${parentId}`;
+  const owner = evda.manifest.owner?.name ?? "";
+
+  const before = runDoctor(evda.dir);
+  const manifestFile = join(evda.dir, "evda.json");
+  const parentBefore = readFileSync(manifestFile, "utf8");
+  const existed = existsSync(abs);
+  // The outermost folder this call creates, so an undo leaves no empty parent behind.
+  const parts = rel.split("/");
+  let top = abs;
+  for (let i = 1; i <= parts.length; i++) {
+    const p = join(evda.dir, ...parts.slice(0, i));
+    if (!existsSync(p)) { top = p; break; }
+  }
+  let madeParentBounded = false;
+  try {
+    const argv = [abs, "--yes", "--no-pointer", "--no-guard", "--name", name, "--kind", kind, "--id", id, "--layers", "record,ledger"];
+    if (owner) argv.push("--owner", owner);
+    if (typeof args.purpose === "string" && args.purpose.trim()) argv.push("--purpose", args.purpose.trim());
+    scaffold({ ...parseArgs(argv), force: existed });
+    // The fourth role. record/daily and record/captures fill journal, record/people collections and
+    // the ledger knowledge; work is a folder of effort files until the owner points it at a board.
+    const m = readManifest(abs);
+    m.mapping.work = WORK_DIR;
+    if (evda.manifest.read_by !== undefined && m.read_by === undefined) m.read_by = evda.manifest.read_by;
+    mkdirSync(join(abs, WORK_DIR), { recursive: true });
+    writeFileSync(join(abs, "evda.json"), `${JSON.stringify(m, null, 2)}\n`);
+    if (args.bounded === true && !isBounded(evda.manifest)) {
+      const pm = JSON.parse(parentBefore);
+      pm.subrecords = "bounded";
+      writeFileSync(manifestFile, `${JSON.stringify(pm, null, 2)}\n`);
+      madeParentBounded = true;
+    }
+  } catch (e) {
+    undo();
+    throw e;
+  }
+  const after = falsified("no-doctor") ? { exit: 0, text: "" } : runDoctor(evda.dir);
+  if (before.exit === 0 && after.exit !== 0 && !falsified("keep-broken")) {
+    undo();
+    throw new EvdaError(`REFUSED: doctor was clean on this record before and failed with the sub-EVÐA at ${rel}, so what this call made was removed and the record is as it was.\n\n${after.text}`, { code: "DOCTOR_FAILED", exit: 2 });
+  }
+  return { path: rel, id, name, parentBounded: isBounded(readManifest(evda.dir)), madeParentBounded, doctor: after, doctorBefore: before.exit };
+
+  function undo() {
+    if (existed) for (const n of readdirSync(abs)) rmSync(join(abs, n), { recursive: true, force: true });
+    else rmSync(top, { recursive: true, force: true });
+    writeFileSync(manifestFile, parentBefore);
+  }
+}

package/lib/sync-rules.mjs

@@ -0,0 +1,93 @@
+// Which files in a record sync, and which are left where they are (Spec 08, stages S0 and S1).
+//
+// One definition, read by three things that must agree: the circle plan (what a circle's members
+// are), the coverage check (every file in exactly one circle), and the shadow scan and parity check
+// (what is sent, and what the shadow must equal). Two copies of this list would be two answers to
+// "does this file sync", and parity would pass on a file both sides agreed to skip.
+//
+// Three kinds of thing never sync, and each is counted rather than dropped:
+//
+//   excluded      by name anywhere (.DS_Store, node_modules, .git), by name prefix anywhere (~$, the
+//                 owner file Word, Excel and PowerPoint keep beside a document while it is open), by
+//                 name at the root (.evda, the derived index every device rebuilds), or by a path the
+//                 plan names. Reported as EXCLUDED n.
+//   symlink       never followed and never carried: sync moves bytes, and a link's target may be
+//                 outside the record, missing, or itself. A symlink inside a circle fails the
+//                 coverage check until the plan excludes it.
+//   placeholder   an iCloud stub (`.name.icloud`) for a file whose bytes are not on this disk.
+//                 Syncing the stub would make parity pass while the file never moved, so a stub
+//                 inside a circle fails until it is downloaded.
+//
+// And one kind cannot sync yet: a file larger than the relay's blob lane takes (64 MB, less the
+// seal), which fails the coverage check until the plan excludes it.
+
+import { lstatSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+
+export const EXCLUDE_NAMES = [".DS_Store", "node_modules", ".git", ".Trash", "Icon\r"];
+// A name starting with one of these is one machine's state about a file, not the record. `~$` is
+// the Office owner file: it exists only while a document is open on that machine, and iCloud never
+// carries one, so a shadow fed by the laptop held one Hestia's record could not (HQ-1219,
+// 2026-09-25, `~$e Lantern Version 3.docx`, EXTRA).
+export const EXCLUDE_PREFIXES = ["~$"];
+export const EXCLUDE_ROOT_NAMES = [".evda"];
+// The relay refuses a blob over 64 MiB (`xania-relay/src/relay.mjs`, MAX_BLOB_BYTES); the seal adds
+// a nonce, a tag and an ephemeral key, so leave a margin.
+export const MAX_SYNC_BYTES = 64 * 1024 * 1024 - 64 * 1024;
+
+const PLACEHOLDER = /^\..+\.icloud$/;
+export const isPlaceholder = (name) => PLACEHOLDER.test(name);
+
+const norm = (rel) => rel.replace(/^\/+|\/+$/g, "");
+
+// A predicate over a relative path: is it (or something above it) excluded? `extra` is the plan's
+// own list of excluded paths, each covering itself and everything under it.
+export function excluder(extra = []) {
+  const paths = extra.map(norm).filter((p) => p !== "");
+  return (rel) => {
+    const parts = norm(rel).split("/");
+    if (parts.some((p) => EXCLUDE_NAMES.includes(p) || EXCLUDE_PREFIXES.some((x) => p.startsWith(x)))) return true;
+    if (EXCLUDE_ROOT_NAMES.includes(parts[0])) return true;
+    const r = parts.join("/");
+    return paths.some((p) => r === p || r.startsWith(`${p}/`));
+  };
+}
+
+// Walk a directory without following links. Yields { rel, kind, size } for every entry that is not
+// a directory, where kind is file | symlink | placeholder | excluded | oversize. An excluded
+// directory is yielded once, as itself, and not entered.
+export function* walk(root, { exclude = excluder(), from = "" } = {}) {
+  const dir = from === "" ? root : join(root, from);
+  let names;
+  try {
+    names = readdirSync(dir).sort();
+  } catch (e) {
+    if (e.code === "ENOENT" || e.code === "ENOTDIR") return;
+    throw e;
+  }
+  for (const name of names) {
+    const rel = from === "" ? name : `${from}/${name}`;
+    const st = lstatSync(join(root, rel));
+    if (exclude(rel)) {
+      yield { rel, kind: "excluded", size: st.isDirectory() ? 0 : st.size, dir: st.isDirectory() };
+      continue;
+    }
+    if (st.isSymbolicLink()) { yield { rel, kind: "symlink", size: 0 }; continue; }
+    if (st.isDirectory()) { yield* walk(root, { exclude, from: rel }); continue; }
+    if (isPlaceholder(name)) { yield { rel, kind: "placeholder", size: st.size }; continue; }
+    yield { rel, kind: st.size > MAX_SYNC_BYTES ? "oversize" : "file", size: st.size };
+  }
+}
+
+// The same rules as a filter a scanner applies while it walks: true means do not list it and do not
+// enter it. Everything that is not a plain, syncable file is skipped, and `walk` is what counts them.
+export function scanSkip(extra = []) {
+  const exclude = excluder(extra);
+  return (rel, st) => {
+    if (exclude(rel)) return true;
+    if (st.isSymbolicLink()) return true;
+    if (st.isDirectory()) return false;
+    const name = rel.slice(rel.lastIndexOf("/") + 1);
+    return isPlaceholder(name) || st.size > MAX_SYNC_BYTES;
+  };
+}