@friedbotstudio/create-baseline 0.1.0

package/src/cli/install.js

@@ -0,0 +1,93 @@
+import { cp, mkdir, readdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { buildManifestFromDir, saveManifest } from './manifest.js';
+import { deepMergeMcpServers } from './mcp.js';
+import { pathExists } from './util.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+// Package root contains src/ and obj/template/ as siblings of src/cli/.
+const PACKAGE_ROOT = resolve(__dirname, '../..');
+const NPMRC_TEMPLATE_PATH = join(PACKAGE_ROOT, 'src/.npmrc.template');
+
+export const NEVER_TOUCH = Object.freeze(['.claude/project.json']);
+export const SPECIAL_MERGE = Object.freeze(['.mcp.json']);
+
+async function listFiles(root, base = root, acc = []) {
+  for (const entry of await readdir(root, { withFileTypes: true })) {
+    const full = join(root, entry.name);
+    if (entry.isDirectory()) {
+      await listFiles(full, base, acc);
+    } else if (entry.isFile()) {
+      acc.push(relative(base, full).split(sep).join('/'));
+    }
+  }
+  return acc;
+}
+
+async function writeBaselineManifest(target) {
+  const files = await listFiles(target);
+  const filtered = files.filter((p) => p !== '.claude/.baseline-manifest.json');
+  const m = await buildManifestFromDir(target, filtered);
+  await mkdir(join(target, '.claude'), { recursive: true });
+  await saveManifest(join(target, '.claude/.baseline-manifest.json'), m);
+}
+
+function makeFilter(opts) {
+  return (src, _dest) => {
+    const rel = relative(opts.templateRoot, src).split(sep).join('/');
+    if (rel === '') return true;
+    if (NEVER_TOUCH.includes(rel) && opts.skipNeverTouch) return false;
+    if (SPECIAL_MERGE.includes(rel) && opts.skipSpecialMerge) return false;
+    return true;
+  };
+}
+
+async function applySpecialAndNeverTouch(templateDir, target) {
+  for (const rel of NEVER_TOUCH) {
+    const dst = join(target, rel);
+    if (!(await pathExists(dst))) {
+      const src = join(templateDir, rel);
+      if (await pathExists(src)) {
+        await mkdir(join(target, rel.split('/').slice(0, -1).join('/')), { recursive: true });
+        await cp(src, dst);
+      }
+    }
+  }
+
+  for (const rel of SPECIAL_MERGE) {
+    const src = join(templateDir, rel);
+    const dst = join(target, rel);
+    if (await pathExists(src)) {
+      await deepMergeMcpServers(src, dst);
+    }
+  }
+}
+
+// npm pack drops `.npmrc` from the published tarball even when listed in
+// package.json files (registry hardening). To ship the hardened operator
+// defaults (`ignore-scripts=true`, `min-release-age=7`) into target projects,
+// install.js overlays target/.npmrc from src/.npmrc.template at install time.
+async function materializeNpmrc(target) {
+  const dst = join(target, '.npmrc');
+  if (await pathExists(dst)) return; // never overwrite an existing operator config
+  if (!(await pathExists(NPMRC_TEMPLATE_PATH))) return; // fixture / dev tree without the template — no-op
+  const bytes = await readFile(NPMRC_TEMPLATE_PATH, 'utf8');
+  await writeFile(dst, bytes);
+}
+
+export async function freshInstall(templateDir, target) {
+  const filter = makeFilter({ templateRoot: templateDir, skipNeverTouch: false, skipSpecialMerge: true });
+  await cp(templateDir, target, { recursive: true, force: false, filter });
+  await applySpecialAndNeverTouch(templateDir, target);
+  await materializeNpmrc(target);
+  await writeBaselineManifest(target);
+}
+
+export async function forceInstall(templateDir, target) {
+  const filter = makeFilter({ templateRoot: templateDir, skipNeverTouch: true, skipSpecialMerge: true });
+  await cp(templateDir, target, { recursive: true, force: true, filter });
+  await applySpecialAndNeverTouch(templateDir, target);
+  await materializeNpmrc(target);
+  await writeBaselineManifest(target);
+}

package/src/cli/io.js

@@ -0,0 +1,27 @@
+import { createInterface } from 'node:readline/promises';
+
+export function log(msg) {
+  process.stdout.write(msg + '\n');
+}
+
+export function warn(msg) {
+  process.stderr.write('Warning: ' + msg + '\n');
+}
+
+export function error(msg) {
+  process.stderr.write('Error: ' + msg + '\n');
+}
+
+export const isTTY = !!process.stdin.isTTY;
+
+export async function ask(prompt, opts = {}) {
+  const input = opts.input ?? process.stdin;
+  const output = opts.output ?? process.stdout;
+  const rl = createInterface({ input, output });
+  try {
+    const answer = await rl.question(prompt);
+    return answer.replace(/\r?\n$/, '');
+  } finally {
+    rl.close();
+  }
+}

package/src/cli/manifest.js

@@ -0,0 +1,38 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { join } from 'node:path';
+
+export const MANIFEST_VERSION = 1;
+
+export async function hashFile(path) {
+  const buf = await readFile(path);
+  return createHash('sha256').update(buf).digest('hex');
+}
+
+export async function loadManifest(path) {
+  let text;
+  try {
+    text = await readFile(path, 'utf8');
+  } catch (err) {
+    if (err.code === 'ENOENT') return null;
+    throw err;
+  }
+  return JSON.parse(text);
+}
+
+export async function saveManifest(path, m) {
+  await writeFile(path, JSON.stringify(m, null, 2) + '\n');
+}
+
+export async function buildManifestFromDir(rootDir, fileList) {
+  const files = {};
+  const sorted = [...fileList].sort();
+  for (const rel of sorted) {
+    files[rel] = await hashFile(join(rootDir, rel));
+  }
+  return {
+    manifest_version: MANIFEST_VERSION,
+    generated_at: new Date().toISOString(),
+    files,
+  };
+}

package/src/cli/mcp.js

@@ -0,0 +1,54 @@
+import { readFile, writeFile, access } from 'node:fs/promises';
+
+/**
+ * Merge `template/.mcp.json` into the target's `.mcp.json` with **baseline-refresh**
+ * semantics:
+ *
+ *   - Servers named in the template are baseline-canonical. The merge refreshes
+ *     them from the template — so users running `--merge` receive baseline arg
+ *     and env updates (e.g., the `--browser chrome --isolated` flags on
+ *     playwright). A user who customized a baseline-named server loses that
+ *     customization; intentional customizations belong under a non-baseline name.
+ *   - Servers absent from the template are user-added and are preserved byte-for-byte.
+ *   - Top-level JSON keys outside `mcpServers` follow the same rule: template
+ *     keys are added when missing; target's existing keys are preserved.
+ *   - When the target is absent, the template is written verbatim.
+ *
+ * Decision recorded in: README "MCP merge semantics"; this comment is the
+ * authoritative implementation note.
+ */
+export async function deepMergeMcpServers(templatePath, targetPath) {
+  const templateText = await readFile(templatePath, 'utf8');
+  const template = JSON.parse(templateText);
+
+  let target;
+  try {
+    await access(targetPath);
+    const targetText = await readFile(targetPath, 'utf8');
+    target = JSON.parse(targetText);
+  } catch {
+    await writeFile(targetPath, templateText);
+    return;
+  }
+
+  const tplServers = (template && template.mcpServers) || {};
+  const tgtServers = (target && target.mcpServers) || {};
+
+  // Baseline-canonical names = names that appear in the template. Refresh those
+  // from the template; preserve every other server byte-for-byte.
+  const mergedServers = { ...tgtServers };
+  for (const [name, cfg] of Object.entries(tplServers)) {
+    mergedServers[name] = cfg;
+  }
+
+  const merged = { ...target, mcpServers: mergedServers };
+
+  for (const [key, value] of Object.entries(template || {})) {
+    if (key === 'mcpServers') continue;
+    if (!(key in merged)) {
+      merged[key] = value;
+    }
+  }
+
+  await writeFile(targetPath, JSON.stringify(merged, null, 2) + '\n');
+}

package/src/cli/merge.js

@@ -0,0 +1,107 @@
+import { cp, mkdir, unlink } from 'node:fs/promises';
+import { join, dirname } from 'node:path';
+import { hashFile, saveManifest } from './manifest.js';
+import { deepMergeMcpServers } from './mcp.js';
+import { NEVER_TOUCH, SPECIAL_MERGE } from './install.js';
+import { pathExists } from './util.js';
+
+export const ACTION_KINDS = Object.freeze({
+  ADD: 'ADD',
+  OVERWRITE: 'OVERWRITE',
+  NOOP: 'NOOP',
+  SKIP_CUSTOMIZED: 'SKIP_CUSTOMIZED',
+  PRUNE: 'PRUNE',
+  PRUNE_SKIPPED_CUSTOMIZED: 'PRUNE_SKIPPED_CUSTOMIZED',
+  NEVER_TOUCH_PRESERVE: 'NEVER_TOUCH_PRESERVE',
+  NEVER_TOUCH_ADD: 'NEVER_TOUCH_ADD',
+  SPECIAL_MERGE: 'SPECIAL_MERGE',
+});
+
+async function copyFile(src, dst) {
+  await mkdir(dirname(dst), { recursive: true });
+  await cp(src, dst, { force: true });
+}
+
+export async function threeWayMerge(templateDir, target, oldManifest, newManifest) {
+  const actions = [];
+  const oldFiles = oldManifest?.files ?? {};
+  const newFiles = newManifest?.files ?? {};
+  const allPaths = new Set([...Object.keys(oldFiles), ...Object.keys(newFiles)]);
+
+  for (const rel of allPaths) {
+    const tplPath = join(templateDir, rel);
+    const tgtPath = join(target, rel);
+
+    if (NEVER_TOUCH.includes(rel)) {
+      if (await pathExists(tgtPath)) {
+        actions.push({ kind: ACTION_KINDS.NEVER_TOUCH_PRESERVE, path: rel, reason: 'NEVER_TOUCH path present in target' });
+      } else if (rel in newFiles) {
+        await copyFile(tplPath, tgtPath);
+        actions.push({ kind: ACTION_KINDS.NEVER_TOUCH_ADD, path: rel, reason: 'NEVER_TOUCH path absent; written from template' });
+      }
+      continue;
+    }
+
+    if (SPECIAL_MERGE.includes(rel)) {
+      if (rel in newFiles && await pathExists(tplPath)) {
+        await deepMergeMcpServers(tplPath, tgtPath);
+        actions.push({ kind: ACTION_KINDS.SPECIAL_MERGE, path: rel, reason: 'additive deep-merge applied' });
+      }
+      continue;
+    }
+
+    const newHash = newFiles[rel];
+    const oldHash = oldFiles[rel];
+    const targetExists = await pathExists(tgtPath);
+    const tgtHash = targetExists ? await hashFile(tgtPath) : null;
+
+    if (!targetExists && newHash) {
+      await copyFile(tplPath, tgtPath);
+      actions.push({ kind: ACTION_KINDS.ADD, path: rel, reason: 'new in template; not present in target' });
+      continue;
+    }
+
+    if (newHash && tgtHash === newHash) {
+      actions.push({ kind: ACTION_KINDS.NOOP, path: rel, reason: 'target already matches new template' });
+      continue;
+    }
+
+    if (newHash && oldHash && tgtHash === oldHash) {
+      await copyFile(tplPath, tgtPath);
+      actions.push({ kind: ACTION_KINDS.OVERWRITE, path: rel, reason: 'target untouched since last install; updated' });
+      continue;
+    }
+
+    if (newHash && tgtHash && tgtHash !== oldHash) {
+      actions.push({ kind: ACTION_KINDS.SKIP_CUSTOMIZED, path: rel, reason: 'target customized since last install' });
+      continue;
+    }
+
+    if (!newHash && oldHash) {
+      // File was part of the baseline at last install but has since been
+      // removed upstream. Two cases:
+      //   - target unchanged since last install (tgtHash == oldHash) → safe to
+      //     prune. Otherwise the user accumulates stale baseline files forever.
+      //   - target customized (tgtHash != oldHash) → preserve to avoid
+      //     destroying user work; report drift via exit 3.
+      // Pruning only runs when --merge already applies; there is no separate
+      // flag (decision recorded in README).
+      if (targetExists && tgtHash === oldHash) {
+        await unlink(tgtPath);
+        actions.push({ kind: ACTION_KINDS.PRUNE, path: rel, reason: 'removed from new template; target was untouched — deleted' });
+      } else if (targetExists) {
+        actions.push({ kind: ACTION_KINDS.PRUNE_SKIPPED_CUSTOMIZED, path: rel, reason: 'removed from new template; target customized — preserved' });
+      }
+      continue;
+    }
+  }
+
+  if (newManifest) {
+    await mkdir(join(target, '.claude'), { recursive: true });
+    await saveManifest(join(target, '.claude/.baseline-manifest.json'), newManifest);
+  }
+
+  const skipKinds = [ACTION_KINDS.SKIP_CUSTOMIZED, ACTION_KINDS.PRUNE_SKIPPED_CUSTOMIZED];
+  const exitCode = actions.some((a) => skipKinds.includes(a.kind)) ? 3 : 0;
+  return { actions, exitCode };
+}

package/src/cli/plantuml.js

@@ -0,0 +1,121 @@
+import { mkdir, writeFile, readFile, rename, unlink } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { join, delimiter } from 'node:path';
+import { get as httpsGet } from 'node:https';
+import { existsSync, statSync } from 'node:fs';
+import { pathExists } from './util.js';
+
+export const UPSTREAM_URL = 'https://github.com/plantuml/plantuml/releases/download/v1.2026.2/plantuml-asl-1.2026.2.jar';
+export const PINNED_SHA256 = 'c348f6a26d999f81fd05b5d49834bb70df9cf35fab0939c4edecb0909e64022b';
+export const PINNED_SIZE = 19395808;
+
+export const FETCH_OUTCOMES = Object.freeze({
+  WROTE: 'WROTE',
+  SKIPPED_SYSTEM_PLANTUML: 'SKIPPED_SYSTEM_PLANTUML',
+  SKIPPED_ALREADY_PRESENT: 'SKIPPED_ALREADY_PRESENT',
+  SKIPPED_NO_PLANTUML_FLAG: 'SKIPPED_NO_PLANTUML_FLAG',
+  SKIPPED_DRY_RUN: 'SKIPPED_DRY_RUN',
+  WARNED_NETWORK_FAILURE: 'WARNED_NETWORK_FAILURE',
+  WARNED_HASH_MISMATCH: 'WARNED_HASH_MISMATCH',
+  ERRORED_REQUIRE_PLANTUML: 'ERRORED_REQUIRE_PLANTUML',
+});
+
+export function detectSystemPlantuml() {
+  const pathEnv = process.env.PATH || '';
+  for (const dir of pathEnv.split(delimiter)) {
+    if (!dir) continue;
+    const candidate = join(dir, 'plantuml');
+    try {
+      if (existsSync(candidate) && statSync(candidate).isFile()) return candidate;
+    } catch {}
+  }
+  return null;
+}
+
+function sha256Hex(buf) {
+  return createHash('sha256').update(buf).digest('hex');
+}
+
+async function defaultHttpsFetch(url, maxRedirects = 5) {
+  return new Promise((resolve, reject) => {
+    const follow = (currentUrl, hops) => {
+      httpsGet(currentUrl, (res) => {
+        if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+          if (hops <= 0) return reject(new Error('Too many redirects'));
+          res.resume();
+          return follow(res.headers.location, hops - 1);
+        }
+        if (res.statusCode !== 200) {
+          res.resume();
+          return reject(new Error(`Non-200 status: ${res.statusCode}`));
+        }
+        const chunks = [];
+        res.on('data', (c) => chunks.push(c));
+        res.on('end', () => resolve(Buffer.concat(chunks)));
+        res.on('error', reject);
+      }).on('error', reject);
+    };
+    follow(url, maxRedirects);
+  });
+}
+
+async function writeJarAtomic(target, buffer) {
+  const dir = join(target, '.claude/bin');
+  await mkdir(dir, { recursive: true });
+  const dst = join(dir, 'plantuml.jar');
+  const tmp = dst + '.tmp.' + process.pid;
+  try {
+    await writeFile(tmp, buffer);
+    await rename(tmp, dst);
+  } catch (err) {
+    try { await unlink(tmp); } catch {}
+    throw err;
+  }
+  return dst;
+}
+
+export async function fetchPlantumlIfMissing(target, opts = {}) {
+  const fetcher = opts.fetch ?? defaultHttpsFetch;
+  const systemPath = opts.systemPlantumlPath !== undefined
+    ? opts.systemPlantumlPath
+    : detectSystemPlantuml();
+
+  if (systemPath) {
+    return { outcome: FETCH_OUTCOMES.SKIPPED_SYSTEM_PLANTUML, bytesWritten: 0, reason: `system plantuml at ${systemPath}` };
+  }
+  if (opts.noPlantuml) {
+    return { outcome: FETCH_OUTCOMES.SKIPPED_NO_PLANTUML_FLAG, bytesWritten: 0, reason: '--no-plantuml flag set' };
+  }
+  if (opts.dryRun) {
+    return { outcome: FETCH_OUTCOMES.SKIPPED_DRY_RUN, bytesWritten: 0, reason: `would fetch ${UPSTREAM_URL} (sha256 ${PINNED_SHA256.slice(0, 8)}…)` };
+  }
+
+  const targetJar = join(target, '.claude/bin/plantuml.jar');
+  if (await pathExists(targetJar)) {
+    const existing = await readFile(targetJar);
+    if (sha256Hex(existing) === PINNED_SHA256) {
+      return { outcome: FETCH_OUTCOMES.SKIPPED_ALREADY_PRESENT, bytesWritten: 0, reason: 'jar already present with matching sha256' };
+    }
+  }
+
+  let bytes;
+  try {
+    bytes = await fetcher(UPSTREAM_URL);
+  } catch (err) {
+    if (opts.requirePlantuml) {
+      return { outcome: FETCH_OUTCOMES.ERRORED_REQUIRE_PLANTUML, bytesWritten: 0, reason: `network failure: ${err.message}` };
+    }
+    return { outcome: FETCH_OUTCOMES.WARNED_NETWORK_FAILURE, bytesWritten: 0, reason: err.message };
+  }
+
+  const hash = sha256Hex(bytes);
+  if (hash !== PINNED_SHA256) {
+    if (opts.requirePlantuml) {
+      return { outcome: FETCH_OUTCOMES.ERRORED_REQUIRE_PLANTUML, bytesWritten: 0, reason: `sha256 mismatch: got ${hash.slice(0, 8)}…` };
+    }
+    return { outcome: FETCH_OUTCOMES.WARNED_HASH_MISMATCH, bytesWritten: 0, reason: `expected ${PINNED_SHA256.slice(0, 8)}… got ${hash.slice(0, 8)}…` };
+  }
+
+  await writeJarAtomic(target, bytes);
+  return { outcome: FETCH_OUTCOMES.WROTE, bytesWritten: bytes.length, reason: `wrote ${bytes.length} bytes` };
+}

