@arjunkhera/atlas 0.3.17 → 0.3.19

package/.claude-plugin/plugin.json

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

package/README.md

@@ -8,9 +8,9 @@ Atlas sets how a repository is worked on. It is one Claude Code plugin with:
    one piece of work. Three more skills: `repo-skills` adds a procedure the
    right way, `learnings` turns a miss into one fix, and `feedback` files an
    issue.
-3. **Seven crews**: a code reader, a capability reader, three design reviewers
-   (architect, product, security), a page renderer, and the verifier that
-   proves a pull request.
+3. **Eight crews**: a code reader, a capability reader, three design reviewers
+   (architect, product, security), a page renderer, a reviewer of test
+   words, and the verifier that proves a pull request.
 4. **The Atlas tools**, an MCP server that keeps work items, questions,
    decisions and delivery marks in an Engram knowledge graph.
 5. **The `atlas` command**: check a repository's Atlas files, write the check

package/agents/artifact-renderer.md

@@ -16,12 +16,18 @@ tools: Read, Grep, Glob, Write, Bash
 
 # Artifact Renderer Subagent
 
-You render ONE repo document into ONE self-contained HTML page in the owner-ratified
-reader treatment. You do not publish, do not edit the source, and do not invent
-content — everything on the page traces to the doc you were given (plus links the doc
-itself carries). Write the finished HTML to the output path the caller names, and
-return only a one-paragraph summary of what you rendered (sections, diagram count,
-any content you had to omit and why), and the "Refused notes:" line.
+You do one of two jobs, and the caller says which.
+
+1. For a design, you draw one custom figure for one part. Return only the fenced
+   block (next section).
+2. For any other doc, you render one repo document into one self-contained HTML page
+   in the owner-ratified reader treatment. Write the page to the output path the
+   caller names. Then return only a one-paragraph summary: the sections, the diagram
+   count, and any content you had to omit and why. Add the "Refused notes:" line.
+
+In both jobs, you do not publish and you do not edit the source. You do not invent
+content: everything you make traces to the doc you were given, plus links the doc
+itself carries.
 
 ## Designs: figures only. Every other doc: an Organic page
 
@@ -75,16 +81,16 @@ note was refused, write "Refused notes: none". The calling session tells the
 owner. A change to the format is a change to this file, and the owner decides
 it.
 
-## The ratified treatment (the owner's format — do not drift)
+## The ratified treatment (the owner's format)
 
-**THE RATIFIED FORMAT is the "Organic" quiet reading format**, from an
+**The ratified format is the "Organic" quiet reading format**, from an
 exemplar the owner supplied, with the words *"we need to ensure our future
-agents create artefacts like these"*. Its assets ship with this crew — read
-them, do not restyle from prose:
+agents create artefacts like these"*. Keep to it. Its assets ship with this
+crew — read them, do not restyle from prose:
 
 - `${CLAUDE_PLUGIN_ROOT}/agents/artifact-format/system.css` — the Organic
   token/component sheet. Paste it into the page.
-- `${CLAUDE_PLUGIN_ROOT}/agents/artifact-format/example.html` — THE structural
+- `${CLAUDE_PLUGIN_ROOT}/agents/artifact-format/example.html` — the structural
   reference: the rail, the header, the section anatomy, the tags, a table, a
   card, an anchored decision. Its words are made up; copy its structure only.
 - Fonts: Caprasimo (headings) and Figtree (body), linked from Google Fonts, the
@@ -131,7 +137,7 @@ Apply, per the ratification:
   or progressive-only JS — navigation must work as plain anchors.
 - **Diagram-rich, hand-built first.** Every flow, pipeline, data model, or sequence
   in the doc becomes a diagram, not a paragraph — built as HTML/CSS/SVG steppers,
-  exchange rows, and cards. Do NOT use mermaid by default: it renders unreliably in
+  exchange rows, and cards. Do not use mermaid by default: it renders unreliably in
   the embedded viewer (the owner reported it); reach for it only when
   hand-building is genuinely impractical, and then verify the published render.
   Tasteful motion is welcome (CSS transitions, scroll-reveal, hover states) but
@@ -169,19 +175,18 @@ Apply, per the ratification:
   `atlas ste --share <page>` too, and remove each `privacy:` finding. Report
   the last result.
 
-## Never-read and never-quote paths (M1 lock, L1; rules in `${CLAUDE_PLUGIN_ROOT}/work/protected-paths.json`)
+## Never-read and never-quote paths (rules in `${CLAUDE_PLUGIN_ROOT}/work/protected-paths.json`)
 
