ketatlas 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.2.1
+
+- Show compact numeric progress badges after workflow step counts, with status counts, checklist completion and blockers in tooltips.
+- Place project-wide verified/checklist percentages and blockers next to Screens in the top bar.
+- Deduplicate reused screens and variants, exclude process-only steps, and update the sidebar after saves, refreshes and flow navigation.
+
 ## 0.2.0
 
 - Track delivery per screen in a separate progress JSON, with acceptance checks, blockers, ownership, task references and PR/test/release evidence.

package/README.md

@@ -17,15 +17,15 @@ 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.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
+npx --yes ketatlas@0.2.1 scaffold my-atlas --template web
+npx --yes ketatlas@0.2.1 serve my-atlas/atlas.json
+npx --yes ketatlas@0.2.1 audit my-atlas/atlas.json --strict
 ```
 
 Or install the CLI once for your user account:
 
 ```sh
-npm install --global ketatlas@0.2.0
+npm install --global ketatlas@0.2.1
 ketatlas scaffold my-atlas
 ketatlas serve my-atlas/atlas.json
 ketatlas audit my-atlas/atlas.json --strict

package/docs/progress.md

@@ -2,6 +2,12 @@
 
 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.
 
+## Sidebar and project completion
+
+Project-wide verified/checklist percentages and blocker counts appear in the top bar beside **Screens**. The sidebar shows one compact numeric badge after each workflow’s step count (`2 steps [30%]`). **Verified %** is the number of Verified screens divided by the total unique screens in that scope. Repeated nodes and error variants count once; note/external nodes do not count. Screenless flows have no badge. Percentages round down so unfinished work cannot appear as 100%.
+
+The badge tooltip and accessible label include status counts, blockers and **Checks %**, which counts completed recorded acceptance checks over all recorded checks, with an explicit unscoped-screen count when checklists are missing. This is not an estimate of effort, and 100% of a partial checklist does not make a screen Verified. Saving or refreshing progress updates the sidebar; changing or searching workflows preserves the current progress.
+
 ## Status and scope
 
 | Status      | Meaning                                                                                       |
@@ -63,11 +69,11 @@ Evidence kinds are `pr`, `test`, `release`, `reference`. Required fields: `id`,
 ## 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
+npx --yes ketatlas@0.2.1 serve atlas.json
+npx --yes ketatlas@0.2.1 serve atlas.json --read-only
+npx --yes ketatlas@0.2.1 progress atlas.json --init
+npx --yes ketatlas@0.2.1 progress atlas.json --json
+npx --yes ketatlas@0.2.1 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ketatlas",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Interactive HTML maps for screens, workflows, and user journeys.",
   "type": "module",
   "license": "MIT",

package/skills/ketatlas/SKILL.md

@@ -141,3 +141,5 @@ Update the project's README with flow-to-screen/state coverage, assumptions, dem
 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.
+
+Sidebar percentages distinguish Verified screens from completed recorded checks. Do not assign arbitrary weights to intermediate statuses or remove unknown/unscoped screens to inflate completion. Workflow counts deduplicate screen IDs, including variants; process-only flows have no screen percentage.

package/src/index.d.ts

@@ -170,3 +170,12 @@ export function loadAtlas(
   url: string | URL,
   options?: AtlasOptions,
 ): Promise<AtlasInstance>;
+
+/** Unique-screen delivery and recorded-check completion for one workflow; screenless flows return null percentages. */
+export function summarizeFlowProgress(
+  data: AtlasProgress,
+  flow: AtlasFlow,
+): ReturnType<typeof summarizeProgress> & {
+  verifiedPercent: number | null;
+  checks: { done: number; total: number; unscoped: number; percent: number | null };
+};

package/src/index.js

@@ -1,6 +1,11 @@
 import { mountProgress } from "./progress-ui.js";
 import { emptyProgress, requireProgress } from "./progress.js";
-export { validateProgress, summarizeProgress, progressStatuses } from "./progress.js";
+export {
+  validateProgress,
+  summarizeProgress,
+  summarizeFlowProgress,
+  progressStatuses,
+} from "./progress.js";
 import { normalizeAtlas, safeURL } from "./config.js";
 import { layoutAtlas, edgePath } from "./layout.js";
 import { template, escapeHTML as e } from "./template.js";
