@arjunkhera/atlas 0.3.18 → 0.3.20

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "atlas",
-  "version": "0.3.18",
+  "version": "0.3.20",
   "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/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.18",
+  "version": "0.3.20",
   "description": "Atlas: the delivery lifecycle, its crews and the Atlas tools, as a Claude Code plugin for any repository.",
   "type": "module",
   "license": "UNLICENSED",

package/skills/lead/SKILL.md

@@ -92,7 +92,7 @@ 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 upgrade` | When the owner asks to upgrade Atlas. Call the `atlas_upgrade` tool instead: the Bash sandbox blocks this command. Run the command by hand only where that tool is missing |
 | `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 |

package/skills/tests/SKILL.md

@@ -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`.
@@ -249,23 +249,16 @@ Use these steps when you write or change an assertion.
 
 ## 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/mcp.mjs

@@ -25,6 +25,7 @@ import { COST_MEANING, DECISION_KINDS } from './lib/questions.mjs';
 import { FATAL_CONCLUSIONS } from './lib/delivery.mjs';
 import { createMcpServer } from './lib/mcp-stdio.mjs';
 import { childEnvironment } from './lib/child-env.mjs';
+import { upgrade } from '../door/lib/install.mjs';
 export { childEnvironment };
 
 const ATLAS_VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
@@ -72,6 +73,7 @@ export const TOOLS = [
   { name: 'where_are_we', description: 'Answer "where are we with X" in six parts: live support and known limits from the code read at question time, then in progress, delivered and proposed from the items, then the current priority decision. Every row carries a citation: a path and a line, an entity id, a pull request, or a decision date. The code half comes from the sub-agent digests, which are refused when they cite a never-read path or quote a never-quote path, and every string is scrubbed by pattern. Computed at read time and never stored. Scope: read, no owner flag needed.', inputSchema: { type: 'object', required: ['product', 'capability', 'code'], properties: { product: S('Product registry id.'), capability: S('The capability the question is about, the X.'), code: { type: 'array', description: 'One digest per repo, from the sub-agents briefed by code_read_brief. At least one is required: an answer with no code read says nothing about what the code does today.', items: CODE_DIGEST }, items: { type: 'array', description: 'Item ids the lead judges to answer this question.', items: { type: 'string' } }, match: { type: 'array', description: 'Terms to match against item titles, summaries and tags. Give items, match, or both.', items: { type: 'string' } }, movement_repos: { type: 'array', description: "Narrow the movement read to these registered repo ids. Default: every repo of the product. The digests' own repos are always read.", items: { type: 'string' } }, since: S('ISO date. Adds what changed since then.') }, additionalProperties: false } },
   { name: 'built_pending_possible', description: 'Answer "what are we building, what is built, what is pending and what can be done": delivered items by date, active items, paused items with their reason, proposed items with their age, and the decisions that set the order. Item records, delivery marks and decisions only; no code read and no GitHub read. Computed at read time and never stored. Scope: read, no owner flag needed.', inputSchema: { type: 'object', properties: { product: S('Limit the view to one product id.'), since: S('ISO date. Limits built and the decisions to what came after it.') }, additionalProperties: false } },
   { name: 'design_index', description: 'List every design: each work item with a design-doc link, in any lifecycle, newest change first, with its product, its state for the hub ("Waiting on the owner", "Building", "Paused", "Shipped", "Dropped"), its design docs and its pages. Also returns design_hub_url, the one hub page. When: before the lead rebuilds the "Design docs" hub, after each design publish, lock and done. Item records only; computed at read time and never stored. Scope: read, no owner flag needed.', inputSchema: { type: 'object', properties: { product: S('Limit the list to one product id.') }, additionalProperties: false } },
+  { name: 'atlas_upgrade', description: 'Move Atlas on this Mac to the newest release: the same steps as the "atlas upgrade --yes" command. It checks that a master release run built the release, installs it and updates the plugin. When: the owner asks to upgrade Atlas. Use this tool and not the command: the Bash sandbox blocks the writes to ~/.npm, ~/.atlas and ~/.claude/plugins, and this server runs outside it. With check true it only reports the loaded and the newest version. Scope: this Mac, no tracker write. Owner present only. Not in a Claude cloud session: a new cloud session installs the newest release.', inputSchema: { type: 'object', properties: { check: { type: 'boolean', description: 'True: report the versions and install nothing.' } }, additionalProperties: false } },
 ];
 
 // The Engram connection: the address and the key, in one setting, separated by
@@ -233,6 +235,34 @@ function writeHealth(env, health) {
   try { mkdirSync(dirname(path), { recursive: true }); writeFileSync(path, `${JSON.stringify(health, null, 2)}\n`, { mode: 0o600 }); } catch { /* health is advice, never a reason to stop */ }
 }
 
+// The atlas_upgrade tool (owner, 12 October 2026: "Atlas upgrade tool"). An
+// agent's Bash runs in a sandbox that cannot write to ~/.npm, ~/.atlas or
+// ~/.claude/plugins, so `atlas upgrade` fails there. This server runs outside
+// that sandbox. The tool runs the same upgrade steps as the command, with the
+// short child environment: never the Engram key.
+const PACKAGE_ROOT = fileURLToPath(new URL('..', import.meta.url));
+const ATLAS_VERSION_OF = (root) => JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')).version;
+function childExec(env) {
+  return (command, args) => execFileSync(command, args, { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024, timeout: 600_000, stdio: ['pipe', 'pipe', 'pipe'], env: childEnvironment(env) });
+}
+export async function runUpgrade({ args = {}, env = process.env, ownerPresent, packageRoot = PACKAGE_ROOT, exec = childExec(env), upgradeFn = upgrade } = {}) {
+  const refuse = (message) => { const error = new Error(message); error.name = 'VerbError'; throw error; };
+  if (!ownerPresent) refuse('atlas_upgrade needs the owner-present flag on the server host (ATLAS_WORK_OWNER_PRESENT=1)');
+  if (inClaudeCloud(env)) refuse('atlas_upgrade does not run in a Claude cloud session. A new cloud session installs the newest release.');
+  const loaded = ATLAS_VERSION_OF(packageRoot);
+  if (args.check) {
+    let newest;
+    try { newest = exec('npm', ['view', '@arjunkhera/atlas', 'version']).trim(); } catch (error) { refuse(`npm could not read the newest version: ${String(error.stderr || error.message).trim().split('\n').slice(0, 3).join(' ')}`); }
+    return { loaded, newest, behind: newest !== loaded };
+  }
+  const lines = [];
+  let code;
+  try { code = await upgradeFn({ packageRoot, options: { yes: true }, line: (text) => lines.push(text), env, exec }); } catch (error) {
+    refuse(`the upgrade stopped: ${String(error.stderr || error.message).trim().split('\n').slice(0, 6).join(' ')}`);
+  }
+  return { ok: code === 0, loaded, output: lines, next: code === 0 ? 'Restart the Claude Code sessions on this Mac to load the new release.' : 'Nothing was installed. Read the output.' };
+}
+
 export function buildServer({ env = process.env, input, output, readGitHub, readLive, log, allowLoopbackHttp = false } = {}) {
   const hostile = hostileVariables(env);
   if (hostile.length) throw new Error(`refusing to start: ${hostile.join(', ')} ${hostile.length === 1 ? 'is' : 'are'} set, and could send the Engram key elsewhere or turn certificate checks off. Unset ${hostile.length === 1 ? 'it' : 'them'}.`);
@@ -256,6 +286,8 @@ export function buildServer({ env = process.env, input, output, readGitHub, read
     ? `Atlas work verbs for the owner's session. Session ${session}; owner present: ${ownerPresent ? 'yes' : 'no: the owner-only tools refuse'}. Call registry_list first to learn the product and repo ids, needs_me to see the open questions, and in_flight to see the active work. Every write needs a request_id. The server stamps writer.session and the bound client; never pass writer, session, actor or role. Unknown product or repo ids are refused. Sub-agents must not receive this server.`
     : `Atlas work verbs. They cannot reach Engram yet: ${connection.message}`;
   const server = createMcpServer({ name: 'atlas-work', version: MANIFEST_VERSION, instructions, tools: TOOLS, input, output, log, call: (name, args, boundTo) => {
+    // The upgrade needs no Engram connection: an old key must not block a new release.
+    if (name === 'atlas_upgrade') return runUpgrade({ args, env, ownerPresent });
     if (!verbs) throw new Error(connection.message);
     // The writer names the one client this server is bound to (D6 R3): stamped by the server, never by the caller.
     if (boundTo && boundTo.session !== bound) { bound = boundTo.session; verbs = verbsFor(bound); }

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"