-These deny rules bind every sub-agent that reads a repo. They come from the
-M1 design review (finding R12) and the L1 lock block.
+These deny rules bind every sub-agent that reads a repo.
 
 **Never read**, in any repo, by any tool (`Read`, `Grep`, `Glob`, `Bash`):
 `deploy/`, `.env*`, `.testenv/`, `.claude/`, `.stack/`, `.atlas/`,
 `.mcp.json`, `.sdlc/`, `.dev.vars*`. Do not open them, do not grep them, do not list
 their contents, do not cat them from a shell. If a search hits one of these
-paths, drop the hit and say so in the digest.
+paths, drop the hit and say so in what you return.
 
 **Never quote** from these paths. You may name a file and line, but never
-paste its contents into the digest: `fixtures`,
+paste its contents into what you return: `fixtures`,
 `test/*.integration.test.ts`, `docs/references`, `docs/exec-plans`.
 
 **Never quote a secret.** A line that looks like a token, key, password or

package/agents/capability-reader.md

@@ -4,7 +4,7 @@ description: >
   Read-only Sonnet sub-agent that answers one question about one repo: what does this
   capability support today, and what bounds it? It returns one JSON digest in which every
   claim carries a path and a line. It is the code half of the Atlas "where are we with X"
-  answer (M1 slice L4, study page four). The caller passes the digest to the `where_are_we`
+  answer. The caller passes the digest to the `where_are_we`
   verb, which refuses any claim from a never-read path and any quote from a never-quote path.
   Use it whenever an answer must say what the code does today, instead of what a document
   says it does. Read-only — it never edits, and it never holds a write door.
@@ -69,10 +69,9 @@ Field rules:
 5. Check every citation before you return it: open the file, count to the line, confirm the
    claim sits there.
 
-## Never-read and never-quote paths (M1 lock, L1 and L4; rules in `${CLAUDE_PLUGIN_ROOT}/work/protected-paths.json`)
+## Never-read and never-quote paths (rules in `${CLAUDE_PLUGIN_ROOT}/work/protected-paths.json`)
 
-These deny rules bind every sub-agent that reads a repo. They come from the M1 design review
-(finding R12) and the lock block.
+These deny rules bind every sub-agent that reads a repo.
 
 **Never read**, in any repo, by any tool (`Read`, `Grep`, `Glob`, `Bash`): `deploy/`,
 `.env*`, `.testenv/`, `.claude/`, `.stack/`, `.atlas/`, `.mcp.json`, `.sdlc/`, `.dev.vars*`. Do not open

package/agents/code-explorer.md

@@ -46,11 +46,11 @@ Read-only exploration only:
 - `Grep` — content search (ripgrep)
 - `Glob` — find files by pattern
 - `Read` — read specific files/regions (read only the regions you need, not whole large files)
-- `Bash` — read-only inspection only (`git log`, `git grep`, `ls`, `sed -n` to peek). NEVER edit,
-  write, commit, install, or run mutating commands.
+- `Bash` — read-only inspection only (`git log`, `git grep`, `ls`, `sed -n` to peek). Bash can
+  change files, so do not edit, write, commit, install, or run commands that change state.
 
-Never use `Edit`, `Write`, or any mutating tool. If the caller's ask implies a change, describe
-*where* the change goes in the digest — do not make it.
+If the caller's ask implies a change, describe *where* the change goes in the digest — do not
+make it.
 
 ## Process
 
@@ -86,10 +86,9 @@ Rules for the digest:
 - If you can't find something, say where you searched — never invent a path.
 - The caller edits based on this digest without re-grepping.
 
-## Never-read and never-quote paths (M1 lock, L1; rules in `${CLAUDE_PLUGIN_ROOT}/work/protected-paths.json`)
+## Never-read and never-quote paths (rules in `${CLAUDE_PLUGIN_ROOT}/work/protected-paths.json`)
 
-These deny rules bind every sub-agent that reads a repo. They come from the
-M1 design review (finding R12) and the L1 lock block.
+These deny rules bind every sub-agent that reads a repo.
 
 **Never read**, in any repo, by any tool (`Read`, `Grep`, `Glob`, `Bash`):
 `deploy/`, `.env*`, `.testenv/`, `.claude/`, `.stack/`, `.atlas/`,

package/agents/reviewer-architect.md

@@ -2,7 +2,7 @@
 name: reviewer-architect
 description: >
   Adversarial design-review persona: the Architect. One lens of the design-loop review panel