@@ -117,6 +122,7 @@ export function createAtlas(container, input, options = {}) {
   world.style.height = height + "px";
   $("map-total").textContent = `${flows.length} flows · ${screens.size} screens`;
   const groups = [...new Set(flows.map((f) => f.group))];
+  let progressUI;
   function sidebar() {
     const q = normalize($("flow-search").value);
     $("flow-list").innerHTML =
@@ -130,10 +136,11 @@ export function createAtlas(container, input, options = {}) {
               ).includes(q),
           );
           return matches.length
-            ? `<section><h2 class="flow-group-title">${e(group)}</h2>${matches.map((f) => `<button class="flow-link ${f === current ? "active" : ""}" data-flow="${f.id}" ${f === current ? 'aria-current="true"' : ""}><span class="flow-number">${String(f.index + 1).padStart(2, "0")}</span><span><strong>${e(f.title)}</strong><small>${f.nodes.length} steps${f.edges.some((a) => a.kind === "recovery") ? " · Recovery branch" : ""}</small></span></button>`).join("")}</section>`
+            ? `<section><h2 class="flow-group-title">${e(group)}</h2>${matches.map((f) => `<button class="flow-link ${f === current ? "active" : ""}" data-flow="${f.id}" ${f === current ? 'aria-current="true"' : ""}><span class="flow-number">${String(f.index + 1).padStart(2, "0")}</span><span class="flow-link-copy"><strong>${e(f.title)}</strong><small>${f.nodes.length} steps <span class="flow-progress" data-progress-flow="${f.id}"></span></small></span></button>`).join("")}</section>`
             : "";
         })
         .join("") || '<p class="mock-filter-empty">No matching workflows.</p>';
