@laitszkin/apollo-toolkit 3.11.4 → 3.11.6

package/AGENTS.md

@@ -62,6 +62,7 @@ This repository enables users to install and run a curated set of reusable agent
 - Users can add focused observability to opaque workflows through targeted logs, metrics, traces, and tests.
 - Users can iteratively improve repository code quality through behavior-neutral naming, simplification, module-boundary, logging, and test-coverage passes.
 - Users can iteratively improve repository performance through evidence-backed module scans, safe hot-path optimization, benchmark guardrails, batching, caching, allocation, concurrency, and repeated full-codebase stage gates.
+- Users can refresh the project HTML architecture atlas to reflect the latest committed or staged code changes by dispatching one subagent per affected feature and updating the base atlas via `apltk architecture` (no spec overlay).
 - Users can select risk-driven test levels and define unit drift checks through a shared testing strategy skill.
 - Users can build against Jupiter's official Solana swap, token, price, lending, trigger, recurring, and portfolio APIs with an evidence-based development guide.
 - Users can render and embed math formulas with KaTeX using official documentation-backed guidance and reusable rendering scripts.

package/CHANGELOG.md

@@ -10,6 +10,40 @@ 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
+
+- New skill `update-project-html`: refreshes the base project HTML architecture atlas (`resources/project-architecture/`) to reflect the latest code changes by reading the existing atlas, resolving the diff scope (`git diff --stat` + staged by default, or against a user-named ref), filtering to code-affecting hunks, and dispatching one write-capable subagent per affected feature to update declarations through `apltk architecture` (no `--spec`); the main agent waits until every subagent finishes before declaring cross-feature edges, then runs `apltk architecture render` and `apltk architecture validate`.
+- README: notes for `update-project-html`, the `commit-and-push` / `version-release` decoupling, the `review-change-set` decoupling + subagent guidance, and the `review-spec-related-changes` parallel secondary-subagent pattern. AGENTS.md: new business-flow bullet for `update-project-html`.
+- Tests (`test/skill-workflows.test.js`): assertions for the four behavior changes above (decoupling and subagent recommendations).
+
+### Changed
+
+- `commit-and-push` and `version-release` no longer chain `discover-edge-cases` or `discover-security-issues` automatically. The `review-change-set` gate stays mandatory for code-affecting scope, and other conditional gates (e.g. `archive-specs`) remain unchanged. Invoke security or edge-case skills explicitly when their scenario applies.
+- `review-change-set` no longer chains `discover-security-issues` and now recommends dispatching one read-only subagent per coherent scope cluster for multi-file diffs; the main agent aggregates structured architecture + simplification findings without re-reading delegated files. Tiny diffs are still reviewed inline.
+- `review-spec-related-changes` keeps its three secondary dependencies (`review-change-set`, `discover-edge-cases`, `discover-security-issues`) but now prefers running each one in its own read-only subagent in parallel, and may also fan out independent business-goal requirement clusters to read-only subagents.
+
+### Fixed
+
 ## [v3.11.4] - 2026-05-12
 
 ### Added

package/README.md

@@ -56,6 +56,7 @@ A curated skill catalog for Codex, OpenClaw, Trae, Agents, and Claude Code with
 - systematic-debug
 - test-case-strategy
 - text-to-short-video
+- update-project-html
 - version-release
 - video-production
 - weekly-financial-event-report
@@ -210,7 +211,10 @@ Compatibility note:
 - `recover-missing-plan` is a local skill used by `enhance-existing-features` and `ship-github-issue-fix` when a referenced `docs/plans/...` spec set is missing or archived.
 - `maintain-skill-catalog` can conditionally use `find-skills`, but its install source is not verified in this repository, so it is intentionally omitted from the table.
 - `read-github-issue` uses GitHub CLI (`gh`) directly for remote issue discovery and inspection, so it does not add any extra skill dependency.
