@arjunkhera/atlas 0.4.50 → 0.4.52

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "atlas",
-  "version": "0.4.50",
+  "version": "0.4.52",
   "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
@@ -167,6 +173,7 @@ const HELP = `atlas — the door into a repo's Atlas files
   atlas gate audit --repo <owner/name> [--since <date>]   each merge since the date (default: one day) that came before its checks were green
   atlas gate audit --repo <owner/name> --commit <sha> [--forced] [--findings <file>]   one commit on the main branch: red when no pull request merged it, one merged it before its checks were green, or a gate run is not from the base workflow
   atlas gate audit --repo <owner/name> --errors [--findings <file>]   red when the gate errored on 3 pull requests in a row
+  atlas gate hold --repo <owner/name> --root <clone> --commit <sha> --from <sha>   the release job only, from the copy on npm: exit 3 holds the release while a merge since --from went to the owner with no act of his
   atlas gate check --base <ref> --head <sha>   the gate: judge a pull request with this copy of Atlas; success, owner or red
       --pr <n> --base-ref <branch>     with --repo: read the comments of the pull request, and let the owner's signed act for this base and head clear owner
       --root <repo>                    the clone that holds both commits (default: this folder); the head is read as git data only
@@ -224,14 +231,14 @@ 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' },
   jobs: { root: 'optional', repo: 'value', branch: 'value', out: 'value', findings: 'value', max: 'value', 'dry-run': 'switch' },
   runner: { repo: 'value', issue: 'value', holder: 'value', from: 'value', json: 'switch' },
   upkeep: { root: 'optional', event: 'value', json: 'switch', last: 'value', base: 'value' },
-  gate: { repo: 'value', root: 'optional', 'dry-run': 'switch', off: 'switch', on: 'switch', pr: 'value', since: 'value', commit: 'value', base: 'value', 'base-ref': 'value', head: 'value', body: 'value', json: 'switch', summary: 'value', output: 'value', days: 'value', branch: 'value', errors: 'switch', forced: 'switch', findings: 'value' },
+  gate: { repo: 'value', root: 'optional', 'dry-run': 'switch', off: 'switch', on: 'switch', pr: 'value', since: 'value', commit: 'value', from: 'value', base: 'value', 'base-ref': 'value', head: 'value', body: 'value', json: 'switch', summary: 'value', output: 'value', days: 'value', branch: 'value', errors: 'switch', forced: 'switch', findings: 'value' },
   approve: { repo: 'value', root: 'optional', key: 'value', provider: 'value', yes: 'switch', out: 'value', file: 'value', signers: 'value', commit: 'value', item: 'value', card: 'value', words: 'value', pr: 'value', head: 'value', decision: 'value', check: 'value' },
   judge: { tasks: 'value', verdict: 'value', seal: 'value', runs: 'value', out: 'value', repo: 'value', budget: 'value', model: 'value' },
   install: { local: 'switch', from: 'value', 'skip-global': 'switch', yes: 'switch', cloud: 'switch' },
@@ -372,13 +379,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') {
@@ -471,7 +505,7 @@ function upkeepVerb(chosen) {
 }
 
 function gateVerb(chosen) {
-  return gateCommand({ what: chosen._[1], repo: chosen.repo, root: rootOf(chosen), dryRun: Boolean(chosen['dry-run']), off: Boolean(chosen.off), on: Boolean(chosen.on), pr: chosen.pr, since: chosen.since, commit: chosen.commit, base: chosen.base, baseRef: chosen['base-ref'], head: chosen.head, body: chosen.body, json: Boolean(chosen.json), summary: chosen.summary, output: chosen.output, days: chosen.days, branch: chosen.branch, errors: Boolean(chosen.errors), forced: Boolean(chosen.forced), findings: chosen.findings }, line);
+  return gateCommand({ what: chosen._[1], repo: chosen.repo, root: rootOf(chosen), dryRun: Boolean(chosen['dry-run']), off: Boolean(chosen.off), on: Boolean(chosen.on), pr: chosen.pr, since: chosen.since, commit: chosen.commit, from: chosen.from, base: chosen.base, baseRef: chosen['base-ref'], head: chosen.head, body: chosen.body, json: Boolean(chosen.json), summary: chosen.summary, output: chosen.output, days: chosen.days, branch: chosen.branch, errors: Boolean(chosen.errors), forced: Boolean(chosen.forced), findings: chosen.findings }, line);
 }
 
 function approveVerb(chosen) {

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/gate.mjs

@@ -22,7 +22,7 @@ import { childEnvironment } from '../../work/lib/child-env.mjs';
 import { parseYaml } from '../../shape/check.mjs';
 import { checkCommand, replayCommand, judge, jobNames, GATE_CHECK, GATE_WORKFLOW } from './gate-check.mjs';
 import { keepFindings, gateErrors, pinCode, slug, AUDIT_JOB } from './gate-audit.mjs';
-import { MARKER as SIGNED_MARKER } from './signed-act.mjs';
+import { MARKER as SIGNED_MARKER, SIGNERS_FILE, AUDIT_CHECK, parseSigners, verifyTexts, findAct, auditCodeDiff } from './signed-act.mjs';
 import { brakeFacts, windowCommits, ciTrips, BrakeError } from './brake.mjs';
 
 export const BRANCH_RULESET = 'atlas gate';
@@ -708,6 +708,93 @@ export function prComments(gh, repo, pr) {
   return kept;
 }
 
+// `atlas gate hold --root <clone> --commit <sha> --from <sha>` (item 4af66381,
+// the release hold). The release job runs it from the trusted copy, the
+// version that npm holds as latest, never from the commit that it judges.
+// `--from` is the commit of that version, from its release record, as
+// `atlas upgrade` finds it. The hold judges
+// each first-parent merge from there to the release commit again, with the
+// rules and the brake of its parent, at the time of its merge. Only a merge
+// that the gate judges success passes: an owner or a red answer holds the
+// release (security review of #290, S1), unless the owner signed one of
+// three acts on the pull request:
+//   1. a merge act for its head (the gate counts it already, so the answer
+//      is success);
+//   2. an accept act for its head, from `atlas approve audit`, for a merge
+//      that changed no audit code;
+//   3. an accept-code act for its merge commit and its audit-code diff, from
+//      `atlas approve audit-code`.
+// It fails closed: a push past the gate, a merge that it cannot judge, a
+// start that the release commit does not hold, or more than HOLD_MAX merges
+// also hold. Exit 0: publish. Exit 3: hold. Any other exit is an error.
+export const HOLD_MAX = 200;
+// git's word for the ancestor test, joined so the package names no ancestry verb (test/package D9).
+const MERGE_BASE = ['merge', 'base'].join('-');
+export const HOLD_EXIT = 3;
+export function holdCommand({ repo, root, commit, from }, line, gh) {
+  const full = (value) => typeof value === 'string' && /^[0-9a-f]{40}$/.test(value);
+  if (!full(commit)) throw new GateError('atlas gate hold needs --commit <full sha>.');
+  if (!full(from)) throw new GateError('atlas gate hold needs --from <full sha>: the commit of the version that npm holds as latest.');
+  if (!root || root === true) throw new GateError('atlas gate hold needs --root <clone>.');
+  const git = (args) => execFileSync('git', ['-C', root, ...args], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], maxBuffer: 64 * 1024 * 1024 }).trim();
+  try { git(['cat-file', '-e', `${commit}^{commit}`]); } catch { throw new GateError(`${commit} is not a commit in ${root}.`); }
+  try { git([MERGE_BASE, '--is-ancestor', '--end-of-options', from, commit]); } catch {
+    line(`HOLD: the published commit ${from.slice(0, 7)} is not in the history of ${commit.slice(0, 7)}, so the hold cannot tell which merges npm does not hold yet.`);
+    return HOLD_EXIT;
+  }
+  const commits = git(['rev-list', '--first-parent', '--reverse', `--max-count=${HOLD_MAX + 1}`, `${from}..${commit}`]).split('\n').filter(Boolean);
+  if (commits.length > HOLD_MAX) { line(`HOLD: more than ${HOLD_MAX} merges since the published commit ${from.slice(0, 7)}.`); return HOLD_EXIT; }
+  const held = [];
+  for (const sha of commits) {
+    const why = holdRow({ repo, root, sha }, gh, git);
+    if (why) { held.push(why); line(`  ✗ ${why}`); }
+  }
+  if (held.length) {
+    line(`HOLD: ${held.length} of ${commits.length} merge(s) since the published commit ${from.slice(0, 7)} went to the owner, and no act of his clears them. The owner signs them with atlas approve audit (atlas approve audit-code <pr> for a merge that changed the audit code). The next release run after his touch publishes.`);
+    return HOLD_EXIT;
+  }
+  line(`atlas gate hold: ${commits.length} merge(s) since the published commit ${from.slice(0, 7)}, each green or signed by the owner. Publish.`);
+  return 0;
+}
+
+// Why one first-parent commit holds the release, or null.
+export function holdRow({ repo, root, sha }, gh, git) {
+  let pull;
+  try { pull = (gh('GET', `repos/${repo}/commits/${sha}/pulls`) ?? []).find((each) => each.merged_at && each.merge_commit_sha === sha); } catch { return `${sha.slice(0, 7)}: GitHub did not say which pull request merged it`; }
+  if (!pull) return `${sha.slice(0, 7)} reached the branch with no pull request: a push past the gate`;
+  const head = String(pull.head?.sha ?? '');
+  let parent;
+  try { parent = git(['rev-parse', '--verify', '--end-of-options', `${sha}^1`]); } catch { return `#${pull.number}: the parent of ${sha.slice(0, 7)} is not in this clone`; }
+  try { git(['cat-file', '-e', `${head}^{commit}`]); } catch { return `#${pull.number}: its head ${head.slice(0, 7)} is not in this clone`; }
+  let texts;
+  try { texts = prComments(gh, repo, pull.number); } catch { return `#${pull.number}: GitHub did not give its comments, so no act of the owner can be read`; }
+  let answer;
+  try {
+    const at = new Date(pull.merged_at);
+    const brake = { ci: brakeRead({ root, base: parent, now: at }, gh, repo), clears: { repo, commentsOf: (one) => commitComments(gh, repo, one) } };
+    // The red main checks of its parent, as the gate read them, so a fix of a red main check is judged as the gate judged it.
+    answer = judge({ root, base: parent, head, body: String(pull.body ?? ''), now: at, brake, redMain: redMain({ root, base: parent }, gh, repo), signed: { repo, pr: Number(pull.number), baseRef: pull.base?.ref ?? null, texts } });
+  } catch (error) { return `#${pull.number}: it cannot be judged (${String(error?.message ?? error).split('\n')[0].slice(0, 160)})`; }
+  if (answer.result === 'success') return null;
+  // The gate did not say success. An accept act, or an accept-code act for a
+  // merge that changed audit code, checked with the keys of its parent,
+  // clears it now. The audit-code test is the one that `atlas approve audit`
+  // keeps, so the hold does not rest on the Mac tool alone.
+  let keys = [];
+  try { keys = parseSigners(git(['show', `${parent}:${SIGNERS_FILE}`])).keys; } catch { keys = []; }
+  const verified = verifyTexts(texts, keys);
+  let code;
+  try { code = auditCodeDiff(gh('GET', `repos/${repo}/commits/${sha}`)?.files); } catch { code = { unknown: true }; }
+  const accepted = code.unknown ? null
+    : code.files.length ? findAct(verified, { kind: 'accept-code', repo, pr: String(pull.number), head, merge: sha, diff: code.print })
+      : findAct(verified, { kind: 'accept', repo, pr: String(pull.number), head, check: AUDIT_CHECK });
+  if (accepted) return null;
+  const row = (answer.rows ?? []).find((each) => each.kind === answer.result) ?? (answer.rows ?? []).find((each) => each.kind === 'owner');
+  const what = answer.result === 'red' ? 'the gate said red' : 'went to the owner';
+  if (code.unknown) return `#${pull.number} (${sha.slice(0, 7)}) ${what}, and GitHub gave no full file list of its merge, so no accept act can be checked`;
+  return `#${pull.number} (${sha.slice(0, 7)}) ${what}${row ? `: ${row.class ?? answer.result}${row.path ? ` ${row.path}` : ''}` : ''}, and no ${code.files.length ? 'merge or accept-code' : 'merge or accept'} act names it`;
+}
+
 // The comment texts of one commit on main that carry the signed-act marker:
 // where the owner posts a brake clear (roadmap R13 line 6). At most three
 // pages of a hundred. A read that fails gives null, so no clear counts.
