ketatlas 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.2.0
+
+- Track delivery per screen in a separate progress JSON, with acceptance checks, blockers, ownership, task references and PR/test/release evidence.
+- Review all screens with filters and shared map badges; edit progress using the local viewer or revision-checked CLI.
+- Refuse stale writes and unsupported verification claims; keep static hosting read-only and existing version 1 workflows compatible.
+- Audit progress references, provide a public schema/API, and test browser editing, concurrency and packaged installation.
+
 ## 0.1.1 — 2026-09-04
 
 - Publish the tested archive through an absolute file path; support guarded retries after a CI workflow fix.

package/README.md

@@ -17,21 +17,21 @@ https://github.com/user-attachments/assets/13f24fc8-7b8e-4bda-9e02-364c120ee163
 [KetAtlas is available on npm](https://www.npmjs.com/package/ketatlas). Use Node.js 22+ and run it from any directory:
 
 ```sh
-npx --yes ketatlas@0.1.1 scaffold my-atlas --template web
-npx --yes ketatlas@0.1.1 serve my-atlas/atlas.json
-npx --yes ketatlas@0.1.1 audit my-atlas/atlas.json --strict
+npx --yes ketatlas@0.2.0 scaffold my-atlas --template web
+npx --yes ketatlas@0.2.0 serve my-atlas/atlas.json
+npx --yes ketatlas@0.2.0 audit my-atlas/atlas.json --strict
 ```
 
 Or install the CLI once for your user account:
 
 ```sh
-npm install --global ketatlas@0.1.1
+npm install --global ketatlas@0.2.0
 ketatlas scaffold my-atlas
 ketatlas serve my-atlas/atlas.json
 ketatlas audit my-atlas/atlas.json --strict
 ```
 
-The consumer folder contains `atlas.json`, its schema, product HTML/CSS/JavaScript, local assets, and documentation. It needs no `package.json`, lockfile, `node_modules`, build step, or copy of the viewer. The CLI supplies scaffold, serving, and static audit from its own installation. `serve` and `audit` leave project files unchanged unless an audit output file is explicitly requested.
+The consumer folder contains `atlas.json`, its schema, product HTML/CSS/JavaScript, local assets, and documentation. It needs no `package.json`, lockfile, `node_modules`, build step, or copy of the viewer. The CLI supplies scaffold, serving, and static audit from its own installation. `audit` leaves project files unchanged unless an output file is explicitly requested. Viewing with `serve` does not write; explicit **Save progress** writes the sibling progress file. Use `--read-only` to disable editing.
 
 Pin the version in run commands or the global installation for reproducible team workflows. Product scripts implement mock screen interactions; they are authored content, not a local installation of KetAtlas. Framework tooling and tests stay in the KetAtlas repository.
 
@@ -75,6 +75,10 @@ See [Agent mockups](docs/agent-mockups.md) for installation options, a ready-to-
 
 URLs resolve relative to the JSON file. Nodes default to a left-to-right row. Set `column` and `row` for branches; set each screen's `viewport` for mobile or desktop dimensions. Reuse a screen in many flows without duplicating its HTML.
 
+## Track delivery
+
+Open **Screens** to filter screen progress, review blockers and edit acceptance checks with PR/test evidence. Records live in a sibling `atlas.progress.json` tracked in Git; repeated nodes share one screen record. A merged PR is not a verified screen. Local saves detect concurrent edits; static hosting is read-only. See [Screen progress](docs/progress.md) for the contract, CLI and embedding API.
+
 ## Commands
 
 | Command                 | Purpose                                                                                    |

package/bin/audit.js

@@ -1,3 +1,4 @@
+import { readProgress, progressPath } from "./progress.js";
 import { readFile, realpath, stat } from "node:fs/promises";
 import { resolve, dirname, relative, sep, extname } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
@@ -93,6 +94,13 @@ export async function auditAtlas(file, { root: rootOption } = {}) {
     for (const f of config.flows)
       for (const n of f.nodes) if (n.url) await inspect(n.url, absolute, `node:${f.id}/${n.id}`);
   }
+  if (result.valid) {
+    try {
+      await readProgress(progressPath(absolute), config);
+    } catch (e) {
+      errors.push({ path: "progress", message: e.message });
+    }
+  }
   for (const url of remote)
     warnings.push({ path: "remote", message: `Remote URL not fetched: ${url}` });
   const flows = Array.isArray(config?.flows) ? config.flows : [];

package/bin/ketatlas.js

@@ -1,4 +1,6 @@
 #!/usr/bin/env node
+import { progressPath, readProgress, saveProgress } from "./progress.js";
+import { summarizeProgress } from "../src/progress.js";
 import { readFile, readdir, mkdir, cp, writeFile, stat } from "node:fs/promises";
 import { resolve, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -13,6 +15,8 @@ const help = `KetAtlas — scaffold, serve, and audit HTML workflow maps
   ketatlas serve <atlas.json> [--port 4178] [--root directory]
   ketatlas audit <atlas.json> [--root directory] [--json] [--strict]
   ketatlas validate <atlas.json>
+  ketatlas progress <atlas.json> [--json] [--init]
+  ketatlas progress <atlas.json> --set <screen-id> --record <record.json> --expect <revision>
   ketatlas --version
 
 Examples:
@@ -118,8 +122,58 @@ async function main(args) {
     );
     return;
   }
+  if (command === "progress") {
+    const { target, options } = parse(rest, {
+      json: "boolean",
+      init: "boolean",
+      set: "string",
+      record: "string",
+      expect: "string",
+    });
+    const file = resolve(target),
+      atlas = JSON.parse(await readFile(file, "utf8"));
+    const valid = validateAtlas(atlas);
+    if (!valid.valid) throw new Error(valid.errors.map((e) => e.message).join("; "));
+    const path = progressPath(file);
+    let result = await readProgress(path, atlas);
+    if (options.init) {
+      if (options.set || options.record || options.expect)
+        throw new Error("Use --init separately from an update.");
+      if (result.revision !== "missing") throw new Error("Progress already exists.");
+      result = await saveProgress(path, file, "missing", (data) => {
+        for (const s of atlas.screens || [])
+          Object.defineProperty(data.screens, s.id, {
+            value: { status: "unassessed" },
+            enumerable: true,
+          });
+        return data;
+      });
+    } else if (options.set || options.record || options.expect) {
+      if (!options.set || !options.record || !options.expect)
+        throw new Error("Updates need --set, --record and --expect from progress --json.");
+      const record = JSON.parse(await readFile(resolve(options.record), "utf8"));
+      result = await saveProgress(path, file, options.expect, (data) => {
+        Object.defineProperty(data.screens, options.set, {
+          value: { ...record, updatedAt: new Date().toISOString() },
+          enumerable: true,
+        });
+        return data;
+      });
+    }
+    const summary = summarizeProgress(result.data, atlas.screens || []);
+    console.log(
+      options.json
+        ? JSON.stringify({ ...result, summary }, null, 2)
+        : `${summary.total} screens · ${summary.counts.verified} verified · ${summary.blocked} blocked\nRevision: ${result.revision}\n${path}`,
+    );
+    return;
+  }
   if (command === "serve") {
-    const { target, options } = parse(rest, { port: "string", root: "string" }),
+    const { target, options } = parse(rest, {
+        port: "string",
+        root: "string",
+        "read-only": "boolean",
+      }),
       port = Number(options.port || 4178);
     if (!Number.isInteger(port) || port < 1 || port > 65535)
       throw new Error("Port must be 1–65535.");
@@ -128,7 +182,7 @@ async function main(args) {
       throw new Error("--root is only needed when serving an atlas JSON file.");
     const server = directory
       ? await serve(target, { port })
-      : await serveAtlas(target, { port, root: options.root });
+      : await serveAtlas(target, { port, root: options.root, readOnly: options["read-only"] });
     console.log(
       `KetAtlas: http://127.0.0.1:${server.address().port}\nServing ${resolve(target)}\nPress Ctrl+C to stop.`,
     );

package/bin/progress.js

@@ -0,0 +1,120 @@
+import { readFile, writeFile, rename, unlink, open, lstat } from "node:fs/promises";
+import { createHash, randomUUID } from "node:crypto";
+import { resolve } from "node:path";
+import { emptyProgress, requireProgress } from "../src/progress.js";
+export const progressPath = (file) => file.replace(/\.json$/i, "") + ".progress.json";
+const hash = (text) => createHash("sha256").update(text).digest("hex");
+export async function readProgress(file, atlas) {
+  try {
+    if ((await lstat(file)).isSymbolicLink())
+      throw new Error("Progress file must not be a symlink.");
+    const text = await readFile(file, "utf8");
+    return { data: requireProgress(JSON.parse(text), atlas), revision: hash(text) };
+  } catch (e) {
+    if (e.code !== "ENOENT") throw e;
+    return { data: emptyProgress(), revision: "missing" };
+  }
+}
+/** Shared by the CLI and local editor. One lock and content revision prevent stale writes. */
+export async function saveProgress(file, atlasFile, expected, change) {
+  file = resolve(file);
+  let lock;
+  try {
+    lock = await open(file + ".lock", "wx");
+  } catch (e) {
+    if (e.code === "EEXIST")
+      throw Object.assign(new Error("Another writer is saving. Reload and retry."), {
+        status: 409,
+      });
+    throw e;
+  }
+  const temp = file + "." + randomUUID() + ".tmp";
+  try {
+    const atlas = JSON.parse(await readFile(atlasFile, "utf8"));
+    const current = await readProgress(file, atlas);
+    if (!expected || expected !== current.revision)
+      throw Object.assign(
+        new Error(
+          "Progress changed since it was loaded. Reload before saving; your draft is still visible.",
+        ),
+        { status: 409 },
+      );
+    const data = requireProgress(change(structuredClone(current.data)), atlas);
+    const text = JSON.stringify(data, null, 2) + "\n";
+    await writeFile(temp, text, { flag: "wx" });
+    if ((await readProgress(file, atlas)).revision !== current.revision)
+      throw Object.assign(new Error("Progress changed during saving. Reload and retry."), {
+        status: 409,
+      });
+    await rename(temp, file);
+    return { data, revision: hash(text) };
+  } finally {
+    await unlink(temp).catch(() => {});
+    await lock.close();
+    await unlink(file + ".lock");
+  }
+}
+export function progressHandler(file, atlasFile, token, editable) {
+  const path = progressPath(file);
+  return async (req, res) => {
+    if (new URL(req.url, "http://localhost").pathname !== "/__ketatlas__/progress") return false;
+    const reply = (status, data) => {
+      res.writeHead(status, { "Content-Type": "application/json", "Cache-Control": "no-store" });
+      res.end(JSON.stringify(data));
+    };
+    try {
+      if (req.method === "GET") {
+        reply(200, {
+          ...(await readProgress(path, JSON.parse(await readFile(atlasFile, "utf8")))),
+          editable,
+        });
+        return true;
+      }
+      if (req.method !== "PUT") {
+        reply(405, { error: "Method not allowed" });
+        return true;
+      }
+      const origin = `http://${req.headers.host}`;
+      if (
+        !editable ||
+        req.headers.origin !== origin ||
+        req.headers["x-ketatlas-token"] !== token ||
+        !req.headers["content-type"]?.startsWith("application/json")
+      ) {
+        reply(403, { error: "Progress writes require the local editor." });
+        return true;
+      }
+      let text = "",
+        size = 0;
+      for await (const chunk of req) {
+        size += chunk.length;
+        if (size > 1024 * 1024) {
+          reply(413, { error: "Progress update is too large." });
+          return true;
+        }
+        text += chunk;
+      }
+      const body = JSON.parse(text);
+      if (
+        typeof body.screenId !== "string" ||
+        !body.record ||
+        typeof body.record !== "object" ||
+        Array.isArray(body.record)
+      )
+        throw new Error("Expected a screen ID and record.");
+      const result = await saveProgress(path, atlasFile, req.headers["if-match"], (data) => {
+        Object.defineProperty(data.screens, body.screenId, {
+          value: { ...body.record, updatedAt: new Date().toISOString() },
+          enumerable: true,
+          writable: true,
+          configurable: true,
+        });
+        return data;
+      });
+      reply(200, { ...result, editable });
+    } catch (e) {
+      reply(e.status || 400, { error: e.message });
+    }
+    return true;
+  };
+}

package/bin/server.js

@@ -21,7 +21,7 @@ const within = (root, path) => {
 /** Local static preview only. Resolves symlinks before checking the root boundary. */
 export async function serve(
   directory,
-  { port = 4178, host = "127.0.0.1", viewer, packageRoot } = {},
+  { port = 4178, host = "127.0.0.1", viewer, packageRoot, handler } = {},
 ) {
   const root = await realpath(resolve(directory));
   if (!(await stat(root)).isDirectory()) throw new Error("Serve root must be a directory.");
@@ -30,6 +30,7 @@ export async function serve(
       res.writeHead(status, { "Content-Type": "text/plain; charset=utf-8" });
       res.end(message);
     };
+    if (handler && (await handler(req, res))) return;
     if (!["GET", "HEAD"].includes(req.method)) return fail(405, "Method not allowed");
     try {
       const pathname = decodeURIComponent(new URL(req.url, "http://localhost").pathname);

package/bin/viewer.js

@@ -1,3 +1,5 @@
+import { randomBytes } from "node:crypto";
+import { progressHandler } from "./progress.js";
 import { readFile, realpath, stat } from "node:fs/promises";
 import { resolve, dirname, relative, sep } from "node:path";
 import { validateAtlas, AtlasValidationError } from "../src/config.js";
@@ -15,6 +17,12 @@ export async function serveAtlas(file, options = {}) {
   if (rel === ".." || rel.startsWith(".." + sep) || rel.startsWith(sep))
     throw new Error("The JSON file must be inside --root.");
   const configURL = "/" + rel.split(sep).map(encodeURIComponent).join("/");
-  const html = `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>KetAtlas</title><style>html,body{margin:0;height:100%}#atlas{height:100dvh}#error{font:16px system-ui;padding:24px;white-space:pre-wrap}</style></head><body><main id="atlas"></main><pre id="error" hidden></pre><script type="module">import {loadAtlas} from '/__ketatlas__/src/index.js';try{window.atlas=await loadAtlas(document.querySelector('#atlas'),${JSON.stringify(configURL).replaceAll("<", "\\u003c")},{syncUrl:true});document.title=${JSON.stringify(config.title).replaceAll("<", "\\u003c")}+' · KetAtlas';}catch(error){const el=document.querySelector('#error');el.hidden=false;el.textContent=error.message;}</script></body></html>`;
-  return serve(root, { ...options, viewer: html, packageRoot });
+  const token = randomBytes(24).toString("hex");
+  const html = `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>KetAtlas</title><style>html,body{margin:0;height:100%}#atlas{height:100dvh}#error{font:16px system-ui;padding:24px;white-space:pre-wrap}</style></head><body><main id="atlas"></main><pre id="error" hidden></pre><script type="module">import {loadAtlas} from '/__ketatlas__/src/index.js';try{window.atlas=await loadAtlas(document.querySelector('#atlas'),${JSON.stringify(configURL).replaceAll("<", "\\u003c")},{syncUrl:true,progressEndpoint:"/__ketatlas__/progress",progressToken:${JSON.stringify(token)}});document.title=${JSON.stringify(config.title).replaceAll("<", "\\u003c")}+' · KetAtlas';}catch(error){const el=document.querySelector('#error');el.hidden=false;el.textContent=error.message;}</script></body></html>`;
+  return serve(root, {
+    ...options,
+    viewer: html,
+    packageRoot,
+    handler: progressHandler(absolute, absolute, token, !options.readOnly),
+  });
 }

package/docs/architecture.md

@@ -1,6 +1,6 @@
 # Architecture
 
-KetAtlas is a static browser viewer plus a Node.js command-line toolkit. There is no database, account service, application backend, or runtime npm dependency.
+KetAtlas is a static browser viewer plus a Node.js command-line toolkit. There is no database, account service or runtime npm dependency. The localhost CLI has a narrow, protected API to read and save the progress sidecar; static hosting remains read-only.
 
 ```text
 atlas.json + screen HTML
@@ -61,3 +61,7 @@ The default theme uses Inter and KetJS's canonical tokens and primitives. `prepa
 ## Version 1 boundaries
 
 KetAtlas is a viewer and authoring toolkit, not a visual graph editor. Users edit JSON and HTML in their normal tools. It does not record a graph by watching clicks, synthesize screens, calculate backend permissions, or execute the arrow graph as an automated test. Cross-flow edges, collaborative editing and browser-based project audits are outside the current contract.
+
+## Delivery tracking
+
+`src/progress.js` owns progress validation and unique-screen counts. `src/progress-ui.js` owns the screen register and progress editor. `bin/progress.js` shares a locked, revision-checked atomic writer between CLI and local HTTP updates. Progress does not alter graph layout or infer completion from PR state. See [Screen progress](progress.md).

package/docs/cli.md

@@ -70,3 +70,7 @@ ketatlas --help
 ```
 
 `validate` checks configuration and graph references only. It is also available as `validateAtlas(data)` in JavaScript. JSON Schema supports editor completion; graph-reference and URL safety checks belong to the runtime validator and audit.
+
+## Screen progress
+
+`progress <atlas.json> --json` reads the progress record, content revision and unique-screen summary. `--init` creates a missing sidecar. `--set <screen-id> --record <record.json> --expect <revision>` replaces one record with conflict detection. `serve <atlas.json> --read-only` disables local progress writes. See [Screen progress](progress.md) for examples and persistence rules.

package/docs/configuration.md

@@ -63,3 +63,7 @@ A node without `screen` defaults to `note` and requires a title. Use `type: "ext
 `from`, `to` and a nonempty `label` are required. Endpoints reference node IDs in the same flow. `kind` is `primary` (default), `conditional`, or `recovery`. Arrows are orthogonal and labels describe the action or condition.
 
 Cross-flow edges are not part of version 1. Reuse the destination screen in another flow, or add an external/note handoff to explain the boundary. Start and outcome markers express authored intent; clicking them does not invoke a backend operation.
+
+## Delivery progress
+
+Delivery records use the optional sibling `<atlas-name>.progress.json`, with `progress.schema.json` and semantic validation, rather than extra properties in the version 1 workflow. See [Screen progress](progress.md).

package/docs/integration.md

@@ -106,3 +106,7 @@ Iframe previews are sandboxed. Scripts and forms work by default, but the page h
 Remote pages can reject framing using CSP or `X-Frame-Options`. KetAtlas cannot override that. Use a permitted embedded route or the **Open in new tab** action. Test links/forms with the default sandbox before sharing a project.
 
 The viewer uses native dialog, Shadow DOM, ResizeObserver, container queries and modern CSS. Chromium is covered by the browser suite. Other modern engines should be qualified against your host application before promising support.
+
+## Progress adapters
+
+`createAtlas` accepts `options.progress`. `loadAtlas` discovers a sibling progress JSON or accepts `progressURL`. Both support `progressRevision`, `saveProgress(screenId, record, revision)` and `reloadProgress()`; adapters return `{data, revision}`. No save adapter means read-only. See [Screen progress](progress.md).

package/docs/progress.md

@@ -0,0 +1,83 @@
+# Screen progress
+
+Open **Screens** to review delivery across the project. Counts use unique screen IDs, not repeated workflow nodes. Filter by status, workflow, blocker, or search names, IDs, tasks and owners. **View in map** focuses a screen; **Screen progress** opens its record from the node inspector. Mockup badges remain separate from implementation status.
+
+## Status and scope
+
+| Status      | Meaning                                                                                       |
+| ----------- | --------------------------------------------------------------------------------------------- |
+| Unassessed  | Implementation has not been compared with the intended screen scope.                          |
+| Planned     | Scope is known; implementation has not started.                                               |
+| In progress | Some work exists, but required implementation is incomplete.                                  |
+| In review   | Required changes are in review.                                                               |
+| Implemented | Required code is merged; full acceptance verification is outstanding.                         |
+| Verified    | Every recorded acceptance check has passed test evidence at a named revision and environment. |
+
+A blocker is independent of status: record the reason and next action. A merged PR does not automatically change the screen's status. A release or pin is separate evidence; neither proves that an environment was deployed or a user journey passed. Counts do not invent a completion percentage.
+
+Acceptance checks have stable IDs, a title, a done flag and evidence references. Completed checks require evidence. Verified additionally requires **each** check to reference a `test` with `state: "passed"`, a nonempty `revision` and `environment`, and no blocker. This is a validation rule for authored claims, not an independent test execution service. Scope the checklist honestly; omitted requirements cannot be verified by the viewer.
+
+A check may identify particular states using `nodes: [{ "flowId": "sign-in", "nodeId": "invalid" }]`. Every referenced node must belong to that screen. The editor displays these state references and preserves them; authors and agents manage the references in JSON. Screens reused across flows share one record.
+
+## Files and persistence
+
+For `atlas.json`, progress lives in **atlas.progress.json** next to it. For `journey.json`, use `journey.progress.json`. Format version 1 of the workflow remains unchanged. Existing viewers still open the workflow JSON. Missing progress means Unassessed and does not create a file merely by viewing the project.
+
+`progress.schema.json` ships with the package and templates. `validateProgress` adds semantic checks for references, safe evidence URLs, timestamps and verification requirements. `audit` validates a present sidecar without fetching evidence URLs or executing tests. Git records history; keep progress alongside the atlas in the same project repository.
+
+```json
+{
+  "version": 1,
+  "screens": {
+    "sign-in": {
+      "status": "in_progress",
+      "owner": "Frontend team",
+      "tasks": ["AUTH-12"],
+      "summary": "Sign-in is implemented; expired-link recovery still needs work.",
+      "checks": [
+        {
+          "id": "submit",
+          "title": "Sign in with valid credentials",
+          "done": true,
+          "evidenceIds": ["pr-12"]
+        },
+        { "id": "recovery", "title": "Recover from an expired link", "done": false }
+      ],
+      "evidence": [
+        {
+          "id": "pr-12",
+          "kind": "pr",
+          "title": "Sign-in implementation",
+          "url": "https://example.test/pull/12",
+          "state": "merged",
+          "revision": "abc123"
+        }
+      ]
+    }
+  }
+}
+```
+
+Evidence kinds are `pr`, `test`, `release`, `reference`. Required fields: `id`, `kind`, `title`, `url`. Optional fields: `state`, `revision`, `environment`, `observedAt`. Screen records also support `updatedAt`, `blocker`, `owner`, `summary`, `tasks`, `checks`, `evidence`; only `status` is required.
+
+## Editing locally and from agents
+
+```sh
+npx --yes ketatlas@0.2.0 serve atlas.json
+npx --yes ketatlas@0.2.0 serve atlas.json --read-only
+npx --yes ketatlas@0.2.0 progress atlas.json --init
+npx --yes ketatlas@0.2.0 progress atlas.json --json
+npx --yes ketatlas@0.2.0 progress atlas.json --set sign-in --record record.json --expect REVISION_FROM_READ
+```
+
+`--init` explicitly creates Unassessed records and refuses an existing progress file. `--set` replaces one complete screen record; preserve existing checklist IDs, evidence and state references. Read the revision with `--json` first. Do not retry a stale revision by blindly substituting a new one: reload and reconcile changes. `updatedAt` is stamped on successful record writes.
+
+The UI and CLI use the same validated, atomic file writer and exclusive lock. Two writers cannot silently overwrite each other. A stale browser save keeps its draft visible; reload the latest record before reconciling. If a process is forcibly killed while holding the lock, inspect that no writer is running before removing the sibling `.lock` file. Direct file edits are supported, but agents should prefer the CLI for coordinated writes.
+
+Only the local CLI editor offers save controls. It uses a per-server write token, same-origin JSON requests, bounded request bodies, and a fixed sidecar path. Screen iframes retain their sandbox and cannot use the write capability. `--read-only` refuses writes. Viewing or auditing alone never writes. Static hosting discovers the sidecar and displays it read-only; no database or runtime dependency is needed.
+
+## Embedding
+
+`createAtlas(container, config, { progress })` accepts in-memory progress. `loadAtlas` discovers the sibling sidecar unless `progress` or `progressURL` is supplied. Missing (404) is optional; invalid JSON, failed requests and malformed records surface errors rather than masquerading as unassessed data.
+
+Hosts may provide `progressRevision`, `saveProgress(screenId, record, revision)` and `reloadProgress()` adapters. Both return `{ data, revision }`. The local CLI supplies these through its protected endpoint. Public helpers `validateProgress`, `summarizeProgress` and `progressStatuses` have no DOM dependency.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ketatlas",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Interactive HTML maps for screens, workflows, and user journeys.",
   "type": "module",
   "license": "MIT",
@@ -18,7 +18,8 @@
       "types": "./src/index.d.ts",
       "import": "./src/index.js"
     },
-    "./schema.json": "./schema.json"
+    "./schema.json": "./schema.json",
+    "./progress.schema.json": "./progress.schema.json"
   },
   "bin": {
     "ketatlas": "bin/ketatlas.js"
@@ -35,19 +36,20 @@
     "templates",
     "skills",
     "docs",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "progress.schema.json"
   ],
   "scripts": {
     "dev": "node bin/ketatlas.js serve examples/atlas.json --root . --port 4178",
     "validate": "node bin/ketatlas.js audit examples/atlas.json --root . && node bin/ketatlas.js audit templates/basic/atlas.json && node bin/ketatlas.js audit templates/web/atlas.json && node bin/ketatlas.js audit templates/process/atlas.json",
     "test": "node --test tests/*.test.js",
-    "test:e2e": "node tests/browser.mjs",
+    "test:e2e": "node tests/browser.mjs && node tests/progress-browser.mjs",
     "check": "npm run validate && npm test && npm run test:e2e",
     "format": "prettier --write src styles/ketatlas.css bin scripts docs examples starter templates skills tests '*.md' '*.json' .github/workflows",
     "format:check": "prettier --check src styles/ketatlas.css bin scripts docs examples starter templates skills tests '*.md' '*.json' .github/workflows",
     "prepare:assets": "node scripts/prepare-assets.mjs",
     "prepack": "node scripts/verify-assets.mjs",
-    "prepare:templates": "node scripts/schema.mjs && node scripts/prepare-templates.mjs",
+    "prepare:templates": "node scripts/schema.mjs && node scripts/progress-schema.mjs && node scripts/prepare-templates.mjs",
     "test:package": "node tests/package.mjs"
   },
   "devDependencies": {

package/progress.schema.json

@@ -0,0 +1,130 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "KetAtlas screen progress",
+  "description": "Semantic validation also checks screen/node IDs, evidence references and verification requirements.",
+  "type": "object",
+  "properties": {
+    "version": {
+      "const": 1
+    },
+    "screens": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "properties": {
+          "status": {
+            "enum": ["unassessed", "planned", "in_progress", "in_review", "implemented", "verified"]
+          },
+          "owner": {
+            "type": "string"
+          },
+          "summary": {
+            "type": "string"
+          },
+          "blocker": {
+            "type": "string"
+          },
+          "updatedAt": {
+            "type": "string",
+            "pattern": "\\S"
+          },
+          "tasks": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "pattern": "\\S"
+            }
+          },
+          "checks": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "id": {
+                  "type": "string",
+                  "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_.-]*$"
+                },
+                "title": {
+                  "type": "string",
+                  "pattern": "\\S"
+                },
+                "done": {
+                  "type": "boolean"
+                },
+                "evidenceIds": {
+                  "type": "array",
+                  "items": {
+                    "type": "string",
+                    "pattern": "\\S"
+                  }
+                },
+                "nodes": {
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "properties": {
+                      "flowId": {
+                        "type": "string",
+                        "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_.-]*$"
+                      },
+                      "nodeId": {
+                        "type": "string",
+                        "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_.-]*$"
+                      }
+                    },
+                    "required": ["flowId", "nodeId"],
+                    "additionalProperties": false
+                  }
+                }
+              },
+              "required": ["id", "title", "done"],
+              "additionalProperties": false
+            }
+          },
+          "evidence": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "id": {
+                  "type": "string",
+                  "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_.-]*$"
+                },
+                "kind": {
+                  "enum": ["pr", "test", "release", "reference"]
+                },
+                "title": {
+                  "type": "string",
+                  "pattern": "\\S"
+                },
+                "url": {
+                  "type": "string",
+                  "pattern": "\\S"
+                },
+                "state": {
+                  "type": "string"
+                },
+                "revision": {
+                  "type": "string"
+                },
+                "environment": {
+                  "type": "string"
+                },
+                "observedAt": {
+                  "type": "string",
+                  "pattern": "\\S"
+                }
+              },
+              "required": ["id", "kind", "title", "url"],
+              "additionalProperties": false
+            }
+          }
+        },
+        "required": ["status"],
+        "additionalProperties": false
+      }
+    }
+  },
+  "required": ["version", "screens"],
+  "additionalProperties": false
+}

