@arjunkhera/atlas 0.3.7 → 0.3.9

package/.claude-plugin/plugin.json

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

package/agents/artifact-renderer.md

@@ -2,8 +2,8 @@
 name: artifact-renderer
 description: >
   Dedicated Sonnet subagent that renders a design doc, PRD, review, or task explainer into
-  the owner-ratified HTML artifact treatment: one light theme in the
-  Claude-website family, written for a smart newcomer ("assume like a fresher"), diagram-rich,
+  the owner-ratified HTML artifact treatment (one light theme in the
+  Claude-website family), or draws one custom figure for a design part, written for a smart newcomer ("assume like a fresher"), diagram-rich,
   with every stable id backlinked to its definition. Invoked by the sdlc-task design loop and
   any session presenting a design/task/review to the owner — rendering is mechanical work and
   runs on Sonnet (sdlc-task skill, "Model tiering"). Input: a repo markdown doc path (+ optional emphasis
@@ -23,26 +23,26 @@ itself carries). Write the finished HTML to the output path the caller names, an
 return only a one-paragraph summary of what you rendered (sections, diagram count,
 any content you had to omit and why).
 
-## Two formats: walkthrough for designs, Organic pages for the rest
-
-**A design doc made from the walkthrough template** (it has `## Part N —`
-and `### Step N —` lines) renders in the **walkthrough format**. The owner
-chose it on 7 October 2026, for designs explained to a new joiner with
-examples and pictures. Its reference file ships with this crew:
-`${CLAUDE_PLUGIN_ROOT}/agents/artifact-format/walkthrough.html`. Copy its
-CSS, script and structure, and swap in the doc's content:
-
-- One tab for each part, then a last "Reference" tab for the rest of the doc.
-- One step block for each step: the picture on the left, and the step text
-  and an example card on the right. The example card holds the doc's
-  `Example:` block, word for word.
-- One hand-built SVG for each part, built from the steps' `Picture:` lines.
-  Each piece carries `data-step` with the step that adds it, so the picture
-  builds up. Never use mermaid on the page.
-- The page works with all scripts removed. Each step block keeps its own
-  copy of the picture, at that step's state. The reference file's comment
-  states the contract.
-- The summary sits in a card at the top of Part 1.
+## Designs: figures only. Every other doc: an Organic page
+
+**A design is a folder** with `design.yaml` and one file for each part.
+`atlas design build <folder>` builds its page, with the rail, the bars, the
+keys and both themes. You never build a design's page by hand.
+
+For a design, the caller asks you for **one custom figure** for one part:
+git lanes, a time line, a scorecard or a data diff. Write it as HTML inside a
+fenced block with the info string `figure`, and return the block. The rules
+are in `${CLAUDE_PLUGIN_ROOT}/skills/sdlc-task/design/README.md`, under
+"Figures":
+
+- Use the page tokens, such as `var(--accent)`, `var(--line)` and
+  `var(--card)`, so the figure works in the light and the dark theme. Never
+  write a colour with no token.
+- A step has a title and one or two sentences. The reader sets the pace.
+  The figure prints as stills, and it works with its script removed.
+- Meaning is never by colour alone.
+- Close every tag. `atlas design check <folder>` flags a figure that does
+  not.
 
 **Every other doc** (an older design, a PRD, a review, a task explainer)
 renders in the Organic page format below.

package/agents/verifier.md

@@ -76,6 +76,35 @@ Verified at <the head commit>, in a fresh worktree.
 Links made for this run: <none, or each ignored file linked>.
 ```
 
+## Scenario proofs
+
+Use this section when the definition of done names scenario assertions,
+such as `week-conflict/e3#a1b2c3`. The steps above still apply. These steps
+replace step 2 for those lines.
+
+1. Make a fresh worktree of the branch, as in the steps above.
+2. Start the product from `atlas/tests.yaml` with run secrets. The kit in
+   `<area>/test/atlas/` does this when the scenarios run. Set `ATLAS_GUARDS_FROM`
+   to `atlas/tests.yaml` of the main branch. A scenario that needs a provided
+   secret follows the rules of the section "Ignored files and secrets".
+3. Run the scenarios that the line names, with the runner command of `tests.yaml`.
+   Note the run id. Evidence goes to `<area>/test/evidence/<run id>/`.
+4. For each named assertion, make your own check through a raw driver of
+   the kit (`test/atlas/drivers/`). Do not use the actions of the repo or its tests.
+   Write a short script in your scratch folder. It starts the environment, sends the
+   calls of the assertion, and reads the answers. Keep the answer that proves the result.
+5. Write the `--own` file in your scratch folder. It is a JSON object with one
+   entry for each assertion: `{ "week-conflict/e3": { "result": "pass", "proof": "refused, revision 2" } }`.
+6. Print the table with `atlas tests proof`. Give it `--root` for the area,
+   `--run` for the run id, and `--own` for your file.
+   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.
+
 ## 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.

