@laitszkin/apollo-toolkit 3.11.5 → 3.11.6

package/CHANGELOG.md

@@ -10,6 +10,24 @@ All notable changes to this repository are documented in this file.
 
 ### Fixed
 
+## [v3.11.6] - 2026-05-12
+
+### Added
+
+- Tests: spec-mode batch-root overlay writes, combined batch diff rendering, legacy HTML-only batch diff fallback, repeated spec render cleanup, and multi-step `undo` coverage for the declarative atlas CLI.
+
+### Changed
+
+- `apltk architecture --spec <spec_dir>` now keeps the existing single-spec layout for standalone plans, but batch member paths resolve to one shared `architecture_diff/` beside `coordination.md` so the whole batch maintains a single overlay and rendered architecture diff.
+- `generate-spec` and `spec-to-project-html` now document the shared batch-root overlay behavior and tighten architecture-diff completion criteria: all intended cross-feature edges, feature-to-feature relationships, and sub-module relationships must be declared explicitly through the CLI instead of being left implicit in prose.
+- Spec-mode atlas persistence now derives overlay state from the merged proposed-after graph, which lets repeated edits collapse back to a minimal diff automatically and adds `apltk architecture undo --steps <n>` for multi-step rollback.
+
+### Fixed
+
+- `apltk architecture diff` now renders batch specs as one combined macro/viewer result instead of showing separate incomplete macro pages per member spec.
+- `apltk architecture diff` preserves compatibility with legacy batch artifacts that only contain rendered HTML plus `_removed.txt`, instead of silently dropping those member diffs when atlas overlay state is absent.
+- Spec-mode scoped renders now clean stale HTML pages and removal state correctly, preventing repeated render/diff runs from crashing on already-removed pages or leaving ghost overlay output behind.
+
 ## [v3.11.5] - 2026-05-12
 
 ### Added

package/generate-spec/SKILL.md

@@ -1,11 +1,14 @@
 ---
 name: generate-spec
 description: >-
-  Author docs/plans trees: run `apltk create-specs`, hydrate `spec/tasks/checklist/contract/design` (+ `coordination.md`/`preparation.md` when parallel/prep dictates), cite official docs for external deps, plan tests via **`test-case-strategy`**, block code edits until explicit user approval.
-  Architecture deltas use `apltk architecture --spec <spec_dir> …` (**flags: `apltk architecture --help`**) → overlay under `<spec_dir>/architecture_diff/`; **`apltk architecture diff`** pages every `docs/plans/**/architecture_diff/` vs the base atlas — never hand-edit `architecture_diff/`.
-  Use when drafting/refreshing specs or restructuring batches — not when executing approved plans (use **`implement-specs*`** instead).
-  Reject vague `tasks.md` missing file/mutation/verifier; SPLIT >3-module scope; never overwrite a neighbor `{change}`.
-  Bad: `- [ ] Add tests`… OK: `- [ ] src/auth/scope.rs — deny unknown scopes — Verify: cargo test scope::defaults`…
+  Author docs/plans trees: run `apltk create-specs`, fill `spec/tasks/checklist/contract/design`
+  (+ `coordination.md`/`preparation.md` for batches), cite official docs, plan tests via
+  **`test-case-strategy`**, and block code edits until approval. Architecture deltas use
+  `apltk architecture --spec <spec_dir> …`: single specs write under `<spec_dir>/architecture_diff/`,
+  while batch member paths resolve to the shared batch-root `architecture_diff/` beside
+  `coordination.md`; `apltk architecture diff` renders the before/after viewer. Use for
+  drafting/refreshing specs or restructuring batches, not execution. Reject vague `tasks.md`
+  rows and split scope beyond 3 modules.
 ---
 
 # Generate Spec
@@ -27,7 +30,7 @@ description: >-
 - **`tasks.md` checklist items**: **every** `- [ ]` **MUST** specify (a) concrete file/function target, (b) specific modification and expected outcome, (c) a verification hook—**no** vague rows (`Implement integration`, `Add tests`). Forbidden vague items **MUST** be rewritten before approval.
 - **MUST** use `test-case-strategy` when planning non-trivial logic tests and checklist mapping (test IDs, drift checks). Every **non-trivial** `tasks.md` implementation item **MUST** name a focused unit drift check, another concrete verification hook, or **`N/A`** with a concrete reason.
 - **MUST NOT** modify implementation code before **explicit user approval** of the spec set. Clarifications **MUST** sync across affected files and **MUST** re-trigger approval. If scope becomes a **different issue**, **MUST** stop editing the old set and create a **new** `change_name`.
-- **MUST** when the proposed change touches the architecture surface (feature / sub-module add / rename / remove, edge add / remove, variable rows, function I/O rows, internal dataflow / error deltas), declare the proposed-after state **only** through `apltk architecture --spec <spec_dir> …` using the exact verbs, subverbs, and flags from **`apltk architecture --help`** (this file must not be treated as the command list). The CLI writes overlay YAML to `<spec_dir>/architecture_diff/atlas/` and renders only the affected proposed-after HTML pages under `<spec_dir>/architecture_diff/`. **`apltk architecture diff`** then builds a paginated **before/after viewer**: it walks every `docs/plans/**/architecture_diff/` tree, pairs each overlay HTML path with the matching file under `resources/project-architecture/` when it exists, and labels pages **modified**, **added**, or **removed** (via `_removed.txt` / removal manifests) so reviewers can scroll the whole architecture delta without opening files by hand. **MUST NOT** hand-author anything under `architecture_diff/**` — the renderer owns layout, DOM, CSS, ARIA, and pan/zoom. For batch specs the overlay lives in **each member spec’s own directory** only — **MUST NOT** duplicate overlay at the batch root. Use this skill’s `references/TEMPLATE_SPEC.md` for field/enum schema; use `init-project-html/SKILL.md` for semantic rules (**subagent gate** + edge kinds + dataflow integrity). When using subagents to draft atlas overlay, the authoring agent **MUST** wait until **all** feature subagents finish before declaring cross-feature **`edge`** (or overlay **`meta`** / **`actor`** that only exists to stitch features), matching `init-project-html` / `spec-to-project-html`.
+- **MUST** when the proposed change touches the architecture surface (feature / sub-module add / rename / remove, edge add / remove, variable rows, function I/O rows, internal dataflow / error deltas), declare the proposed-after state **only** through `apltk architecture --spec <spec_dir> …` using the exact verbs, subverbs, and flags from **`apltk architecture --help`** (this file must not be treated as the command list). The CLI writes overlay YAML to `<spec_dir>/architecture_diff/atlas/` and renders only the affected proposed-after HTML pages under `<spec_dir>/architecture_diff/` for single-spec plans. For batch plans, passing any member spec path to `--spec` resolves to the shared batch-root overlay beside `coordination.md`, so the whole batch maintains **one** `architecture_diff/atlas/` and **one** rendered architecture diff. **`apltk architecture diff`** then builds a paginated **before/after viewer**: it walks every `docs/plans/**/architecture_diff/` tree, pairs each overlay HTML path with the matching file under `resources/project-architecture/` when it exists, and labels pages **modified**, **added**, or **removed** (via `_removed.txt` / removal manifests) so reviewers can scroll the whole architecture delta without opening files by hand. **MUST NOT** hand-author anything under `architecture_diff/**` — the renderer owns layout, DOM, CSS, ARIA, and pan/zoom. Use this skill’s `references/TEMPLATE_SPEC.md` for field/enum schema; use `init-project-html/SKILL.md` for semantic rules (**subagent gate** + edge kinds + dataflow integrity). When using subagents to draft atlas overlay, the authoring agent **MUST** wait until **all** feature subagents finish before declaring cross-feature **`edge`** (or overlay **`meta`** / **`actor`** that only exists to stitch features), matching `init-project-html` / `spec-to-project-html`.
 - Write prose in the **user’s language** by default; keep requirement/task/test IDs traceable across `spec.md`, `tasks.md`, and `checklist.md`.
 - **MUST** use **kebab-case** `change_name`; **MUST NOT** use spaces or arbitrary special characters in names.
 