+    progressUI?.paintSidebar();
   }
   const defs = `<defs>${[
     ["main", "--kv-accent"],
@@ -544,7 +551,7 @@ export function createAtlas(container, input, options = {}) {
     const n = event.target.closest("[data-node]");
     if (n && !event.target.closest("button")) openScreen(nodeByKey.get(n.dataset.node));
   });
-  const progressUI = mountProgress(root, config, progressData, options, (id) => {
+  progressUI = mountProgress(root, config, progressData, options, (id) => {
     const n = nodes.find((n) => n.screenId === id);
     if (n) {
       setCurrent(flowById.get(n.flowId));

package/src/progress-ui.js

@@ -1,5 +1,11 @@
 import { escapeHTML as e } from "./template.js";
-import { progressFor, progressStatuses, summarizeProgress, requireProgress } from "./progress.js";
+import {
+  progressFor,
+  progressStatuses,
+  summarizeProgress,
+  summarizeFlowProgress,
+  requireProgress,
+} from "./progress.js";
 import { safeURL } from "./config.js";
 const optionsHTML = (values, selected) =>
   Object.entries(values)
@@ -32,7 +38,40 @@ export function mountProgress(root, config, initial, options, selectScreen) {
   const badge = (r) =>
     `<span class="progress-badge" data-status="${e(r.status)}">${e(progressStatuses[r.status])}</span>${r.blocker?.trim() ? '<span class="progress-blocked">Blocked</span>' : ""}`;
   const record = (id) => progressFor(data, id);
+  function paintSidebar() {
+    for (const el of root.querySelectorAll("[data-progress-flow], #project-progress")) {
+      const project = el.id === "project-progress";
+      const flow = project
+        ? { nodes: config.screens.map((s) => ({ screen: s.id })) }
+        : config.flows.find((f) => f.id === el.dataset.progressFlow);
+      const summary = summarizeFlowProgress(data, flow);
+      el.hidden = !summary.total;
+      if (!summary.total) {
+        el.textContent = "";
+        el.removeAttribute("title");
+        el.removeAttribute("aria-label");
+        continue;
+      }
+      const statuses = Object.entries(progressStatuses)
+        .filter(([key]) => summary.counts[key])
+        .map(([key, label]) => `${summary.counts[key]} ${label.toLowerCase()}`)
+        .join(" · ");
+      const checks = summary.checks;
+      const details = `${summary.verifiedPercent}% verified · ${summary.counts.verified}/${summary.total} screens. ${statuses}${summary.blocked ? ` · ${summary.blocked} blocked` : ""}. ${checks.total ? `Checks ${checks.percent}% · ${checks.done}/${checks.total}` : "No checks recorded"}${checks.unscoped ? ` · ${checks.unscoped} unscoped` : ""}.`;
+      if (project) {
+        el.innerHTML = `<span><b>${summary.verifiedPercent}%</b> verified</span><span><b>${checks.percent ?? "—"}${checks.percent === null ? "" : "%"}</b> checks</span>${summary.blocked ? `<span class="project-blocked"><b>${summary.blocked}</b> blocked</span>` : ""}`;
+      } else el.textContent = `${summary.verifiedPercent}%`;
+      el.title = details;
+      el.setAttribute("aria-label", details);
+      el.dataset.tone = summary.blocked
+        ? "blocked"
+        : summary.verifiedPercent === 100
+          ? "complete"
+          : "pending";
+    }
+  }
   function paint() {
+    paintSidebar();
     for (const el of root.querySelectorAll("[data-progress-screen]"))
       el.innerHTML = badge(record(el.dataset.progressScreen));
     const summary = summarizeProgress(data, config.screens);
@@ -243,6 +282,7 @@ export function mountProgress(root, config, initial, options, selectScreen) {
   return {
     edit,
     paint,
+    paintSidebar,
     open() {
       paint();
       $("progress-screens").showModal();

package/src/progress.js

@@ -175,3 +175,27 @@ export function summarizeProgress(data, screens) {
   }
   return { total: screens.length, counts, blocked };
 }
+
+/** Delivery counts deduplicate reusable screens, including repeated error variants. */
+export function summarizeFlowProgress(data, flow) {
+  const ids = [...new Set(flow.nodes.filter((n) => n.screen).map((n) => n.screen))];
+  const summary = summarizeProgress(
+    data,
+    ids.map((id) => ({ id })),
+  );
+  let done = 0,
+    total = 0,
+    unscoped = 0;
+  for (const id of ids) {
+    const checks = progressFor(data, id).checks || [];
+    if (!checks.length) unscoped++;
+    total += checks.length;
+    done += checks.filter((check) => check.done).length;
+  }
+  return {
+    ...summary,
+    // Round down so unfinished work can never display as 100%.
+    verifiedPercent: ids.length ? Math.floor((summary.counts.verified * 100) / ids.length) : null,
+    checks: { done, total, unscoped, percent: total ? Math.floor((done * 100) / total) : null },
+  };
+}

package/src/template.js

@@ -10,7 +10,7 @@ export function template(config) {
       <button id="map-menu" class="icon-button" aria-label="Choose a flow" aria-expanded="false" aria-controls="map-sidebar"></button>
       <div class="map-brand"><span class="brand-mark">K</span><span><strong>${escapeHTML(config.title)}</strong><small>KetAtlas · Workflow atlas</small></span></div>
       <span id="map-total" class="map-total"></span>
-      <div class="map-header-actions"><button id="open-progress" data-ui="action" data-variant="secondary">Screens</button><button id="map-help" class="icon-button" aria-label="Help"></button></div>
+      <div class="map-header-actions"><div id="project-progress" class="project-progress" role="group" aria-label="Project progress"></div><button id="open-progress" data-ui="action" data-variant="secondary">Screens</button><button id="map-help" class="icon-button" aria-label="Help"></button></div>
     </header>
     <div class="map-layout">
       <aside id="map-sidebar" class="map-sidebar">

package/styles/ketatlas.css

@@ -1284,3 +1284,76 @@ a svg {
   color: var(--kv-text-muted);
   font-weight: 400;
 }
+
+/* Compact verified-screen badges; detailed counts live in the tooltip. */
+.flow-link-copy {
+  min-width: 0;
+  flex: 1;
+}
+.flow-progress {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex: none;
+  min-width: 34px;
+  height: 20px;
+  padding: 0 var(--kv-space-1);
+  border-radius: var(--kv-radius-full);
+  background: var(--kv-surface-hover);
+  color: var(--kv-text-muted);
+  font-size: var(--kv-text-2xs);
+  font-weight: var(--kv-weight-medium);
+  font-variant-numeric: tabular-nums;
+  line-height: 1;
+  letter-spacing: normal;
+  white-space: nowrap;
+  vertical-align: middle;
+}
+.flow-progress[hidden] {
+  display: none;
+}
+.flow-progress[data-tone="blocked"] {
+  color: var(--kv-warning);
+}
+.flow-progress[data-tone="complete"] {
+  color: var(--kv-positive);
+}
+
+.project-progress {
+  display: flex;
+  align-items: center;
+  gap: var(--kv-space-3);
+  margin-right: var(--kv-space-2);
+  color: var(--kv-text-muted);
+  font-size: var(--kv-text-xs);
+  font-variant-numeric: tabular-nums;
+  white-space: nowrap;
+}
+.project-progress[hidden] {
+  display: none;
+}
+.project-progress b {
+  color: var(--kv-text-main);
+  font-weight: var(--kv-weight-semibold);
+}
+.project-progress .project-blocked,
+.project-progress .project-blocked b {
+  color: var(--kv-warning);
+}
+@container (max-width: 1000px) {
+  .map-header {
+    height: auto;
+    min-height: 72px;
+    flex-wrap: wrap;
+    gap: var(--kv-space-2);
+  }
+  .map-header-actions {
+    flex-basis: 100%;
+    justify-content: flex-end;
+  }
+  .project-progress {
+    margin-right: auto;
+    gap: var(--kv-space-2);
+    font-size: var(--kv-text-2xs);
+  }
+}

package/templates/basic/README.md

@@ -7,7 +7,7 @@ npx ketatlas serve atlas.json
 npx ketatlas audit atlas.json --strict
 ```
 