-- `review-spec-related-changes` is a local skill that depends on `review-change-set`, `discover-edge-cases`, and `discover-security-issues` for secondary code-practice checks after business-goal completion is reviewed against the governing specs.
+- `review-spec-related-changes` is a local skill that depends on `review-change-set`, `discover-edge-cases`, and `discover-security-issues` for secondary code-practice checks after business-goal completion is reviewed against the governing specs; it prefers running each secondary skill in its own read-only subagent in parallel.
+- `update-project-html` is a local skill that depends on `init-project-html` for semantic rules and on the `apltk architecture` CLI to refresh the base atlas after code changes; for spec overlay diagrams use `spec-to-project-html` instead.
+- `commit-and-push` and `version-release` no longer chain `discover-edge-cases` or `discover-security-issues`; invoke those skills explicitly when the review surface needs them.
+- `review-change-set` no longer chains `discover-security-issues`; for multi-file diffs it prefers dispatching one read-only subagent per scope cluster.
 
 ## Release publishing
 

package/commit-and-push/README.md

@@ -31,6 +31,4 @@ When the diff includes code changes, `review-change-set` is still a conditional
 
 Apply the same rule to every other conditional gate: if its scenario is met during classification, it becomes blocking before commit rather than a best-effort follow-up.
 
-That includes risk-driven review gates such as `discover-edge-cases` and `discover-security-issues` whenever the change surface makes them applicable.
-
 For release workflows, use `version-release`.

package/commit-and-push/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: commit-and-push
 description: >-
-  Commit and push only (no semver): inspect staged vs unstaged, classify scopes, run mandated reviews (`review-change-set`, conditional `discover-edge-cases`/`discover-security-issues`), **`submission-readiness-check`** BEFORE final commit honoring `CHANGELOG.md` Unreleased + `archive-specs` redirections, preserve intentional staging splits, forbid UI git stubs, VERIFY remote hashes post-push **`version-release` elsewhere**.
+  Commit and push only (no semver): inspect staged vs unstaged, classify scopes, run the mandated `review-change-set` for code-affecting scope, then **`submission-readiness-check`** BEFORE the final commit honoring `CHANGELOG.md` Unreleased + `archive-specs` redirections, preserve intentional staging splits, forbid UI git stubs, VERIFY remote hashes post-push. **`version-release` elsewhere**.
   Use for “please commit”, “submit”, “push branch” lacking explicit semver/tag language **STOP** tagging here… BAD skip readiness red… GOOD staged subset untouched unrelated dirty files changelog mirrors diff… hashes `git rev-parse HEAD` versus upstream… archive specs before commit flagged…
 ---
 
@@ -10,7 +10,7 @@ description: >-
 ## Dependencies
 
 - Required: **`submission-readiness-check`** immediately before the **final** commit.
-- Conditional: **`archive-specs`** when readiness (or completed specs) requires doc conversion or categorized `docs/` alignment; **`review-change-set`** for every **code-affecting** scope; **`discover-edge-cases`** and **`discover-security-issues`** become **required** when classification/risk indicates (same scope)—treat as blocking, not polish.
+- Conditional: **`archive-specs`** when readiness (or completed specs) requires doc conversion or categorized `docs/` alignment; **`review-change-set`** for every **code-affecting** scope.
 - Optional: none.
 - Fallback: Any **required** dependency unavailable ⇒ **MUST** stop and report—**MUST NOT** “light” commit.
 
@@ -18,7 +18,7 @@ description: >-
 
 - **MUST** use real `git` mutations (`git add`, `git commit`, `git push`, `git stash`, etc.); **MUST NOT** treat UI tokens (`::git-commit`, IDE buttons) as proof of history.
 - **MUST** run **`submission-readiness-check`** before final commit; unresolved readiness (e.g. stale/missing `CHANGELOG.md` **Unreleased**, doc drift) **blocks** commit.
-- Code-affecting: **`review-change-set` MANDATORY**; unresolved confirmed findings **block**. When risk profile matches, **`discover-edge-cases`** / **`discover-security-issues`** equally blocking.
+- Code-affecting: **`review-change-set` MANDATORY**; unresolved confirmed findings **block**.
 - **`archive-specs`**: when readiness says convert/archive or `docs/` mismatch—**MUST** run **before** final commit, not as a vague follow-up.
 - **MUST** reconcile **staged vs unstaged** with user intent—**MUST NOT** broaden scope by auto-staging unrelated files when user staged a subset.
 - **`CHANGELOG.md` `Unreleased`**: for code-affecting or user-visible docs, **MUST** reflect this change before commit; reopen diff after edits to match commit scope.