package/src/cli/util.js

@@ -0,0 +1,10 @@
+import { access } from 'node:fs/promises';
+
+export async function pathExists(p) {
+  try {
+    await access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/memory/_pending.template.md

@@ -0,0 +1,15 @@
+---
+owners: [memory_stop.sh writes; /memory-flush clears]
+category: auto-extracted candidates awaiting curation
+verifies-against: none
+---
+
+# Pending memory candidates
+
+Auto-extracted by `memory_stop.sh` at end of each turn. Run `/memory-flush` to review and commit keepers to the canonical files.
+
+**Content of this file is gitignored.** The file itself (with this header) is committed; everything below the `---` separator below is per-session and not staged.
+
+---
+
+<!-- candidates appended below this line -->

package/src/memory/_resume.template.md

@@ -0,0 +1,12 @@
+---
+name: resume
+type: continuity
+last-updated: never
+trigger: stop
+---
+
+# Resume snapshot
+
+## No prior session
+
+This file is overwritten by `memory_stop.sh` at end of each turn and by `memory_pre_compact.sh` before context compaction. The SessionStart hook reads it on the next session start.

package/src/memory/conventions.template.md

@@ -0,0 +1,26 @@
+---
+owners: [scenario, implement]
+category: repo-specific test and code conventions
+size-cap: 500
+key: short slug
+verifies-against: codebase
+---
+
+# Conventions
+
+Repo-specific patterns the `scenario` and `implement` skills should match. Fixture locations, helper idioms, naming, file layout quirks. Not generic best practices — specific facts about *this* codebase.
+
+Each entry's stable key is a short slug.
+
+Per-entry shape:
+
+```markdown
+## <short-slug>
+
+- Convention: <pattern, rule, or idiom this repo follows>
+- Why: <reason — historical, tooling-driven, performance, etc.>
+- Verified-at: <commit SHA short>
+- Last-touched: <ISO date>
+```
+
+---

package/src/memory/decisions.template.md

@@ -0,0 +1,29 @@
+---
+owners: [spec, rca]
+category: architectural decisions
+size-cap: 500
+key: short slug
+verifies-against: spec/rca artifact
+---
+
+# Architectural decisions
+
+Why this repo took the path it took. Includes rejected alternatives so a future session doesn't re-litigate.
+
+Each entry's stable key is a short slug (e.g., `auth-jwt-vs-session`, `worktree-isolation`).
+
+Per-entry shape:
+
+```markdown
+## <short-slug>
+
+- Decision: <what was chosen>
+- Rationale: <why — the constraint or evidence that decided it>
+- Rejected alternatives:
+  - <alt 1> → <why rejected>
+  - <alt 2> → <why rejected>
+- Source: <spec slug / rca slug / conversation>
+- Verified-at: <commit SHA short>
+```
+
+---

package/src/memory/landmarks.template.md

@@ -0,0 +1,26 @@
+---
+owners: [scout]
+category: codebase landmarks
+size-cap: 500
+key: path:line
+verifies-against: git
+---
+
+# Codebase landmarks
+
+Where things live in this repo. The `scout` skill cites these and re-verifies before use; failed verifications are corrected or deleted in the same run.
+
+Each entry's stable key is `path:line`.
+
+Per-entry shape:
+
+```markdown
+## <path:line>
+
+- Role: <what lives here, why it matters>
+- Verified-at: <commit SHA short>
+- Last-touched: <ISO date>
+- Caveat: <optional — gotcha, neighbour file that must change with this one, etc.>
+```
+
+---

package/src/memory/landmines.template.md

@@ -0,0 +1,27 @@
+---
+owners: [security, integrate, scout]
+category: gotchas and recurring true positives
+size-cap: 500
+key: path:line or short slug
+verifies-against: git
+---
+
+# Landmines
+
+Things that have bitten before and will bite again. "Editing X without also editing Y breaks Z." Recurring true positives from security review. Version skew traps.
+
+Each entry's stable key is `path:line` or a short slug.
+
+Per-entry shape:
+
+```markdown
+## <path:line or slug>
+
+- Path: <file/symbol involved>
+- Trap: <what goes wrong, plain language>
+- Mitigation: <what to check / do instead>
+- Verified-at: <commit SHA short>
+- Last-touched: <ISO date>
+```
+
+---

package/src/memory/libraries.template.md

@@ -0,0 +1,27 @@
+---
+owners: [research]
+category: validated library APIs
+size-cap: 500
+key: lib@version
+verifies-against: lockfile + context7
+---
+
+# Validated library APIs
+
+Library APIs the team has confirmed via `context7` MCP against the version present in this repo's lockfile. Saves a context7 round-trip when a stable choice is referenced again.
+
+Each entry's stable key is `<lib>@<version>`. If the lockfile bumps, re-verify and update the version.
+
+Per-entry shape:
+
+```markdown
+## <lib>@<version>
+
+- Role: <what this lib is used for in this repo>
+- API: <key symbols / canonical call shape>
+- Verified-at: <commit SHA short>
+- Last-touched: <ISO date>
+- Caveat: <optional — version pin reason, breaking-change notes>
+```
+
+---

package/src/memory/pending-questions.template.md

@@ -0,0 +1,28 @@
+---
+owners: [any phase]
+category: cross-session open questions
+size-cap: 500
+key: Q-NNN
+verifies-against: none
+---
+
+# Pending questions
+
+Questions the current session couldn't resolve. Surfaced at next session start so context isn't lost across yields.
+
+Each entry's stable key is auto-numbered `Q-NNN`.
+
+Per-entry shape:
+
+```markdown
+## Q-NNN
+
+- Question: <what's open>
+- Raised in: <date / phase / conversation>
+- Blocker for: <what work is gated on this>
+- Options considered: <a> / <b> / <c>
+- Verified-at: <commit SHA short>
+- Last-touched: <ISO date>
+```
+
+---