package/door/cli.mjs

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 // The atlas command: install, upgrade, doctor, check, status, the tooling
-// writer, the kind drift report, the code-read resolver, the STE check and
-// the design check.
+// writer, the kind drift report, the code-read resolver, the STE check, the
+// design check and page builder, and the tests verbs (the link check and the
+// test kit writer).
 //
 // Stage 1 of the target design retired `setup`, `change`, `helpers` and
 // `test onboarding`: code that guesses meaning retires (decided 28
@@ -10,7 +11,7 @@
 //
 // Nothing here writes to the work graph, and nothing here merges. A person
 // merges every file the tooling writer writes, because both steer agents.
-import { resolve, join, dirname } from 'node:path';
+import { resolve, join, dirname, basename } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { readFileSync, existsSync, realpathSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
@@ -22,8 +23,11 @@ import { scan, toText, verdict, CHECK_VERSION, SPECS } from '../shape/check.mjs'
 import { packagePackageVersion } from './lib/releases.mjs';
 import { install, upgrade, doctor } from './lib/install.mjs';
 import { checkPaths, LIMITS } from './lib/ste.mjs';
-import { checkDesignFile, MAX_STEP_SENTENCES } from './lib/design.mjs';
+import { checkDesignFolder } from './lib/design.mjs';
+import { writeDesignPage, readTracker } from './lib/design-build.mjs';
 import { loadPrivateTerms } from './lib/privacy.mjs';
+import { checkCommand as testsCheck, writeCommand as testsWrite } from './lib/tests.mjs';
+import { proofCommand as testsProof } from './lib/proof.mjs';
 
 export const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 const ATLAS_VERSION = packagePackageVersion(PACKAGE_ROOT);
@@ -44,7 +48,21 @@ const HELP = `atlas — the door into a repo's Atlas files
   atlas ste <file or folder> …         measure markdown and HTML against the STE limits
       --share                          also run the privacy filter, quotes included
       --terms <file>                   private terms; default ~/.config/atlas/private-terms.txt
-  atlas design <file> …                check a walkthrough design doc: summary, parts, an example and a picture in each step
+  atlas design check <folder> …        check a design folder: each needed part, no state line, every code in the Key
+  atlas design build <folder>          build the design's page from its folder
+      --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 tests check --root <area>      run the link check on the tests of an area
+      --halves <list>                  static, lint, run; default all three
+      --evidence <dir>                 where the evidence files are; default <area>/test/evidence
+      --guards-from <file>             tests.yaml of the main branch; a changed guard part is a finding
+      --run <id>                       read the evidence of this run only; default the newest run
+  atlas tests write --root <area>      copy the shipped test kit into <area>/test/atlas/
+  atlas tests proof --root <area>      print the proof table of one run, one row for each assertion
+      --run <id>                       the run; default the newest run in the evidence folder
+      --own <file>                     JSON of the verifier's own checks: { id: { result, proof } }
 
   atlas install                        install Atlas for every folder on this Mac
   atlas upgrade [--version <v>]        check, show and install a newer release
@@ -70,7 +88,8 @@ export const FLAGS = Object.freeze({
   'kind-drift': { root: 'optional', 'record-kind': 'value', registry: 'value', repo: 'value' },
   check: { root: 'optional', repo: 'value', 'fail-on': 'value' },
   ste: { share: 'switch', terms: 'value' },
-  design: {},
+  design: { tracker: 'value', out: 'value', draft: 'switch' },
+  tests: { root: 'optional', halves: 'value', evidence: 'value', 'guards-from': 'value', tests: 'value', 'dry-run': 'switch', run: 'value', own: 'value' },
   install: { local: 'switch', from: 'value', 'skip-global': 'switch', yes: 'switch' },
   upgrade: { version: 'optional', yes: 'switch' },
   doctor: {},
@@ -208,18 +227,48 @@ function steCommand(chosen) {
 }
 
 function designCommand(chosen) {
-  const paths = chosen._.slice(1);
-  if (!paths.length) throw new Error('give a design doc: atlas design <file>');
+  const what = chosen._[1];
+  const folders = chosen._.slice(2);
+  if (what !== 'check' && what !== 'build') throw new Error('use atlas design check <folder> or atlas design build <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') {
+    if (folders.length > 1) throw new Error('atlas design build takes one folder.');
+    const folder = resolve(folders[0]);
+    const out = resolve(chosen.out ?? join('docs', 'artifacts', `${basename(folder)}.html`));
+    const tracker = chosen.tracker !== undefined ? readTracker(resolve(chosen.tracker)) : null;
+    const result = writeDesignPage(folder, out, { tracker, draft: Boolean(chosen.draft) });
+    if (!result.html) {
+      for (const finding of result.findings) line(`${join(folders[0], finding.file)}:${finding.line}  ${finding.rule}  ${finding.why}`);
+      line('');
+      line(`No page written: the check has ${result.findings.length} finding(s). Fix them, or build a draft with --draft.`);
+      return 1;
+    }
+    line(`Wrote ${out}: ${result.parts} parts, ${result.groups} groups, ${result.figures} figure(s).${tracker ? '' : ' No tracker data: the tracker parts say so.'}`);
+    if (result.findings.length) line(`A draft: the check has ${result.findings.length} finding(s). Run atlas design check ${folders[0]}.`);
+    return 0;
+  }
   let count = 0;
-  for (const path of paths) {
-    for (const finding of checkDesignFile(resolve(path))) { count += 1; line(`${path}:${finding.line}  ${finding.rule}  ${finding.why}`); }
+  for (const folder of folders) {
+    for (const finding of checkDesignFolder(resolve(folder))) { count += 1; line(`${join(folder, finding.file)}:${finding.line}  ${finding.rule}  ${finding.why}`); }
   }
   line('');
-  line(`${paths.length} design doc(s) read; ${count} finding(s). Each step needs an Example block and a picture, and at most ${MAX_STEP_SENTENCES} sentences before its example.`);
-  line(count ? 'Fix the doc by hand. This check never rewrites.' : 'GREEN');
+  line(`${folders.length} design(s) read; ${count} finding(s). The parts each kind needs are in skills/sdlc-task/design/parts.yaml.`);
+  line(count ? 'Fix the design by hand. This check never rewrites.' : 'GREEN');
   return count ? 1 : 0;
 }
 
+function testsCommand(chosen) {
+  const root = rootOf(chosen);
+  const what = chosen._[1];
+  if (what === 'check') {
+    return testsCheck({ halves: chosen.halves, evidence: chosen.evidence, tests: chosen.tests, guardsFrom: chosen['guards-from'], run: chosen.run }, root, line, PACKAGE_ROOT);
+  }
+  if (what === 'write') return testsWrite({ dryRun: Boolean(chosen['dry-run']) }, root, PACKAGE_ROOT, line);
+  if (what === 'proof') return testsProof({ run: chosen.run, own: chosen.own, evidence: chosen.evidence }, root, line);
+  throw new Error(`there is no tests verb "${what ?? ''}". Use check, write or proof.`);
+}
+
 function checkCommand(chosen) {
   const root = rootOf(chosen);
   const report = scan({ root, repoId: chosen.repo ?? null });
@@ -250,6 +299,7 @@ export async function main(argv = process.argv.slice(2)) {
     case 'check': return checkCommand(chosen);
     case 'ste': return steCommand(chosen);
     case 'design': return designCommand(chosen);
+    case 'tests': return testsCommand(chosen);
     default: throw new Error(`there is no verb "${command}". Run "atlas help".`);
   }
 }

package/door/kit-releases.json

@@ -0,0 +1,4 @@
+{
+  "note": "Every kit of the folder tests/ that a release of Atlas shipped, as the kit hash of its manifest (the sha256 of the sorted lines of path and file hash). The kit of this package is always accepted and need not be listed. When a release changes anything in tests/, add the kit hash of the release before it here. atlas tests check reads this list; git history is never read.",
+  "releases": []
+}