@@ -27,7 +27,7 @@ description: >-
 - **MUST NOT** run version bump, tag, or GitHub release (**use `version-release`**).
 - Clean worktree requests: **MUST** inspect `HEAD`, upstream, last commit—**MUST NOT** fabricate “pushed” when already satisfied or impossible.
 
-**Repository regression checks (verbatim requirements):** Treat root `CHANGELOG.md` `Unreleased` coverage as mandatory for code-affecting or user-visible changes. Re-open the final `CHANGELOG.md` diff after readiness updates. **`review-change-set` is required for code-affecting changes**; Run `review-change-set` for every code-affecting change before continuing; treat unresolved review findings as blocking. Any conditional gate whose trigger is confirmed by this classification becomes mandatory before commit. Treat every scenario-matched gate as blocking before commit. **`discover-edge-cases` and `discover-security-issues` are important review gates**—when their scenario is met, treat them as blocking review gates, not optional polish.
+**Repository regression checks (verbatim requirements):** Treat root `CHANGELOG.md` `Unreleased` coverage as mandatory for code-affecting or user-visible changes. Re-open the final `CHANGELOG.md` diff after readiness updates. **`review-change-set` is required for code-affecting changes**; Run `review-change-set` for every code-affecting change before continuing; treat unresolved review findings as blocking. Any conditional gate whose trigger is confirmed by this classification becomes mandatory before commit. Treat every scenario-matched gate as blocking before commit.
 
 ## Standards (summary)
 
@@ -54,7 +54,7 @@ description: >-
 3. **Branch target** — Honor user branch; if switch needed, protect unrelated changes; cherry-pick/replay off wrong branch safely; worktree cases: identify authoritative target **before** replay.
    - **Pause →** Am I about to merge noise because diff > issue scope—should I stop and narrow first?
 
-4. **Code-affecting gates** — `review-change-set` always; add `discover-edge-cases` / `discover-security-issues` when risk/trigger says so; fix or document blockers; re-test material logic.
+4. **Code-affecting gates** — `review-change-set` always; fix or document blockers; re-test material logic.
 
 5. **Readiness** — Run **`submission-readiness-check`**; if it routes to **`archive-specs`**, run that **now**; fix `Unreleased` bullets; recheck changelog vs staged intent.
    - **Pause →** Could I commit while readiness still red—**why not**?

package/commit-and-push/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Commit and Push"
   short_description: "Submit local changes with commit and push only"
-  default_prompt: "Use $commit-and-push to inspect the current git state and classify the diff. Treat every conditional gate whose scenario is met as blocking before any commit: if the change set includes code changes, run $review-change-set; if the reviewed risk profile says edge-case or security review is needed, run $discover-edge-cases and $discover-security-issues as blocking gates too; if completed specs should be converted or docs need normalization, ensure $archive-specs runs through $submission-readiness-check; if changelog synchronization is needed, complete it before continuing. Then run any additional required code-quality skills, hand the repository to $submission-readiness-check so it can synchronize completed plan archives, project docs, AGENTS.md/CLAUDE.md, and CHANGELOG.md before any commit, confirm root CHANGELOG.md Unreleased reflects the actual pending change set, preserve user staging intent, create a concise Conventional Commit, and push to the intended branch without any versioning or release steps."
+  default_prompt: "Use $commit-and-push to inspect the current git state and classify the diff. Treat every conditional gate whose scenario is met as blocking before any commit: if the change set includes code changes, run $review-change-set; if completed specs should be converted or docs need normalization, ensure $archive-specs runs through $submission-readiness-check; if changelog synchronization is needed, complete it before continuing. Then run any additional required code-quality skills, hand the repository to $submission-readiness-check so it can synchronize completed plan archives, project docs, AGENTS.md/CLAUDE.md, and CHANGELOG.md before any commit, confirm root CHANGELOG.md Unreleased reflects the actual pending change set, preserve user staging intent, create a concise Conventional Commit, and push to the intended branch without any versioning or release steps."

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.