@@ -85,15 +88,15 @@ Always materialize: `spec.md`, `tasks.md`, `checklist.md`, `contract.md`, `desig
 
 When the spec changes a feature module, sub-module, edge, variable row, function I/O row, internal dataflow, or error row:
 
-1. **Discover commands:** run **`apltk architecture --help`** in the target workspace; use that output for every `add` / `set` / `remove` / `reorder` spelling and required flag. Do not copy long command tables from skills — they go stale.
-2. **Declare proposed-after state** with `apltk architecture --spec <spec_dir> …` for each mutation (pass `--no-render` while batching if you prefer a single render at the end).
-3. **`apltk architecture render --spec <spec_dir>`** — emits/updates only the HTML files touched by this overlay plus assets.
-4. **`apltk architecture validate --spec <spec_dir>`** — **MUST** return OK before the spec is approval-ready (resolve dangling edges, unknown enums, bad dataflow references).
-5. **`apltk architecture diff`** — **MUST** run before hand-off when atlas changed; confirm the paginated viewer shows sensible **modified** / **added** / **removed** counts and that each interesting path pairs correctly (base `resources/project-architecture/…` vs `<spec_dir>/architecture_diff/…`). A page appearing as **remove + add** instead of **modified** usually means a **slug rename** was split wrong — fix with intentional remove+add or a single coherent mutation sequence.
+**Completion standard:** the overlay is not complete until every intended cross-feature **edge**, every feature-to-feature dependency or call/return relationship, and every sub-module-to-sub-module relationship inside the affected scope has been declared precisely through the CLI. It is **not** acceptable to leave relationship structure implied only by prose in `spec.md` / `design.md`; the architecture diff must explicitly express the real proposed-after topology.
 
-**Where files land:** overlay YAML under `<spec_dir>/architecture_diff/atlas/`; rendered proposed-after HTML under `<spec_dir>/architecture_diff/`. Cross-feature edges whose far endpoint exists only in the **base** atlas still resolve when merged — but you **must** `validate` to catch mistakes.
+1. **Discover commands:** run **`apltk architecture --help`** in the target workspace; use that output for every `add` / `set` / `remove` / `reorder` spelling and required flag. Do not copy long command tables from skills — they go stale.
+2. **Declare proposed-after state** with `apltk architecture --spec <spec_dir> …` for each mutation (pass `--no-render` while batching if you prefer a single render at the end). In a batch, keep using the member spec path; the CLI resolves writes to the batch-root `architecture_diff/` beside `coordination.md`.
+3. **`apltk architecture render --spec <spec_dir>`** — emits/updates only the HTML files touched by this overlay plus assets. In a batch, this updates the shared batch-root render.
+4. **`apltk architecture validate --spec <spec_dir>`** — **MUST** return OK before the spec is approval-ready (resolve dangling edges, unknown enums, bad dataflow references). In a batch, this validates the shared batch-root overlay.
+5. **`apltk architecture diff`** — **MUST** run before hand-off when atlas changed; confirm the paginated viewer shows sensible **modified** / **added** / **removed** counts and that each interesting path pairs correctly (base `resources/project-architecture/…` vs the spec or batch-root `architecture_diff/…`). Use this pass to verify that the rendered graph actually contains the full intended relationship set: all relevant feature-level seams, all required sub-module seams, and no missing edge that the design prose depends on. A page appearing as **remove + add** instead of **modified** usually means a **slug rename** was split wrong — fix with intentional remove+add or a single coherent mutation sequence.
 
-**Batch specs:** each `<spec_dir>` is one member directory under `docs/plans/...`; **never** duplicate overlay at the batch root.
+**Where files land:** single-spec plans write overlay YAML under `<spec_dir>/architecture_diff/atlas/` and rendered proposed-after HTML under `<spec_dir>/architecture_diff/`. Batch plans write both under the batch root beside `coordination.md`, even when the CLI call uses a member spec path. Cross-feature edges whose far endpoint exists only in the **base** atlas still resolve when merged — but you **must** `validate` to catch mistakes.
 
 **Subagent coordination:** if multiple features are drafted in parallel, **do not** declare cross-feature **`edge`** (or overlay **`meta` / `actor`** used only to stitch features) until **all** feature workers report done — see `init-project-html/SKILL.md` Rule 3 and `spec-to-project-html`.
 
@@ -102,6 +105,7 @@ When the spec changes a feature module, sub-module, edge, variable row, function
 - **Pause →** Did I touch any file under `architecture_diff/` by hand? Revert and re-run the CLI verb instead.
 - **Pause →** Does `apltk architecture validate --spec <spec_dir>` return OK?
 - **Pause →** Does `apltk architecture diff` pair the spec’s pages correctly?
+- **Pause →** Have I explicitly declared every intended edge, feature-to-feature relationship, and sub-module relationship in the CLI output, or am I still relying on prose to imply missing structure?
 
 ### 4) Clarifications and approval
 

package/generate-spec/agents/openai.yaml

@@ -4,7 +4,7 @@ interface:
   default_prompt: >-
     Use $generate-spec to create or update single-spec plans under docs/plans/<date>/<change_name>/ or parallel batches under docs/plans/<date>/<batch_name>/<change_name>/ with shared coordination.md and, only when specs cannot be parallel-safe without prior shared work, minimal non-business preparation.md; treat references/templates/*.md as binding format; member specs assume preparation finished—do not duplicate preparation tasks; surface collisions early and resolve ownership via coordination.md; fill BDD in spec.md; integrate $test-case-strategy into tasks/checklists.
     **Critical layering:** design.md + contract.md are higher-level guiding context only (architecture + cite-backed external truth; coarse INT-### / EXT-### anchors). tasks.md MUST be the ONLY enumerated runnable queue with path-level edits and verification hooks—derive tasks FROM spec + design + contract WITHOUT mirroring checklist rows into design/contract; optionally cite INT/EXT on task lines for traceability—never duplicate task choreography inside design.md or contract.md.
-    **Architecture overlay + diff:** When the spec touches atlas surface (feature/sub-module, edges, function/variable rows, dataflow, errors), declare proposed-after state ONLY via `apltk architecture --spec <spec_dir> …`. **Exact verbs/flags: ALWAYS `apltk architecture --help`.** CLI writes `<spec_dir>/architecture_diff/atlas/` + renders affected HTML under `<spec_dir>/architecture_diff/`. NEVER hand-author `architecture_diff/**`.
-    After mutations: `render --spec`, `validate --spec` (must be OK pre-approval). **`apltk architecture diff`** opens the paginated before/after viewer over all `docs/plans/**/architecture_diff/` vs base `resources/project-architecture/` — run it when atlas changed; verify modified/added/removed pairing.
-    Batch specs: one overlay per member directory—never at batch root. If subagents draft multiple features: **wait until ALL finish** before cross-feature `edge` / stitching `meta` / `actor` (same gate as $init-project-html / $spec-to-project-html).
+    **Architecture overlay + diff:** When the spec touches atlas surface (feature/sub-module, edges, function/variable rows, dataflow, errors), declare proposed-after state ONLY via `apltk architecture --spec <spec_dir> …`. **Exact verbs/flags: ALWAYS `apltk architecture --help`.** Single-spec plans write `<spec_dir>/architecture_diff/atlas/` + rendered HTML under `<spec_dir>/architecture_diff/`. Batch plans resolve any member `--spec` path to the shared batch-root `architecture_diff/` beside `coordination.md`, so the whole batch keeps one architecture diff. NEVER hand-author `architecture_diff/**`.
+    Completion standard for atlas work: every intended cross-feature edge, every feature-to-feature relationship, and every sub-module relationship in scope must be expressed precisely through the CLI output — not left implicit in prose. After mutations: `render --spec`, `validate --spec` (must be OK pre-approval). **`apltk architecture diff`** opens the paginated before/after viewer over all `docs/plans/**/architecture_diff/` vs base `resources/project-architecture/` — run it when atlas changed; verify modified/added/removed pairing and confirm the rendered graph contains the full intended relationship set.
+    If subagents draft multiple features: **wait until ALL finish** before cross-feature `edge` / stitching `meta` / `actor` (same gate as $init-project-html / $spec-to-project-html).
     Field/enums: this skill's references/TEMPLATE_SPEC.md. Semantics: $init-project-html SKILL.md.

package/init-project-html/lib/atlas/cli.js

@@ -23,7 +23,7 @@
 //
 // Global flags:
 //   --project <root>     project root; creates resources/project-architecture/ if missing
-//   --spec <spec_dir>    spec directory; mutations go to <spec_dir>/architecture_diff/atlas/
+//   --spec <spec_dir>    single specs write to <spec_dir>/architecture_diff/atlas/; batch member paths resolve to the coordination.md root
 //   --no-render          skip auto-render after a mutation
 //   --no-open            for open/diff: skip launching the browser
 //   --out <dir>          for diff: override viewer output directory
@@ -41,6 +41,7 @@ const ATLAS_INDEX_REL = path.join(ATLAS_REL, 'index.html');
 const ATLAS_DIRNAME = stateLib.ATLAS_DIRNAME;
 const DIFF_DIRNAME = 'architecture_diff';
 const PLANS_REL = path.join('docs', 'plans');
+const COORDINATION_FILE = 'coordination.md';
 const REMOVED_TXT = '_removed.txt';
 const DEFAULT_DIFF_OUT_REL = path.join('.apollo-toolkit', 'architecture-diff');
 
@@ -63,12 +64,12 @@ Verbs:
   meta set                              edit meta.title / meta.summary
   actor add|remove                      manage top-level actors
   validate                              run schema + referential checks
-  undo                                  revert the most recent mutation
+  undo                                  revert the most recent mutation (use --steps <n> for multi-step rollback)
   help                                  show this help
 
 Global flags:
   --project <root>                      explicit project root (default: nearest ancestor with atlas markers, else cwd); missing directories under resources/project-architecture/ are created automatically
-  --spec <spec_dir>                     mutations write to <spec_dir>/architecture_diff/atlas/
+  --spec <spec_dir>                     single specs write to <spec_dir>/architecture_diff/atlas/; batch member paths write to the coordination.md root
   --no-render                           skip auto-render after a mutation
   --no-open                             for open/diff: skip launching the browser
   --out <dir>                           for diff: override viewer output directory
@@ -81,6 +82,7 @@ Examples:
   apltk architecture dataflow add --feature register --submodule api --step "Validate body" --fn handlePost --reads "body" --writes "token"
   apltk architecture --spec docs/plans/2026-05-11/add-2fa submodule set --feature register --slug api --role "..."
   apltk architecture validate
+  apltk architecture undo --steps 3 --spec docs/plans/2026-05-11/add-2fa
   apltk architecture diff
 `;
 
