@arjunkhera/atlas 0.3.7 → 0.3.9

package/door/lib/proof.mjs

@@ -0,0 +1,127 @@
+// `atlas tests proof`: the proof table of design section 5.7, made from the
+// evidence of ONE run, or with no --run the newest run of each scenario.
+//
+//   atlas tests proof --root <area> [--run <id>] [--own <file>] [--evidence <dir>]
+//
+// One row for each assertion, one column for each way in, a column for the
+// verifier's own check, and a short proof. `--own` is a JSON file of
+// { "<scenario>/e1": { "result": "pass", "proof": "revision 1" } }; a full id
+// (with its #fingerprint) works as a key too. A way that is blocked or failed
+// shows its reason in the proof column. Evidence of a fault run is left out.
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { newestRunPerScenario } from '../../tests/link-check.mjs';
+
+const MAX_CELL = 110;
+
+const clean = (text) => String(text ?? '').replace(/\s+/g, ' ').replace(/\|/g, '\\|').trim();
+const clip = (text, n = MAX_CELL) => { const t = clean(text); return t.length > n ? `${t.slice(0, n - 3)}...` : t; };
+const label = (result) => String(result ?? '').toUpperCase();
+
+function summary(value) {
+  if (value === undefined || value === null) return '';
+  return typeof value === 'string' ? value : JSON.stringify(value);
+}
+
+const usage = (message) => Object.assign(new Error(message), { usage: true });
+
+// Reads the --own file. Throws an Error with a plain message on a bad file.
+export function readOwn(file) {
+  let data;
+  try { data = JSON.parse(readFileSync(file, 'utf8')); } catch (error) { throw usage(`--own ${file} cannot be read as JSON: ${error.code ?? error.message}`); }
+  if (!data || typeof data !== 'object' || Array.isArray(data)) throw usage('--own must hold a JSON object of { id: { result, proof } }');
+  for (const [id, one] of Object.entries(data)) {
+    if (!one || typeof one !== 'object' || typeof one.result !== 'string') throw usage(`--own: the entry "${id}" must be { "result": "pass", "proof": "..." }`);
+  }
+  return data;
+}
+
+export function buildProof({ evidenceDir, runId = null, own = {} }) {
+  const perScenario = runId ? null : newestRunPerScenario(evidenceDir);
+  if (!runId && !perScenario.size) throw new Error(`there is no run in ${evidenceDir}`);
+  const names = runId ? [runId] : [...new Set(perScenario.values())].sort();
+  const newest = new Map();
+  const used = new Set();
+  let faultRuns = 0;
+  for (const id of names) {
+    const dir = join(evidenceDir, id);
+    if (!existsSync(dir)) throw new Error(`the run "${id}" has no folder in ${evidenceDir}`);
+    for (const name of readdirSync(dir).sort()) {
+      if (!name.endsWith('.json')) continue;
+      let data;
+      try { data = JSON.parse(readFileSync(join(dir, name), 'utf8')); } catch { continue; }
+      if (data?.evidence !== 1) continue;
+      if (data.fault_run) { faultRuns += 1; continue; }
+      if (perScenario && perScenario.get(data.scenario) !== id) continue;
+      used.add(id);
+      const before = newest.get(data.scenario);
+      if (!before || String(data.started) >= String(before.started)) newest.set(data.scenario, data);
+    }
+  }
+  const id = runId ?? [...used].sort().join(', ');
+  if (!newest.size) throw new Error(`the run "${id}" has no evidence file that counts${faultRuns ? ' (only fault runs)' : ''}`);
+  const scenarios = [...newest.values()].sort((a, b) => (a.scenario < b.scenario ? -1 : 1));
+  const ways = [...new Set(scenarios.flatMap((s) => Object.keys(s.ways ?? {})))];
+  const rows = [];
+  const blocked = [];
+  for (const s of scenarios) {
+    for (const [way, w] of Object.entries(s.ways ?? {})) {
+      if (w.verdict === 'blocked' || w.verdict === 'fail') blocked.push(`${s.scenario} through ${way} is ${w.verdict}${w.reason ? `: ${clip(w.reason, 200)}` : ''}`);
+    }
+    const ids = [...new Set((s.assertions ?? []).map((a) => a.id))];
+    for (const full of ids) {
+      const short = full.replace(/#[0-9a-f]+$/, '');
+      const entries = (s.assertions ?? []).filter((a) => a.id === full);
+      const cells = Object.fromEntries(ways.map((way) => {
+        const e = entries.find((x) => x.way === way);
+        return [way, e ? label(e.result) : '-'];
+      }));
+      const problems = entries.filter((e) => e.result !== 'pass' && e.result !== 'not here').map((e) => {
+        const why = e.proof?.error ?? e.proof?.why ?? s.ways?.[e.way]?.reason ?? '';
+        return `${e.way} ${e.result}${why ? `: ${why}` : ''}`;
+      });
+      const passed = entries.find((e) => e.result === 'pass' && e.proof?.value !== undefined);
+      const mine = own[full] ?? own[short] ?? null;
+      const parts = [];
+      if (problems.length) parts.push(problems.join('; '));
+      else if (passed) parts.push(summary(passed.proof.value));
+      if (mine?.proof) parts.push(`own: ${summary(mine.proof)}`);
+      rows.push({
+        label: `${short.replace('/', ' ')}`, full, cells, own: mine ? label(mine.result) : '-',
+        proof: clip(parts.join(' | ')),
+      });
+    }
+  }
+  return { runId: id, environment: scenarios[0].environment, ways, rows, blocked, faultRuns, scenarios: scenarios.map((s) => s.scenario) };
+}
+
+export function renderProof(proof) {
+  const out = [];
+  out.push(`${proof.runId.includes(', ') ? 'Runs' : 'Run'} ${proof.runId}, environment ${proof.environment}, ${proof.scenarios.length} scenario(s): ${proof.scenarios.join(', ')}.`);
+  out.push('');
+  out.push(`| Assertion | ${proof.ways.join(' | ')} | Verifier's own check | Proof |`);
+  out.push(`|---|${proof.ways.map(() => '---').join('|')}|---|---|`);
+  for (const r of proof.rows) out.push(`| ${r.label} | ${proof.ways.map((w) => r.cells[w]).join(' | ')} | ${r.own} | ${r.proof} |`);
+  if (proof.blocked.length) {
+    out.push('');
+    out.push('Blocked or failed ways in:');
+    for (const b of proof.blocked) out.push(`- ${clean(b)}`);
+  }
+  if (proof.faultRuns) {
+    out.push('');
+    out.push(`${proof.faultRuns} evidence file(s) of fault runs were left out.`);
+  }
+  return out;
+}
+
+export function proofCommand(chosen, root, line) {
+  try {
+    const own = chosen.own ? readOwn(resolve(chosen.own)) : {};
+    const evidenceDir = resolve(chosen.evidence ?? join(root, 'test', 'evidence'));
+    for (const text of renderProof(buildProof({ evidenceDir, runId: chosen.run ?? null, own }))) line(text);
+    return 0;
+  } catch (error) {
+    line(`proof: ${error.message}`);
+    return error.usage ? 2 : 1;
+  }
+}

package/door/lib/tests.mjs

@@ -0,0 +1,190 @@
+// The two verbs of `atlas tests`.
+//
+//   atlas tests check --root <area>   run the link check on an area
+//   atlas tests write --root <area>   copy the shipped test kit into <area>/test/atlas/
+//   atlas tests proof --root <area>   print the proof table of one run (proof.mjs)
+//
+// The kit is the folder `tests/` of this package: the contract library, the
+// drivers, the stand-in helper and the link check. `write` copies each file
+// byte for byte and writes `manifest.json` beside them, with the package
+// version and the sha256 of each file. It refuses to replace a file whose hash
+// the manifest does not list, so a hand edit is never lost. It refuses to write
+// through a link. It also writes <area>/test/evidence/.gitignore (ignore
+// everything) and, at the repo root, a .gitignore line for .env.test when it
+// is missing, and it says what it added. A person merges every file that it
+// writes.
+import { createHash } from 'node:crypto';
+import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative, resolve } from 'node:path';
+import { checkArea, formatFinding, HALVES, kitHashOf, loadKitReleases } from '../../tests/link-check.mjs';
+import { packagePackageVersion } from './releases.mjs';
+
+export const KIT_SOURCE = 'tests';
+export const KIT_TARGET = 'test/atlas';
+export const MANIFEST = 'manifest.json';
+
+const sha256 = (bytes) => createHash('sha256').update(bytes).digest('hex');
+
+export class KitRefusal extends Error {
+  constructor(message) { super(message); this.name = 'KitRefusal'; }
+}
+
+function filesUnder(dir, prefix = '') {
+  const out = [];
+  for (const name of readdirSync(dir).sort()) {
+    const full = join(dir, name);
+    if (statSync(full).isDirectory()) out.push(...filesUnder(full, `${prefix}${name}/`));
+    else out.push(`${prefix}${name}`);
+  }
+  return out;
+}
+
+// The kit hash of this package, and the hashes of every kit a release shipped.
+// The current kit is always accepted, so a release need not list itself.
+export const KIT_RELEASES_FILE = join('door', 'kit-releases.json');
+
+export function currentKitHash(packageRoot) {
+  return kitHashOf(Object.fromEntries([...kitFiles(packageRoot)].map(([path, bytes]) => [path, sha256(bytes)])));
+}
+
+export function acceptedKitHashes(packageRoot) {
+  const file = join(packageRoot, KIT_RELEASES_FILE);
+  return [...(existsSync(file) ? loadKitReleases(file) : []), currentKitHash(packageRoot)];
+}
+
+// A path under `root` must not be a link, and none of its parents under `root`.
+function assertPlain(root, path) {
+  const parts = relative(root, path).split(/[\\/]/).filter(Boolean);
+  let at = root;
+  for (const part of parts) {
+    at = join(at, part);
+    const stat = lstatSyncSafe(at);
+    if (!stat) return;
+    if (stat.isSymbolicLink()) throw new KitRefusal(`${relative(root, at) || at} is a link. "atlas tests write" never writes through a link. Nothing was written. Replace the link with a plain folder or file.`);
+  }
+}
+function lstatSyncSafe(path) { try { return lstatSync(path); } catch { return null; } }
+
+// The repo root of an area: the nearest folder above it with a .git, or the area itself.
+function repoRootOf(root) {
+  let dir = resolve(root);
+  for (;;) {
+    if (existsSync(join(dir, '.git'))) return dir;
+    const up = dirname(dir);
+    if (up === dir) return resolve(root);
+    dir = up;
+  }
+}
+
+// Makes sure that a .gitignore file has each line. Returns { state, file, added }.
+function ensureLines(file, lines, dryRun) {
+  const have = existsSync(file) ? readFileSync(file, 'utf8') : null;
+  const present = new Set((have ?? '').split('\n').map((l) => l.trim()));
+  const added = lines.filter((l) => !present.has(l));
+  if (!added.length) return { state: 'current', file, added };
+  if (!dryRun) {
+    mkdirSync(dirname(file), { recursive: true });
+    const base = have === null ? '' : (have.endsWith('\n') || have === '' ? have : `${have}\n`);
+    writeFileSync(file, `${base}${added.join('\n')}\n`);
+  }
+  return { state: have === null ? 'new' : 'add', file, added };
+}
+
+export function kitFiles(packageRoot) {
+  const dir = join(packageRoot, KIT_SOURCE);
+  return new Map(filesUnder(dir).map((path) => [path, readFileSync(join(dir, path))]));
+}
+
+// Writes the kit into <root>/test/atlas. Returns { version, rows, changed }.
+export function writeKit(root, packageRoot, { dryRun = false } = {}) {
+  const version = packagePackageVersion(packageRoot);
+  const target = join(root, KIT_TARGET);
+  const manifestPath = join(target, MANIFEST);
+  let known = {};
+  if (existsSync(manifestPath)) {
+    try { known = JSON.parse(readFileSync(manifestPath, 'utf8')).files ?? {}; } catch { throw new KitRefusal(`${KIT_TARGET}/${MANIFEST} is not JSON; move it away and run again`); }
+  }
+  const files = kitFiles(packageRoot);
+  assertPlain(root, join(root, 'test'));
+  assertPlain(root, target);
+  assertPlain(root, manifestPath);
+  for (const path of files.keys()) assertPlain(root, join(target, path));
+  const evidenceIgnore = join(root, 'test', 'evidence', '.gitignore');
+  const repoRoot = repoRootOf(root);
+  const rootIgnore = join(repoRoot, '.gitignore');
+  assertPlain(root, join(root, 'test', 'evidence'));
+  assertPlain(root, evidenceIgnore);
+  if (repoRoot === resolve(root)) assertPlain(root, rootIgnore);
+  else if (existsSync(rootIgnore) && lstatSync(rootIgnore).isSymbolicLink()) throw new KitRefusal(`${rootIgnore} is a link. "atlas tests write" never writes through a link. Nothing was written.`);
+  const rows = [];
+  const refused = [];
+  for (const [path, bytes] of files) {
+    const hash = sha256(bytes);
+    const file = join(target, path);
+    if (!existsSync(file)) { rows.push({ state: 'new', path, sha256: hash }); continue; }
+    const have = sha256(readFileSync(file));
+    if (have === hash) rows.push({ state: 'current', path, sha256: hash });
+    else if (known[path] === have) rows.push({ state: 'replace', path, sha256: hash });
+    else refused.push(path);
+  }
+  if (refused.length) {
+    throw new KitRefusal(`${refused.length} file(s) in ${KIT_TARGET}/ differ from the manifest, so they were edited by hand or came from an unknown copy: ${refused.slice(0, 5).join(', ')}. Nothing was written. Restore them, or move them away.`);
+  }
+  for (const path of Object.keys(known)) if (!files.has(path)) rows.push({ state: 'orphan', path, sha256: known[path] });
+  const manifest = `${JSON.stringify({ atlas: version, files: Object.fromEntries([...files].map(([p, b]) => [p, sha256(b)])) }, null, 2)}\n`;
+  const manifestChanged = !existsSync(manifestPath) || readFileSync(manifestPath, 'utf8') !== manifest;
+  const ignores = [
+    ensureLines(evidenceIgnore, ['*', '!.gitignore'], dryRun),
+    ensureLines(rootIgnore, ['.env.test'], dryRun),
+  ];
+  const changed = rows.some((r) => r.state === 'new' || r.state === 'replace') || manifestChanged || ignores.some((i) => i.state !== 'current');
+  if (!dryRun) {
+    for (const row of rows) {
+      if (row.state !== 'new' && row.state !== 'replace') continue;
+      const file = join(target, row.path);
+      mkdirSync(dirname(file), { recursive: true });
+      writeFileSync(file, files.get(row.path));
+    }
+    mkdirSync(target, { recursive: true });
+    if (manifestChanged) writeFileSync(manifestPath, manifest);
+  }
+  return { version, rows, ignores, changed };
+}
+
+// The `check` verb. Prints one line for each finding. Returns the exit code.
+export function checkCommand(chosen, root, line, packageRoot) {
+  const halves = chosen.halves ? String(chosen.halves).split(',').map((s) => s.trim()).filter(Boolean) : [...HALVES];
+  const result = checkArea({
+    root, halves, evidence: chosen.evidence, tests: chosen.tests ?? 'test',
+    guardsFrom: chosen.guardsFrom || process.env.ATLAS_GUARDS_FROM || null,
+    run: chosen.run ?? null,
+    kitReleases: acceptedKitHashes(packageRoot),
+  });
+  for (const finding of result.findings) line(formatFinding(finding));
+  line('');
+  line(`${result.scenarios.length} scenario(s) read; halves: ${halves.join(', ')}; ${result.findings.length} finding(s).`);
+  line(result.findings.length ? 'RED' : 'GREEN');
+  return result.findings.length ? 1 : 0;
+}
+
+export function writeCommand(chosen, root, packageRoot, line) {
+  try {
+    const result = writeKit(root, packageRoot, { dryRun: chosen.dryRun });
+    line(`Atlas ${result.version}: the test kit in ${KIT_TARGET}/`);
+    for (const row of result.rows) line(`  ${row.state.padEnd(8)} ${row.path}  sha256 ${row.sha256.slice(0, 12)}…`);
+    for (const one of result.ignores) {
+      const name = relative(root, one.file) || one.file;
+      if (one.state === 'current') line(`  ${'current'.padEnd(8)} ${name}  (has its lines)`);
+      else line(`  ${(one.state === 'new' ? 'new' : 'add').padEnd(8)} ${name}  ${chosen.dryRun ? 'would add' : 'added'}: ${one.added.join(', ')}`);
+    }
+    line('');
+    line(result.changed
+      ? `${chosen.dryRun ? 'Dry run. Nothing was written. ' : ''}The files come from the package. No edit by hand afterwards. A person merges them.`
+      : 'Nothing changed. Every file already matches the package.');
+    return 0;
+  } catch (error) {
+    if (!(error instanceof KitRefusal)) throw error;
+    line(`Refused: ${error.message}`);
+    return 1;
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arjunkhera/atlas",
-  "version": "0.3.7",
+  "version": "0.3.9",
   "description": "Atlas: the delivery lifecycle, its crews and the Atlas tools, as a Claude Code plugin for any repository.",
   "type": "module",
   "license": "UNLICENSED",
@@ -20,6 +20,7 @@
     "door/",
     "work/",
     "shape/",
+    "tests/",
     "skills/",
     "agents/",
     ".claude-plugin/",

package/skills/lead/SKILL.md

@@ -56,6 +56,7 @@ say that when you hand over a page.
 | Review a design or a diff | The three reviewer crews, as sdlc-task says |
 | Prove a pull request against its definition of done | The `atlas:verifier` crew |
 | Render a page for the owner | The `atlas:artifact-renderer` crew |
+| Onboard an area to tests, review scenario words, write or convert a test, sort a red test, plant faults | The `atlas:tests` skill |
 
 A crew reads and reports. It never holds the Atlas tools.
 
@@ -99,6 +100,8 @@ set. A test keeps the two lists equal.
 | `atlas kind-drift` | When the repo record and `atlas.yaml` may disagree on the kind; this command retires in stage 2, the onboarding stage |
 | `atlas code-read` | To resolve the citations of a code digest |
 | `atlas ste` | Before each publish; `--share` before a page goes to anyone else |
-| `atlas design` | Before you render a design doc made from the walkthrough template |
+| `atlas tests` | `write` puts the test kit in an area. `check` runs before a merge. `proof` prints the proof table of one run |
+| `atlas design` | `check` before you show a design; `build` to make its page |
 
 A person merges every file that `atlas tooling` writes.
+A person merges every file that `atlas tests write` writes.

package/skills/sdlc-task/SKILL.md

@@ -49,8 +49,9 @@ does not repeat those rules; follow the lead.
 **A change after the owner approved a design** is not a new lock. Say so at
 once, and never build against a sentence you know is wrong. Show the owner the
 change in one screen. When the owner approves it, record the owner's words with
-`decision_record` on the same item, and write the change into the design file
-with the date. (Target design, flow 4: long frozen texts with hashes retire.)
+`decision_record` on the same item. Name the part it touched, and change
+that part in the design folder. (Target design, flow 4: long frozen texts
+with hashes retire.)
 
 ## start
 
@@ -64,12 +65,12 @@ with the date. (Target design, flow 4: long frozen texts with hashes retire.)
    (`registry_list`); it may be `main` or `master`. Branch from it, and never
    commit to it. Local sessions use `feature/`, `fix/` or `chore/`; cloud
    sessions use `claude/`. The pull request targets that branch.
-4. **Design doc** (standard and above): copy
-   [`templates/design-doc.md`](templates/design-doc.md) to
-   `docs/design-docs/<slug>.md`, fill the Summary and Part 1, and list it in
-   `docs/index.md` in the commit that first lands it. Hotfix tier skips the
-   doc: the definition of done lives on the work item, and a resume anchor
-   covers pauses.
+4. **Design** (standard and above): follow [`design/README.md`](design/README.md).
+   Pick the kinds, and say why. Make the folder `docs/design-docs/<slug>/`
+   with `design.yaml`, then write the Summary, Your words and Goals first.
+   Read the template for each part in `design/parts/`. List the folder in
+   `docs/index.md` in the commit that first lands it. Hotfix tier skips the design: the definition of done lives on
+   the work item, and a resume anchor covers pauses.
 5. Enter the design loop.
 
 ## The design loop (between start and lock)
@@ -85,16 +86,17 @@ Talk to the owner by the `atlas:lead` skill. What this loop adds:
   they presume was ever decided.** A bug report says the code surprised
   someone; it does not say what the code should do.
 - **User stories before the definition of done.** Never write checks for a
-  flow no story walks through.
-- **The doc accretes in real time.** Every resolved question, decision and
-  approach lands in the design doc as it happens. Record each question with
-  `question_ask`, each answer with `question_answer`, each decision with
-  `decision_record`.
+  flow no story walks through. When the design has a flow a user walks, write
+  its Stories part first, whatever kinds it picks.
+- **The design grows in real time.** Record each question with
+  `question_ask`, each answer with `question_answer` and each decision with
+  `decision_record`, as it happens. The tracker holds them. Change the part
+  the answer touches in the design folder at the same time.
 - **Adversarial review before the owner approves.** Standard tier: at least one
   persona. Initiative: the panel, `atlas:reviewer-pm`, `atlas:reviewer-architect`
   and `atlas:reviewer-security`, each briefed with the doc path, in parallel.
   Brief each one to ask whether the design is the right thing. An unresolved
-  finding goes into the doc's open questions.
+  finding goes to the tracker with `question_ask`.
 
 ## lock
 
@@ -105,17 +107,22 @@ A lock is the owner's approval of a short design (target design, flow 4).
    `lifecycle.yaml` `lock.holds` lists: the definition of done, written as checks; the kind of change, its impact and its undo; and
    each existing test it expects to change. A change that cannot be undone
    shows in bold at the top.
-2. **Show it as a walkthrough page before you ask.** Run `atlas design` and
-   `atlas ste` on the design doc, and fix each finding by hand. Render the
-   page with the `atlas:artifact-renderer` crew, in the walkthrough format,
-   and publish it. Call `item_link` twice: kind `design-doc` for the doc, and
-   kind `artifact` for the page. Link the page from the design doc, and
+2. **Show the design's page before you ask.** Run
+   `atlas design check <folder>` and `atlas ste` on the folder, and fix each
+   finding by hand. A part that needs a custom figure goes to the
+   `atlas:artifact-renderer` crew first. Run
+   `atlas design build <folder> --tracker <item.json>`, with the tracker
+   data that `design/README.md` names. Run `atlas ste` on the page and
+   publish it. Link the folder and the page with `item_link`. Then
    rebuild the hub (see "The design hub" below).
 3. **The owner approves it in the owner's own words.** Gate on
    `lifecycle.yaml` `lock.preconditions`. Record the words with
-   `decision_record`, and mark the design doc "Approved <date>", with the words.
-4. Call `item_lock` with the definition of done as `scope.text` and the design
-   file as `scope.design_doc`. The verb keeps a fingerprint of that text for
+   `decision_record`. The tracker holds the approval; the design file does
+   not.
+4. Call `item_lock` with the definition of done as `scope.text`. Set
+   `scope.design_doc` to a link to the design at the approved commit, such
+   as `https://github.com/<owner>/<repo>/tree/<sha>/docs/design-docs/<slug>`.
+   The verb keeps a fingerprint of that text for
    the tools. No person reads or writes a hash, and no frozen text is copied
    into the doc.
    Rebuild the hub, so the design reads "Building".
@@ -164,8 +171,10 @@ next action. One short paragraph.
    migration reaches the running node after the merge.
 2. If anything was a struggle, encode the fix where it stops a repeat — a lint,
    then a tool, then a skill, then a doc — and say which.
-3. Design doc status: `SHIPPED <date>`.
-4. Rebuild the hub, so the design reads "Shipped".
+3. Rebuild the design's page and the hub, so both read "Shipped". The
+   design folder does not change: the tracker holds the delivery. A design
+   from before 9 October 2026 is one file. Keep its page, and rebuild only
+   the hub.
 
 ## The design hub
 

package/skills/sdlc-task/design/README.md

@@ -0,0 +1,187 @@
+# How to write a design
+
+Every Atlas design has the same spine. It adds the parts of each kind it
+needs. A design keeps no state: the tracker holds anything that changes as
+the work moves. The page shows those facts, read only.
+
+The look was agreed with the owner on 9 October 2026. The boards are on the
+canvas at https://claude.ai/artifact/DP7WmrRzqyGKTkQQQ6Ev8A.
+
+## One home for each fact
+
+| Ask this | If yes, it lives in |
+|---|---|
+| Does it change as the work moves? | The tracker: the stage, splits, questions, answers, decisions, the approval, the lock, changes after approval and the proof. |
+| Does it explain why or how? | The design: the problem, the owner's words, the goals, how it works, the options and their reasons, the contract and the done line. |
+
+## Pick the kinds
+
+Pick one kind or more. One design can mix kinds: an interface change with a
+hard flow is a Contract and a Flow. A part that two kinds need appears once.
+
+| Kind | Pick it when | Example |
+|---|---|---|
+| Decide | There are several ways, and one must win. | Test before merge |
+| Flow | The behaviour is the hard part. | When a test goes red |
+| Contract | An interface, a schema or a command changes. | A document viewer route |
+| Initiative | Many designs serve one goal. | Support for many file types |
+
+Set `shared: true` when many repos use the design, such as Atlas itself.
+Then "Each kind of repo" is needed. For a design in one product it is
+optional.
+
+## All parts by kind
+
+`needed` means the check fails when the part is missing or empty.
+`shared` means needed when the design is shared. `—` means the kind does
+not use the part. The registry is [parts.yaml](parts.yaml), and a test keeps
+this table equal to it.
+
+| Part | File holds | Decide | Flow | Contract | Initiative |
+|---|---|---|---|---|---|
+| Summary | `summary` | needed | needed | needed | needed |
+| Your words | `words` | needed | needed | needed | needed |
+| Goals and non-goals | `goals` | needed | needed | needed | needed |
+| Problem today | `problem` | needed | if it applies | if it applies | — |
+| Yardstick | `yardstick` | needed | — | — | — |
+| Proposal | `proposal` | needed | — | — | — |
+| Alternatives | `alternatives` | needed | if it applies | if it applies | — |
+| Scorecard | `scorecard` | needed | — | — | — |
+| Build list | `build` | needed | if it applies | if it applies | — |
+| Who and what | `actors` | if it applies | needed | if it applies | — |
+| Stories | `stories` | if it applies | needed | if it applies | — |
+| Edge cases | `edges` | if it applies | needed | if it applies | — |
+| Records | `records` | — | needed | if it applies | — |
+| States | `states` | — | if it applies | — | — |
+| Routes and interface | `routes` | — | — | needed | — |
+| Calls and answers | `calls` | — | — | needed | — |
+| Data change | `data` | — | — | needed | — |
+| Migration and undo | `migration` | — | — | needed | — |
+| Security | `security` | if it applies | if it applies | needed | — |
+| Rollout | `rollout` | if it applies | if it applies | needed | — |
+| Why one initiative | `why` | — | — | — | needed |
+| Shared decisions | `shared-decisions` | — | — | — | needed |
+| Order and dependencies | `order` | — | — | — | needed |
+| Risks | `risks` | needed | needed | needed | needed |
+| Test and proof plan | `proof` | needed | needed | needed | — |
+| Each kind of repo | `repos` | shared | shared | shared | — |
+| Change and undo | `change` | needed | needed | needed | if it applies |
+| Done line | `done` | needed | needed | needed | needed |
+| Key | `key` | needed | needed | needed | needed |
+
+The page also shows six parts from the tracker: Questions, Decisions,
+Approval and lock, Since approval, Family and Roll-up. No file holds them.
+The builder counts the Roll-up from the Family list.
+
+## What the lock needs
+
+The lock reads `lock.holds` and `lock.preconditions` in `lifecycle.yaml`.
+Each one has a home:
+
+| The lock needs | Where it lives |
+|---|---|
+| The definition of done | The Done line part |
+| The kind of change, its impact, its undo and the tests it changes | The Change and undo part |
+| The chosen approach | The Proposal part of a Decide design. In the other kinds, the design itself is the approach. |
+| No open question | The tracker: `needs_me` shows none for the item |
+| The owner's approval in his own words | The tracker: `decision_record` |
+
+## Tier and kind
+
+The tier (hotfix, standard or initiative) sets how much process the work
+gets. The kind sets which parts the design has. The two are separate: an
+initiative-tier piece of work can be a Decide design, and an Initiative
+design holds a family of designs.
+
+At initiative tier, a Decide design goes deep:
+
+1. The Problem today part has a figure of today. The Proposal part has a
+   figure of the target.
+2. At least two options get full depth in Alternatives: their costs, their
+   risks and why each one lost.
+
+At standard tier, one chosen approach and one rejected option are enough.
+
+## What we kept from the Engram template
+
+Every section of the Engram design template has a home. The sections that
+change as work moves went to the tracker.
+
+| Engram section | Its home now |
+|---|---|
+| Status, container, tier | The top strip, read from the tracker |
+| Context and goal | Your words and Summary |
+| Goals, non-goals, success metrics | Goals and non-goals |
+| Flows | Flow kind: Stories and States |
+| User stories | Flow kind: Stories, one walkthrough each |
+| Architecture | The Summary figure, the Proposal, and the Contract parts |
+| Approaches considered | Decide kind: Alternatives and Scorecard |
+| Open and resolved questions | Tracker: Questions |
+| Decision log | Tracker: Decisions. The reasons stay in the design. |
+| Risks and failure modes | Risks |
+| Test and eval plan | Test and proof plan |
+| Acceptance criteria | Done line |
+| Lock block | Tracker: Approval and lock |
+| Deviation log | Tracker: Since approval, with the part each change touched |
+
+## The folder
+
+```text
+docs/design-docs/<slug>/
+  design.yaml      title, item, product, kinds, shared, look
+  summary.md       ---
+                   part: summary
+                   ---
+                   # Summary
+                   ...
+  words.md         part: words
+  ...
+```
+
+1. Name each file as you like. The `part:` line in its front matter says
+   which part it is.
+2. `design.yaml` holds what the design is, never where it stands. Its keys
+   are `title`, `item`, `product`, `kinds`, `shared` and `look`. `look`
+   links a mock or a canvas. The tracker holds the link to the published
+   page.
+3. When the repo's docs lint needs every page linked from an index, add an
+   `index.md` that links each part file. The check then makes sure it links
+   all of them.
+4. A part file may have a `title:` line. The page then uses it as the
+   heading of the part.
+
+## Write each part
+
+1. Read the template for the part in [parts/](parts/). It says what the
+   part holds, the rules for it and a short example.
+2. Write the part in your own file. Do not copy the template.
+3. Write "No change" and the reason when a needed part does not apply.
+   An empty part fails the check.
+4. Put every code you use, such as `US-3` or `M1`, in the Key.
+5. Never write a state line, such as "Status: approved". The check flags it.
+
+## Figures
+
+1. Use a woodcut figure when a stock figure fits: a flow chart, a sequence,
+   a state machine or swim lanes. Use a fenced block with the info string
+   `woodcut wc-<type>`. It holds the figure data as JSON, in the woodcut
+   shape.
+2. Draw your own figure when the subject has its own shape. Git lanes, a
+   time line and a data diff are examples. Use a fenced block with the info
+   string `figure`. It holds the HTML. Use the page tokens, such as
+   `var(--accent)` and `var(--line)`, so the figure works in both themes.
+3. Both kinds follow the same rules. A step has a title and one or two
+   sentences. The reader sets the pace. The figure prints as stills.
+   Meaning is never by colour alone.
+
+## Check and build
+
+1. Run `atlas design check <folder>`. Fix each finding by hand.
+2. Read the item, its questions, decisions and links with the Atlas tools.
+   Copy their fields into one JSON file, as the tools return them. The
+   shape is at the top of `door/lib/design-build.mjs`. The builder
+   refuses a field that the tracker does not hold.
+3. Run `atlas design build <folder> --tracker <item.json>`. It writes the
+   page only when the check is GREEN. `--draft` builds a page marked as a
+   draft.
+4. Run `atlas ste` on the page, then publish it.