-Edit `atlas.json` to change nodes, edges, and screen URLs. Screen URLs are relative to that file. Refresh the browser after editing. No wrapper HTML, package manifest, lockfile, node_modules, or build step is needed. Alternatively, install the CLI once with npm install --global ketatlas@0.2.0 and use ketatlas serve atlas.json.
+Edit `atlas.json` to change nodes, edges, and screen URLs. Screen URLs are relative to that file. Refresh the browser after editing. No wrapper HTML, package manifest, lockfile, node_modules, or build step is needed. Alternatively, install the CLI once with npm install --global ketatlas@0.2.1 and use ketatlas serve atlas.json.
 
 Edit the HTML files in screens/ to replace the sample product. styles/design-system.css is generated from the pinned KetJS design system; do not manually fork its tokens.
 

package/templates/process/README.md

@@ -7,7 +7,7 @@ npx ketatlas serve atlas.json
 npx ketatlas audit atlas.json --strict
 ```
 
-Edit `atlas.json` to change nodes, edges, and screen URLs. Screen URLs are relative to that file. Refresh the browser after editing. No wrapper HTML, package manifest, lockfile, node_modules, or build step is needed. Alternatively, install the CLI once with npm install --global ketatlas@0.2.0 and use ketatlas serve atlas.json.
+Edit `atlas.json` to change nodes, edges, and screen URLs. Screen URLs are relative to that file. Refresh the browser after editing. No wrapper HTML, package manifest, lockfile, node_modules, or build step is needed. Alternatively, install the CLI once with npm install --global ketatlas@0.2.1 and use ketatlas serve atlas.json.
 
 This template models a process without HTML screens. Add a screen registry and screen nodes when needed.
 

package/templates/web/README.md

@@ -7,7 +7,7 @@ npx ketatlas serve atlas.json
 npx ketatlas audit atlas.json --strict
 ```
 
-Edit `atlas.json` to change nodes, edges, and screen URLs. Screen URLs are relative to that file. Refresh the browser after editing. No wrapper HTML, package manifest, lockfile, node_modules, or build step is needed. Alternatively, install the CLI once with npm install --global ketatlas@0.2.0 and use ketatlas serve atlas.json.
+Edit `atlas.json` to change nodes, edges, and screen URLs. Screen URLs are relative to that file. Refresh the browser after editing. No wrapper HTML, package manifest, lockfile, node_modules, or build step is needed. Alternatively, install the CLI once with npm install --global ketatlas@0.2.1 and use ketatlas serve atlas.json.
 
 Edit the HTML files in screens/ to replace the sample product. styles/design-system.css is generated from the pinned KetJS design system; do not manually fork its tokens.