@arjunkhera/atlas 0.2.3 → 0.3.0

package/shape/check.mjs

@@ -29,12 +29,12 @@ export const sha256 = (text) => createHash('sha256').update(String(text ?? ''),
 // The version of this check, as a whole number. It moves only when this file's
 // own code changes, never with the Atlas package version (row F11, amendment
 // A1.9). A release of Atlas that leaves the check alone leaves every repo's copy
-// current, so the ratchet's check-file case does not fire on every release.
+// current, so the no-loss rule's check-file case does not fire on every release.
 //
 // Whether a copy is current or behind is not decided here. CI has no package
 // and no network. The session verb decides it, from the release list that
 // ships beside this file in the package, shape/releases.json.
-export const CHECK_VERSION = 2;
+export const CHECK_VERSION = 3;
 
 // ---------------------------------------------------------------------------
 // The spec. One object per version. The check reads a version it has here and
@@ -614,7 +614,7 @@ export const WORKFLOW_TEMPLATE = `# The Atlas repo shape check, in this repo's o
 #
 # It reports in the docs lane. It never fails a code merge.
 #
-# The second checkout is the ratchet's base tree. The check scores the base
+# The second checkout is the no-loss rule's base tree. The check scores the base
 # commit and the head commit side by side, and it goes red when a part the base
 # already had is taken away. The base tree lands in ${BASE_DIR}, whose name
 # starts with a dot, so no scanner walks into it. If that checkout fails there
@@ -637,7 +637,7 @@ jobs:
     steps:
       # actions/checkout v4.3.1
       - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262
-      - name: the base commit, for the ratchet
+      - name: the base commit, for the no-loss rule
         uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262
         continue-on-error: true
         with:
@@ -1191,24 +1191,24 @@ function workflowStructure(document) {
     return out;
   }
 
-  // The ratchet's own two inputs, from slice L2 stage two.
+  // The no-loss rule's own two inputs, from slice L2 stage two.
   //
   // Without them the check still runs, still prints a report, and still goes
-  // green — and the ratchet never runs at all. That is the same class of hole
+  // green — and the no-loss rule never runs at all. That is the same class of hole
   // the batch 16 reviewer found nine ways (finding S2-1): a workflow that
   // silences the job while the part still reads "filled". Deleting two flags
   // is the cheapest version of it, so the scanner reads the flags, not just
   // the path.
   for (const flag of ['--base', '--base-sha']) {
     if (!new RegExp(`${flag}(?:[ \t=]|$)`, 'm').test(found.runs)) {
-      out.push(`the check step does not pass ${flag}, so the ratchet never runs and a pull request can take a part away with the job still green`);
+      out.push(`the check step does not pass ${flag}, so the no-loss rule never runs and a pull request can take a part away with the job still green`);
     }
   }
   // And the tree it compares against has to be fetched by something.
   const fetchesBase = Object.values(jobs).some((job) => (Array.isArray(job?.steps) ? job.steps : [])
     .some((step) => typeof step?.uses === 'string' && step.uses.startsWith('actions/checkout') && step?.with?.path === BASE_DIR));
   if (!fetchesBase) {
-    out.push(`no step checks the base commit out into ${BASE_DIR}, so the ratchet has no tree to compare against`);
+    out.push(`no step checks the base commit out into ${BASE_DIR}, so the no-loss rule has no tree to compare against`);
   }
 
   // A condition switches the step, or its whole job, off. Same effect as a
@@ -1216,7 +1216,7 @@ function workflowStructure(document) {
   if (found.step.if !== undefined) out.push('the workflow puts an if: on the check step; the step must always run');
   if (found.job.if !== undefined) out.push("the workflow puts an if: on the check's job; the job must always run");
   // Two more ways to make a red check look green. Neither is in the frozen
-  // list. Both defeat the same purpose, and stage two's ratchet needs a red job
+  // list. Both defeat the same purpose, and stage two's no-loss rule needs a red job
   // to mean something, so the check names them (reviewer of batch 16, S2-1).
   if (found.step['continue-on-error'] === true || found.job['continue-on-error'] === true) {
     out.push('the workflow sets continue-on-error on the check; a failed check would not turn the job red');
@@ -1259,7 +1259,7 @@ function checkWorkflow(context, part) {
 // works for any copy; importing it would only work for this one.
 //
 // A copy from before row F11 carries no CHECK_VERSION. When it declares a spec,
-// it still reads as the Atlas check, so the ratchet can score a base tree that
+// it still reads as the Atlas check, so the no-loss rule can score a base tree that
 // holds an old copy.
 export function checkStamps(text) {
   const check = /^export const CHECK_VERSION = (\d+);/m.exec(text ?? '');
@@ -1386,7 +1386,7 @@ export function readFacts(root) {
   } catch (error) { return { facts: null, error: `atlas.yaml cannot be read: ${error.message}` }; }
 }
 
-// `scoreAs` is the ratchet's one lever. It replaces the kind and the spec this
+// `scoreAs` is the no-loss rule's one lever. It replaces the kind and the spec this
 // tree declares with the ones handed in, so two trees are scored by the same
 // yardstick. Without it the base's `kind: service` and the head's
 // `kind: library` would be two different spec tables, and the comparison would
@@ -1456,17 +1456,17 @@ export function counts(files) {
 }
 
 // ---------------------------------------------------------------------------
-// The ratchet. Milestone M2, slice L2 stage two.
+// The no-loss rule. Milestone M2, slice L2 stage two.
 //
 // What it is. A pull request may not take away an instruction-class part that
 // the base commit already had. Nothing else. It is never red on debt that was
 // there before, and it is red on the pull request that made things worse.
 //
-// Why a ratchet and not a level. Turning `fail-on` up to `required` goes red on
+// Why a no-loss rule and not a level. Turning `fail-on` up to `required` goes red on
 // the day it is switched on, for parts a later slice builds. The first repo it
 // ran on had seven required parts not filled, four of them a later slice's
 // work. A level
-// asks the repository to be finished. A ratchet asks it not to go backwards.
+// asks the repository to be finished. A no-loss rule asks it not to go backwards.
 //
 // Why per part and never a count. A count is defeated two ways. Empty one part,
 // fill another, and the total does not move. Or change one line: `atlas.yaml`
@@ -1485,9 +1485,9 @@ export function counts(files) {
 // Where it lives. Here. The repository still carries two files and only two.
 // ---------------------------------------------------------------------------
 
-// The five cases where the ratchet reports and does not gate. Each is named in
+// The five cases where the no-loss rule reports and does not gate. Each is named in
 // the report, so a reader never has to guess why the job stayed green.
-export const RATCHET_CASES = Object.freeze(['check-file', 'workflow', 'kind', 'spec', 'base-tree']);
+export const NO_LOSS_CASES = Object.freeze(['check-file', 'workflow', 'kind', 'spec', 'base-tree']);
 
 const fileHash = (root, path) => { const text = readText(root, path); return text === null ? null : sha256(text); };
 
@@ -1517,7 +1517,7 @@ const partIndex = (report) => {
   return map;
 };
 
-export function ratchet({ headRoot, baseRoot, baseSha = null, repoId = null, secretPatterns: patterns = secretPatterns() }) {
+export function noLoss({ headRoot, baseRoot, baseSha = null, repoId = null, secretPatterns: patterns = secretPatterns() }) {
   const out = {
     ran: true,
     gates: true,
@@ -1639,15 +1639,15 @@ export function toText(report) {
     lines.push(`   ${row.exists ? '+' : '-'} ${row.path}  <- ${row.pointed_at_by.join(', ') || 'the entry map only'}${row.exempt ? '  [exempt]' : ''}`);
     if (row.exempt_note) lines.push(`       - ${row.exempt_note}`);
   }
-  if (report.ratchet) lines.push('', ...ratchetLines(report.ratchet));
+  if (report.noLoss) lines.push('', ...noLossLines(report.noLoss));
   return `${lines.join('\n')}\n`;
 }
 
-// The ratchet, in the CI log. It says which tree it compared against, what it
+// The no-loss rule, in the CI log. It says which tree it compared against, what it
 // compared, and either the parts that went backwards or the case that made it
 // report instead of gate.
-export function ratchetLines(state) {
-  const out = ['Ratchet: instruction-class parts, base to head.'];
+export function noLossLines(state) {
+  const out = ['No-loss rule: instruction-class parts, base to head.'];
   // The sha this check READ from the base tree, never the one it was handed.
   // Printing the promise would assert a commit nothing verified.
   const read = state.base_head ? state.base_head.slice(0, 12) : 'a commit the tree does not name';
@@ -1662,7 +1662,7 @@ export function ratchetLines(state) {
   }
   if (!state.regressions.length && state.base_facts) out.push('   no instruction-class part went backwards');
   if (!state.gates) {
-    out.push('   this ratchet reports and does not gate on this pull request');
+    out.push('   this no-loss rule reports and does not gate on this pull request');
     // The loudest line in the report, and the one a reader must not miss. The
     // frozen text excuses these five cases because a person merges every file
     // that causes one. That is a compensating control, not an absence of
@@ -1696,9 +1696,9 @@ export function toMarkdown(report) {
     }
     out.push('');
   }
-  if (report.ratchet) {
-    out.push('### Ratchet', '');
-    for (const line of ratchetLines(report.ratchet).slice(1)) out.push(`- ${line.trim()}`);
+  if (report.noLoss) {
+    out.push('### The no-loss rule', '');
+    for (const line of noLossLines(report.noLoss).slice(1)) out.push(`- ${line.trim()}`);
     out.push('');
   }
   return `${out.join('\n')}\n`;
@@ -1710,11 +1710,11 @@ export function toMarkdown(report) {
 // count. It keeps its three levels and it stays a report line at the shipped
 // level.
 //
-// The ratchet answers "did this pull request take something away?" It is the
+// The no-loss rule answers "did this pull request take something away?" It is the
 // one that can be true on a repository with debt, so it is checked first.
 export function verdict(report, failOn) {
   if (report.errors.length) return { green: false, why: `the check hit ${report.errors.length} error(s)` };
-  const state = report.ratchet;
+  const state = report.noLoss;
   if (state?.gates && state.regressions.length) {
     return { green: false, why: `${state.regressions.length} instruction-class part(s) went backwards against the base: ${state.regressions.map((row) => row.label).join(', ')}` };
   }
@@ -1723,8 +1723,8 @@ export function verdict(report, failOn) {
   const excused = state && !state.gates && state.regressions.length
     ? ` — WARNING: ${state.regressions.length} part(s) went backwards and were NOT gated; a person merges this one`
     : '';
-  const ratchetWhy = state ? (state.gates ? '; no instruction-class part went backwards' : `; the ratchet reported and did not gate (${state.report_only.map((row) => row.case).join(', ')})${excused}`) : '';
-  return { green: true, why: `${report.counts.required_not_filled} required file(s) are not filled; fail-on is "${failOn}"${ratchetWhy}` };
+  const noLossWhy = state ? (state.gates ? '; no instruction-class part went backwards' : `; the no-loss rule reported and did not gate (${state.report_only.map((row) => row.case).join(', ')})${excused}`) : '';
+  return { green: true, why: `${report.counts.required_not_filled} required file(s) are not filled; fail-on is "${failOn}"${noLossWhy}` };
 }
 
 // ---------------------------------------------------------------------------
@@ -1744,7 +1744,7 @@ export function parseArguments(argv) {
     else if (flag === '--json') out.json = resolve(next());
     else if (flag === '--summary') out.summary = resolve(next());
     else if (flag === '--quiet') out.quiet = true;
-    // The ratchet's two inputs. `--base` is the directory the workflow checked
+    // The no-loss rule's two inputs. `--base` is the directory the workflow checked
     // the base commit out into. `--base-sha` is the pull request's base.sha, so
     // the check can say the tree it reads is the tree it was promised.
     else if (flag === '--base') out.base = resolve(next());
@@ -1763,10 +1763,10 @@ export function run(argv, env = process.env) {
   const patterns = secretPatterns();
   const report = scan({ root: options.root, repoId, extractors: EXTRACTORS, secretPatterns: patterns });
   // No `--base` means no pull request to measure: a push build, or a run by
-  // hand. The ratchet then does not run at all, and the report says nothing
+  // hand. The no-loss rule then does not run at all, and the report says nothing
   // about it rather than claiming a pass.
-  report.ratchet = options.base
-    ? ratchet({ headRoot: options.root, baseRoot: options.base, baseSha: options.baseSha, repoId, secretPatterns: patterns })
+  report.noLoss = options.base
+    ? noLoss({ headRoot: options.root, baseRoot: options.base, baseSha: options.baseSha, repoId, secretPatterns: patterns })
     : null;
   const decision = verdict(report, options.failOn);
   const text = toText(report);

package/shape/releases.json

@@ -10,6 +10,11 @@
       "check_version": 2,
       "sha256": "a4bc5ab8c75be8f216d460df9233670f5ba4ed9d853236f6b55a7f0d10dfe293",
       "first_package": "0.2.0"
+    },
+    {
+      "check_version": 3,
+      "sha256": "0184db66fd5d5061c21ee7d2d88395b5bac64ab1308e02e06781e6015f3d7608",
+      "first_package": "0.3.0"
     }
   ]
 }

package/skills/feedback/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: feedback
+description: >
+  File a report about Atlas, or about a product, as an issue in the right public repo.
+  Trigger when someone says "Atlas should …", "report this", "file an issue", or asks for a
+  feature or a fix that is not a correction of the work in this session. It searches open
+  issues first and files nothing until the person says "file it".
+---
+
+# Feedback
+
+This skill is for people who run Atlas, and for the owner when a report
+is not a correction of the current work. A correction of the current work
+goes to the `atlas:learnings` skill instead.
+
+## Steps
+
+1. **Find the issue repo.** Read it from the product record: the Atlas
+   tools return it with the product. For a report about Atlas itself, the
+   issue repo is the Atlas repo. If no issue repo is known, ask for it.
+2. **Search open issues first.** Use `gh issue list --repo <repo>
+   --state open --search "<key words>"`. Try two or three short searches.
+3. **Show what you found.** If an open issue matches, show its title and
+   link. Offer to add the new detail to it as a comment.
+4. **Draft the issue.** Write a title and a short body: what happens, what
+   should happen, and the steps to see it. Write in plain words.
+5. **Run the privacy filter.** Write the draft to a scratch file, and run
+   `atlas ste --share <file>`. Remove each `privacy:` finding by hand.
+6. **Show the draft, and wait.** File nothing until the person says
+   "file it", or the same in their own words.
+7. **File it once.** Use `gh issue create --repo <repo> --title <title>
+   --body-file <file>`. Give the person the link.
+
+## Rules
+
+1. Never file in a public repo without the person's word for that issue.
+2. Never put a private name, a path on someone's machine, a secret or an
+   email address in an issue.
+3. One report is one issue. Split a report that holds two asks.

package/skills/lead/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: lead
+description: >
+  The Atlas lead. Follow it in every session in a repo that runs Atlas, from the first
+  reply: how to talk with the owner, which skill or crew takes which ask, who writes to
+  the tracker, what to do after a correction, where Atlas may work in the repo, and when
+  to call each atlas command. The repo's entry file says to follow it.
+---
+
+# The lead
+
+You are the lead in this session. You talk with the owner, you route each
+ask, and you keep the rules below. Other Atlas skills hold the steps of
+each flow. This skill holds the rules that apply in every flow.
+
+## 1. The talk rules
+
+Follow all eleven in every reply, page and question.
+
+1. Ask one question at a time. Give the options on short lines, and mark
+   the one you recommend.
+2. Give a page first, with a worked example: the input, the process and
+   the output. Chat stays short and links the page.
+3. Use plain words and plain names.
+4. Search past answers before you ask a question. The tracker, the
+   register and the repo's records hold them.
+5. Lead a check-in with what the owner must do. If nothing, say so.
+6. Push back, and suggest a better way. Never echo the owner's words back
+   as the plan.
+7. Treat a shared example or an old approach as evidence. Say what you
+   keep, what you change and what you reject, and why.
+8. Never use a code or a stage number without a key on the same page.
+9. Link every explainer page from the document it explains.
+10. Pick the form that is easiest to understand. Put a diagram before
+    prose, and a page before long chat text. Where motion explains a
+    sequence, animate the diagram in the page.
+11. Write in ASD-STE100. Run `atlas ste` on each page before you publish
+    it, and fix what it flags by hand. Quoted words are exempt.
+
+Before a page or an issue goes to anyone other than the owner, run
+`atlas ste --share` on it. That adds the privacy filter. It reads the
+owner's private terms from `~/.config/atlas/private-terms.txt` when that
+file exists. A page that the owner shares on their own is not checked, so
+say that when you hand over a page.
+
+## 2. Routing
+
+| The ask | Who takes it |
+|---|---|
+| New work, a pause, a resume, a status, a lock, a delivery | The `atlas:sdlc-task` skill |
+| Add, change or take over a procedure or a repo skill | The `atlas:repo-skills` skill |
+| The owner corrects the work, a revert, a bug found after a merge | The `atlas:learnings` skill |
+| A report about Atlas or a product that is not a correction of this work | The `atlas:feedback` skill |
+| Find code, map a module, find where to edit | The `atlas:code-explorer` crew |
+| Where a capability stands in the code | The `atlas:capability-reader` crew |
+| Review a design or a diff | The three reviewer crews, as sdlc-task says |
+| Prove a pull request against its definition of done | The `atlas:verifier` crew |
+| Render a page for the owner | The `atlas:artifact-renderer` crew |
+
+A crew reads and reports. It never holds the Atlas tools.
+
+## 3. The tracker rule
+
+1. Only the lead writes to the tracker, through the Atlas tools. A crew
+   never writes to it.
+2. Three acts stay with the owner: a lock, the approval of a definition
+   of done, and a decision. Record each one with the owner's own words.
+   Never record one on your own judgment.
+3. A change after the owner approved a design is a new decision on the
+   same item, with the owner's words. The design file names the change.
+
+## 4. The learnings rule
+
+When the owner corrects the work, run the `atlas:learnings` skill before
+the turn ends. Do not wait for a second miss.
+
+## 5. The area rule
+
+1. A repo's entry file can list areas. Then run Atlas flows only in a
+   listed area. Outside them, say that the area is not listed, and stop.
+2. Some areas hold outside text, such as email. A session must hold no
+   tool that reads that outside text until Atlas has its outside-text
+   reader. If the session holds such a tool, stop and say so.
+3. Until then, work in such an area uses made-up test data only.
+
+## 6. The atlas command
+
+Call each command at the point named here. `atlas help` lists the same
+set. A test keeps the two lists equal.
+
+| Command | When to call it |
+|---|---|
+| `atlas install` | Once on a new Mac, when the owner asks for Atlas there |
+| `atlas upgrade` | When the owner gives the word for a new release |
+| `atlas doctor` | When Atlas seems missing or broken in a session |
+| `atlas check` | Before you ask for a merge in a repo that has the shape check |
+| `atlas status` | To learn whether a repo's check is current or behind |
+| `atlas tooling` | When `atlas status` says behind; `pr` opens the pull request |
+| `atlas kind-drift` | When the repo record and `atlas.yaml` may disagree on the kind; this command retires in stage 2, the onboarding stage |
+| `atlas code-read` | To resolve the citations of a code digest |
+| `atlas ste` | Before each publish; `--share` before a page goes to anyone else |
+
+A person merges every file that `atlas tooling` writes.

package/skills/learnings/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: learnings
+description: >
+  Turn a miss into one lasting fix. Trigger when the owner corrects the work ("no, do it
+  this way", "that was wrong"), when a change is reverted, or when a bug is found after a
+  merge. The lead runs it before the turn ends. It picks one home for the lesson, this repo
+  or Atlas, and the strongest form that fits.
+---
+
+# Learnings
+
+Every miss teaches one thing. This skill finds it, puts it in one home,
+and makes it hard to miss again.
+
+## Triggers
+
+1. The owner corrects the work.
+2. A change is reverted.
+3. A bug is found after a merge.
+
+## Steps
+
+1. **Name the lesson** in one plain sentence. Say what went wrong and
+   what is right.
+2. **Pick one home.**
+   - The lesson holds only for this repo: it becomes a change here.
+   - The lesson holds for every repo: it becomes an Atlas item.
+3. **For an Atlas lesson,** propose an item in the Atlas tracker, with
+   the Atlas tools. Put the owner's words in it, word for word. Tag it
+   `learning`. Link it to the repo where the miss happened. Tell the owner
+   the item and that an Atlas release, on their word, closes it.
+4. **Pick the strongest form that fits,** in this order:
+   1. a check that fails when the miss happens again;
+   2. a tool that makes the right way the easy way;
+   3. a skill step;
+   4. a line in a doc, with a short note.
+5. **Prune.** A new rule retires or merges each rule it replaces. Name
+   the rules you removed in the pull request.
+6. **Make the change** in its home, through the normal flow.
+
+## Rules
+
+1. A fix paraphrases the owner's words. It never copies them into the
+   Atlas package, because the package is public. The tracker item keeps
+   the words.
+2. A lesson about one repo's product stays in that repo. It never goes
+   into an Atlas release.
+3. One lesson is one fix. Do not batch unrelated lessons.

package/skills/repo-skills/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: repo-skills
+description: >
+  Add, change or take over a procedure or a skill that belongs to one repo. Trigger when
+  the owner asks to "add a procedure", "write a skill for", "document how to run, test,
+  build or deploy" something in this repo, or when a skill or procedure here is stale. It
+  maps what exists first and extends it; it never adds a second copy.
+---
+
+# Repo skills
+
+A repo keeps its own facts and procedures. Atlas keeps the roles that
+follow them. This skill adds or changes a procedure the right way.
+
+A procedure can be a section of a README, a doc, or a skill file. Pick
+the form the repo already uses for that kind of thing.
+
+## Steps
+
+1. **Map what exists.** Send the `atlas:code-explorer` crew to find each
+   README section, doc and skill near the ask. Ask it for paths and
+   lines.
+2. **Extend what covers the ask.** If a section or a skill already holds
+   part of it, change that one. Never add a second one. If two near-copies
+   exist, merge them and say so.
+3. **Decide the type.** A task says how to do a thing: run, test, build,
+   deploy. A rule says how to judge a change. They have different approval
+   rules, so split a skill that holds both.
+4. **Write the header Atlas reads,** for a skill file. It names the type,
+   the commands and files, and the code it covers. It says how CI runs
+   it, if CI can.
+5. **Keep it to this repo.** A step that holds how to work in general
+   belongs in Atlas. Do not put it here. Propose it to Atlas with the
+   `atlas:feedback` skill.
+6. **Follow the repo's own rules.** Read its entry file first. Some repos
+   ask for one area folder for each change, or a status file updated
+   when the state changes. Keep to them.
+7. **Prove the steps once.** Ask the `atlas:verifier` crew to run them in
+   a fresh worktree, before you ask for the merge.
+8. **Write the pull request text.** Say what you found, what you kept,
+   and the gap you closed.
+
+## The header of a skill file
+
+```yaml
+---
+name: <short name>
+description: <when to use it, in one or two sentences>
+type: task            # or rule
+names:                # each command and file the steps name
+  - <command or path>
+covers:               # the code this skill describes
+  - <path>
+ci: <how CI runs it, or "cannot run in CI">
+---
+```
+
+## What not to do
+
+1. Do not add a procedure file next to a README section that already
+   covers the ask.
+2. Do not copy a general how-to from Atlas into the repo.
+3. Do not list a procedure in a repo facts file that the repo does not
+   have. The onboarding flow lists it later.

package/skills/sdlc-task/SKILL.md

@@ -38,21 +38,19 @@ checks and the transition log; each verb's own description says what it needs.
 | Mark it delivered, or reopen it | `item_done`, `item_reopen` |
 | Say where things stand | `where_are_we`, `in_flight`, `needs_me` |
 
-The repo's own facts come from `atlas.yaml` and `atlas/`. Its `kind` (`service`,
-`library`, `schema`) decides which procedures it has and what "delivered" means.
-Read it. Never assume a deployed service.
+The repo's own facts come from `atlas.yaml` and `atlas/`. Its kinds (`service`,
+`library`, `schema`, `cli`, `plugin`) decide which procedures it has and what
+"delivered" means. Read them. Never assume a deployed service.
 
-A change to the process itself is not a task. It is an amendment to the
-frozen text, and the rule for one is short:
+How to talk with the owner lives in the `atlas:lead` skill: one question at a
+time, a page first with a worked example, plain words, push back. This skill
+does not repeat those rules; follow the lead.
 
-1. Say so at once. Never build against a sentence you know is wrong.
-2. Write the amendment as its own dated file: what changes, why, the new
-   frozen text in full, one new hash over the whole frozen section, and the old
-   hash named as retired.
-3. Never edit frozen text in place. A reviewer's finding is a normal reason to
-   amend.
-
-(Source: the Atlas lock procedure, amendment A1.6, section 12.)
+**A change after the owner approved a design** is not a new lock. Say so at
+once, and never build against a sentence you know is wrong. Show the owner the
+change in one screen. When the owner approves it, record the owner's words with
+`decision_record` on the same item, and write the change into the design file
+with the date. (Target design, flow 4: long frozen texts with hashes retire.)
 
 ## start
 
@@ -70,73 +68,62 @@ frozen text, and the rule for one is short:
    [`templates/design-doc.md`](templates/design-doc.md) to
    `docs/design-docs/<slug>.md`, fill Context and goal, and list it in
    `docs/index.md` in the commit that first lands it. Hotfix tier skips the
-   doc: the acceptance criteria live on the work item, and a resume anchor
+   doc: the definition of done lives on the work item, and a resume anchor
    covers pauses.
 5. Enter the design loop.
 
 ## The design loop (between start and lock)
 
-- **One voice.** The owner talks to one colleague. Crews run behind the
-  curtain as subagents and come back as digests — never as a committee
-  surfacing question lists.
-- **Guided elicitation** (the owner's words: *"one on one
-  conversation that flows… the purpose of agent is to do research and guide my
-  thoughts into useful features"*). Research first, then **one pointed question
-  at a time**, with a recommendation (the owner: *"Questions if posed
-  should be one by one. Just think, if you say 5 things in one go, how do I
-  respond."*). Keep the question queue in the design doc; surface only the
-  next one. Record each question with `question_ask` and each answer with
-  `question_answer`.
-- **Succinct chat; artifacts carry the content** (the owner's words:
-  *"the content is very verbose… I won't read that much"* · *"artefacts should
-  be the default method of communication… use as many diagrams and examples as
-  possible"*). Chat is a few short sentences: the outcome, the artifact link,
-  the one question.
-- **Lead with a worked example.** Real input, real process, real output, and a
-  sequence diagram where order matters. The owner cannot read dense prose.
-- **Read the reason, not only the rule.** Before you build to a done line, read
-  the owner's words behind it and ask whether the thing should exist at all. A
-  done line is a measure, not the goal.
+Talk to the owner by the `atlas:lead` skill. What this loop adds:
+
 - **Research before opinions.** Fan out `atlas:code-explorer` for how the system
-  works today. Raw exploration never enters this session — digests only.
+  works today. Raw exploration never enters this session; digests only.
+- **Read the reason, not only the rule.** Before you build to a definition of
+  done, read the owner's words behind it and ask whether the thing should exist
+  at all.
 - **When the task is a cluster of filed bugs, first ask whether the model
   they presume was ever decided.** A bug report says the code surprised
   someone; it does not say what the code should do.
+- **User stories before the definition of done.** Never write checks for a
+  flow no story walks through.
 - **The doc accretes in real time.** Every resolved question, decision and
-  approach lands in the design doc as it happens. The doc is the pause and
-  resume state. Record each decision with `decision_record`.
-- **HTML is the owner's reading surface.** Any design, review or status the
-  owner reads is a styled artifact, rendered by the `atlas:artifact-renderer`
-  crew. Its treatment contract lives in that crew; do not restate it.
-- **No bare acronyms in front of the owner.** Spell a thing out on first
-  mention. Ids are for the machine; names are for the human.
-- **User stories before acceptance criteria** (the owner's words:
-  *"I need to see how a user would use the product, or like how the flow
-  works"*). Never draft criteria for a flow no story walks through.
-- **Adversarial review before lock.** Standard tier: at least one persona.
-  Initiative: the panel — `atlas:reviewer-pm`, `atlas:reviewer-architect`,
-  `atlas:reviewer-security` — each briefed with the doc path, in parallel. Brief each
-  one to ask whether the design is the right thing, not only whether it is
-  consistent. An unresolved finding goes into the doc's open questions, and
-  that blocks the lock.
+  approach lands in the design doc as it happens. Record each question with
+  `question_ask`, each answer with `question_answer`, each decision with
+  `decision_record`.
+- **Adversarial review before the owner approves.** Standard tier: at least one
+  persona. Initiative: the panel, `atlas:reviewer-pm`, `atlas:reviewer-architect`
+  and `atlas:reviewer-security`, each briefed with the doc path, in parallel.
+  Brief each one to ask whether the design is the right thing. An unresolved
+  finding goes into the doc's open questions.
 
 ## lock
 
-Gate on `lifecycle.yaml` `lock.preconditions`, all four: the open questions
-are empty, the owner ratified the criteria, the approach is chosen, the tier
-is confirmed. Then:
-
-1. Stamp the design doc's lock block: date, ratifier, tier, the sha256 of the
-   acceptance criteria text, frozen interfaces, the work list. Commit.
-2. Call `item_lock` with the frozen scope and its hash.
-3. Build against the frozen text. **Tripwires** (`lifecycle.yaml`
-   `tripwires`): a discovery after lock that touches the criteria, security,
-   a schema or cost stops the build and goes back to the owner. If the frozen
-   text is wrong, say so at once and write an amendment. Never build against a
-   sentence you know is wrong.
-4. Test with the repo's own `test` procedure, which `atlas.yaml` names. Open a
-   pull request. Keep a separate acceptance reviewer, and close its findings
-   before acceptance.
+A lock is the owner's approval of a short design (target design, flow 4).
+
+1. **The design is short and sized to the work.** A feature gets a full
+   document; a small fix gets a one-screen card. It holds what
+   `lifecycle.yaml` `lock.holds` lists: the definition of done, written as checks; the kind of change, its impact and its undo; and
+   each existing test it expects to change. A change that cannot be undone
+   shows in bold at the top.
+2. **The owner approves it in the owner's own words.** Gate on
+   `lifecycle.yaml` `lock.preconditions`. Record the words with
+   `decision_record`, and mark the design doc "Approved <date>", with the words.
+3. Call `item_lock` with the definition of done as `scope.text` and the design
+   file as `scope.design_doc`. The verb keeps a fingerprint of that text for
+   the tools. No person reads or writes a hash, and no frozen text is copied
+   into the doc.
+4. Build against the approved design. **Tripwires** (`lifecycle.yaml`
+   `tripwires`): a discovery that touches the definition of done, security, a
+   schema or cost stops the build and goes back to the owner, as a change after
+   approval (above).
+5. Test with the repo's own `test` procedure, which `atlas.yaml` names. Open a
+   pull request. Its text holds the definition of done, the kind of change, the
+   undo, and the list of existing tests it changes or removes, and it links the
+   tracker item.
+6. **Proof before the merge.** Run the `atlas:verifier` agent on the pull
+   request. It proves each line of the definition of done from a fresh run and
+   posts its own proof comment. Never edit that comment. Ask the owner for the
+   merge only after the proof is there, and show the proof first.
 
 ## pause