@arjunkhera/atlas 0.4.50 → 0.4.51

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "atlas",
-  "version": "0.4.50",
+  "version": "0.4.51",
   "description": "Atlas: the delivery lifecycle, its crews and the Atlas tools, for any repository.",
   "author": {
     "name": "Arjun Khera"

package/door/cli.mjs

@@ -24,6 +24,7 @@ import { install, upgrade, doctor } from './lib/install.mjs';
 import { checkPaths, LIMITS } from './lib/ste.mjs';
 import { checkDesignFolder, designFolderOf, repoRootFrom } from './lib/design.mjs';
 import { writeDesignPage, readTracker } from './lib/design-build.mjs';
+import { listDesigns, freezeDesign } from './lib/design-freeze.mjs';
 import { writePage } from './lib/page.mjs';
 import { writeViewPage, viewCapabilities } from './lib/view.mjs';
 import { loadPrivateTerms } from './lib/privacy.mjs';
@@ -71,6 +72,11 @@ const HELP = `atlas — the door into a repo's Atlas files
       --tracker <file>                 the tracker data, as JSON, from the lead
       --out <file>                     the page; default docs/artifacts/<folder name>.html
       --draft                          build even when the check has findings, and mark the page a draft
+  atlas design list                    list each design with its item: live in the design folder, or frozen in archive/
+      --json                           print the rows as JSON: folder, item, state
+  atlas design freeze <folder> …       freeze the design of a done item: move it to archive/ at its old path, point the links there
+      --date <YYYY-MM-DD>              the frozen date for its page rows; default today
+      --dry-run                        say what would change, and change nothing
 
   atlas page build <file or folder>    build an explainer page from markdown: woodcut figures, the Atlas theme, light and dark
       --out <file>                     the page; default <file or folder>.html beside it
@@ -224,7 +230,7 @@ export const FLAGS = Object.freeze({
   status: { root: 'optional', all: 'switch', json: 'switch' },
   check: { root: 'optional', repo: 'value', 'fail-on': 'value', json: 'switch' },
   ste: { share: 'switch', terms: 'value' },
-  design: { tracker: 'value', out: 'value', draft: 'switch', root: 'optional' },
+  design: { tracker: 'value', out: 'value', draft: 'switch', root: 'optional', date: 'value', 'dry-run': 'switch', json: 'switch' },
   page: { out: 'value', title: 'value' },
   view: { product: 'value', name: 'value', out: 'value' },
   tests: { root: 'optional', halves: 'value', evidence: 'value', 'guards-from': 'value', tests: 'value', 'dry-run': 'switch', run: 'value', own: 'value', base: 'value', head: 'value', list: 'value', side: 'value', old: 'value', new: 'value', covers: 'switch', findings: 'value', repo: 'value', max: 'value', bot: 'value', since: 'value', out: 'value', text: 'switch', json: 'switch', scenario: 'value', language: 'value' },
@@ -372,13 +378,40 @@ function designCommand(chosen) {
   const what = chosen._[1];
   const folders = chosen._.slice(2);
   if (what === 'folder') {
-    if (folders.length || chosen.tracker !== undefined || chosen.out !== undefined || chosen.draft) throw new Error('atlas design folder takes only --root.');
+    if (folders.length || chosen.tracker !== undefined || chosen.out !== undefined || chosen.draft || chosen.date !== undefined || chosen['dry-run'] || chosen.json) throw new Error('atlas design folder takes only --root.');
     const where = designFolderOf(chosen.root === undefined || chosen.root === true ? repoRootFrom(process.cwd()) : resolve(chosen.root));
     line(where.folder);
     return 0;
   }
-  if (chosen.root !== undefined) throw new Error('--root works only with atlas design folder.');
-  if (what !== 'check' && what !== 'build') throw new Error('use atlas design check <folder>, atlas design build <folder> or atlas design folder');
+  if (what === 'list' || what === 'freeze') {
+    if (chosen.tracker !== undefined || chosen.out !== undefined || chosen.draft) throw new Error(`--tracker, --out and --draft work only with atlas design build.`);
+    const root = chosen.root === undefined || chosen.root === true ? repoRootFrom(process.cwd()) : resolve(chosen.root);
+    if (what === 'list') {
+      if (folders.length || chosen.date !== undefined || chosen['dry-run']) throw new Error('atlas design list takes only --root and --json.');
+      const rows = listDesigns(root);
+      if (chosen.json) { line(JSON.stringify(rows, null, 2)); return 0; }
+      for (const row of rows) line(`${row.state.padEnd(7)} ${(row.item ?? 'no item').slice(0, 8).padEnd(8)}  ${row.folder}`);
+      line('');
+      line(`${rows.filter((row) => row.state === 'live').length} live, ${rows.filter((row) => row.state === 'frozen').length} frozen. Freeze a live design when the tracker says its item is done: atlas design freeze <folder>.`);
+      return 0;
+    }
+    if (chosen.json) throw new Error('--json works only with atlas design list.');
+    if (!folders.length) throw new Error('give a design folder: atlas design freeze <folder>');
+    if (chosen.date !== undefined && !/^\d{4}-\d{2}-\d{2}$/.test(chosen.date)) throw new Error(`--date "${chosen.date}": write a date as YYYY-MM-DD`);
+    for (const folder of folders) {
+      // A folder that cannot freeze is a finding about the input, not a
+      // wrong command: say why and stop with exit 1.
+      let report;
+      try { report = freezeDesign(root, folder, { date: chosen.date, dryRun: Boolean(chosen['dry-run']) }); } catch (error) { line(`Not frozen: ${error.message}`); return 1; }
+      const links = report.links.reduce((n, one) => n + one.count, 0);
+      line(`${report.dryRun ? 'Would move' : 'Moved'} ${report.from} to ${report.to} (item ${report.item ? report.item.slice(0, 8) : 'none'}): ${links} link(s) in ${report.links.length} file(s), ${report.index ? 'its index entry under Frozen designs' : 'no index entry'}, ${report.pages} page row(s) frozen.`);
+    }
+    if (!chosen['dry-run']) line('Stage the move with git add -A, so git sees each file as moved. Then run atlas upkeep check.');
+    return 0;
+  }
+  if (chosen.root !== undefined) throw new Error('--root works only with atlas design folder, list and freeze.');
+  if (chosen.date !== undefined || chosen['dry-run'] || chosen.json) throw new Error('--date, --dry-run and --json work only with atlas design list and freeze.');
+  if (what !== 'check' && what !== 'build') throw new Error('use atlas design check <folder>, atlas design build <folder>, atlas design folder, atlas design list or atlas design freeze <folder>');
   if (!folders.length) throw new Error(`give a design folder: atlas design ${what} <folder>`);
   if (what === 'check' && (chosen.tracker !== undefined || chosen.out !== undefined || chosen.draft)) throw new Error('--tracker, --out and --draft work only with atlas design build.');
   if (what === 'build') {

package/door/lib/changed-docs.mjs

@@ -58,14 +58,31 @@ export function changedPaths(root, base, head) {
 }
 
 // The line numbers of one file that the pull request adds or changes, from
-// the hunks of a diff with no context.
+// the hunks of a diff with no context. A line that the pull request only
+// moves is not new text, and so is a line whose only change is a link
+// target: the words are the same words (item e4df0d33, where
+// `atlas design freeze` moves index entries and points links at the
+// archive). Each removed line can excuse one added line.
+export const sameWords = (line) => line.replace(/\]\(\s*(?:<[^>\n]*>|[^)\s]*)(?:\s+"[^"]*")?\s*\)/g, ']()').replace(/^(\s{0,3}\[[^\]\n]+\]:\s*)\S+/, '$1').trimEnd();
 export function addedLines(root, base, head, path) {
   const out = git(root, ['diff', '-U0', '--no-renames', '--no-ext-diff', '--no-textconv', `${base}...${head}`, '--', path]);
+  const removed = new Map();
+  for (const row of out.split('\n')) {
+    if (row.startsWith('-') && !row.startsWith('---')) {
+      const key = sameWords(row.slice(1));
+      if (key.trim()) removed.set(key, (removed.get(key) ?? 0) + 1);
+    }
+  }
   const lines = new Set();
-  for (const [, start, count] of out.matchAll(/^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/gm)) {
-    const first = Number(start);
-    const n = count === undefined ? 1 : Number(count);
-    for (let line = first; line < first + n; line += 1) lines.add(line);
+  let at = null;
+  for (const row of out.split('\n')) {
+    const hunk = row.match(/^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/);
+    if (hunk) { at = Number(hunk[1]); continue; }
+    if (at === null || !row.startsWith('+') || row.startsWith('+++')) continue;
+    const key = sameWords(row.slice(1));
+    if (removed.get(key) > 0) removed.set(key, removed.get(key) - 1);
+    else if (key.trim()) lines.add(at);
+    at += 1;
   }
   return lines;
 }

package/door/lib/design-freeze.mjs

@@ -0,0 +1,251 @@
+// A design freezes when its item is done (tracker item e4df0d33). Code, no
+// model, no key, no network. `atlas design list` and `atlas design freeze`
+// use it.
+//
+// The owner, 31 October 2026: "Guide and product documentation is the one
+// that is supposed to be kept updated, design is just a fleeting item of work
+// that gets done, delivered and forgotten. But we should be able to read
+// those anytime later".
+//
+// So a design is a decision record. While its item is open, it lives in the
+// design folder. When the item is done, `atlas design freeze` moves it to
+// archive/ at its old path, and it is frozen:
+// 1. The folder moves as it is. Not one byte of it changes, so the gate reads
+//    the move as a move into the archive, not as an edit of the archive.
+// 2. Each relative link in a live markdown file that points into the folder
+//    points at the new place, and so does each `sources:` entry in its front
+//    matter. Only the link target changes, never the words around it.
+// 3. The docs index entry of the folder moves under "## Frozen designs", so a
+//    reader still finds it there.
+// 4. Each row of docs/artifacts.json that is built from the folder names the
+//    new place and a frozen date, so the page is never called stale.
+// The upkeep check reads no frozen design: archive/ is outside docs/, so the
+// doc-sources rule and the docs index rule never see it.
+//
+// The rule reads no repo kind: a service, a library and a plugin keep designs
+// alike.
+import { readFileSync, writeFileSync, existsSync, statSync, readdirSync, renameSync, mkdirSync } from 'node:fs';
+import { join, posix, relative, resolve, sep } from 'node:path';
+import { parseYaml, markdownFiles, DOCS_INDEX_PATH } from '../../shape/check.mjs';
+import { designFolderOf, DESIGN_FILE } from './design.mjs';
+
+export const ARCHIVE = 'archive';
+export const FROZEN_HEADING = '## Frozen designs';
+const ARTIFACTS = 'docs/artifacts.json';
+const DATE = /^\d{4}-\d{2}-\d{2}$/;
+
+const readText = (path) => { try { return readFileSync(path, 'utf8'); } catch { return null; } };
+const isDir = (path) => { try { return statSync(path).isDirectory(); } catch { return false; } };
+const toPosix = (path) => path.split(sep).join('/');
+
+function itemOf(root, folder) {
+  try { return String(parseYaml(readText(join(root, folder, DESIGN_FILE)) ?? '')?.item ?? '') || null; } catch { return null; }
+}
+
+function designsUnder(root, folder) {
+  const path = join(root, folder);
+  if (!isDir(path)) return [];
+  return readdirSync(path, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() && existsSync(join(path, entry.name, DESIGN_FILE)))
+    .map((entry) => posix.join(folder, entry.name))
+    .sort();
+}
+
+// Every design of the repo: the live ones in the design folder, and the
+// frozen ones at the same path under archive/. Each row names its item.
+export function listDesigns(root) {
+  const { folder } = designFolderOf(root);
+  const live = designsUnder(root, folder).map((path) => ({ folder: path, item: itemOf(root, path), state: 'live' }));
+  const frozen = designsUnder(root, posix.join(ARCHIVE, folder)).map((path) => ({ folder: path, item: itemOf(root, path), state: 'frozen' }));
+  return [...live, ...frozen];
+}
+
+// The design whose item id starts with `prefix`: live first, then frozen.
+export function designsOfItem(rows, prefix) {
+  const want = String(prefix ?? '').toLowerCase();
+  return want ? rows.filter((row) => row.item && row.item.toLowerCase().startsWith(want)) : [];
+}
+
+// A relative link target that points into `from` (a posix path from the repo
+// root) is rewritten to point at `to`. `file` is the markdown file that holds
+// the link. A target with a scheme, a bare anchor, or a path outside the
+// folder is kept as it is.
+export function moveTarget(file, target, from, to) {
+  if (!target || /^[a-z][a-z0-9+.-]*:/i.test(target) || target.startsWith('#') || target.startsWith('/')) return null;
+  const cut = target.search(/[#?]/);
+  const path = cut === -1 ? target : target.slice(0, cut);
+  const tail = cut === -1 ? '' : target.slice(cut);
+  if (!path) return null;
+  let decoded = path;
+  try { decoded = decodeURIComponent(path); } catch { /* keep it as written */ }
+  const at = posix.normalize(posix.join(posix.dirname(file), decoded));
+  const slash = decoded.endsWith('/');
+  const clean = at.replace(/\/$/, '');
+  if (clean !== from && !clean.startsWith(`${from}/`)) return null;
+  const moved = to + clean.slice(from.length);
+  let next = posix.relative(posix.dirname(file), moved) || '.';
+  if (slash) next += '/';
+  return next + tail;
+}
+
+// The markdown text with each link into `from` pointed at `to`. Inline links
+// and reference definitions; text inside code is never changed.
+export function rewriteLinks(text, file, from, to) {
+  let count = 0;
+  const lines = String(text).split('\n');
+  let fence = null;
+  const out = lines.map((one) => {
+    const open = one.match(/^\s*(`{3,}|~{3,})/);
+    if (fence) {
+      if (open && open[1][0] === fence[0] && open[1].length >= fence.length) fence = null;
+      return one;
+    }
+    if (open) { fence = open[1]; return one; }
+    // Inline code spans stay as they are: split on them, and rewrite the rest.
+    const parts = one.split(/(`+[^`\n]*`+)/);
+    return parts.map((part, index) => {
+      if (index % 2 === 1) return part;
+      let next = part.replace(/(\]\(\s*)(<[^>\n]+>|[^)\s]+)((?:\s+"[^"]*")?\s*\))/g, (whole, head, raw, end) => {
+        const angled = raw.startsWith('<');
+        const moved = moveTarget(file, angled ? raw.slice(1, -1) : raw, from, to);
+        if (moved === null) return whole;
+        count += 1;
+        return `${head}${angled ? `<${moved}>` : moved}${end}`;
+      });
+      next = next.replace(/^(\s{0,3}\[[^\]\n]+\]:\s*)(\S+)/, (whole, head, raw) => {
+        const moved = moveTarget(file, raw, from, to);
+        if (moved === null) return whole;
+        count += 1;
+        return `${head}${moved}`;
+      });
+      return next;
+    }).join('');
+  });
+  return { text: out.join('\n'), count };
+}
+
+// The front matter of a markdown text with each `sources:` entry in `from`
+// pointed at `to`. A doc may name a design as a source; the path must still
+// resolve, or the upkeep check calls the doc stale.
+export function rewriteSources(text, from, to) {
+  const match = String(text).match(/^---\n([\s\S]*?)\n---(\n|$)/);
+  if (!match) return { text, count: 0 };
+  let count = 0;
+  const head = match[1].replace(/^(\s*-\s*['"]?)([^'"\s#]+)/gm, (whole, lead, path) => {
+    const clean = path.replace(/\/+$/, '');
+    if (clean !== from && !clean.startsWith(`${from}/`)) return whole;
+    count += 1;
+    return `${lead}${to}${path.slice(from.length)}`;
+  });
+  return { text: count ? `---\n${head}\n---${match[2]}${String(text).slice(match[0].length)}` : text, count };
+}
+
+// The docs index with the entry of the moved folder under the heading for
+// frozen designs. An entry is one list line that links the folder's
+// design.yaml, and the indented lines below it.
+export function moveIndexEntry(text, link) {
+  const lines = String(text).replace(/\n$/, '').split('\n');
+  const at = lines.findIndex((one) => /^- /.test(one) && one.includes(`](${link})`));
+  if (at === -1) return { text, moved: false };
+  let end = at + 1;
+  while (end < lines.length && /^ {2,}\S/.test(lines[end])) end += 1;
+  const entry = lines.splice(at, end - at);
+  // Drop a blank line that the cut left doubled.
+  if (lines[at - 1] === '' && lines[at] === '') lines.splice(at, 1);
+  let head = lines.indexOf(FROZEN_HEADING);
+  if (head === -1) {
+    while (lines.length && lines[lines.length - 1] === '') lines.pop();
+    lines.push('', FROZEN_HEADING, '', 'Designs of done items, frozen in the archive at their old path. They say why each part works the way it does. The user guide says how it works now.', '');
+    head = lines.indexOf(FROZEN_HEADING);
+  }
+  // The section runs to the next heading. Keep its entries in name order.
+  let stop = lines.findIndex((one, index) => index > head && /^#{1,6} /.test(one));
+  if (stop === -1) stop = lines.length;
+  const key = (one) => (one.match(/^- \[([^\]]*)\]/)?.[1] ?? one).toLowerCase();
+  let put = stop;
+  for (let index = head + 1; index < stop; index += 1) {
+    if (/^- /.test(lines[index]) && key(lines[index]) > key(entry[0])) { put = index; break; }
+  }
+  if (put === stop) {
+    while (put > head + 1 && lines[put - 1] === '') put -= 1;
+    const before = lines[put - 1];
+    lines.splice(put, 0, ...(before !== undefined && /^\S/.test(before) && !/^- /.test(before) ? ['', ...entry] : entry));
+  } else {
+    lines.splice(put, 0, ...entry);
+  }
+  return { text: `${lines.join('\n')}\n`, moved: true };
+}
+
+// The rows of docs/artifacts.json built from the folder: each path names the
+// new place, and the row gets a frozen date. The file keeps its form: two
+// spaces, one row per object, a new line at the end.
+export function freezeRows(text, from, to, date) {
+  const data = JSON.parse(text);
+  const rows = Array.isArray(data?.artifacts) ? data.artifacts : [];
+  let count = 0;
+  // The folder as a whole path word: at the start or after a space or a
+  // quote, and at the end or before a slash, a space or a quote.
+  const word = new RegExp(`(^|[\\s'"(])${from.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?=$|[\\s/'")])`, 'g');
+  const hit = (value) => typeof value === 'string' && new RegExp(word.source).test(value);
+  for (const row of rows) {
+    if (!row || typeof row !== 'object') continue;
+    if (!Object.values(row).some(hit)) continue;
+    for (const [key, value] of Object.entries(row)) {
+      if (typeof value === 'string') row[key] = value.replace(word, `$1${to}`);
+    }
+    if (typeof row.frozen !== 'string') row.frozen = date;
+    count += 1;
+  }
+  return { text: `${JSON.stringify(data, null, 2)}\n`, count };
+}
+
+// Move one live design to the archive. `folder` is a path from the repo root
+// or from here. With dryRun, it changes nothing and says what it would do.
+export function freezeDesign(root, folder, { date = new Date().toISOString().slice(0, 10), dryRun = false } = {}) {
+  if (!DATE.test(date)) throw new Error(`--date "${date}": write a date as YYYY-MM-DD`);
+  const abs = resolve(folder);
+  const from = toPosix(relative(root, abs)).replace(/\/+$/, '');
+  if (!from || from.startsWith('..') || from.startsWith('/')) throw new Error(`${folder} is not inside the repo ${root}`);
+  if (from === ARCHIVE || from.startsWith(`${ARCHIVE}/`)) throw new Error(`${from} is in ${ARCHIVE}/: it is frozen already`);
+  if (!existsSync(join(root, from, DESIGN_FILE))) throw new Error(`${from} holds no ${DESIGN_FILE}: it is not a design folder`);
+  const { folder: designs } = designFolderOf(root);
+  if (posix.dirname(from) !== designs) throw new Error(`${from} is not a design in the design folder ${designs}/. Run atlas design list`);
+  const to = posix.join(ARCHIVE, from);
+  if (existsSync(join(root, to))) throw new Error(`${to} exists already. Move it away by hand, or keep the design live`);
+
+  const report = { from, to, item: itemOf(root, from), links: [], index: false, pages: 0, dryRun };
+  const writes = [];
+  // Links in live markdown files. The files inside the moved folder keep
+  // their bytes, so the move stays a pure move.
+  for (const file of markdownFiles(root)) {
+    if (file === from || file.startsWith(`${from}/`)) continue;
+    const text = readText(join(root, file));
+    if (text === null) continue;
+    const next = rewriteLinks(text, file, from, to);
+    const named = rewriteSources(next.text, from, to);
+    if (next.count + named.count) { report.links.push({ file, count: next.count + named.count }); writes.push([file, named.text]); }
+  }
+  // The docs index entry moves under the frozen heading.
+  const indexAt = writes.findIndex(([file]) => file === DOCS_INDEX_PATH);
+  const indexText = indexAt === -1 ? readText(join(root, DOCS_INDEX_PATH)) : writes[indexAt][1];
+  if (indexText !== null) {
+    const link = posix.relative(posix.dirname(DOCS_INDEX_PATH), posix.join(to, DESIGN_FILE));
+    const moved = moveIndexEntry(indexText, link);
+    if (moved.moved) {
+      report.index = true;
+      if (indexAt === -1) writes.push([DOCS_INDEX_PATH, moved.text]);
+      else writes[indexAt][1] = moved.text;
+    }
+  }
+  // The page rows.
+  const rowsText = readText(join(root, ARTIFACTS));
+  if (rowsText !== null) {
+    const next = freezeRows(rowsText, from, to, date);
+    if (next.count) { report.pages = next.count; writes.push([ARTIFACTS, next.text]); }
+  }
+  if (dryRun) return report;
+  mkdirSync(join(root, posix.dirname(to)), { recursive: true });
+  renameSync(join(root, from), join(root, to));
+  for (const [file, text] of writes) writeFileSync(join(root, file), text);
+  return report;
+}

package/door/lib/doc-sources.mjs

@@ -9,10 +9,15 @@
 // 1. a .md file under docs/, by its front matter: `sources:` (a list of
 //    paths from the repo root; a path that ends in / is a folder), or
 //    `sources_why:` (why it names no code);
-// 2. a design folder (a folder under docs/ that holds design.yaml), by the
-//    same two keys in design.yaml. Its parts are one unit with it;
-// 3. a procedure: the SKILL.md that atlas.yaml `procedures:` names, by the
+// 2. a procedure: the SKILL.md that atlas.yaml `procedures:` names, by the
 //    same two keys in its front matter.
+// A design folder (a folder under docs/ that holds design.yaml) is no unit
+// (item e4df0d33). A design is a decision record: the user guide and the
+// reference pages say how the code works now, and they name their code. The
+// owner, 31 October 2026: "Guide and product documentation is the one that
+// is supposed to be kept updated, design is just a fleeting item of work".
+// Its `sources:` key stays legal, and nothing gates on it. When its item is
+// done, `atlas design freeze` moves it to archive/.
 // A doc that must not change (a locked text, the owner's own words) can name
 // its code in a `sources.yaml` beside it, or in a folder above it under docs/:
 // `files: { <name>: { sources: [...] } }` for one file, or `sources:` and
@@ -94,16 +99,8 @@ function procedureFiles(root) {
 // names neither its code nor a reason.
 export function docUnits(root) {
   const units = [];
-  const folders = new Set();
   for (const file of markdownFiles(root, 'docs')) {
-    const folder = designFolderOf(root, file);
-    if (folder) {
-      if (folders.has(folder)) continue;
-      folders.add(folder);
-      const where = posix.join(folder, DESIGN);
-      units.push({ unit: folder, kind: 'design', where, named: declared(yamlOf(readText(root, where) ?? ''), 'sources_why') ?? fromSidecar(root, where), generated: false });
-      continue;
-    }
+    if (designFolderOf(root, file)) continue;
     const head = headOf(readText(root, file));
     units.push({ unit: file, kind: 'doc', where: file, named: declared(head, 'sources_why') ?? fromSidecar(root, file), generated: head?.generated === true });
   }
@@ -141,7 +138,7 @@ export function covers(root, source, path) {
 const touchedItself = (unit, changed) => changed.some((path) => path === unit.unit || path === unit.where || path.startsWith(`${unit.unit}/`));
 
 // The pull request text that marks a doc "still true": one line that names the
-// unit (its path, or for a design folder its folder) and says "still true".
+// unit (its path, or for a procedure its folder) and says "still true".
 export function stillTrue(body, unit) {
   const text = String(body ?? '').replace(/<!--[\s\S]*?(?:-->|$)/g, '');
   return text.split('\n').some((line) => /still true/i.test(line) && (line.includes(unit.unit) || line.includes(unit.where)));
@@ -232,9 +229,7 @@ function changedLines(root, parent, commit) {
 // then against each folder it names, then against packages/<name>/.
 const CITE = /`?([\w.@-]+(?:\/[\w.@-]+)*\.[A-Za-z]{1,5}):(\d+)(?:-(\d+))?/g;
 function citedLines(root, unit) {
-  const files = unit.kind === 'design'
-    ? markdownFiles(root, unit.unit).concat([unit.where])
-    : [unit.where];
+  const files = [unit.where];
   const out = [];
   for (const file of files) {
     const text = readText(root, file) ?? '';

package/door/lib/owner-only.mjs

@@ -542,9 +542,30 @@ export function classify({ root, base, head, rules: rulesRef = null, classes = l
   const signs = classes.classes.flatMap((entry) => (entry.signs ?? []).map((sign) => ({ ...sign, class: entry.id })));
   const secrets = SECRET_PATTERNS.map((pattern) => ({ id: pattern.id, regex: compile(pattern.source) }));
 
+  // A pure move into the archive (item e4df0d33): a file at P is deleted, and
+  // archive/P is added with the same bytes and mode. `atlas design freeze`
+  // makes such moves when a design's item is done. The archive floor keeps
+  // archived records from change; a move of one unchanged file into it at its
+  // own path changes no record, so that floor alone does not send the add to
+  // the owner. The delete of P still meets every rule on P, and every other
+  // rule and sign still reads archive/P.
+  const deleted = new Map(changes.filter((one) => one.status === 'D').map((one) => [one.path, one]));
+  const pureMove = (change) => {
+    if (change.status !== 'A' || !change.path.startsWith('archive/')) return false;
+    const from = change.path.slice('archive/'.length);
+    const gone = deleted.get(from);
+    if (!gone || from.startsWith('archive/') || gone.oldMode !== change.newMode) return false;
+    const blob = (ref, path) => (ref === null ? null : git(root, ['rev-parse', '--verify', '--quiet', `${ref}:${path}`], { allowFail: true })?.toString('utf8').trim() || null);
+    const a = blob(base, from), b = blob(head, change.path);
+    if (a && b) return a === b;
+    const before = readAt(root, base, from), after = readAt(root, head, change.path);
+    return before !== null && after !== null && before === after;
+  };
+
   for (const change of changes) {
     const { path } = change;
     const hits = [];
+    const moved = pureMove(change);
     // A symlink or a submodule can point anywhere, so it always comes to the owner.
     if ([change.oldMode, change.newMode].includes('120000')) hits.push(['rule-book', 'a symlink changed']);
     if ([change.oldMode, change.newMode].includes('160000')) hits.push(['rule-book', 'a submodule changed']);
@@ -560,6 +581,7 @@ export function classify({ root, base, head, rules: rulesRef = null, classes = l
     const kitRelease = change.status === 'M' && signs.some((sign) => sign.version_key && matchesAny(sign.paths, path) && versionOnly(baseText, headText, sign.version_key));
     for (const rule of release ? [] : rules) {
       if (!ruleHits(rule, path)) continue;
+      if (moved && rule.pattern === 'archive/' && rule.cause === 'floor: archive') { hits.push([null, 'cleared']); continue; }
       if (kitRelease && rule.cause.startsWith('list: ')) continue;
       if (rule.atlas_yaml) {
         const cause = atlasYamlCause(baseText, headText, classes.atlas_yaml);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arjunkhera/atlas",
-  "version": "0.4.50",
+  "version": "0.4.51",
   "description": "Atlas: the delivery lifecycle, its crews and the Atlas tools, as a Claude Code plugin for any repository.",
   "type": "module",
   "license": "UNLICENSED",

package/skills/lead/SKILL.md

@@ -121,7 +121,7 @@ set. A test keeps the two lists equal.
 | `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 tests` | `write` puts the test kit in an area. `check` runs before a merge. `kept` runs the kept tests of a path 1 area and writes their evidence. `proof`, `verdict`, `named`, `covers` and `rerun` read the results of a run. `changed`, `before` and `after` run the test checks of the gate: changed tests, new cases fail on old code, old cases pass on new code. `sweep` and `issues` run the daily sweep |
-| `atlas design` | `folder` to learn where designs live; `check` before you show a design; `build` to make its page |
+| `atlas design` | `folder` to learn where designs live; `check` before you show a design; `build` to make its page. `list` shows each design and its item; `freeze` moves the design of a done item to `archive/` |
 | `atlas page` | `build <file or folder>` makes an explainer page, as talk rule 10 says. It refuses markdown with no woodcut figure that walks. Run `atlas ste` on the page, then publish it |
 | `atlas view` | `build --product <id>` makes the project view page of one product, when the owner asks for it or after an Atlas release changes it. Publish it with only the grant the command prints |
 | `atlas jobs` | The `atlas-jobs` workflow calls `check`, then `file`, once a day. A session calls it only to see what the watcher would file: `check`, then `file --dry-run` |

package/skills/sdlc-task/SKILL.md

@@ -212,9 +212,17 @@ next action. One short paragraph.
 2. If anything was a struggle, run the `atlas:learnings` skill. It picks the
    home and the form of the fix, and records the lesson.
 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
+   design's files do not change: the tracker holds the delivery. A design
    in the older format is one file, not a folder. Keep its page, and rebuild
    only the hub.
+4. The design freezes. The next daily upkeep run moves its folder to
+   `archive/` at its old path, with `atlas design freeze <folder>`. The guide
+   lists it under "Why it works this way". Do not move it yourself, unless
+   you open a pull request for this repo anyway. Then run
+   `atlas design freeze <folder>`, `git add -A`, and put the move in it.
+   Owner, 31 October 2026: "design is just a fleeting item of work that
+   gets done, delivered and forgotten. But we should be able to read those
+   anytime later".
 
 ## The design hub
 

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

@@ -27,11 +27,14 @@ 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.
 
-Name the code the design describes under `sources:` in `design.yaml`.
-It is a list of paths from the repo root. A path that ends in `/` is a
-folder. A design with no code yet says why under `sources_why:`. A pull
-request that changes a named path updates the design, or marks it "still
-true" (roadmap R39). `atlas upkeep check` reads both keys.
+A design is a record of one decision. It is live in the design folder
+while its item is open. When the item is done, `atlas design freeze <folder>`
+moves it to `archive/` at its old path, and it never changes again.
+
+The user guide and the reference pages say how the code works now. Each
+one names its code under `sources:`. A pull request that changes that code
+updates the page, or marks it "still true" (roadmap R39). `atlas upkeep
+check` reads no `sources:` key of a design (item e4df0d33).
 
 ## All parts by kind
 

package/skills/upkeep/SKILL.md

@@ -3,7 +3,8 @@ name: upkeep
 description: >
   The daily upkeep run of a repo that runs Atlas. It keeps the tracker and the docs true:
   it marks merged deliveries, keeps next steps true, closes issues that have an item, and
-  fixes the docs index and dead doc links in one pull request that it merges itself.
+  freezes the designs of done items and fixes the docs index and dead doc links in one
+  pull request that it merges itself.
   Trigger when a scheduled task says "run the atlas:upkeep skill", or when the owner asks
   for an upkeep run now.
 ---
@@ -74,10 +75,20 @@ If the tracker cannot be reached, skip this half and say so.
 ## The docs half
 
 1. Check out a fresh copy of the default branch.
-2. Run `atlas upkeep check --root .`. If it is green, the docs half is done.
-3. If an open pull request from an earlier upkeep run exists, work on its
-   branch. Otherwise make the branch `claude/upkeep-<YYYY-MM-DD>`.
-4. Fix each finding:
+2. **Find the designs of done items.** Run `atlas design list`. Read the
+   state of the item of each live design in the tracker, for example with
+   `built_pending_possible` for the product. Keep each
+   design whose item is done. Skip a design with no item, and a design
+   whose item is open, paused or dropped. When the tracker cannot be
+   reached, keep none.
+3. Run `atlas upkeep check --root .`. If it is green and step 2 kept no
+   design, the docs half is done.
+4. If an open pull request from an earlier upkeep run exists, work on its
+   branch. Otherwise make the branch `claude/upkeep-<YYYY-MM-DD>`. Then run
+   `atlas design freeze <folder>` for each design that step 2 kept. It
+   moves the folder to `archive/` at its old path. It points each link at
+   the new place, and moves the index entry under "Frozen designs".
+5. Fix each finding:
    1. An unlisted file: add one line to `docs/index.md`, in the section
       that fits. Describe the file in a few plain words. For a design
       folder, list its `design.yaml` once.
@@ -87,14 +98,17 @@ If the tracker cannot be reached, skip this half and say so.
    3. A dead link: point it at the moved file. When the new target is not
       clear, leave the link and list it in the report. Change only the link
       target, never the words around it.
-5. Run `atlas upkeep check` again, and `atlas check` when the repo has the
+6. Run `atlas upkeep check` again, and `atlas check` when the repo has the
    shape check. Both must not get worse.
-6. Commit, push, and open or update one pull request. The title is
+7. Stage with `git add -A`, so git sees each frozen file as moved.
+   Commit, push, and open or update one pull request. The title is
    "Upkeep <date>: <what changed>". The body lists each change on one line.
    It ends with "no item: the daily upkeep run".
-7. Wait for every check on the pull request. When all are green and the
-   diff changes only index lines and link targets, run `atlas gate` with
-   the verb `ready`, `--repo` and `--pr`. On READY, merge it with a merge
+8. Read the diff. It may change only index lines, link targets, page rows
+   and the moves of the freeze. Otherwise leave the pull request open and
+   say why in the report.
+9. Wait for every check on the pull request. When all are green, run
+   `atlas gate` with the verb `ready`, `--repo` and `--pr`. On READY, merge it with a merge
    commit at the head SHA that ready read. The merge door hook refuses any
    other merge. When the branch is behind the main branch, merge the main
    branch in, wait for green, and run `ready` again. Otherwise leave it
@@ -112,7 +126,7 @@ its own log entry. The line is plain text:
 Upkeep <date> · Atlas <version>
 Marked: <n> (<item ids and pull requests>)
 Next steps fixed: <n> · Comments: <n> · Issues closed: <n>
-Docs: <n> fixes, <merged #n | open #n, why | none>
+Docs: <n> fixes, <n> designs frozen, <merged #n | open #n, why | none>
 Left for the owner: <red merges, sweep mismatch, old questions, unclear links, or none>
 ```
 
@@ -134,6 +148,6 @@ Output:
 Upkeep 2026-10-22 · Atlas 0.3.25
 Marked: 1 (6dbd71b0 #148)
 Next steps fixed: 0 · Comments: 0 · Issues closed: 0
-Docs: 1 fix, merged #161
+Docs: 1 fix, 0 designs frozen, merged #161
 Left for the owner: none
 ```