@@ -763,9 +850,9 @@ export function brakeRead({ root, base, now = new Date() }, gh, repo, pages = 3)
   return ciTrips({ commits, runs, homes, checks, live: facts.live, liveChecks }, jobsOf);
 }
 
-// `atlas gate apply|ready|audit|check|replay`. Returns the exit code.
-export function gateCommand({ what, repo, root, dryRun = false, off = false, on = false, pr, since, commit, base, baseRef, head, body, json = false, summary, output, days, branch, errors = false, forced = false, findings, home = homedir() }, line, gh = ghApi) {
-  if (!['apply', 'ready', 'audit', 'check', 'replay'].includes(what)) throw new GateError(`there is no gate verb "${what ?? ''}". Use apply, ready, audit, check or replay.`);
+// `atlas gate apply|ready|audit|check|replay|hold`. Returns the exit code.
+export function gateCommand({ what, repo, root, dryRun = false, off = false, on = false, pr, since, commit, from, base, baseRef, head, body, json = false, summary, output, days, branch, errors = false, forced = false, findings, home = homedir() }, line, gh = ghApi) {
+  if (!['apply', 'ready', 'audit', 'check', 'replay', 'hold'].includes(what)) throw new GateError(`there is no gate verb "${what ?? ''}". Use apply, ready, audit, check, replay or hold.`);
   // With --repo, check reads the red main checks from GitHub; without, it judges git data alone.
   const named = repo && repo !== true && /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repo) && !repo.split('/').some((part) => /^\.+$/.test(part));
   if (what === 'check') {
@@ -787,6 +874,7 @@ export function gateCommand({ what, repo, root, dryRun = false, off = false, on
     }
     return code;
   }
+  if (what === 'hold') return holdCommand({ repo, root, commit, from }, line, gh);
   if (what === 'audit') return auditCommand({ repo, root, since, commit, errors, forced, findings }, line, gh);
   if (off && on) throw new GateError('pick --off or --on, not both.');
   const mode = off ? 'off' : on ? 'on' : 'apply';

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/door/lib/signed-act.mjs

@@ -113,13 +113,14 @@ export const AUDIT_CHECKS = Object.freeze(['gate · push audit', AUDIT_CHECK]);
 // The files whose change lets a merge write its own audit: every repo file
 // of the gate and audit groups of GATE_FILE_GROUPS in gate-audit.mjs (a test
 // keeps this list a superset), the signed act that the gate reads, and the
-// job file of the audit. `atlas approve audit` never signs a merge that
+// job file of the audit, and the release job, which runs the release hold
+// (item 4af66381). `atlas approve audit` never signs a merge that
 // changed one (security review 2 of item 0ca9fced, S3). Such a merge takes
 // an accept-code act instead, and its words quote the test AUDIT_CODE_TEST
 // (item f36c6b0f).
 export const AUDIT_WORKFLOW = '.github/workflows/atlas-gate-audit.yml';
 export const AUDIT_CODE = Object.freeze([
-  AUDIT_WORKFLOW, '.github/workflows/atlas-gate.yml', '.github/workflows/atlas-jobs.yml',
+  AUDIT_WORKFLOW, '.github/workflows/atlas-gate.yml', '.github/workflows/atlas-jobs.yml', '.github/workflows/release.yml',
   'packages/atlas/bin/atlas', 'packages/atlas/door/cli.mjs', 'packages/atlas/owner-only.yaml', 'packages/atlas/door/jobs/gate-audit.yaml',
   ...['gate.mjs', 'gate-audit.mjs', 'gate-check.mjs', 'owner-only.mjs', 'jobs.mjs', 'issues.mjs', 'signed-act.mjs'].map((name) => `packages/atlas/door/lib/${name}`),
   'packages/atlas/shape/check.mjs', 'packages/atlas/work/lib/child-env.mjs',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arjunkhera/atlas",
-  "version": "0.4.50",
+  "version": "0.4.52",
   "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,13 +121,13 @@ 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` |
 | `atlas runner` | Only in a runner run, as the `atlas:runner` skill says: `start` first, `claim` before each build, `line` last. A lead session never runs the runner |
 | `atlas upkeep` | `check` before you ask for a merge. It reads the docs index, dead doc links, the code each doc names and stale pages. In a pull request it also reads the tracker item, the changed designs, and STE on the changed lines. The daily upkeep run calls it on the main branch. `replay` before the doc-sources rule changes how it gates. `procedures` runs the procedure steps tagged `atlas-run`; CI runs it with `--base` on each pull request |
-| `atlas gate` | `apply` once per repo, by the owner on his Mac, after the repo's `required_checks` exist. `--dry-run` first. `--off` and `--on` are the break glass. On a plan with no rulesets it reports advisory mode. `ready` before each merge, `check` in the `atlas-gate` workflow, `replay` before a change to the owner-only list. `audit` in the daily upkeep run, and with `--commit` in the push job of a repo that has one |
+| `atlas gate` | `apply` once per repo, by the owner on his Mac, after the repo's `required_checks` exist. `--dry-run` first. `--off` and `--on` are the break glass. On a plan with no rulesets it reports advisory mode. `ready` before each merge, `check` in the `atlas-gate` workflow, `replay` before a change to the owner-only list, `hold` only in the release job. `audit` in the daily upkeep run, and with `--commit` in the push job of a repo that has one |
 | `atlas approve` | Never from a session. Only the owner runs it, on his Mac, with his key's touch. When the gate says "owner" for a pull request, ask him once for the signed act: name each pull request, its class and its cause. Put the owner pull requests of one day in one ask, so one touch signs them. `act`, `verify` and `key-check` work the same way. Each morning with open audit issues, ask him for `audit`, and `audit-code <pr>` per audit-code merge; record its words as one decision, then close each issue |
 | `atlas judge` | In the fresh-agent test only, as the `atlas:fresh-agent-test` skill says. `seal` after the pick, `brief` to read a sealed ask, `run` for each sealed task, `check` after the grade |
 

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
 ```