@arjunkhera/atlas 0.4.49 → 0.4.51

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "atlas",
-  "version": "0.4.49",
+  "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';
@@ -34,6 +35,7 @@ import { runKept } from '../tests/kept.mjs';
 import { sweepCommand as testsSweep, coversCommand as testsCovers } from '../tests/sweep.mjs';
 import { issuesCommand as testsIssues } from './lib/issues.mjs';
 import { jobsCommand } from './lib/jobs.mjs';
+import { runnerCommand } from './lib/runner.mjs';
 import { changedCommand as testsChanged } from './lib/changed-tests.mjs';
 import { beforeCommand as testsBefore } from './lib/fails-before.mjs';
 import { afterCommand as testsAfter } from './lib/passes-after.mjs';
@@ -70,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
@@ -143,6 +150,13 @@ const HELP = `atlas — the door into a repo's Atlas files
       --dry-run                        print what it would open; change nothing
                                        The token is only GITHUB_TOKEN. The atlas-jobs workflow runs both, once a day
 
+  atlas runner start --repo <owner/name>   the start of a runner run: the start checks, the inputs it may build, the outside issues and the room under the caps; writes nothing
+      --branch <name>                  the default branch; default GitHub's answer
+      --json                           print the whole answer as JSON
+  atlas runner claim --repo <owner/name> --issue <n> --holder <run id>   claim one atlas-job issue; the oldest live claim holds it
+  atlas runner line --from <file>      print the last line of a run, from a JSON file of ids and counts
+                                       Until the A2 exit test, the runner works on the scratch repo only
+
   atlas upkeep check --root <repo>     the upkeep check: the docs index, dead doc links, the code each doc names, stale pages, and in a pull request its tracker item, its changed designs and STE on its changed lines
   atlas upkeep replay --root <repo>    what the doc-sources rule would have asked of the last merges; writes nothing
   atlas upkeep procedures --root <repo>  run the procedure steps marked atlas-run; --base <ref> runs only the procedures a change touches
@@ -216,11 +230,12 @@ 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' },
   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' },
@@ -363,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') {
@@ -453,6 +495,10 @@ function jobsVerb(chosen) {
   return jobsCommand({ what: chosen._[1], root: rootOf(chosen), repo: chosen.repo, branch: chosen.branch, out: chosen.out, findings: chosen.findings, max: chosen.max, dryRun: Boolean(chosen['dry-run']), args: [...chosen._, ...Object.values(chosen).filter((v) => typeof v === 'string')] }, line);
 }
 
+function runnerVerb(chosen) {
+  return runnerCommand({ what: chosen._[1], repo: chosen.repo, issue: chosen.issue, holder: chosen.holder, from: chosen.from, json: Boolean(chosen.json), args: [...chosen._, ...Object.values(chosen).filter((v) => typeof v === 'string')] }, line);
+}
+
 function upkeepVerb(chosen) {
   return upkeepCommand({ what: chosen._[1], event: chosen.event, json: Boolean(chosen.json), last: chosen.last, base: chosen.base }, rootOf(chosen), line);
 }
@@ -512,6 +558,7 @@ export async function main(argv = process.argv.slice(2)) {
     case 'view': return viewCommand(chosen);
     case 'tests': return testsCommand(chosen);
     case 'jobs': return jobsVerb(chosen);
+    case 'runner': return runnerVerb(chosen);
     case 'upkeep': return upkeepVerb(chosen);
     case 'gate': return gateVerb(chosen);
     case 'judge': return judgeVerb(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/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);