package/skills/ketatlas/SKILL.md

@@ -135,3 +135,9 @@ For local projects, fix structural errors, missing assets, and unreachable nodes
 When browser automation is available, inspect the map and actual HTML at the declared viewport. Exercise each requested flow's primary route and relevant recovery route, and check for console errors and accidental clipping. Audit alone does not prove interaction, appearance, or complete coverage. If browser verification is unavailable, state that limit and still deliver the auditable files.
 
 Update the project's README with flow-to-screen/state coverage, assumptions, demo inputs, and run commands. Return the output location, the serve command or live preview URL, audit results, and any remaining limitations. Do not claim that a mockup implements production APIs or native application behavior.
+
+## Maintain screen delivery progress
+
+When implementing or reviewing screens, track progress in the sibling `<atlas-name>.progress.json`. Use KetAtlas 0.2.0 or newer. Keep version 1 workflow JSON unchanged. Read `ketatlas progress atlas.json --json`, preserve existing evidence/check IDs and state references, then update one record with `--set <screen-id> --record <record.json> --expect <revision>`. Re-read and reconcile conflicts instead of overwriting another writer. Run `audit` after updates.
+
+Map task scope to screen IDs before assigning progress. Start unknown coverage at `unassessed`; a mockup is not implementation evidence. Use `planned`, `in_progress`, `in_review`, `implemented`, `verified` with a separate blocker reason/next action. Link PRs and exact merge commits, pin/release evidence, and test evidence at the revision/environment actually checked. Do not infer deployment, full screen coverage or verification from a PR merge or green aggregate CI. Completed acceptance checks need evidence; `verified` requires passed test evidence with revision and environment for every recorded check and no blocker. Track error/recovery states using check `nodes` references. Leave unrelated or unreviewed product surfaces unassessed and say why. See `docs/progress.md` in the package for the complete contract.