@@ -171,7 +173,15 @@ function resolveProjectRoot(flags) {
 
 function specOverlayDir(projectRoot, specFlag) {
   const specDir = path.isAbsolute(String(specFlag)) ? String(specFlag) : path.resolve(projectRoot, String(specFlag));
-  return { specDir, overlayDir: path.join(specDir, DIFF_DIRNAME, ATLAS_DIRNAME), htmlOutDir: path.join(specDir, DIFF_DIRNAME) };
+  const plansRoot = path.join(projectRoot, PLANS_REL);
+  const batchRoot = fs.existsSync(path.join(specDir, COORDINATION_FILE)) ? specDir : findBatchRoot(specDir, plansRoot);
+  const rootDir = batchRoot || specDir;
+  return {
+    specDir,
+    rootDir,
+    overlayDir: path.join(rootDir, DIFF_DIRNAME, ATLAS_DIRNAME),
+    htmlOutDir: path.join(rootDir, DIFF_DIRNAME),
+  };
 }
 
 function baseAtlasDir(projectRoot) {
@@ -207,26 +217,21 @@ function ensureBaseAtlasDir(projectRoot) {
 async function performMutation(projectRoot, flags, action, args, mutate) {
   const isSpec = Boolean(flags.spec);
   const base = stateLib.load(baseAtlasDir(projectRoot));
-  let overlay = null;
   let merged = base;
-  let touchedFeatureSlugs = new Set();
 
   if (isSpec) {
     const { overlayDir } = specOverlayDir(projectRoot, flags.spec);
-    overlay = stateLib.loadOverlay(overlayDir);
+    const overlay = stateLib.loadOverlay(overlayDir);
     merged = stateLib.mergeOverlay(base, overlay);
     const before = JSON.parse(JSON.stringify({ base, overlay }));
-    const result = mutate(merged, base, overlay) || {};
-    if (result.touchedFeatures) for (const slug of result.touchedFeatures) touchedFeatureSlugs.add(slug);
+    mutate(merged, base, overlay);
     stateLib.writeUndoSnapshot(overlayDir, before);
-    syncOverlayFromMerged({ base, overlay, merged, touchedFeatureSlugs, removalsHint: result.removalsHint });
-    stateLib.saveOverlay(overlayDir, overlay);
+    stateLib.saveOverlay(overlayDir, stateLib.deriveOverlay(base, merged));
     stateLib.appendHistory(overlayDir, { action, args, mode: 'spec' });
   } else {
     ensureBaseAtlasDir(projectRoot);
     const before = JSON.parse(JSON.stringify({ base }));
-    const result = mutate(base, base, null) || {};
-    if (result.touchedFeatures) for (const slug of result.touchedFeatures) touchedFeatureSlugs.add(slug);
+    mutate(base, base, null);
     stateLib.writeUndoSnapshot(baseAtlasDir(projectRoot), before);
     stateLib.save(baseAtlasDir(projectRoot), base);
     stateLib.appendHistory(baseAtlasDir(projectRoot), { action, args, mode: 'base' });
@@ -237,47 +242,6 @@ async function performMutation(projectRoot, flags, action, args, mutate) {
   }
 }
 
-function syncOverlayFromMerged({ base, overlay, merged, touchedFeatureSlugs, removalsHint }) {
-  // Compare merged top-level fields against base; if they differ, sync into overlay.
-  if (JSON.stringify(merged.meta || {}) !== JSON.stringify(base.meta || {})) overlay.meta = merged.meta;
-  if (JSON.stringify(merged.actors || []) !== JSON.stringify(base.actors || [])) overlay.actors = merged.actors || [];
-  if (JSON.stringify(merged.edges || []) !== JSON.stringify(base.edges || [])) overlay.edges = merged.edges || [];
-
-  const baseOrder = (base.features || []).map((f) => f.slug);
-  const mergedOrder = (merged.features || []).map((f) => f.slug);
-  if (JSON.stringify(baseOrder) !== JSON.stringify(mergedOrder)) {
-    overlay.featureOrder = mergedOrder;
-  }
-
-  // Persist touched (or simply differing) features into overlay.features
-  const baseFeatureMap = new Map((base.features || []).map((f) => [f.slug, f]));
-  const mergedFeatureMap = new Map((merged.features || []).map((f) => [f.slug, f]));
-  for (const slug of touchedFeatureSlugs) {
-    if (!mergedFeatureMap.has(slug)) continue;
-    const baseFeat = baseFeatureMap.get(slug);
-    const mergedFeat = mergedFeatureMap.get(slug);
-    if (!baseFeat || JSON.stringify(baseFeat) !== JSON.stringify(mergedFeat)) {
-      overlay.features[slug] = mergedFeat;
-    }
-  }
-  // Apply hinted removals
-  if (removalsHint) {
-    if (Array.isArray(removalsHint.features)) {
-      const seen = new Set(overlay.removed.features || []);
-      for (const slug of removalsHint.features) seen.add(slug);
-      overlay.removed.features = [...seen];
-      // also drop from overlay.features if present
-      for (const slug of removalsHint.features) delete overlay.features[slug];
-    }
-    if (Array.isArray(removalsHint.submodules)) {
-      const seen = new Map();
-      for (const item of overlay.removed.submodules || []) seen.set(`${item.feature}::${item.submodule}`, item);
-      for (const item of removalsHint.submodules) seen.set(`${item.feature}::${item.submodule}`, item);
-      overlay.removed.submodules = [...seen.values()];
-    }
-  }
-}
-
 async function runRender({ projectRoot, flags }) {
   if (flags.spec) {
     const { overlayDir, htmlOutDir } = specOverlayDir(projectRoot, flags.spec);
@@ -642,9 +606,14 @@ async function verbValidate(flags, projectRoot, io) {
 
 async function verbUndo(flags, projectRoot, io) {
   const dir = flags.spec ? specOverlayDir(projectRoot, flags.spec).overlayDir : baseAtlasDir(projectRoot);
-  const snapshot = stateLib.readUndoSnapshot(dir);
+  const stepsRaw = flags.steps === undefined ? 1 : Number(flags.steps);
+  if (!Number.isInteger(stepsRaw) || stepsRaw < 1) {
+    io.stderr.write('--steps must be a positive integer.\n');
+    return 1;
+  }
+  const snapshot = stateLib.consumeUndoSnapshot(dir, stepsRaw);
   if (!snapshot) {
-    io.stderr.write('No undo snapshot found.\n');
+    io.stderr.write(stepsRaw === 1 ? 'No undo snapshot found.\n' : `Unable to undo ${stepsRaw} steps; history is shorter.\n`);
     return 1;
   }
   if (flags.spec) {
@@ -655,9 +624,8 @@ async function verbUndo(flags, projectRoot, io) {
     stateLib.save(baseAtlasDir(projectRoot), snapshot.base);
     stateLib.appendHistory(baseAtlasDir(projectRoot), { action: 'undo', mode: 'base' });
   }
-  stateLib.clearUndoSnapshot(dir);
   if (!flags['no-render']) await runRender({ projectRoot, flags });
-  io.stdout.write('atlas: undo applied\n');
+  io.stdout.write(`atlas: undo applied (${stepsRaw} step${stepsRaw === 1 ? '' : 's'})\n`);
   return 0;
 }
 
@@ -678,36 +646,27 @@ async function verbOpen(flags, projectRoot, io) {
 async function verbDiff(flags, projectRoot, io) {
   const outDir = flags.out ? path.resolve(String(flags.out)) : path.join(projectRoot, DEFAULT_DIFF_OUT_REL);
   fs.mkdirSync(outDir, { recursive: true });
+  const changes = await collectDiffChanges({ projectRoot, outDir });
 
+  const html = renderDiffViewer({ changes, projectRoot, outDir });
+  const indexPath = path.join(outDir, 'index.html');
+  fs.writeFileSync(indexPath, html, 'utf8');
+  io.stdout.write(`${indexPath}\n`);
+  io.stdout.write(`Diff pages: ${changes.length} (modified=${changes.filter((c) => c.kind === 'modified').length}, added=${changes.filter((c) => c.kind === 'added').length}, removed=${changes.filter((c) => c.kind === 'removed').length})\n`);
+  if (!flags['no-open']) openInBrowser(indexPath);
+  return 0;
+}
+
+async function collectDiffChanges({ projectRoot, outDir }) {
   const plansRoot = path.join(projectRoot, PLANS_REL);
-  const diffDirs = walkArchitectureDiffDirs(plansRoot);
-  const resourcesRoot = path.join(projectRoot, ATLAS_REL);
+  const groups = groupDiffDirsByBatch({ projectRoot, plansRoot });
   const changes = [];
 
-  for (const diffDir of diffDirs) {
-    const specDir = path.dirname(diffDir);
-    const specLabel = path.relative(projectRoot, specDir);
-    for (const after of walkAfterStateHtml(diffDir)) {
-      const beforeAbs = path.join(resourcesRoot, after.rel);
-      const beforeExists = fs.existsSync(beforeAbs);
-      changes.push({
-        kind: beforeExists ? 'modified' : 'added',
-        rel: after.rel,
-        spec: specLabel,
-        beforePath: beforeExists ? path.relative(projectRoot, beforeAbs) : null,
-        afterPath: path.relative(projectRoot, after.abs),
-      });
-    }
-    for (const removedRel of readRemovedManifest(diffDir)) {
-      const beforeAbs = path.join(resourcesRoot, removedRel);
-      if (!fs.existsSync(beforeAbs)) continue;
-      changes.push({
-        kind: 'removed',
-        rel: removedRel,
-        spec: specLabel,
-        beforePath: path.relative(projectRoot, beforeAbs),
-        afterPath: null,
-      });
+  for (const group of groups) {
+    if (group.kind === 'batch') {
+      changes.push(...await collectBatchGroupChanges({ projectRoot, outDir, group }));
+    } else {
+      changes.push(...collectSingleSpecChanges({ projectRoot, specDir: group.specDir, specLabel: group.label }));
     }
   }
 
@@ -716,14 +675,171 @@ async function verbDiff(flags, projectRoot, io) {
     if (a.kind !== b.kind) return a.kind.localeCompare(b.kind);
     return a.rel.localeCompare(b.rel);
   });
+  return changes;
+}
 
-  const html = renderDiffViewer({ changes, projectRoot, outDir });
-  const indexPath = path.join(outDir, 'index.html');
-  fs.writeFileSync(indexPath, html, 'utf8');
-  io.stdout.write(`${indexPath}\n`);
-  io.stdout.write(`Diff pages: ${changes.length} (modified=${changes.filter((c) => c.kind === 'modified').length}, added=${changes.filter((c) => c.kind === 'added').length}, removed=${changes.filter((c) => c.kind === 'removed').length})\n`);
-  if (!flags['no-open']) openInBrowser(indexPath);
-  return 0;
+function groupDiffDirsByBatch({ projectRoot, plansRoot }) {
+  const groups = new Map();
+  for (const diffDir of walkArchitectureDiffDirs(plansRoot)) {
+    const specDir = path.dirname(diffDir);
+    const batchRoot = findBatchRoot(specDir, plansRoot);
+    const isBatchMember = Boolean(batchRoot && batchRoot !== specDir);
+    const key = isBatchMember ? batchRoot : specDir;
+    if (!groups.has(key)) {
+      groups.set(key, {
+        kind: isBatchMember ? 'batch' : 'single',
+        key,
+        label: path.relative(projectRoot, key),
+        specDir: isBatchMember ? null : specDir,
+        members: [],
+      });
+    }
+    groups.get(key).members.push({ specDir, diffDir, label: path.relative(projectRoot, specDir) });
+  }
+  return [...groups.values()]
+    .map((group) => ({ ...group, members: group.members.sort((a, b) => a.specDir.localeCompare(b.specDir)) }))
+    .sort((a, b) => a.key.localeCompare(b.key));
+}
+
+function findBatchRoot(specDir, plansRoot) {
+  const absolutePlansRoot = path.resolve(plansRoot);
+  let current = path.resolve(path.dirname(specDir));
+  while (current.startsWith(`${absolutePlansRoot}${path.sep}`) || current === absolutePlansRoot) {
+    if (fs.existsSync(path.join(current, COORDINATION_FILE))) return current;
+    if (current === absolutePlansRoot) break;
+    current = path.dirname(current);
+  }
+  return null;
+}
+
+function collectSingleSpecChanges({ projectRoot, specDir, specLabel }) {
+  const overlayDir = path.join(specDir, DIFF_DIRNAME, ATLAS_DIRNAME);
+  if (!hasOverlayState(overlayDir)) {
+    return collectHtmlManifestChanges({ projectRoot, diffDir: path.join(specDir, DIFF_DIRNAME), specLabel });
+  }
+  const base = stateLib.load(baseAtlasDir(projectRoot));
+  const overlay = stateLib.loadOverlay(overlayDir);
+  const merged = stateLib.mergeOverlay(base, overlay);
+  const diff = stateLib.diffPages(base, merged);
+  return diffToChanges({
+    projectRoot,
+    specLabel,
+    htmlRoot: path.join(specDir, DIFF_DIRNAME),
+    diff,
+  });
+}
+
+function hasOverlayState(overlayDir) {
+  return fs.existsSync(path.join(overlayDir, stateLib.INDEX_FILE))
+    || fs.existsSync(path.join(overlayDir, stateLib.FEATURES_DIR))
+    || fs.existsSync(path.join(overlayDir, stateLib.REMOVED_FILE));
+}
+
+async function collectBatchGroupChanges({ projectRoot, outDir, group }) {
+  const batchRootOverlayDir = path.join(group.key, DIFF_DIRNAME, ATLAS_DIRNAME);
+  if (hasOverlayState(batchRootOverlayDir)) {
+    return collectSingleSpecChanges({ projectRoot, specDir: group.key, specLabel: group.label });
+  }
+
+  const memberOverlayDirs = group.members.map((member) => ({
+    ...member,
+    overlayDir: path.join(member.specDir, DIFF_DIRNAME, ATLAS_DIRNAME),
+  }));
+  if (memberOverlayDirs.some((member) => !hasOverlayState(member.overlayDir))) {
+    return group.members.flatMap((member) => (
+      collectSingleSpecChanges({ projectRoot, specDir: member.specDir, specLabel: member.label })
+    ));
+  }
+
+  const base = stateLib.load(baseAtlasDir(projectRoot));
+  let merged = JSON.parse(JSON.stringify(base));
+  for (const member of memberOverlayDirs) {
+    const overlay = stateLib.loadOverlay(member.overlayDir);
+    merged = stateLib.mergeOverlay(merged, overlay);
+  }
+  const diff = stateLib.diffPages(base, merged);
+  const htmlRoot = path.join(outDir, '_batch', group.label);
+  await renderLib.renderAll({
+    outDir: htmlRoot,
+    state: merged,
+    scope: renderLib.scopeFromDiff(diff),
+    removedPaths: renderLib.removedPagePathsFromDiff(diff),
+  });
+  return diffToChanges({
+    projectRoot,
+    specLabel: group.label,
+    htmlRoot,
+    diff,
+  });
+}
+
+function diffToChanges({ projectRoot, specLabel, htmlRoot, diff }) {
+  const resourcesRoot = path.join(projectRoot, ATLAS_REL);
+  const changes = [];
+  const add = (kind, rel) => {
+    const beforeAbs = path.join(resourcesRoot, rel);
+    const afterAbs = kind === 'removed' ? null : path.join(htmlRoot, rel);
+    if (kind === 'removed' && !fs.existsSync(beforeAbs)) return;
+    changes.push({
+      kind,
+      rel,
+      spec: specLabel,
+      beforePath: kind === 'added' ? null : path.relative(projectRoot, beforeAbs),
+      afterPath: afterAbs ? path.relative(projectRoot, afterAbs) : null,
+    });
+  };
+
+  if (diff.macroChanged) {
+    add('modified', renderLib.pagePathFor('macro'));
+  }
+  for (const slug of diff.modifiedFeatures || []) {
+    add('modified', renderLib.pagePathFor('feature', { featureSlug: slug }));
+  }
+  for (const slug of diff.addedFeatures || []) {
+    add('added', renderLib.pagePathFor('feature', { featureSlug: slug }));
+  }
+  for (const item of diff.modifiedSubmodules || []) {
+    add('modified', renderLib.pagePathFor('submodule', { featureSlug: item.feature, submoduleSlug: item.submodule }));
+  }
+  for (const item of diff.addedSubmodules || []) {
+    add('added', renderLib.pagePathFor('submodule', { featureSlug: item.feature, submoduleSlug: item.submodule }));
+  }
+  for (const slug of diff.removedFeatures || []) {
+    add('removed', renderLib.pagePathFor('feature', { featureSlug: slug }));
+  }
+  for (const item of diff.removedSubmodules || []) {
+    add('removed', renderLib.pagePathFor('submodule', { featureSlug: item.feature, submoduleSlug: item.submodule }));
+  }
+
+  return changes;
+}
+
+function collectHtmlManifestChanges({ projectRoot, diffDir, specLabel }) {
+  const resourcesRoot = path.join(projectRoot, ATLAS_REL);
+  const changes = [];
+  for (const after of walkAfterStateHtml(diffDir)) {
+    const beforeAbs = path.join(resourcesRoot, after.rel);
+    const beforeExists = fs.existsSync(beforeAbs);
+    changes.push({
+      kind: beforeExists ? 'modified' : 'added',
+      rel: after.rel,
+      spec: specLabel,
+      beforePath: beforeExists ? path.relative(projectRoot, beforeAbs) : null,
+      afterPath: path.relative(projectRoot, after.abs),
+    });
+  }
+  for (const removedRel of readRemovedManifest(diffDir)) {
+    const beforeAbs = path.join(resourcesRoot, removedRel);
+    if (!fs.existsSync(beforeAbs)) continue;
+    changes.push({
+      kind: 'removed',
+      rel: removedRel,
+      spec: specLabel,
+      beforePath: path.relative(projectRoot, beforeAbs),
+      afterPath: null,
+    });
+  }
+  return changes;
 }
 
 function walkArchitectureDiffDirs(plansRoot) {
@@ -1021,6 +1137,7 @@ module.exports = {
   specOverlayDir,
   runRender,
   walkArchitectureDiffDirs,
+  collectDiffChanges,
   walkAfterStateHtml,
   readRemovedManifest,
   renderDiffViewer,

package/init-project-html/lib/atlas/render.js

@@ -560,11 +560,40 @@ async function renderAll({ outDir, state, scope = null, removedPaths = [] }) {
   // do not linger with the previous (broken) markup or styling.
   if (!scope) {
     sweepOrphanFeaturePages(outDir, state);
+  } else {
+    sweepScopedHtml(outDir, new Set(written.map((file) => file.split(path.sep).join('/'))));
   }
 
   return { written, layout };
 }
 
+function sweepScopedHtml(outDir, keepPaths) {
+  function recurse(dir) {
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch (_e) { return; }
+    for (const entry of entries) {
+      if (entry.name === 'assets' || entry.name === 'atlas' || entry.name.startsWith('.')) continue;
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        recurse(full);
+        let remaining;
+        try { remaining = fs.readdirSync(full); } catch (_e) { remaining = null; }
+        if (remaining && remaining.length === 0) {
+          fs.rmSync(full, { recursive: true, force: true });
+        }
+        continue;
+      }
+      if (!entry.isFile() || !entry.name.toLowerCase().endsWith('.html')) continue;
+      const rel = path.relative(outDir, full).split(path.sep).join('/');
+      if (!keepPaths.has(rel)) {
+        fs.rmSync(full, { force: true });
+      }
+    }
+  }
+
+  recurse(outDir);
+}
+
 function sweepOrphanFeaturePages(outDir, state) {
   const featuresRoot = path.join(outDir, 'features');
   if (!fs.existsSync(featuresRoot)) return;

package/init-project-html/lib/atlas/state.js

@@ -26,6 +26,7 @@ const REMOVED_FILE = '_removed.yaml';
 const FEATURES_DIR = 'features';
 const HISTORY_FILE = 'atlas.history.log';
 const UNDO_FILE = 'atlas.history.undo.json';
+const UNDO_STACK_FILE = 'atlas.history.undo.stack.json';
 const ATLAS_DIRNAME = 'atlas';
 
 function readYaml(file) {
@@ -257,6 +258,51 @@ function mergeOverlay(base, overlay) {
   return merged;
 }
 
+function deriveOverlay(base, merged) {
+  const overlay = {
+    meta: null,
+    actors: null,
+    edges: null,
+    featureOrder: null,
+    features: {},
+    removed: { features: [], submodules: [] },
+  };
+
+  if (JSON.stringify(merged.meta || {}) !== JSON.stringify(base.meta || {})) {
+    overlay.meta = merged.meta || {};
+  }
+  if (JSON.stringify(merged.actors || []) !== JSON.stringify(base.actors || [])) {
+    overlay.actors = merged.actors || [];
+  }
+  if (JSON.stringify(merged.edges || []) !== JSON.stringify(base.edges || [])) {
+    overlay.edges = merged.edges || [];
+  }
+
+  const baseOrder = (base.features || []).map((feature) => feature.slug);
+  const mergedOrder = (merged.features || []).map((feature) => feature.slug);
+  if (JSON.stringify(mergedOrder) !== JSON.stringify(baseOrder)) {
+    overlay.featureOrder = mergedOrder;
+  }
+
+  const baseFeatures = new Map((base.features || []).map((feature) => [feature.slug, feature]));
+  const mergedFeatures = new Map((merged.features || []).map((feature) => [feature.slug, feature]));
+
+  for (const [slug, feature] of mergedFeatures) {
+    const baseFeature = baseFeatures.get(slug);
+    if (!baseFeature || JSON.stringify(feature) !== JSON.stringify(baseFeature)) {
+      overlay.features[slug] = feature;
+    }
+  }
+
+  for (const slug of baseFeatures.keys()) {
+    if (!mergedFeatures.has(slug)) {
+      overlay.removed.features.push(slug);
+    }
+  }
+
+  return overlay;
+}
+
 // diffPages compares the merged after-state against the base and
 // classifies which HTML pages must be regenerated (modified) versus
 // emitted fresh (added) versus listed in _removed.txt (removed).
@@ -361,19 +407,52 @@ function appendHistory(atlasDir, entry) {
 }
 
 function writeUndoSnapshot(atlasDir, state) {
-  fs.mkdirSync(atlasDir, { recursive: true });
-  fs.writeFileSync(path.join(atlasDir, UNDO_FILE), JSON.stringify(state, null, 2), 'utf8');
+  const stack = readUndoStack(atlasDir);
+  stack.push(state);
+  writeUndoStack(atlasDir, stack);
 }
 
 function readUndoSnapshot(atlasDir) {
-  const file = path.join(atlasDir, UNDO_FILE);
-  if (!fs.existsSync(file)) return null;
-  return JSON.parse(fs.readFileSync(file, 'utf8'));
+  const stack = readUndoStack(atlasDir);
+  return stack.length > 0 ? stack[stack.length - 1] : null;
 }
 
 function clearUndoSnapshot(atlasDir) {
-  const file = path.join(atlasDir, UNDO_FILE);
-  if (fs.existsSync(file)) fs.rmSync(file);
+  writeUndoStack(atlasDir, []);
+}
+
+function consumeUndoSnapshot(atlasDir, steps = 1) {
+  if (!Number.isInteger(steps) || steps < 1) return null;
+  const stack = readUndoStack(atlasDir);
+  if (stack.length < steps) return null;
+  const snapshot = stack[stack.length - steps];
+  writeUndoStack(atlasDir, stack.slice(0, stack.length - steps));
+  return snapshot;
+}
+
+function readUndoStack(atlasDir) {
+  const stackFile = path.join(atlasDir, UNDO_STACK_FILE);
+  if (fs.existsSync(stackFile)) {
+    return JSON.parse(fs.readFileSync(stackFile, 'utf8'));
+  }
+  const latestFile = path.join(atlasDir, UNDO_FILE);
+  if (fs.existsSync(latestFile)) {
+    return [JSON.parse(fs.readFileSync(latestFile, 'utf8'))];
+  }
+  return [];
+}
+
+function writeUndoStack(atlasDir, stack) {
+  const stackFile = path.join(atlasDir, UNDO_STACK_FILE);
+  const latestFile = path.join(atlasDir, UNDO_FILE);
+  if (!stack || stack.length === 0) {
+    if (fs.existsSync(stackFile)) fs.rmSync(stackFile);
+    if (fs.existsSync(latestFile)) fs.rmSync(latestFile);
+    return;
+  }
+  fs.mkdirSync(atlasDir, { recursive: true });
+  fs.writeFileSync(stackFile, JSON.stringify(stack, null, 2), 'utf8');
+  fs.writeFileSync(latestFile, JSON.stringify(stack[stack.length - 1], null, 2), 'utf8');
 }
 
 module.exports = {
@@ -383,6 +462,7 @@ module.exports = {
   FEATURES_DIR,
   HISTORY_FILE,
   UNDO_FILE,
+  UNDO_STACK_FILE,
   readYaml,
   writeYaml,
   load,
@@ -390,6 +470,7 @@ module.exports = {
   loadOverlay,
   saveOverlay,
   mergeOverlay,
+  deriveOverlay,
   diffPages,
   normalizeFeature,
   normalizeSubmodule,
@@ -397,6 +478,7 @@ module.exports = {
   writeUndoSnapshot,
   readUndoSnapshot,
   clearUndoSnapshot,
+  consumeUndoSnapshot,
   macroVisualOf,
   featureVisualOf,
 };

package/init-project-html/scripts/architecture.js

@@ -43,12 +43,12 @@ Usage:
                                               Manage component rows and edges
   apltk architecture meta set                 Update meta.title / meta.summary
   apltk architecture actor add|remove         Manage top-level actors
-  apltk architecture undo                     Revert the most recent mutation
+  apltk architecture undo [--steps <n>]      Revert the most recent mutation or roll back multiple steps
   apltk architecture --help                   Show this help
 
 Global flags:
   --project <root>   Project root (default: nearest ancestor with resources/project-architecture/, else cwd); missing layout dirs are created when needed
-  --spec <spec_dir>  Mutations write to <spec_dir>/architecture_diff/atlas/
+  --spec <spec_dir>  Single specs write locally; batch member paths write to the coordination.md root architecture_diff/atlas/
   --no-render        Skip auto-render after a mutation
   --no-open          For open/diff: skip launching the browser
   --out <dir>        For diff: override viewer output directory
@@ -255,21 +255,14 @@ function runDiff(opts, io) {
   if (!projectRoot) {
     projectRoot = process.cwd();
   }
-  fs.mkdirSync(path.join(projectRoot, RESOURCES_REL), { recursive: true });
-  const outDir = opts.out || path.join(projectRoot, DEFAULT_OUT_REL);
-  fs.mkdirSync(outDir, { recursive: true });
-
-  const changes = collectChanges(projectRoot);
-  const html = renderViewer({ changes, projectRoot, outDir });
-  const indexPath = path.join(outDir, 'index.html');
-  fs.writeFileSync(indexPath, html, 'utf8');
-
-  io.stdout.write(`${indexPath}\n`);
-  io.stdout.write(
-    `Diff pages: ${changes.length} (modified=${changes.filter((c) => c.kind === 'modified').length}, added=${changes.filter((c) => c.kind === 'added').length}, removed=${changes.filter((c) => c.kind === 'removed').length})\n`,
-  );
-  if (opts.open) openInBrowser(indexPath);
-  return 0;
+  const bootstrap = path.join(__dirname, 'architecture-bootstrap-render.js');
+  const args = [bootstrap, 'diff', '--project', projectRoot];
+  if (opts.out) args.push('--out', opts.out);
+  if (!opts.open) args.push('--no-open');
+  const result = spawnSync(process.execPath, args, { encoding: 'utf8' });
+  if (result.stdout) io.stdout.write(result.stdout);
+  if (result.stderr) io.stderr.write(result.stderr);
+  return result.status || 0;
 }
 
 // main(argv, io) is sync and supports the legacy verbs `open` and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@laitszkin/apollo-toolkit",
-  "version": "3.11.5",
+  "version": "3.11.6",
   "description": "Apollo Toolkit npm installer for managed skill copying across Codex, OpenClaw, and Trae.",
   "license": "MIT",
   "author": "LaiTszKin",

package/spec-to-project-html/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: spec-to-project-html
 description: >-
-  Sync the project HTML architecture atlas to active planning specs by driving `apltk architecture --spec <spec_dir>`. The CLI writes overlay YAML under `<spec_dir>/architecture_diff/atlas/` and re-renders only the affected proposed-after HTML pages — macro SVG and per-sub-module internal-dataflow diagrams stay zoomable like the base atlas — so `apltk architecture diff` pairs before/after by path under `docs/plans/**/architecture_diff/`. Preserve the two-layer rule and the responsibility split: **subagents only** — each subagent reads ONE affected feature and declares EVERY intra-feature overlay change; the main agent **waits until all subagents finish**, then aggregates outbound summaries and declares **only** cross-feature edges. **Exact CLI spelling:** always `apltk architecture --help`. Ground every declaration in repo evidence; mark `TBD` when code is missing.
+  Sync the project HTML architecture atlas to active planning specs by driving `apltk architecture --spec <spec_dir>`. Single specs write overlay YAML under `<spec_dir>/architecture_diff/atlas/`; batch member paths resolve to the shared batch-root `architecture_diff/` beside `coordination.md`. The CLI re-renders only the affected proposed-after HTML pages — macro SVG and per-sub-module internal-dataflow diagrams stay zoomable like the base atlas — so `apltk architecture diff` pairs before/after by path under `docs/plans/**/architecture_diff/`. Preserve the two-layer rule and the responsibility split: **subagents only** — each subagent reads ONE affected feature and declares EVERY intra-feature overlay change; the main agent **waits until all subagents finish**, then aggregates outbound summaries and declares **only** cross-feature edges. **Exact CLI spelling:** always `apltk architecture --help`. Ground every declaration in repo evidence; mark `TBD` when code is missing.
 ---
 
 # Spec To Project HTML
@@ -17,7 +17,7 @@ description: >-
 ## Non-negotiables
 
 - **MUST** read specs in order unless the user directs otherwise: `spec.md` → `design.md` → `contract.md` → coordination notes.
-- **MUST** declare every change through the CLI with `--spec <spec_dir>` (exact verbs/flags: **`apltk architecture --help`**). The CLI writes overlay YAML to `<spec_dir>/architecture_diff/atlas/` and re-renders only the affected proposed-after HTML pages there. **MUST NOT** hand-edit `architecture_diff/**/*.html` — the renderer owns those files.
+- **MUST** declare every change through the CLI with `--spec <spec_dir>` (exact verbs/flags: **`apltk architecture --help`**). Single specs write overlay YAML to `<spec_dir>/architecture_diff/atlas/` and re-render only the affected proposed-after HTML pages there. Batch member paths resolve to the shared batch-root `architecture_diff/` beside `coordination.md`, so the whole batch keeps one overlay and one rendered diff. **MUST NOT** hand-edit `architecture_diff/**/*.html` — the renderer owns those files.
 - **MUST** obey the semantic rules from `init-project-html/SKILL.md`:
   - Sub-module pages stay self-only — express cross-boundary interactions via **edges** (cross-feature or intra-feature), never as sub-module page prose.
   - Feature pages stay lightweight — cross-sub-module choreography belongs in **edges**, not in `dataflow` prose that pretends to cross features.
@@ -38,7 +38,7 @@ description: >-
 - **Evidence**: cite the spec passage (design subsystem entry) alongside the code path; record the citation in `meta.summary` or in sub-module purposes when relevant.
 - **Execution**: locate the plan set → list affected feature modules → subagent fan-out → **all complete** → cross-feature edges → `render --spec` if batched → `validate --spec` → `diff` check → handover.
 - **Quality**: macro overlay still shows every cross-feature data-row the spec requires; sub-module declarations stay self-only; `apltk architecture diff` opens cleanly with no orphan pages; no dangling edges.
-- **Output**: touches only `<spec_dir>/architecture_diff/atlas/**` (overlay state) and `<spec_dir>/architecture_diff/**/*.html` (renderer output). Base `resources/project-architecture/` is **NEVER** mutated.
+- **Output**: single specs touch only `<spec_dir>/architecture_diff/atlas/**` (overlay state) and `<spec_dir>/architecture_diff/**/*.html` (renderer output); batch specs write the same artifacts under the batch root beside `coordination.md`. Base `resources/project-architecture/` is **NEVER** mutated.
 
 ## Acceptance criteria (mirrors `init-project-html`)
 
@@ -92,7 +92,7 @@ List overlay files touched (or verb families used), the diff counts (`modified`
 
 ## Sample hints
 
-- **Batch merge**: each member spec’s `--spec <member_dir>` writes its own overlay; `diff` lists each spec’s section in the paginated viewer.
+- **Batch merge**: each member spec still calls `--spec <member_dir>`, but the CLI resolves writes to the shared batch-root overlay beside `coordination.md`; `diff` shows the batch as one combined architecture delta.
 - **Spec shrinks scope**: prefer `submodule set --role "deprecated: ..."` before `submodule remove` so reviewers see intent.
 - **Design-only change**: still review edges — order shifts surface as edge mutations; `validate --spec` catches dangling references.
 

package/spec-to-project-html/agents/openai.yaml

@@ -3,7 +3,7 @@ interface:
   short_description: "Sync the project HTML architecture atlas with active planning specs via `apltk architecture --spec`"
   default_prompt: >-
     Use $spec-to-project-html. Read docs/plans (spec → design → contract). Every overlay mutation: `apltk architecture --spec <spec_dir> …`. **Exact commands: `apltk architecture --help`** — do not trust long command lists in docs.
-    CLI writes `<spec_dir>/architecture_diff/atlas/*.yaml` + affected HTML under `<spec_dir>/architecture_diff/`. Base `resources/project-architecture/` is read-only here. NEVER hand-edit `architecture_diff/**`.
+    Single specs write `<spec_dir>/architecture_diff/atlas/*.yaml` + affected HTML under `<spec_dir>/architecture_diff/`. Batch member paths resolve to the shared batch-root `architecture_diff/` beside `coordination.md`, so one batch keeps one overlay + one rendered diff. Base `resources/project-architecture/` is read-only here. NEVER hand-edit `architecture_diff/**`.
     **`apltk architecture diff`** builds a paginated viewer: scans all `docs/plans/**/architecture_diff/`, pairs overlay paths with base atlas HTML by relative path, labels modified/added/removed — use it to verify the architecture delta before hand-off.
     **Subagents only:** dispatch ONE write-capable subagent per AFFECTED feature; each applies ALL intra-feature overlay mutations (`submodule`/`function`/`variable`/`dataflow`/`error`/`edge` within that feature). Each returns ONLY change summary + outbound boundary deltas for OTHER features.
     **HARD GATE:** main agent MUST wait until ALL subagents finish before ANY cross-feature `edge add|remove`, overlay `meta` that stitches multiple features, or shared `actor` for cross-feature context. Then `render --spec`, `validate --spec`.