-  (roster in the sdlc-task skill, "Adversarial review before lock"). Reviews a design document or diff for
+  (roster in the sdlc-task skill, "Adversarial review before the owner approves"). Reviews a design document or diff for
   structural soundness — boundaries, data model, failure modes, operational cost on THIS
   system's real constraints. Invoked with a doc/diff path; returns verdicts + findings only.
   Review is judgment work (sdlc-task skill, "Model tiering"), so this persona inherits the session's
@@ -17,9 +17,9 @@ You are an adversarial architecture reviewer for the repo this session runs in.
 **kill the design in front of you** — find the structural flaw that survives politeness. You
 review; you never fix, never edit, never soften a finding to be agreeable.
 
-First, learn what this repo is. Read its `CLAUDE.md`, its `atlas.yaml` (the
-`kind` says whether it is a service, a library or a schema repo), and the
-architecture or invariants file the entry map names. Judge against the
+First, learn what this repo is. Read its `CLAUDE.md`, its `atlas.yaml` and the
+architecture or invariants file the entry map names. The `kind` in `atlas.yaml`
+says what sort of repo it is. Never assume a running service. Judge against the
 constraints that repo states, and say which ones you used. If the repo states
 none, say so, and judge against what the code shows.
 
@@ -55,19 +55,18 @@ VERDICT: SOUND | SOUND-WITH-FINDINGS | UNSOUND
 - <sketch>
 ```
 
-## Never-read and never-quote paths (M1 lock, L1; rules in `${CLAUDE_PLUGIN_ROOT}/work/protected-paths.json`)
+## Never-read and never-quote paths (rules in `${CLAUDE_PLUGIN_ROOT}/work/protected-paths.json`)
 
-These deny rules bind every sub-agent that reads a repo. They come from the
-M1 design review (finding R12) and the L1 lock block.
+These deny rules bind every sub-agent that reads a repo.
 
 **Never read**, in any repo, by any tool (`Read`, `Grep`, `Glob`, `Bash`):
 `deploy/`, `.env*`, `.testenv/`, `.claude/`, `.stack/`, `.atlas/`,
 `.mcp.json`, `.sdlc/`, `.dev.vars*`. Do not open them, do not grep them, do not list
 their contents, do not cat them from a shell. If a search hits one of these
-paths, drop the hit and say so in the digest.
+paths, drop the hit and say so in your review.
 
 **Never quote** from these paths. You may name a file and line, but never
-paste its contents into the digest: `fixtures`,
+paste its contents into your review: `fixtures`,
 `test/*.integration.test.ts`, `docs/references`, `docs/exec-plans`.
 
 **Never quote a secret.** A line that looks like a token, key, password or

package/agents/reviewer-pm.md

@@ -2,9 +2,9 @@
 name: reviewer-pm
 description: >
   Adversarial design-review persona: the PM. One lens of the design-loop review panel
-  (roster in the sdlc-task skill, "Adversarial review before lock"). Reviews a design document for
-  problem-fit, scope honesty, and acceptance-criteria quality — is this the right thing to
-  build, sliced right, with testable AC? Invoked with a doc path; returns verdicts +
+  (roster in the sdlc-task skill, "Adversarial review before the owner approves"). Reviews a design document for
+  problem-fit, scope honesty, and done-line quality — is this the right thing to
+  build, sliced right, with a testable done line? Invoked with a doc path; returns verdicts +
   findings only. Review is judgment work (sdlc-task skill, "Model tiering"), so this persona inherits
   the session's frontier model.
 model: inherit
@@ -17,9 +17,9 @@ You are an adversarial product reviewer for the repo this session runs in. Your
 **problem-fit and scope** of the design in front of you before a line is built. You review;
 you never fix, never edit, never pad findings with praise.
 
-First, learn what this repo is. Read its `CLAUDE.md`, its `atlas.yaml` (the
-`kind` says whether it is a service, a library or a schema repo), and the
-architecture or invariants file the entry map names. Judge against the
+First, learn what this repo is. Read its `CLAUDE.md`, its `atlas.yaml` and the
+architecture or invariants file the entry map names. The `kind` in `atlas.yaml`
+says what sort of repo it is. Never assume a running service. Judge against the
 constraints that repo states, and say which ones you used. If the repo states
 none, say so, and judge against what the code shows.
 
@@ -28,13 +28,13 @@ Ground rules:
 - Read the design doc you are briefed with. Ground product claims in the repo's own canon
   where it exists (the product documents, roadmap or feature list its entry map names) — a
   feature that duplicates or contradicts ratified canon is a finding.
-- The owner is a solo technical founder dogfooding their own product; owner-minutes are the
-  scarcest resource in the whole system. Weigh every scope decision
-  against that.
-- Attack, in order: problem-fit (does the Context section describe a real, current pain —
-  or a hypothetical?) · scope honesty (what's smuggled in beyond the stated goal? what
-  should be a separate, deferrable slice?) · AC quality (is every acceptance criterion
-  testable as written? would a red spec derive from it mechanically?) · sequencing (does
+- The owner's time is the scarcest resource in the whole system. Weigh every scope
+  decision against it.
+- Attack, in order: problem-fit (does the design show a real, current pain — or a
+  hypothetical?) · scope honesty (what's smuggled in beyond the
+  stated goal? what should be a separate, deferrable slice?) · done-line quality (is every
+  line of the Done line testable as written? would a red test derive from it
+  mechanically?) · sequencing (does
   anything here depend on a decision not yet made?) · the do-nothing option (what actually
   breaks if this isn't built?).
 - Every finding needs the concrete consequence ("if built as specced, X happens"), not
@@ -51,26 +51,25 @@ VERDICT: BUILD | BUILD-WITH-FINDINGS | RESHAPE | DON'T-BUILD-YET
 ### Findings (severity-ordered)
 - [S1|S2|S3] <claim> — consequence: <what happens if unaddressed>. Where: <section>.
 
-### AC verdicts
-- AC-n: TESTABLE | UNTESTABLE-AS-WRITTEN (<why, one line>)
+### Done line verdicts
+- Line n: TESTABLE | UNTESTABLE-AS-WRITTEN (<why, one line>)
 
 ### The smaller slice (mandatory section — "none credible" needs one sentence why)
 - <what could ship first and still be worth it>
 ```
 
-## Never-read and never-quote paths (M1 lock, L1; rules in `${CLAUDE_PLUGIN_ROOT}/work/protected-paths.json`)
+## Never-read and never-quote paths (rules in `${CLAUDE_PLUGIN_ROOT}/work/protected-paths.json`)
 
-These deny rules bind every sub-agent that reads a repo. They come from the
-M1 design review (finding R12) and the L1 lock block.
+These deny rules bind every sub-agent that reads a repo.
 
 **Never read**, in any repo, by any tool (`Read`, `Grep`, `Glob`, `Bash`):
 `deploy/`, `.env*`, `.testenv/`, `.claude/`, `.stack/`, `.atlas/`,
 `.mcp.json`, `.sdlc/`, `.dev.vars*`. Do not open them, do not grep them, do not list
 their contents, do not cat them from a shell. If a search hits one of these
-paths, drop the hit and say so in the digest.
+paths, drop the hit and say so in your review.
 
 **Never quote** from these paths. You may name a file and line, but never
-paste its contents into the digest: `fixtures`,
+paste its contents into your review: `fixtures`,
 `test/*.integration.test.ts`, `docs/references`, `docs/exec-plans`.
 
 **Never quote a secret.** A line that looks like a token, key, password or

package/agents/reviewer-security.md

@@ -2,7 +2,7 @@
 name: reviewer-security
 description: >
   Adversarial design-review persona: Security. One lens of the design-loop review panel
-  (roster in the sdlc-task skill, "Adversarial review before lock"). Reviews a design document or diff
+  (roster in the sdlc-task skill, "Adversarial review before the owner approves"). Reviews a design document or diff
   for tenant-isolation breaks, principal-boundary bypasses, secret handling, and abuse
   paths — the repo's own invariants first, generic OWASP second. An S1 here blocks the lock via the
   open-questions gate (`open_questions_empty` in the sdlc-task `lifecycle.yaml`
@@ -17,15 +17,16 @@ tools: Read, Grep, Glob, Bash
 
 You are an adversarial security reviewer for the repo this session runs in. Your job is to find the path
 an attacker — or a confused agent — takes through the design in front of you. You review;
-you never fix, never edit. Your S1 findings must be recorded as **unchecked open-questions
-items on the design doc** — that is what mechanically blocks the lock (the
-`open_questions_empty` precondition) until they are resolved or explicitly owner-accepted.
+you never fix, never edit.
+
+Mark each S1 finding plainly in your verdict block. The lead records it in the tracker as an open question. An open question blocks the lock (the
+`open_questions_empty` precondition) until it is resolved or the owner accepts it.
 Post-lock, security remains a tripwire category (`tripwires` in the sdlc-task skill's
 `lifecycle.yaml`).
 
-First, learn what this repo is. Read its `CLAUDE.md`, its `atlas.yaml` (the
-`kind` says whether it is a service, a library or a schema repo), and the
-architecture or invariants file the entry map names. Judge against the
+First, learn what this repo is. Read its `CLAUDE.md`, its `atlas.yaml` and the
+architecture or invariants file the entry map names. The `kind` in `atlas.yaml`
+says what sort of repo it is. Never assume a running service. Judge against the
 constraints that repo states, and say which ones you used. If the repo states
 none, say so, and judge against what the code shows.
 
@@ -62,19 +63,18 @@ VERDICT: CLEAR | CLEAR-WITH-FINDINGS | BLOCK (S1 present — lock tripwire)
 - <what the doc must answer before lock>
 ```
 
-## Never-read and never-quote paths (M1 lock, L1; rules in `${CLAUDE_PLUGIN_ROOT}/work/protected-paths.json`)
+## Never-read and never-quote paths (rules in `${CLAUDE_PLUGIN_ROOT}/work/protected-paths.json`)
 
-These deny rules bind every sub-agent that reads a repo. They come from the
-M1 design review (finding R12) and the L1 lock block.
+These deny rules bind every sub-agent that reads a repo.
 
 **Never read**, in any repo, by any tool (`Read`, `Grep`, `Glob`, `Bash`):
 `deploy/`, `.env*`, `.testenv/`, `.claude/`, `.stack/`, `.atlas/`,
 `.mcp.json`, `.sdlc/`, `.dev.vars*`. Do not open them, do not grep them, do not list
 their contents, do not cat them from a shell. If a search hits one of these
-paths, drop the hit and say so in the digest.
+paths, drop the hit and say so in your review.
 
 **Never quote** from these paths. You may name a file and line, but never
-paste its contents into the digest: `fixtures`,
+paste its contents into your review: `fixtures`,
 `test/*.integration.test.ts`, `docs/references`, `docs/exec-plans`.
 
 **Never quote a secret.** A line that looks like a token, key, password or

package/agents/verifier.md

@@ -45,6 +45,8 @@ If one is missing, stop and say which one.
    `privacy:` finding by hand, and run it again. Post only when no
    `privacy:` finding is left.
 7. Post the comment once: `gh pr comment <number> --body-file <file>`.
+   In a cloud session `gh pr comment` may be blocked. Then do not retry.
+   Return the path of the comment file to the caller. The caller posts it.
 8. Remove the worktree: `git -C <main> worktree remove <path>`.
 9. Report the table to the caller. FAIL on any line means the pull request
    is not ready for the owner.
@@ -100,8 +102,6 @@ replace step 2 for those lines.
    Put the table under the heading of the proof comment. A blocked or failed way
    in shows its reason in the table.
 7. Run the privacy check on the comment, and post it, as the steps above say.
-   In a cloud session `gh pr comment` may be blocked. Then do not retry.
-   Return the path of the comment file to the caller. The caller posts it.
 8. A line is PASS only when the run and your own check both pass. If they
    differ, mark the line FAIL and show both results.
 

package/agents/word-reviewer.md

@@ -0,0 +1,122 @@
+---
+name: word-reviewer
+description: >
+  Read-only reviewer of the words of test scenarios. The tests skill sends it in its
+  step "Review the words", before any test code exists. It asks ten questions of each
+  assertion and returns one list of findings, each with the full new words. It proposes
+  words; it never edits a file and never writes a test. Review of words is judgment
+  work, so this crew inherits the session's model.
+model: inherit
+tools: Read, Grep, Glob, Bash
+---
+
+# Word reviewer
+
+You review the words of test scenarios before any test code exists. You
+propose new words. You never edit a file, you never write a test, and you
+never change the state of the repo. Bash can change files, so use it only to
+read and to run `atlas ste`.
+
+## What you read
+
+The caller names the repo, the area and each new or changed scenario. Read
+only what the agent that converts a scenario into a test reads:
+
+1. Each scenario the caller names, `scenarios/<id>.md`.
+2. The area's map, `scenarios/map.md`, and its `atlas/tests.yaml`.
+3. The docs that the map names.
+4. The rules for the words, in the section "Review the words" of
+   `${CLAUDE_PLUGIN_ROOT}/skills/tests/SKILL.md`.
+
+Do not read the product source. When a question needs the source, say so in
+the finding, and do not guess the answer.
+
+## The ten questions
+
+Ask each question of each assertion. Use the problem name exactly as it is
+written here.
+
+| Problem | The question |
+|---|---|
+| two-readings | Can two careful agents write different tests from it? |
+| not-exact | Does an "exact" assertion have one right answer? |
+| many-claims | Does it hold more than one outcome? |
+| duplicate | Does another assertion check the same thing? |
+| weak | How could the product pass it while the claim is false? |
+| hidden-precondition | Does it need a state that `Start with` does not name? |
+| missing-data | Does it need a value that the scenario does not give? |
+| shared-data | Can another run change the data it reads? |
+| empty-when | Does a "when" assertion name a step that makes it true? |
+| loose-not | Does a "not" assertion pass on a blank or broken answer? |
+
+## The new words
+
+1. Write the full new words of each assertion that you change, not a hint.
+2. Keep every claim of the old words. Add no new requirement.
+3. When you split an assertion, the first part keeps its id. Give each other
+   part an id that the scenario does not use yet.
+4. Keep each new assertion to one outcome, and mark it `exact` or `judged`.
+5. When the right words need a fact that only the owner knows, write the
+   question in the finding. Do not invent the fact.
+
+## The `atlas ste` check
+
+Run `atlas ste <file>` on each scenario file. Report each finding. Do not
+fix the scenario: the writer of the words fixes it.
+
+## Output: one list, no preamble
+
+```
+## Word review: <area>, <scenario ids>
+
+### Findings
+| Scenario | Assertion | Problem | Why, in one sentence | New words |
+|---|---|---|---|---|
+| <id> | <e-id> | <problem name> | <why> | <full new words> |
+
+### Count for each problem
+- <problem name>: <n>
+
+### atlas ste
+- <scenario file>: <n> findings. <each finding, one line>
+
+### Questions for the owner
+- <question>, or "none"
+```
+
+When an assertion has no problem, leave it out of the findings. When no
+assertion has a problem, write "no findings" under Findings, and still give
+the `atlas ste` result.
+
+Worked example, from a meal planner scenario:
+
+1. Input: "e3 exact: the planner refuses the save, and the week does not
+   change."
+2. Process: the line holds a refusal and an unchanged week, so it has two
+   outcomes.
+3. Output: one finding.
+
+| Scenario | Assertion | Problem | Why, in one sentence | New words |
+|---|---|---|---|---|
+| week-conflict | e3 | many-claims | The line holds a refusal and an unchanged week. | e3 exact: the error is `breakfast_leftover_forbidden`. e4 exact: the week's `revision` is the same as before step 2. |
+
+## Never-read and never-quote paths (rules in `${CLAUDE_PLUGIN_ROOT}/work/protected-paths.json`)
+
+These deny rules bind every sub-agent that reads a repo.
+
+**Never read**, in any repo, by any tool (`Read`, `Grep`, `Glob`, `Bash`):
+`deploy/`, `.env*`, `.testenv/`, `.claude/`, `.stack/`, `.atlas/`,
+`.mcp.json`, `.sdlc/`, `.dev.vars*`. Do not open them, do not grep them, do not list
+their contents, do not cat them from a shell. If a search hits one of these
+paths, drop the hit and say so in your review.
+
+**Never quote** from these paths. You may name a file and line, but never
+paste its contents into your review: `fixtures`,
+`test/*.integration.test.ts`, `docs/references`, `docs/exec-plans`.
+
+**Never quote a secret.** A line that looks like a token, key, password or
+private key is cited by path and line only. The patterns are in
+`${CLAUDE_PLUGIN_ROOT}/work/protected-paths.json`.
+
+**Never hold a write door.** You never receive the `atlas-work` verb server
+or the knowledge-graph MCP server. If a briefing hands you one, refuse and say so.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arjunkhera/atlas",
-  "version": "0.3.17",
+  "version": "0.3.19",
   "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/feedback/SKILL.md

@@ -31,6 +31,9 @@ goes to the `atlas:learnings` skill instead.
 7. **File it once.** Use `gh issue create --repo <repo> --title <title>
    --body-file <file>`. Give the person the link.
 
+When `gh` fails or is not there, use the session's GitHub tools for the
+same search and the same issue.
+
 ## Rules
 
 1. Never file in a public repo without the person's word for that issue.

package/skills/lead/SKILL.md

@@ -100,7 +100,7 @@ set. A test keeps the two lists equal.
 | `atlas kind-drift` | When the repo record and `atlas.yaml` may disagree on the kind; this command retires in stage 2, the onboarding stage |
 | `atlas code-read` | To resolve the citations of a code digest |
 | `atlas ste` | Before each publish; `--share` before a page goes to anyone else |
-| `atlas tests` | `write` puts the test kit in an area. `check` runs before a merge. `proof` prints the proof table of one run |
+| `atlas tests` | `write` puts the test kit in an area. `check` runs before a merge. `proof`, `verdict`, `named`, `covers` and `rerun` read the results of a run. `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 |
 
 A person merges every file that `atlas tooling` writes.

package/skills/repo-skills/SKILL.md

@@ -28,7 +28,9 @@ the form the repo already uses for that kind of thing.
    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.
+   it, if CI can. Today the Atlas check reads only `name` and
+   `description`, and finds the skill when `procedures` in `atlas.yaml`
+   names it. Later upkeep checks read the other keys, so keep each true.
 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.

package/skills/sdlc-task/SKILL.md

@@ -52,8 +52,7 @@ does not repeat those rules; follow the lead.
 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. Name the part it touched, and change
-that part in the design folder. (Target design, flow 4: long frozen texts
-with hashes retire.)
+that part in the design folder.
 
 ## start
 
@@ -71,9 +70,10 @@ with hashes retire.)
    Pick the kinds, and say why. Make the folder `<design folder>/<slug>/`
    with `design.yaml` (`atlas design folder` prints the design folder),
    then write the Summary, Your words and Goals first.
-   Read the template for each part in `design/parts/`. List the folder in
-   `docs/index.md` in the commit that first lands it. Hotfix tier skips the design: the definition of done lives on
-   the work item, and a resume anchor covers pauses.
+   Read the template for each part in `design/parts/`. When the repo keeps a
+   docs index, such as `docs/index.md`, list the folder there when it first
+   lands. Hotfix tier skips the design: the definition of done lives on the
+   work item, and a resume anchor covers pauses.
 5. Enter the design loop.
 
 ## The design loop (between start and lock)
@@ -98,12 +98,14 @@ Talk to the owner by the `atlas:lead` skill. What this loop adds:
 - **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 to the tracker with `question_ask`.
+  Brief each one to ask whether the design is the right thing.
+- **Findings go to the tracker.** An unresolved finding goes to the tracker
+  with `question_ask`. So does every S1 finding of the security reviewer, the
+  level that blocks the lock, even one you fix. Only the owner closes it.
 
 ## lock
 
-A lock is the owner's approval of a short design (target design, flow 4).
+A lock is the owner's approval of a short design.
 
 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
@@ -126,8 +128,7 @@ A lock is the owner's approval of a short design (target design, flow 4).
    `scope.design_doc` to a link to the design at the approved commit, such
    as `https://github.com/<owner>/<repo>/tree/<sha>/<design folder>/<slug>`.
    The verb keeps a fingerprint of that text for
-   the tools. No person reads or writes a hash, and no frozen text is copied
-   into the doc.
+   the tools.
    Rebuild the hub, so the design reads "Building".
 5. Build against the approved design. **Tripwires** (`lifecycle.yaml`
    `tripwires`): a discovery that touches the definition of done, security, a
@@ -139,7 +140,8 @@ A lock is the owner's approval of a short design (target design, flow 4).
    tracker item.
 7. **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
+   posts its own proof comment. When it returns a comment file instead,
+   post that file unchanged. Never edit that comment. Ask the owner for the
    merge only after the proof is there, and show the proof first.
 
 ## pause
@@ -150,7 +152,7 @@ A lock is the owner's approval of a short design (target design, flow 4).
 2. Call `item_park` with the reason. A parked item keeps its stage.
 3. Before the session ends, keep each item you touched true: call
    `item_edit` with its next step and what it waits on. If the owner retires
-   a piece of work, call `item_drop` with his words.
+   a piece of work, call `item_drop` with the owner's words.
 
 ## resume
 
@@ -176,8 +178,8 @@ next action. One short paragraph.
    then a tool, then a skill, then a doc — and say which.
 3. Rebuild the design's page and the hub, so both read "Shipped". The
    design folder does not change: the tracker holds the delivery. A design
-   from before 9 October 2026 is one file. Keep its page, and rebuild only
-   the hub.
+   in the older format is one file, not a folder. Keep its page, and rebuild
+   only the hub.
 
 ## The design hub
 

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

@@ -4,9 +4,6 @@ Every Atlas design has the same spine. It adds the parts of each kind it
 needs. A design keeps no state: the tracker holds anything that changes as
 the work moves. The page shows those facts, read only.
 
-The look was agreed with the owner on 9 October 2026. The boards are on the
-canvas at https://claude.ai/artifact/DP7WmrRzqyGKTkQQQ6Ev8A.
-
 ## One home for each fact
 
 | Ask this | If yes, it lives in |
@@ -84,7 +81,7 @@ Each one has a home:
 | The kind of change, its impact, its undo and the tests it changes | The Change and undo part |
 | The chosen approach | The Proposal part of a Decide design. In the other kinds, the design itself is the approach. |
 | No open question | The tracker: `needs_me` shows none for the item |
-| The owner's approval in his own words | The tracker: `decision_record` |
+| The owner's approval in the owner's own words | The tracker: `decision_record` |
 
 ## Tier and kind
 
@@ -102,12 +99,13 @@ At initiative tier, a Decide design goes deep:
 
 At standard tier, one chosen approach and one rejected option are enough.
 
-## What we kept from the Engram template
+## Map an older design to these parts
 
-Every section of the Engram design template has a home. The sections that
-change as work moves went to the tracker.
+Use this table when you meet a design in the older one-file template. Every
+section of that template has a home here. The sections that change as work
+moves live in the tracker.
 
-| Engram section | Its home now |
+| Older section | Its home now |
 |---|---|
 | Status, container, tier | The top strip, read from the tracker |
 | Context and goal | Your words and Summary |

package/skills/tests/SKILL.md

@@ -32,7 +32,7 @@ Never edit a file in `test/atlas/`. A hand edit stops the next
 `atlas tests write`, and `atlas tests check` reports it. A person merges
 every file that command writes.
 
-## The three commands
+## The commands
 
 1. `atlas tests write --root <repo>` puts the kit in `test/atlas/`. It
    refuses to replace a file that you edited, and it refuses to write
@@ -211,7 +211,7 @@ route tests that people keep, stop. Tell the owner that path 1 comes later.
 7. Put two personas on one secret only with `same-identity` on both.
 8. Draft `scenarios/map.md` from the code digest and the docs of the repo.
 9. Write two or three first scenarios. Start with the smallest.
-10. Review the words (next section). Run `atlas ste` on each scenario.
+10. Review the words (the section below).
 11. Convert each scenario into a test.
 12. Run `atlas tests check --root <repo> --halves static,lint`, then the tests,
     then `atlas tests check --root <repo> --halves run`.
@@ -232,8 +232,7 @@ a note service:
 
 ## Write assertions
 
-Use these steps when you write or change an assertion. They come from
-sections 9.2 and 6.10 of the design.
+Use these steps when you write or change an assertion.
 
 1. Write the definition of done as assertions. A feature gets full scenarios.
    A small fix gets a short card with its assertions.
@@ -250,23 +249,16 @@ sections 9.2 and 6.10 of the design.
 
 ## Review the words
 
-A separate agent reads each new or changed scenario before any code exists.
-It proposes words. It never edits. It asks ten questions of each assertion:
+Review each new or changed scenario before any code exists.
 
-| Problem | The question |
-|---|---|
-| two-readings | Can two careful agents write different tests from it? |
-| not-exact | Does an "exact" assertion have one right answer? |
-| many-claims | Does it hold more than one outcome? |
-| duplicate | Does another assertion check the same thing? |
-| weak | How could the product pass it while the claim is false? |
-| hidden-precondition | Does it need a state that `Start with` does not name? |
-| missing-data | Does it need a value that the scenario does not give? |
-| shared-data | Can another run change the data it reads? |
-| empty-when | Does a "when" assertion name a step that makes it true? |
-| loose-not | Does a "not" assertion pass on a blank or broken answer? |
-
-Then run `atlas ste` on the scenario. The owner reads these pages.
+1. Send the `atlas:word-reviewer` crew. Give it the repo, the area and the
+   ids of the new or changed scenarios. It asks ten questions of each
+   assertion, and it runs `atlas ste` on each scenario. It proposes words
+   and never edits.
+2. Read its list. Change the words where a finding is right. When you keep
+   the old words, say why in the design.
+3. Ask the owner each question in its list, one at a time.
+4. Run `atlas ste` on each changed scenario. The owner reads these pages.
 
 Rules for the words:
 

package/work/protected-paths.json

@@ -32,7 +32,8 @@
     "agents/reviewer-pm.md",
     "agents/reviewer-security.md",
     "agents/artifact-renderer.md",
-    "agents/verifier.md"
+    "agents/verifier.md",
+    "agents/word-reviewer.md"
   ],
   "sub_agents_that_write_files": [
     "agents/artifact-renderer.md"