@nurix/etna 0.20.26 → 0.20.28

package/data/harnesses/code/hooks/mount.mjs

@@ -0,0 +1,470 @@
+// harness/code/hooks/mount.mjs
+// The one SessionStart hook: mount the pinned harness version, check latest.json for a newer one,
+// then run awareness.mjs after the tree is settled. Self-contained on purpose — lib/ is itself a
+// mounted path a bare clone lacks — so the shared core below is a byte copy of
+// packages/cli/lib/install/mount.mjs, pinned equal by tests/mount.test.mjs. Never blocks: exit 0 always.
+// Fuller account: docs/harness/code/hooks.md § mount.mjs.
+
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+import { createHash } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+// --- shared mount core: start ---
+const DEFAULT_ORIGIN = 'https://cdn.nustack.io';
+const MOUNT_BLOCK_START = '# etna:mount:start';
+const MOUNT_BLOCK_END = '# etna:mount:end';
+const MOUNTED_CLAUDE_SUBDIRS = ['skills', 'agents', 'rules', 'scripts', 'hooks'];
+const CONTRACT_NEGATIONS = [
+  '!.claude/harness.json',
+  '!.claude/settings.json',
+  '!.claude/hooks/',
+  '!.claude/hooks/mount.mjs',
+  '!.codex/hooks.json',
+];
+const FETCH_CONCURRENCY = 8;
+const CAPABILITY_GATES = { '.claude/rules/cloudflare.md': 'worker' };
+
+function sha256Of(bytes) {
+  return createHash('sha256').update(bytes).digest('hex');
+}
+
+// The machine cache every repository on the machine shares; ETNA_CACHE_DIR relocates it.
+function cacheRoot(env = process.env) {
+  return env.ETNA_CACHE_DIR || join(homedir(), '.etna', 'cache');
+}
+
+// True for a path the mount owns; the contract layer (the committed half) answers false.
+function isMountedPath(path) {
+  if (path === '.claude/hooks/mount.mjs' || path === '.codex/hooks.json') return false;
+  const parts = path.split('/');
+  if (parts[0] === '.claude') return parts.length > 2 && MOUNTED_CLAUDE_SUBDIRS.includes(parts[1]);
+  return (parts[0] === '.agents' || parts[0] === '.codex') && parts.length > 1;
+}
+
+// Numeric dotted-version order: negative, zero or positive, like a sort comparator.
+function compareVersions(a, b) {
+  const left = String(a).split('.').map((part) => parseInt(part, 10) || 0);
+  const right = String(b).split('.').map((part) => parseInt(part, 10) || 0);
+  for (let i = 0; i < Math.max(left.length, right.length); i++) {
+    const diff = (left[i] || 0) - (right[i] || 0);
+    if (diff !== 0) return diff;
+  }
+  return 0;
+}
+
+function readJsonFile(file) {
+  try {
+    return JSON.parse(readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+// Temp file then rename, so a concurrent reader sees the old file or the new one, never a torn one.
+function writeAtomic(file, bytes) {
+  mkdirSync(dirname(file), { recursive: true });
+  const temp = join(dirname(file), `.${basename(file)}.mount-${process.pid}`);
+  writeFileSync(temp, bytes);
+  renameSync(temp, file);
+}
+
+async function fetchBytes(url, fetchImpl, timeoutMs) {
+  const response = await fetchImpl(url, { signal: AbortSignal.timeout(timeoutMs) });
+  if (!response.ok) throw new Error(`GET ${url} answered ${response.status}`);
+  return Buffer.from(await response.arrayBuffer());
+}
+
+// Runs task over items with a bounded number in flight.
+async function eachLimited(items, task) {
+  let next = 0;
+  const worker = async () => {
+    while (next < items.length) {
+      const item = items[next];
+      next += 1;
+      await task(item);
+    }
+  };
+  await Promise.all(Array.from({ length: Math.min(FETCH_CONCURRENCY, items.length) }, worker));
+}
+
+// The version manifest, from the machine cache when present, else fetched and cached.
+async function resolveManifest({ origin, slug, version, cacheDir, fetchImpl, timeoutMs }) {
+  const cached = join(cacheDir, slug, version, 'manifest.json');
+  if (existsSync(cached)) return { manifest: JSON.parse(readFileSync(cached, 'utf8')), source: 'cache' };
+  const bytes = await fetchBytes(`${origin}/harness/${slug}/${version}/manifest.json`, fetchImpl, timeoutMs);
+  const manifest = JSON.parse(bytes.toString('utf8'));
+  writeAtomic(cached, bytes);
+  return { manifest, source: 'origin' };
+}
+
+// One file's bytes by sha256: the object cache first, else fetched, verified, and cached.
+async function readObject({ origin, entry, cacheDir, fetchImpl, timeoutMs }) {
+  const file = join(cacheDir, 'objects', entry.sha256);
+  if (existsSync(file)) {
+    const bytes = readFileSync(file);
+    if (sha256Of(bytes) === entry.sha256) return bytes;
+  }
+  const bytes = await fetchBytes(`${origin}/${entry.key}`, fetchImpl, timeoutMs);
+  if (sha256Of(bytes) !== entry.sha256) throw new Error(`${entry.path}: fetched bytes do not match the manifest`);
+  writeAtomic(file, bytes);
+  return bytes;
+}
+
+function mountedEntries(manifest) {
+  return (manifest.files || []).filter(
+    (entry) => (entry.policy === undefined || entry.policy === 'mount') && isMountedPath(entry.path),
+  );
+}
+
+// A Worker's config at the root, or one or two directory levels down (node_modules and dot dirs skipped).
+function hasWorkerConfig(projectDir) {
+  const names = ['wrangler.jsonc', 'wrangler.toml'];
+  const search = (dir, depth) => {
+    if (names.some((name) => existsSync(join(dir, name)))) return true;
+    if (depth === 0) return false;
+    let entries = [];
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return false;
+    }
+    return entries.some(
+      (entry) => entry.isDirectory() && entry.name !== 'node_modules' && !entry.name.startsWith('.') && search(join(dir, entry.name), depth - 1),
+    );
+  };
+  return search(projectDir, 2);
+}
+
+// The mounted entries this project's capabilities admit; a gated rule mounts only where its capability is.
+function admittedEntries(projectDir, entries) {
+  const capabilities = { worker: null };
+  return entries.filter((entry) => {
+    const gate = entry.requires || CAPABILITY_GATES[entry.path];
+    if (!gate) return true;
+    if (capabilities[gate] === null) capabilities[gate] = gate === 'worker' ? hasWorkerConfig(projectDir) : false;
+    return capabilities[gate] === true;
+  });
+}
+
+function filesBelow(root, rel) {
+  const full = join(root, rel);
+  let stat;
+  try {
+    stat = statSync(full);
+  } catch {
+    return [];
+  }
+  if (!stat.isDirectory()) return [rel];
+  return readdirSync(full).flatMap((name) => filesBelow(root, `${rel}/${name}`));
+}
+
+// On-disk files the mount may delete: inside owned component names, and the hooks tree bar mount.mjs.
+function prunableFiles(projectDir, owned) {
+  const out = [];
+  for (const sub of ['skills', 'agents', 'rules', 'scripts']) {
+    for (const name of owned[sub] || []) out.push(...filesBelow(projectDir, `.claude/${sub}/${name}`));
+  }
+  for (const rel of filesBelow(projectDir, '.claude/hooks')) if (rel !== '.claude/hooks/mount.mjs') out.push(rel);
+  for (const name of owned.skills || []) out.push(...filesBelow(projectDir, `.agents/skills/${name}`));
+  for (const name of owned.agents || []) {
+    out.push(...filesBelow(projectDir, `.codex/agents/${name.replace(/\.md$/, '')}.toml`));
+  }
+  return out.filter((rel) => rel !== '.claude/hooks');
+}
+
+function unionOwned(...maps) {
+  const out = {};
+  for (const map of maps) {
+    for (const [sub, names] of Object.entries(map || {})) out[sub] = [...new Set([...(out[sub] || []), ...names])];
+  }
+  return out;
+}
+
+function removeEmptyParents(projectDir, rel) {
+  let dir = dirname(rel);
+  while (dir.split('/').length > 2) {
+    const full = join(projectDir, dir);
+    try {
+      if (readdirSync(full).length > 0) return;
+      rmSync(full, { recursive: true, force: true });
+    } catch {
+      return;
+    }
+    dir = dirname(dir);
+  }
+}
+
+// Writes the manifest's mounted files that differ on disk, then deletes owned names the manifest omits.
+async function mountFromManifest({ projectDir, manifest, origin, cacheDir, fetchImpl, timeoutMs, priorOwned }) {
+  const all = mountedEntries(manifest);
+  const entries = admittedEntries(projectDir, all);
+  const listed = new Set(entries.map((entry) => entry.path));
+  const written = [];
+  const failed = [];
+  const removed = [];
+  const stale = entries.filter((entry) => {
+    const dest = join(projectDir, entry.path);
+    return !(existsSync(dest) && sha256Of(readFileSync(dest)) === entry.sha256);
+  });
+  await eachLimited(stale, async (entry) => {
+    try {
+      writeAtomic(join(projectDir, entry.path), await readObject({ origin, entry, cacheDir, fetchImpl, timeoutMs }));
+      written.push(entry.path);
+    } catch {
+      failed.push(entry.path);
+    }
+  });
+  for (const rel of prunableFiles(projectDir, unionOwned(manifest.owned, priorOwned))) {
+    if (listed.has(rel)) continue;
+    rmSync(join(projectDir, rel), { force: true });
+    removeEmptyParents(projectDir, rel);
+    removed.push(rel);
+  }
+  return { written: written.sort(), failed: failed.sort(), removed, mountedPaths: all.map((entry) => entry.path) };
+}
+
+// The block's lines: contract negations, then the mounted top-level names and the state folder.
+function ignoreBlockLines(mountedPaths) {
+  const names = new Set(['.claude/state/']);
+  for (const path of mountedPaths) {
+    const parts = path.split('/');
+    if (parts[0] === '.claude') names.add(parts.length > 3 ? `${parts.slice(0, 3).join('/')}/` : path);
+    else names.add(parts.length > 2 ? `${parts[0]}/${parts[1]}/` : path);
+  }
+  return [
+    MOUNT_BLOCK_START,
+    '# Managed by etna: the mounted harness, rewritten on every mount. Edit outside this block.',
+    ...CONTRACT_NEGATIONS,
+    ...[...names].sort(),
+    MOUNT_BLOCK_END,
+  ];
+}
+
+// Rewrites the managed block at the end of .gitignore; a bare `.claude` line becomes `.claude/*`.
+function writeIgnoreBlock(projectDir, mountedPaths) {
+  const file = join(projectDir, '.gitignore');
+  const before = existsSync(file) ? readFileSync(file, 'utf8') : '';
+  const kept = [];
+  let inBlock = false;
+  for (const line of before.split('\n')) {
+    if (line.trim() === MOUNT_BLOCK_START) inBlock = true;
+    else if (inBlock) inBlock = line.trim() !== MOUNT_BLOCK_END;
+    else {
+      const bare = /^(\/?)\.claude\/?\s*$/.exec(line);
+      kept.push(bare ? `${bare[1]}.claude/*` : line);
+    }
+  }
+  while (kept.length && kept[kept.length - 1].trim() === '') kept.pop();
+  const block = ignoreBlockLines(mountedPaths).join('\n');
+  const after = (kept.length ? `${kept.join('\n')}\n\n` : '') + `${block}\n`;
+  if (after === before) return false;
+  writeAtomic(file, after);
+  return true;
+}
+
+// Records what is mounted, beside the folder's self-ignoring `*` .gitignore.
+function recordMount(projectDir, record) {
+  const dir = join(projectDir, '.claude', 'state');
+  mkdirSync(dir, { recursive: true });
+  if (!existsSync(join(dir, '.gitignore'))) writeFileSync(join(dir, '.gitignore'), '*\n');
+  const body = { ...record, mountedAt: new Date().toISOString() };
+  writeAtomic(join(dir, 'mount.json'), `${JSON.stringify(body, null, 2)}\n`);
+}
+
+function mountSettings(marker) {
+  const mount = (marker && marker.mount) || {};
+  return {
+    origin: String(mount.origin || DEFAULT_ORIGIN).replace(/\/+$/, ''),
+    track: mount.track === 'pinned' ? 'pinned' : 'latest',
+  };
+}
+
+// Mounts the pinned version unless the mount record already names it.
+async function mountHarness({ projectDir, cacheDir = cacheRoot(), fetchImpl = globalThis.fetch, timeoutMs = 5000, force = false }) {
+  const marker = readJsonFile(join(projectDir, '.claude', 'harness.json'));
+  if (!marker || !marker.harness || !marker.version) return { status: 'unmarked' };
+  const { origin } = mountSettings(marker);
+  const slug = marker.harness;
+  const version = marker.version;
+  const prior = readJsonFile(join(projectDir, '.claude', 'state', 'mount.json'));
+  if (!force && prior && prior.version === version) return { status: 'current', slug, version, digest: prior.digest };
+  let resolved;
+  try {
+    resolved = await resolveManifest({ origin, slug, version, cacheDir, fetchImpl, timeoutMs });
+  } catch (error) {
+    return { status: 'unavailable', slug, version, origin, reason: error.message };
+  }
+  const { manifest, source } = resolved;
+  const result = await mountFromManifest({
+    projectDir,
+    manifest,
+    origin,
+    cacheDir,
+    fetchImpl,
+    timeoutMs,
+    priorOwned: prior && prior.owned,
+  });
+  writeIgnoreBlock(projectDir, result.mountedPaths);
+  if (result.failed.length === 0) {
+    recordMount(projectDir, { version, digest: manifest.digest || null, owned: manifest.owned || null });
+  }
+  return { status: result.failed.length ? 'partial' : 'mounted', slug, version, source, ...result };
+}
+
+async function readLatest({ origin, slug, fetchImpl, timeoutMs }) {
+  return JSON.parse((await fetchBytes(`${origin}/harness/${slug}/latest.json`, fetchImpl, timeoutMs)).toString('utf8'));
+}
+
+// Stages a version into the cache, the manifest verified against the pointer and written last.
+async function stageVersion({ origin, slug, latest, cacheDir, fetchImpl, timeoutMs }) {
+  const bytes = await fetchBytes(`${origin}/${latest.manifest}`, fetchImpl, timeoutMs);
+  if (sha256Of(bytes) !== latest.manifestSha256) {
+    throw new Error(`the ${slug} ${latest.version} manifest does not match latest.json's manifestSha256 — nothing staged`);
+  }
+  const manifest = JSON.parse(bytes.toString('utf8'));
+  await eachLimited(mountedEntries(manifest), (entry) => readObject({ origin, entry, cacheDir, fetchImpl, timeoutMs }));
+  writeAtomic(join(cacheDir, slug, latest.version, 'manifest.json'), bytes);
+  return manifest;
+}
+
+// Asks latest.json for a newer version; stages it, and on track latest moves the pin.
+async function checkForUpdate({ projectDir, cacheDir = cacheRoot(), fetchImpl = globalThis.fetch, timeoutMs = 2000 }) {
+  const markerFile = join(projectDir, '.claude', 'harness.json');
+  const marker = readJsonFile(markerFile);
+  if (!marker || !marker.harness || !marker.version) return { status: 'unmarked' };
+  const { origin, track } = mountSettings(marker);
+  const slug = marker.harness;
+  let latest;
+  try {
+    latest = await readLatest({ origin, slug, fetchImpl, timeoutMs });
+  } catch (error) {
+    return { status: 'unreachable', reason: error.message };
+  }
+  if (!latest || !latest.version || compareVersions(latest.version, marker.version) <= 0) return { status: 'current' };
+  if (!existsSync(join(cacheDir, slug, latest.version, 'manifest.json'))) {
+    try {
+      await stageVersion({ origin, slug, latest, cacheDir, fetchImpl, timeoutMs: Math.max(timeoutMs, 5000) });
+    } catch (error) {
+      return { status: 'refused', reason: error.message, notice: `Harness update not staged: ${error.message}` };
+    }
+  }
+  const mounted = marker.version;
+  if (track === 'latest') writeAtomic(markerFile, `${JSON.stringify({ ...marker, version: latest.version }, null, 2)}\n`);
+  const tail = track === 'pinned' ? ' (track: pinned — bump `version` in .claude/harness.json to take it)' : '';
+  return {
+    status: 'staged',
+    from: mounted,
+    to: latest.version,
+    track,
+    notice: `Harness ${slug} ${latest.version} is ready (mounted ${mounted}); restart the session to run on it${tail}`,
+  };
+}
+// --- shared mount core: end ---
+
+const HOOK_DIR = dirname(fileURLToPath(import.meta.url));
+
+function readStdinText() {
+  try {
+    return readFileSync(0, 'utf8');
+  } catch {
+    return '';
+  }
+}
+
+// The one line a mount result earns in the session context, or null when nothing happened.
+function mountLine(result) {
+  if (result.status === 'mounted' || result.status === 'partial') {
+    const failed = result.failed.length ? `; ${result.failed.length} file(s) failed verification and kept their prior copy` : '';
+    return `Harness: mounted ${result.slug} ${result.version} from the ${result.source} — ${result.written.length} file(s) written, ${result.removed.length} removed${failed}`;
+  }
+  if (result.status === 'unavailable') {
+    return `Harness ${result.slug} ${result.version} not mounted — ${result.origin} unreachable and no cached copy; the session runs on what is on disk.`;
+  }
+  return null;
+}
+
+// Runs awareness.mjs after the mount, handing it the same payload; its stdout is returned.
+function runAwareness(raw) {
+  const script = join(HOOK_DIR, 'awareness.mjs');
+  if (!existsSync(script)) return '';
+  const result = spawnSync(process.execPath, [script], {
+    input: raw,
+    encoding: 'utf8',
+    env: process.env,
+    timeout: 12000,
+    maxBuffer: 16 * 1024 * 1024,
+  });
+  return result.stdout || '';
+}
+
+function emit(lines, notices, awareness) {
+  if (!lines.length) {
+    if (awareness) process.stdout.write(awareness);
+    return;
+  }
+  let parsed = null;
+  try {
+    parsed = awareness ? JSON.parse(awareness) : null;
+  } catch {
+    parsed = null;
+  }
+  const context = parsed && parsed.hookSpecificOutput && parsed.hookSpecificOutput.additionalContext;
+  const prefix = lines.join('\n');
+  const out = {
+    ...(parsed || {}),
+    hookSpecificOutput: { hookEventName: 'SessionStart', additionalContext: context ? `${prefix}\n\n${context}` : prefix },
+  };
+  if (notices.length) out.systemMessage = notices.join('\n');
+  process.stdout.write(JSON.stringify(out));
+}
+
+async function main() {
+  const raw = readStdinText();
+  let payload = {};
+  try {
+    payload = raw ? JSON.parse(raw) : {};
+  } catch {
+    payload = {};
+  }
+  const projectDir = process.env.CLAUDE_PROJECT_DIR || payload.cwd || process.cwd();
+  const lines = [];
+  const notices = [];
+  try {
+    const result = await mountHarness({ projectDir });
+    const line = mountLine(result);
+    if (line) lines.push(line);
+    if (result.status === 'unavailable') notices.push(line);
+  } catch (error) {
+    lines.push(`Harness mount failed (${error.message}); the session runs on what is on disk.`);
+  }
+  try {
+    const update = await checkForUpdate({ projectDir });
+    if (update.notice) {
+      lines.push(update.notice);
+      notices.push(update.notice);
+    }
+  } catch {
+    /* the update check is a convenience */
+  }
+  emit(lines, notices, runAwareness(raw));
+}
+
+try {
+  await main();
+} catch {
+  /* never block a session */
+} finally {
+  process.exitCode = 0;
+}

package/data/harnesses/code/skills/documentation/SKILL.md

@@ -7,7 +7,7 @@ description: "Use when creating or substantively editing ANY markdown doc — in
 
 **This skill is a template & generator library, not an orchestrator.** It supplies the templates, the frontmatter-derivation generator, and the co-authoring workflow that _agents_ call to produce individual docs. It does **not** baseline, audit, or reconcile a repo's doc tree — that is the **`maintenance` agent (baseline mode)**, which calls this skill for each template it scaffolds. Reach here to generate _one_ doc from a template; reach for the `maintenance` agent (baseline mode) to bring a whole repo into shape.
 
-Document contracts and architecture, not implementation details. Signatures and API shapes belong in a reference document (an API reference, an environment registry); every other genre states design and promises and leaves mechanism to the code — never paste full implementations (they rot fast). Use ASCII diagrams over prose for flows. Only document state at persistence boundaries (Redux persistence, DB schemas, API shapes), not component-level or transient state. Mark deprecated fields with `// UNUSED:` comments stating why the field is dead now — never where it went or when it dies. Breaking changes belong in changelogs only, not module docs.
+Document contracts and architecture, not implementation details. Signatures and API shapes belong in a reference document (an API reference, an environment registry); every other genre states design and promises and leaves mechanism to the code — never paste full implementations (they rot fast). A diagram sits beside the prose and never replaces it: ASCII for structure at rest, mermaid for behaviour over time (`references/style-guide.md` § Diagrams). Only document state at persistence boundaries (Redux persistence, DB schemas, API shapes), not component-level or transient state. Mark deprecated fields with `// UNUSED:` comments stating why the field is dead now — never where it went or when it dies. Breaking changes belong in changelogs only, not module docs.
 
 ---
 
@@ -42,9 +42,9 @@ Document contracts and architecture, not implementation details. Signatures and
 | "Folded in from the `NuStack-X` repo (2026-06-12)." | "Vendor-connector catalogue; one subpath per vendor." |
 | "was X, now Y", "the old worker", "Phase 2 softened this", "v1 → v2" | The current fact, with no predecessor named |
 
-The journey — dates, migrations, progress, supersessions — lives only in records (`docs/history/`); when reality changes, a truth document simply becomes correct. The full strip-list and the record-side rules: [`references/style-guide.md`](references/style-guide.md) § The Two Natures — Tense & History.
+The journey — dates, migrations, progress, supersessions — lives only in records (`docs/history/`); when reality changes, a truth document simply becomes correct. The full strip-list and the record-side rules: [`references/style-guide.md`](references/style-guide.md) § The Two Natures — tense and history.
 
-**A date in a truth document is a defect, and the list of exceptions is closed.** Not a softened preference: a truth document carries no dated line at all, because a date answers *when did this happen*, which is a record's question, and a reader who needs the answer is reading the wrong file. The four exceptions, and there are no others: the frontmatter's tooling keys (`last-reviewed:`, `last-updated:`, `rev:` — written by tooling, never by you), an Architecture Decision's **Decision Changelog** tail, `docs/structure.md`'s **Health Log** tail, and a dated path inside a link or code span, which is a *citation* of a record rather than a claim about the present.
+**A date in a truth document is a defect, and the list of exceptions is closed.** Not a softened preference: a truth document carries no dated line at all, because a date answers *when did this happen*, which is a record's question, and a reader who needs the answer is reading the wrong file. The three exceptions, and there are no others: the frontmatter's tooling keys (`last-reviewed:`, `last-updated:`, `rev:` — written by tooling, never by you), an Architecture Decision's **Decision Changelog** tail, and a dated path inside a link or code span, which is a *citation* of a record rather than a claim about the present. The `maintenance` agent's Health Log is a record of its own (`docs/history/health-log.md`), not a tail on a truth document.
 
 **Cite a record by what it is, never by when it was.** `the dev reset runbook` links to the file; "the 2026-09-13 reset" states a date the reader must now keep in their head and that goes stale as soon as a second reset happens. The link carries the date in its path, where it belongs, and the prose stays true forever.
 
@@ -74,9 +74,9 @@ The two guarantees are complementary and both break on mixing: a reader holding
 - **Indexes describe directories, never files.** `docs/README.md` — the top-level index of the documentation folder — is a description of its directories: one entry per folder saying what the folder holds, who reads it and how its files are named. It carries no file list and no file tree: not a per-file row, not a `├──` tree of files, not a tree at all — `docs/structure.md` is the one place the tree lives, as the authority on placement. The same holds for a `README.md` / `Readme.md` at any level of `docs/`. `ls` is the roster, and the ownership index is how a document is found for a path. A per-file row has to be edited on every add, rename and retirement, so the index's history records roster churn instead of what the index said, and a reader cannot tell when the index itself changed. The only files an index may link are the mandated scaffolds (`structure.md`, `operations/setup.md`, `history/CHANGELOG.md`, `history/backlog.md`, `memory/main.md`) and a sibling folder's own `Readme.md`. `scripts/doc-lint.mjs` blocks the rest as `index-lists-files`, and blocks a tree drawn in a folder index as `index-file-tree`. An inverse (which checklists verify a feature, which docs a folder holds) is generated, never written.
 - **Truth documents cite records for the _why_, never the _when_.** `Provenance: AD-002` is good; "decided in AD-002 and shipped 2026-06-13" is not. Routing/index docs point only to truth documents as a topic's authority — never a plan or changelog entry as the "read first" source. (An index _of the records themselves_ — a History section listing `plans/`, `changelog/` — is sanctioned.)
 
-**A document is intent and promises; facts are the graph's.** An owning document (feature, package, system) answers why the product is shaped this way and what it promises, and names the objects it designs in `objects:`. Every computable fact — a table's columns and vocabularies, a foreign key and its delete rule, which function writes which column, which route sits behind which guard, which code a refusal answers, which file holds what — is the code graph's to compute (`docs/architecture/systems/knowledge-layer.md`), and a hand-typed copy of it is the defect this rule removes: it reads as authoritative and is wrong the day the code moves. Mechanism stays in the code, reasons stay in the document, and the document points by object and symbol name, never by line number. `doc-lint` blocks the retired mechanism sections in an owning document (`mechanism-section`) and an owning document without `objects:`. `keywords:` is not a key: an object's name is its discovery term. **The body is read by people** — plain English a newcomer reads top to bottom, with code named only at a cross-cutting seam the graph would not lead a reader to from the feature's own files (a middleware, a gate, a hook, a shared store) and every other identifier in the closing **For the agent** footer; the owning genres read Why it exists · How it works · What was decided · What it promises · Known gaps · For the agent (`references/style-guide.md` § Documents are read by people; `doc-lint` warns `body-identifier`, `list-not-prose`, `formula-run`).
+**A document is intent and promises; facts are the graph's.** An owning document (feature, package, system) answers why the product is shaped this way and what it promises, and names the objects it designs in `objects:`. Every computable fact — a table's columns and vocabularies, a foreign key and its delete rule, which function writes which column, which route sits behind which guard, which code a refusal answers, which file holds what — is the code graph's to compute (`docs/architecture/systems/knowledge-layer.md`), and a hand-typed copy of it is the defect this rule removes: it reads as authoritative and is wrong the day the code moves. Mechanism stays in the code, reasons stay in the document, and the document points by object and symbol name, never by line number. `doc-lint` blocks the retired mechanism sections in an owning document (`mechanism-section`) and an owning document without `objects:`. `keywords:` is not a key: an object's name is its discovery term. **The body is scanned by people** — sharp bullets under noun-phrase headings, each a bold noun-phrase label, a colon, then one or two plain sentences; code named only where a person types or sees it, or at a cross-cutting seam the graph would not lead a reader to (a middleware, a gate, a hook, a shared store); every other pointer in the closing **For the agent** footer. The owning genres read Scope · Flows (Flow for a system, Usage for a package) · Decisions · Promises · Gaps · For the agent (`references/style-guide.md` § Labels, § Owning documents — the body and the footer; `doc-lint` warns `body-identifier`, `clause-label` and `second-person`).
 
-**Every document that explains is written from the outside in, and every sentence passes the stability test.** Open on the question and its boundary, then the model with its numbered principles, then the parts and how they relate, then each part's decisions — and stop at the genre's deepest layer: decisions for doctrine, cross-package behaviour for a system, the public contract for a package, the full user-facing behaviour for a feature. A sentence that would have to change when a function is renamed, a file moves, or a route, column or error code changes is the code's, not the document's. The code is the authority on *what*; the document is the authority on *why*, and a disagreement on *why* is a defect to raise. The layers, the test and the per-genre depth table are [`references/style-guide.md`](references/style-guide.md) § Shape — the model first, the detail after.
+**Every document that explains is written from the outside in, and every sentence passes the stability test.** Open on the question and its boundary, then the model with its numbered principles, then the parts and how they relate, then each part's decisions — and stop at the genre's deepest layer: decisions for doctrine, cross-package behaviour for a system, the public contract for a package, the full user-facing behaviour for a feature. A sentence that would have to change when a function is renamed, a file moves, or a route, column or error code changes is the code's, not the document's. The code is the authority on *what*; the document is the authority on *why*, and a disagreement on *why* is a defect to raise. **Every heading and every bold bullet label is a noun phrase** — it names; it has no verb, so it carries no tense, person or voice ("Decisions", never "What was decided"; "Organization user:", never "You already belong to an organization:"), and the sentence after it is third person ("user lands…", never "you land…"). The layers, the test, the label rule and the per-genre depth table are [`references/style-guide.md`](references/style-guide.md) § Shape — the model first, the detail after, and § Labels.
 
 **No empty stubs.** Never leave a template section as an empty placeholder — omit any section with nothing real to say (each template declares its required core; everything else is optional). Write an explicit "None" only where the absence itself is information (e.g., a plan's Cross-Module Contracts Affected, an LLD's Ownership Conflicts). An empty table stub reads as "not yet researched"; an omitted section reads as "doesn't apply" — keep those meanings distinct.
 
@@ -186,7 +186,7 @@ update, and the `maintenance` agent's baseline pass, route there.
 | File | Use For |
 | --- | --- |
 | `templates/` | One file per template, indexed by [`Readme.md`](templates/Readme.md) — feature (LLD), changelog, plan, AD, steering docs, API reference, environment registry, operations procedure, migration runbook, protected files, READMEs, and the baseline scaffolds |
-| `references/style-guide.md` | Writing rules, formatting conventions, the two-natures tense rules |
+| `references/style-guide.md` | The writing-style authority: the eight principles, depth per genre, the outside-in shape and stability test, noun-phrase labels and third-person voice, the owning document's body and footer, the two-natures tense rules, diagrams, headings, reference-document detail |
 | `references/instruction-style.md` | The style for instruction files (`CLAUDE.md`, rules, agents, skill prose) — the every-line test, armor vs. narration, voice, negative space |
 | `references/frontmatter.md` | Deriving a feature doc's `objects:` / `owns:` / `module:` / `status:` from code |
 | `references/untemplated.md` | How to write a document no template covers (nature, placement, shape) + the co-authoring workflow |

package/data/harnesses/code/skills/documentation/references/examples.md

@@ -146,37 +146,41 @@ Replaced change-tracking merge with version-based conflict resolution.
 
 ---
 
-## Example 4: Data Flow
+## Example 4: Flow
 
-### ❌ Bad: Prose Description
+### ❌ Bad: Mechanism narrated in a paragraph
 
 ```markdown
+## Data Flow
+
 When the page loads, the useAppInit hook calls the syncData function. This function first fetches data from the server using the API. Then it gets the local data from Redux. After that, it compares versions...
 ```
 
-### ✅ Good: Diagram + Key Points
+**Problems:** names a hook, a function and a store that a rename would invalidate (the stability test); runs parallel cases together in one paragraph; gives a scanning reader no label to land on; "Data Flow" is a retired mechanism section.
 
-```markdown
-## Data Flow
+### ✅ Good: Labelled bullets, a role-level diagram beside them
 
-┌─────────────────────────────────────────┐
-│               DATA SYNC                 │
-├─────────────────────────────────────────┤
-│                                         │
-│   ┌──────┐     ┌──────┐     ┌──────┐    │
-│   │Server│────▶│Merge │────▶│Redux │    │
-│   │ API  │     │      │     │Store │    │
-│   └──────┘     └──────┘     └──────┘    │
-│        │                                │
-│        ▼                                │
-│   Version Check                         │
-│                                         │
-└─────────────────────────────────────────┘
-
-**Trigger:** `useAppInit()` on page load
-
-**Version Rule:** Match → local wins, Mismatch → server wins
+````markdown
+## Flows
+
+### Page load
+
+- **Fresh data:** the page fetches the server's copy and the local copy on every load; nothing is cached between visits.
+- **Matching versions:** local changes win and are kept.
+- **Mismatched versions:** the server's copy wins and local changes are dropped.
+
+```mermaid
+sequenceDiagram
+  participant Page
+  participant Server
+  participant Store
+  Page->>Server: fetch the server's copy
+  Page->>Store: read the local copy
+  Page->>Store: write the merged copy
 ```
+````
+
+**Why it works:** every fact is in the bullets, so a reader who greps finds it without the diagram; the labels are noun phrases a scanning reader lands on; the diagram names roles, never a function or a file, so no rename touches it.
 
 ---
 
@@ -242,7 +246,7 @@ The feature doc states only what is:
 ```markdown
 ## Export Pipeline
 
-`src/export/run.js` renders every export format from one job queue. Output is
+The exporter renders every export format from one job queue. Output is
 buffered per job (streaming is out of scope — see `docs/history/backlog.md`).
 ```
 
@@ -272,8 +276,8 @@ Extracted export logic from the `reports` worker into `src/export/`.
 | ---------- | -------------------- | --------------------------- |
 | Code       | Full implementations | Signatures + contracts      |
 | State      | Every occurrence     | Persistence points only     |
-| Flows      | Prose paragraphs     | ASCII diagrams              |
+| Flows      | Paragraphs naming functions | Labelled bullets in plain words, a role-level diagram beside them |
 | Changelogs | "Updated X"          | Function names + migrations |
 | Decisions  | New doc per revision | One AD per subject, updated in place |
 | History    | Narrated in the doc  | Present-tense doc + dated record |
-| Length     | 100+ lines           | 20-40 lines                 |
+| Length     | Padded with mechanism | The genre's own expectation; length is a signal, never a target |