@laitszkin/apollo-toolkit 3.11.4 → 3.11.6

package/review-change-set/README.md

@@ -10,7 +10,7 @@ This skill:
 2. Rejects authorship bias, including confidence in code written earlier in the same conversation.
 3. Looks for architecture-level abstraction opportunities.
 4. Looks for code that can be simplified without changing behavior.
-5. Runs `discover-security-issues` as a required adversarial cross-check for code-affecting changes.
+5. For multi-file or multi-module diffs, dispatches one read-only subagent per coherent scope cluster and aggregates structured findings on the main agent.
 
 ## When to use
 
@@ -27,7 +27,7 @@ Use this skill when the task asks you to:
 - Treat recent edits as untrusted until evidence proves otherwise.
 - Prefer fewer, stronger findings over broad speculative advice.
 - Focus on architecture and simplification, not cosmetic style feedback.
-- Reuse confirmed security findings from `discover-security-issues` instead of hand-waving about risk.
+- For wide diffs, prefer parallel read-only subagents over loading every file into one context.
 
 ## Example
 
@@ -44,7 +44,7 @@ Expected behavior:
 - changed files are read before conclusions,
 - findings cite exact evidence,
 - architecture issues are prioritized over style comments,
-- security-sensitive changes are cross-checked through `discover-security-issues`.
+- multi-module diffs are reviewed by parallel read-only subagents and aggregated into one report.
 
 ## References
 

package/review-change-set/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: review-change-set
 description: >-
-  Unbiased **git diff** review: architecture (boundaries, duplication, ownership) then simplification (real deletes/flattening, not churn)—discard conversation bias. Code-affecting changes **MUST** cross-check with **`discover-security-issues`**; integrate only **confirmed** findings—no invented CWE drama.
+  Unbiased **git diff** review: architecture (boundaries, duplication, ownership) then simplification (real deletes/flattening, not churn)—discard conversation bias. For diffs spanning multiple files/modules, **prefer dispatching one read-only subagent per scope cluster** (each owns its files end-to-end), then aggregate confirmed findings on the main agent without re-reading delegated files.
   Use for pre-commit/pre-PR review, refactor/abstraction second opinion, “review my branch” **STOP** greenfield feature design from scratch—use planning skills… BAD style-only nits… GOOD evidence + named abstraction target…
 ---
 
@@ -10,9 +10,9 @@ description: >-
 ## Dependencies
 
 - Required: none.
-- Conditional: **`discover-security-issues`** for **code-affecting** changes before final conclusions.
+- Conditional: none.
 - Optional: none.
-- Fallback: If the security cross-check is **required** but unavailable, **MUST** stop and report.
+- Fallback: If a downstream consumer (e.g. `commit-and-push`) needs additional safety checks (security, edge cases), invoke those skills explicitly there — this skill no longer chains them automatically.
 
 ## Non-negotiables
 
@@ -21,14 +21,15 @@ description: >-
 - Prefer **architecture** and **maintainability** over style-only.
 - Abstraction only when it cuts duplication, clarifies ownership, or stabilizes boundaries.
 - Simplification only when behavior-preserving and genuinely simpler—**MUST NOT** shuffle complexity.
-- **MUST** invoke **`discover-security-issues`** on code-affecting scope; **MUST NOT** fabricate security issues not confirmed by that pass.
+- For non-trivial diffs (multiple files, multiple modules, or large per-file changes), **SHOULD** dispatch **read-only subagents** — one per coherent scope cluster (e.g. one feature/package, one layer, or one logical concern). Each subagent reads its assigned files end-to-end and returns ONLY structured findings (architecture + simplification with `path:line` evidence). The main agent **MUST NOT** re-read delegated files; it aggregates confirmed findings, deduplicates cross-cluster overlaps, and writes the final report. Tiny one-file diffs may be reviewed inline without subagents.
+- **MUST NOT** fabricate findings the diff does not actually contain; subagent reports stay confined to architecture and simplification.
 
 ## Standards (summary)
 
-- **Evidence**: Full diff + minimum context reads to understand behavior.
-- **Execution**: Git state → baseline → architecture → simplification → security integration → report.
-- **Quality**: Actionable, outsider perspective; clear merge of confirmed security results.
-- **Output**: Scope, architecture findings, simplification findings, security cross-check summary, residual uncertainty.
+- **Evidence**: Full diff + minimum context reads to understand behavior; subagent reports cite `path:line` per finding.
+- **Execution**: Git state → baseline → (subagent fan-out for multi-cluster diffs OR inline read for tiny diffs) → architecture → simplification → aggregate → report.
+- **Quality**: Actionable, outsider perspective; subagent fan-out keeps each context window small; no duplicated findings across clusters.
+- **Output**: Scope, architecture findings, simplification findings, residual uncertainty.
 
 ## Workflow
 
@@ -40,45 +41,56 @@ description: >-
 - No diff → `No active git change set to review` and stop.
    - **Pause →** Am I about to review **only** unstaged while staged also ships?
 
-### 2) Baseline
+### 2) Plan the read pattern
 
-- Read every changed file E2E; pull in minimal callers/callees/config to interpret moves and interfaces.
+- **Tiny diff** (one file or a handful of small hunks in one module) → read inline; skip subagents.
+- **Multi-file or multi-module diff** → cluster the changed files into coherent scopes (one feature/package, one layer, one logical concern). Dispatch **one read-only subagent per cluster**. Hand each subagent: the cluster file list, its slice of `git diff`/`git diff --cached`, and the structured-report contract below. The main agent **MUST NOT** read the delegated files itself.
+
+> **Cluster `<scope>` subagent contract**
+> - Read every file in this cluster E2E plus the minimum callers/callees/config needed to interpret behavior.
+> - Discard authorship bias; behavior comes from code/tests/config, not chat memory.
+> - Return ONLY a structured findings block:
+>   - `Architecture`: list of `{ title, evidence (path:line), abstraction target, why current shape is weaker }`.
+>   - `Simplification`: list of `{ title, evidence (path:line), candidate change, behavior-preserving benefit }`.
+>   - `Outbound concerns`: any boundary issue that touches another cluster (so the orchestrator can deduplicate).
+> - No source dumps, no opinions about tasks outside this cluster, no security/edge-case fabrication.
+
+   - **Pause →** Did I cluster correctly so that one subagent owns each coherent boundary, or am I about to split a duplicated helper across two subagents and miss the dedup signal?
+
+### 3) Baseline (inline path) or aggregate (subagent path)
+
+- Inline: read every changed file E2E; pull in minimal callers/callees/config to interpret moves and interfaces.
+- Subagent: wait for **every** cluster subagent to return. Aggregate their findings, then deduplicate any architecture finding two clusters reported via their `Outbound concerns` block.
 - Behavior from **code, tests, config, execution**—not from chat memory.
    - **Pause →** Can I quote **one concrete behavior** change this diff introduces—not intent?
 
-### 3) Architecture first
+### 4) Architecture first
 
 Flag only if evidence-backed: duplicated workflows, cross-layer leakage, wrong helper ownership, repeated condition trees, unstable interfaces.
 Each finding **MUST** name abstraction target **and** why current shape is weaker.
    - **Pause →** Is this “different style” or a real **boundary** problem?
 
-### 4) Simplification second
+### 5) Simplification second
 
 Redundant branches/wrappers, deep nesting, duplicated validation, oversize functions, dead compat—**only** if it truly reduces complexity.
    - **Pause →** Would this refactor just **move** lines between files?
 
-### 5) Security cross-check
-
-- Run **`discover-security-issues`** on the **same** code-affecting scope.
-- Merge **confirmed** findings that affect safety of this structure; omit unconfirmed noise.
-   - **Pause →** Did I cite **their** severity + repro—or paraphrase fear?
-
 ### 6) Report
 
-1. **Scope** — staged/unstaged; extra context paths read.
+1. **Scope** — staged/unstaged; extra context paths read; cluster list when subagents were used.
 2. **Architecture** — title, evidence (`path:line`), candidate, why weaker.
 3. **Simplification** — title, evidence, candidate, benefit.
-4. **Security cross-check** — confirmed items reused from **`discover-security-issues`**, relevance to this diff.
-5. **Residual uncertainty** — hypotheses / follow-up checks.
+4. **Residual uncertainty** — hypotheses / follow-up checks.
 
-If nothing actionable: `No actionable abstraction or simplification finding identified` (security section still reflects cross-check outcome).
+If nothing actionable: `No actionable abstraction or simplification finding identified`.
 
 ## Sample hints
 
 - **Staged only**: User ran `git add -p` → findings tagged **staged** vs **unstaged** separately.
 - **Rename-heavy**: Read old→new path mapping before calling “duplication.”
-- **Tiny diff**: One-file guard clause → architecture section may be empty; security pass still runs if code-affecting.
+- **Tiny diff**: One-file guard clause → architecture section may be empty; reviewed inline without subagents.
+- **Wide refactor across packages**: cluster by package; one read-only subagent per package; dedupe duplicated-helper findings on the main agent.
 
 ## References
 
-- **`discover-security-issues`**: confirmed adversarial findings for code-affecting scope.
+- Downstream consumers (e.g. `commit-and-push`, `version-release`, `review-spec-related-changes`) decide independently when to add security or edge-case passes; this skill no longer wires them.

package/review-change-set/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Review Change Set"
-  short_description: "Independent diff review for architecture, simplification, and confirmed security cross-checks"
-  default_prompt: "Use $review-change-set to read the active git change set end-to-end, discard any bias toward code written earlier in the conversation, review it like an independent reviewer for architecture-level abstraction and simplification opportunities, and run $discover-security-issues as an adversarial cross-check for code-affecting changes."
+  short_description: "Independent diff review for architecture and simplification opportunities"
+  default_prompt: "Use $review-change-set to read the active git change set end-to-end, discard any bias toward code written earlier in the conversation, and review it like an independent reviewer for architecture-level abstraction and simplification opportunities. For multi-file or multi-module diffs, prefer dispatching one read-only subagent per coherent scope cluster (each owns its files end-to-end and returns structured architecture + simplification findings with path:line evidence); the main agent aggregates and deduplicates without re-reading delegated files."

package/review-spec-related-changes/README.md

@@ -9,7 +9,7 @@ This skill:
 1. Resolves the governing `docs/plans/...` spec scope from user input or recent repository changes.
 2. Checks whether each business goal and acceptance criterion is actually implemented.
 3. Treats unmet business goals as the most severe review findings.
-4. Runs secondary code-practice review through `review-change-set`, `discover-edge-cases`, and `discover-security-issues` for code-affecting scopes.
+4. Runs secondary code-practice review through `review-change-set`, `discover-edge-cases`, and `discover-security-issues` for code-affecting scopes — preferably as parallel read-only subagents (one per skill) that report back to the main agent.
 5. Reports business-goal gaps separately from edge-case, security, and maintainability findings.
 
 ## When to use
@@ -27,6 +27,7 @@ Use this skill when the task asks you to:
 - Missing required behavior is more severe than ordinary code-practice issues.
 - Secondary edge-case, security, and code-review findings remain clearly separated.
 - Findings must cite concrete spec and code evidence.
+- For multi-skill reviews, prefer parallel read-only subagents (one per secondary skill) over chaining the skills sequentially on the main agent.
 
 ## Example
 
@@ -41,7 +42,7 @@ Expected behavior:
 
 - the named spec set is read before judging the code,
 - business-goal gaps are listed first and treated as highest severity,
-- secondary review skills are invoked for the same implementation scope,
+- secondary review skills are invoked for the same implementation scope, preferably as one read-only subagent per skill running in parallel,
 - the final report separates spec-compliance findings from edge-case, security, and code-review findings.
 
 ## References

package/review-spec-related-changes/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: review-spec-related-changes
 description: >-
-  Read-only spec compliance versus governing docs/plans: score each business-oriented requirement Met/Partial/Not-met using code/tests/commands—checked `tasks.md` boxes are never sufficient proof; ambiguity between two plausible plan roots halts execution; when runtime code exists, sequentially run **`review-change-set`**, **`discover-edge-cases`**, and **`discover-security-issues`** on the same scoped diff afterward.
-  Use for questions like “does this PR satisfy coordination.md + spec.md R2?” or user pins a `{change}` folder.
-  Do not mutate repositories, reorder reports to bury missing goals, skip the tertiary review bundle on code-bearing diffs, or rely on intent without file evidence **BAD**, lead with refactor comments while R1 failing **FORBIDDEN**… GOOD pair every Not-met cite with `spec.md` ref + concrete path:test gap…
+  Read-only spec compliance vs governing docs/plans: score every business requirement Met/Partial/Not-met from code/tests/commands—checked `tasks.md` boxes never count; ambiguity between two plan roots halts execution; on code-bearing diffs run **`review-change-set`**, **`discover-edge-cases`**, **`discover-security-issues`** on the same scope afterward — **prefer one read-only subagent per secondary skill in parallel** so the main agent aggregates without re-reading. Independent requirement clusters may also be scored by parallel read-only subagents.
+  Use for “does this PR satisfy coordination.md + spec.md R2?” or a user-pinned `{change}` folder.
+  Do not mutate repos, bury missing goals, skip the tertiary bundle on code-bearing diffs, or rest on intent without evidence; FORBIDDEN to lead with refactor comments while R1 is failing. GOOD: pair every Not-met cite with a `spec.md` ref + concrete path:test gap.
 ---
 
 # Review Spec Related Changes
@@ -23,14 +23,17 @@ description: >-
 - **MUST** classify each business goal / acceptance item as `Met`, `Partially met`, `Not met`, or `Deferred/N/A` **only** using verifiable evidence (code, tests, commands, traces)—checked boxes in `tasks.md` are **not** proof by themselves.
 - **MUST** treat **unmet or partially met required business goals** as **highest severity**. **MUST NOT** let edge-case, security, or style findings **outrank** those gaps in the reported order or implied priority.
 - **MUST** finish the business-goal verdict **before** invoking secondary skills; **MUST** still run `review-change-set`, `discover-edge-cases`, and `discover-security-issues` on the **same** implementation scope when code is involved (after step 1 verdict is written).
+- **SHOULD** parallelize the secondary reviews when code is involved by dispatching **one read-only subagent per secondary skill** (one for `review-change-set`, one for `discover-edge-cases`, one for `discover-security-issues`). Each subagent receives the same diff scope, follows that skill’s own SKILL.md, and returns ONLY its structured findings; the main agent aggregates them in the fixed report order without re-running the underlying analysis. Single-file or trivial diffs may be reviewed inline without subagents.
+- For business-goal scoring itself, **MAY** parallelize by dispatching one read-only subagent per **independent requirement cluster** (requirements that share no owned paths and no shared spec section), each returning Met/Partial/Not-met with cited evidence. The main agent owns final ordering, severity, and any cross-requirement reconciliation. Tightly coupled requirements stay on the main agent.
 - **MUST NOT** rest conclusions on author intent, branch names, or chat memory unless **repository evidence** agrees.
+- **MUST NOT** let subagents mutate repositories, archive specs, or commit — every dispatched subagent runs in **read-only** mode.
 - Prefer **fewer confirmed findings** over broad speculation; unproven items belong under **Residual uncertainty**, not as faux defects.
 
 ## Standards (summary)
 
 - **Evidence**: Full read of governing docs + minimal code/diff context + spec-named verification commands when safe to run.
-- **Execution**: Scope resolution → business compliance → required secondary reviews → ordered report.
-- **Quality**: Business-first severity; secondary findings separated unless they also block an acceptance criterion.
+- **Execution**: Scope resolution → business compliance (optionally fanned out by independent requirement cluster) → parallel secondary reviews via per-skill read-only subagents → aggregated ordered report.
+- **Quality**: Business-first severity; secondary findings separated unless they also block an acceptance criterion; subagent reports stay strictly within their assigned skill’s scope.
 - **Output**: Ordered list: business gaps → edge cases → security → code review → passing summary → residual uncertainty.
 
 ## Scope resolution
@@ -53,17 +56,19 @@ description: >-
    - **Pause →** Which items are **mandatory** acceptance vs explicitly **out of scope** or deferred?
    - **Pause →** What observable failure would make me change a `Met` to `Not met` for the top risk requirement?
 
-2. **Implementation evidence** — Read the relevant diff/staged/commits/files. Trace the minimum code path to validate claims. Run spec-named checks when available and safe.
+2. **Implementation evidence** — Read the relevant diff/staged/commits/files. Trace the minimum code path to validate claims. Run spec-named checks when available and safe. When the spec contains **independent requirement clusters** (disjoint owned paths, disjoint spec sections), **MAY** dispatch one read-only subagent per cluster to score Met/Partial/Not-met with cited evidence; the main agent reconciles cross-requirement effects and owns the final verdict ordering. Tightly coupled requirements stay on the main agent.
    - **Pause →** What is the **smallest** code path I have not yet read that could still falsify a `Met`?
    - **Pause →** Am I about to score `Met` from **intent** or from **tests/commands** I actually ran or inspected?
+   - **Pause →** If I clustered, is every cluster genuinely disjoint, or am I about to lose a cross-requirement contradiction by running them in isolation?
 
 3. **Business-goal verdict first** — Emit every `Not met` / `Partially met` **before** secondary findings, with **exact** spec cites and code/test evidence. While required goals stay failed, **MUST NOT** frame archival, release, or “done” narratives that imply compliance.
    - **Pause →** If I sorted findings by “interesting” instead of business impact, which line would unfairly rise above a missing goal?
    - **Pause →** For each `Partially met`, what single **missing proof** (test, wire-up, error path) am I naming explicitly?
 
-4. **Secondary reviews (code-affecting)** — On the same scope: `review-change-set` (architecture/simplification), `discover-edge-cases` (reproducible edge/observability risks), `discover-security-issues` (reproducible security). Keep outputs labeled so they do not read as business-goal substitutions.
+4. **Secondary reviews (code-affecting)** — On the same scope: `review-change-set` (architecture/simplification), `discover-edge-cases` (reproducible edge/observability risks), `discover-security-issues` (reproducible security). **Prefer dispatching one read-only subagent per skill in parallel** so each runs in its own context with the full SKILL.md it owns; hand each subagent the same diff scope and the structured-report contract from that skill. The main agent waits for every subagent to return, then keeps outputs labeled so they do not read as business-goal substitutions. Trivial single-file diffs may run inline without subagents. The main agent **MUST NOT** re-run a secondary skill it already delegated, and subagents **MUST NOT** mutate the repository.
    - **Pause →** Does this secondary finding **force** a business re-score—if yes, did I revise step 3 before publishing?
    - **Pause →** Is the diff scope identical to what I used for business mapping (no silent file creep)?
+   - **Pause →** Did every dispatched secondary subagent return — or am I about to publish from partial summaries?
 
 5. **Final report (fixed order)** — (1) Business-goal failures (always top severity for required gaps). (2) Edge-case. (3) Security. (4) Code-review / maintainability. (5) Passing evidence for goals confirmed `Met`. (6) Residual uncertainty (skipped commands, unmapped spec text, unverifiable externals). If nothing actionable: state that explicitly **and** still cite docs and evidence reviewed.
    - **Pause →** What commands or spec paragraphs remain **unverified**—are they all listed under residual uncertainty?

package/review-spec-related-changes/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Review Spec Related Changes"
   short_description: "Review spec-backed changes for business-goal completion and secondary code-practice risks"
-  default_prompt: "Use $review-spec-related-changes to resolve the recent or user-specified spec documents, verify each business goal and acceptance criterion against the related implementation evidence, treat unmet business goals as the most severe findings, and then run $review-change-set, $discover-edge-cases, and $discover-security-issues on the same code-affecting scope for secondary code-practice review."
+  default_prompt: "Use $review-spec-related-changes to resolve the recent or user-specified spec documents, verify each business goal and acceptance criterion against the related implementation evidence, and treat unmet business goals as the most severe findings. When code is involved, prefer dispatching one read-only subagent per secondary skill in parallel — one for $review-change-set, one for $discover-edge-cases, one for $discover-security-issues — each running against the same diff scope and returning structured findings; the main agent waits for all secondary subagents, then aggregates them into the fixed report order without re-running any of those skills. Independent requirement clusters with disjoint owned paths may also be scored by parallel read-only business-goal subagents; tightly coupled requirements stay on the main agent. Subagents always run in read-only mode."

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`.

package/update-project-html/README.md

@@ -0,0 +1,38 @@
+# update-project-html
+
+`update-project-html` refreshes the project HTML architecture atlas (`resources/project-architecture/`) so it reflects the latest code changes.
+
+## What this skill does
+
+1. Reads the current atlas (`atlas.index.yaml` + per-feature YAML).
+2. Resolves the diff scope (`git diff --stat` + `git diff --cached --stat` by default, or `git diff --stat <base>..HEAD` when the user names a ref).
+3. Filters to code-affecting hunks and maps each changed file to an existing or new feature.
+4. Dispatches one write-capable subagent per affected feature to deep-read only its own changed files and apply every intra-feature mutation through `apltk architecture` (no `--spec`).
+5. Waits until every subagent finishes, then declares cross-feature edges, runs `apltk architecture render`, and validates.
+
+## When to use
+
+Use this skill when the task asks you to:
+
+- update or refresh the existing project architecture diagram after code changes,
+- bring `resources/project-architecture/` back in sync with the current branch or a specific commit range,
+- reflect a recent PR or batch of commits in the canonical atlas before merging or releasing.
+
+If no atlas exists yet, use `init-project-html` to bootstrap one. For planned but unshipped work scoped to a `docs/plans/...` spec, use `spec-to-project-html` to write under `<spec_dir>/architecture_diff/` instead of the base atlas.
+
+## Core principles
+
+- The CLI owns atlas state and renderer output; agents never hand-edit `resources/project-architecture/**/*.html`.
+- Every mutation traces to a specific file + diff hunk; absent code never produces atlas entries.
+- Subagent fan-out is the only safe read pattern: one feature per subagent, no shared source loading.
+- Cross-feature wiring happens **after** every subagent finishes — never from partial summaries.
+
+## References
+
+- [`SKILL.md`](./SKILL.md) — full workflow and execution rules.
+- [`../init-project-html/SKILL.md`](../init-project-html/SKILL.md) — semantic rulebook.
+- [`../spec-to-project-html/SKILL.md`](../spec-to-project-html/SKILL.md) — spec overlay flow.
+
+## License
+
+MIT

package/update-project-html/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: update-project-html
+description: >-
+  Refresh the base project HTML architecture atlas to reflect the latest code changes: read the existing atlas, resolve diff scope (`git diff --stat` + staged by default, or `git diff --stat <base>..HEAD` when a ref is named), filter to code-affecting hunks, and update affected feature/sub-module declarations through `apltk architecture` (no `--spec` — base atlas, not spec overlays). **Subagents only:** dispatch ONE write-capable subagent per affected feature; each deep-reads only its own changed files, applies every intra-feature delta (function/variable/dataflow/error/intra-feature edge add|set|remove|reorder), and returns ONLY (i) sub-module change summary and (ii) outbound boundary deltas. The main agent waits until every subagent finishes before declaring cross-feature edges, then `apltk architecture render` + `validate`. Exact CLI: `apltk architecture --help`. Anchor every change to the actual diff. For unshipped spec work use `spec-to-project-html`; first-time bootstrap use `init-project-html`.
+---
+
+# Update Project HTML
+
+## Dependencies
+
+- Required: **`init-project-html`** — its `SKILL.md` is the semantic rulebook (acceptance criteria, two-layer rule, `edge.kind` enum, function/variable referencing rules); **`apltk architecture --help`** is the verb/flag source of truth.
+- Conditional: **`spec-to-project-html`** when the user actually wants an overlay scoped to a `docs/plans/...` spec rather than the base atlas — that skill uses `--spec`.
+- Optional: **`align-project-documents`** when feature names in the atlas no longer match the `docs/features` set after the diff.
+- Fallback: changed code references components that are absent from the atlas → declare new sub-modules / functions / variables before referencing them; if a single feature’s diff is too large for one subagent context, split that feature’s subagent by sub-module folder. **MUST NOT** invent components for code paths that were never read.
+
+## Non-negotiables
+
+- **MUST** mutate atlas state only through the CLI (`apltk architecture …`). The renderer owns `resources/project-architecture/**/*.html` — agents **MUST NOT** hand-edit those files.
+- **MUST** target the **base atlas** (no `--spec` flag). This skill is for code that has *already shipped* (or is about to be committed) and therefore belongs in the canonical diagram. For planned/unmerged work scoped to a spec, redirect to **`spec-to-project-html`**. For repos with no atlas yet, redirect to **`init-project-html`**.
+- **MUST** decide the diff scope **before** reading any source files: working tree (`git diff --stat`) + staged (`git diff --cached --stat`) by default; an explicit ref/range when the user names one (e.g. `git diff --stat $(git merge-base HEAD origin/main)..HEAD` for a PR refresh). Print the literal command(s) you ran in the report so the run is reproducible.
+- **MUST** filter to **code-affecting** hunks — exclude pure docs/markdown/asset edits, generated files, lockfiles, and formatting-only diffs that do not change runtime behavior. Record skipped buckets in the report so reviewers can audit the filter.
+- **MUST** preserve the existing atlas structure for parts the diff did not touch — never delete features, sub-modules, or edges just because the current diff is silent about them. Only mutate what the diff actually changed (rename, move, remove, add, behavior change).
+- **MUST** use the **subagent fan-out** pattern from `init-project-html` Rule 3:
+  1. Enumerate **affected features** from the filtered diff (path → feature mapping using existing atlas YAML + folder layout). No function-body deep reads at this stage.
+  2. Dispatch **one write-capable subagent per affected feature**. Each deep-reads only its own changed files (use `git diff` for exact deltas plus the post-change source for context), applies every intra-feature mutation via `apltk architecture` (`function`, `variable`, `dataflow`, `error`, intra-feature `edge` add|set|remove|reorder), and returns ONLY (i) sub-module change summary and (ii) outbound boundary deltas (cross-feature edges to add/change/remove with endpoints + suggested kind/label).
+  3. **HARD GATE:** the main agent **MUST** wait until **every** dispatched subagent has finished (success or explicit failure report) before declaring any cross-feature `edge`, shared `meta` that stitches multiple features, or `actor` that exists only for cross-feature context.
+- **MUST** run `apltk architecture render` (when subagents batched with `--no-render`) and `apltk architecture validate` after the cross-feature wiring; resolve every reported error before reporting completion.
+- **MUST NOT** re-read source for a delegated feature in the main agent and **MUST NOT** re-declare intra-feature components a subagent already owns.
+- **MUST NOT** generate spec overlay artifacts (`<spec_dir>/architecture_diff/atlas/`) — that is **`spec-to-project-html`**’s job.
+
+## Standards (summary)
+
+- **Evidence**: every CLI mutation traces to a specific file + diff hunk; record the chosen diff scope and skipped buckets in `meta.summary` via the CLI.
+- **Execution**: read base atlas → resolve diff scope → filter to code-affecting hunks → map paths to features → subagent fan-out → wait for all → cross-feature edges → `render` → `validate` → handover.
+- **Quality**: macro SVG still reflects every cross-feature data-row that exists in the *new* code; sub-module declarations stay self-only; `apltk architecture validate` returns OK.
+- **Output**: updated `resources/project-architecture/atlas/**/*.yaml` + re-rendered `resources/project-architecture/**/*.html` + a report listing affected features, mutation counts, skipped diff buckets, and the `validate` outcome.
+
+## Acceptance criteria
+
+The atlas update is only complete when **all** of the following hold:
+
+1. Every code-affecting hunk in the chosen diff scope is reflected in either an intra-feature mutation (function/variable/dataflow/error/edge) or a cross-feature edge — or is explicitly listed under "no diagram impact" in the handover report with a one-line reason.
+2. `apltk architecture validate` returns OK.
+3. Macro acceptance criteria from `init-project-html` still hold: cross-boundary interaction expressed as `call`/`return`/`data-row`/`failure` edges (never sub-module page prose); each touched sub-module’s internal diagram has function-to-function flow plus declared variable reads/writes for non-trivial steps.
+4. The handover report cites: chosen diff scope (literal commands), affected feature list, per-feature mutation counts, skipped diff buckets (with reasons), and confirmation that **all subagents completed before cross-feature wiring**.
+
+## How to use `apltk architecture`
+
+**Authoritative command tree:** run **`apltk architecture --help`** (same output as `apltk architecture help`). Same families as `init-project-html`:
+
+- `feature` / `submodule` — structural mutations (use **`set`** for label/role updates, **`remove`** when code deleted the entry point, **`add`** when the diff introduced a new module).
+- `function` / `variable` / `dataflow` / `error` — per-sub-module rows. Declare new symbols **before** referencing them in `dataflow`. Use the row-level `remove` (see `--help`) to delete obsolete rows the diff dropped.
+- `edge` — intra- or cross-feature seams. Prefer stable **`--id`** when re-applying the same edge after a mutation cycle. `kind` ∈ `call` | `return` | `data-row` | `failure`.
+- `meta` / `actor` — only when the diff actually changed the macro narrative (e.g. summary now needs to record the diff scope or new omissions).
+- `render` (when you batched with `--no-render`) → `validate` → done.
+
+This skill **never** uses `--spec`. If the user wants overlay diagrams for a planning doc, redirect to **`spec-to-project-html`**.
+
+## Workflow
+
+**Chain-of-thought:** Answer **`Pause →`** before moving on. Validator red **MUST** block "done."
+
+### 1) Read the current atlas (no source code yet)
+
+- Open `resources/project-architecture/index.html` to confirm the atlas exists and renders. If it does not, redirect to **`init-project-html`** — this skill is for refreshes, not bootstraps.
+- List `resources/project-architecture/atlas/atlas.index.yaml` and the per-feature YAMLs to learn the current feature set, sub-modules, and edge ids.
+   - **Pause →** Do I actually have a base atlas to update? If not — stop and route to **`init-project-html`**.
+
+### 2) Resolve diff scope
+
+- Default: **uncommitted** (`git diff --stat`) + **staged** (`git diff --cached --stat`); show both. If the user pointed at a ref/range/commit, use that instead (`git diff --stat <base>..HEAD`, `git diff --stat HEAD~N`, `git show --stat <sha>`, etc.).
+- Print the chosen diff scope as the literal command(s) you ran so the report is reproducible.
+   - **Pause →** Is this the diff the user actually meant — or am I about to refresh the atlas against the wrong baseline?
+
+### 3) Filter to code-affecting changes
+
+- Drop pure docs/markdown/assets/lockfiles/generated/format-only diffs. Keep source files in language directories the project actually treats as code (open the project layout if uncertain).
+- Group remaining files into **affected features** using the per-feature YAML’s declared paths plus folder/package heuristics. Record the path → feature mapping.
+   - **Pause →** Did I drop a hunk that actually changes runtime behavior (e.g. a config file the runtime reads)? Re-include if so.
+   - **Pause →** Are there changed files I cannot map to any existing feature — do they create a new feature, or do they extend an existing one? Decide explicitly before delegating.
+
+### 4) Subagent fan-out — workers own features; orchestrator owns cross-feature seams **after** all workers finish
+
+Dispatch one **write-capable** subagent per affected feature. Hand each subagent: its feature slug, the list of changed files in that feature, the diff scope command(s), the existing feature-module list (so it knows other features’ slugs for outbound edges), and **`apltk architecture --help`** as the flag reference.
+
+> **Feature `<slug>` subagent contract**
+> - Read the existing per-feature YAML and every changed file in this feature E2E (with `git diff` for the exact delta plus the post-change source for context).
+> - For every behavior change in this feature, apply the matching CLI mutation: structural (`feature` / `submodule`), rows (`function`, `variable`, `dataflow`, `error`), and intra-feature **`edge`** add/set/remove/reorder.
+> - Declare new functions / variables **before** referencing them from `dataflow`.
+> - Run **`apltk architecture validate`** before returning.
+> - **Return ONLY**: (i) sub-module change list (slug + change kind + one-line reason) and (ii) outbound boundary deltas (cross-feature edges to add/change/remove with endpoints + suggested kind/label). No source dumps.
+
+**Orchestrator — after every subagent has completed:**
+
+```bash
+# only when meta.summary needs to record the diff scope or new omissions
+apltk architecture meta set --summary "..." --no-render
+# one edge mutation per cross-feature interaction reported by the subagents
+apltk architecture edge add --from <featA>/<subA> --to <featB>/<subB> --kind call|return|data-row|failure --label "..." --no-render
+apltk architecture edge remove --id <stable_id> --no-render
+apltk architecture render
+apltk architecture validate
+```
+
+The main agent **MUST NOT** re-declare a subagent’s intra-feature components, and **MUST NOT** open source files for any feature it delegated.
+   - **Pause →** Did every subagent return — or am I about to wire cross-feature edges from partial summaries?
+
+### 5) Handover report
+
+Report: chosen diff scope (literal commands), affected features (count), per-feature mutation summary, cross-feature edge deltas (added / removed / changed), skipped diff buckets (with reasons), `validate` outcome, and the location of the rendered atlas (`resources/project-architecture/index.html`).
+
+## Sample hints
+
+- **Renamed function**: subagent removes the old `function` row, adds the new one, and updates every `dataflow` step that referenced it — do **not** silently leave the old row.
+- **Deleted sub-module**: subagent uses `submodule remove` (see `--help`) and reports the outbound edges to drop; the orchestrator removes the cross-feature edges by stable `--id` after the gate.
+- **New cross-feature data-row**: only one subagent will see the producing side and another only the consumer side — both subagents flag it as an outbound boundary; the orchestrator declares the single `data-row` edge **after** the gate.
+- **Pure formatting diff**: skip entirely; record under "no diagram impact" in the report so future runs do not re-litigate the file.
+- **PR refresh against `main`**: when the user asks to refresh the atlas to reflect "everything on this branch", use `git diff --stat $(git merge-base HEAD origin/main)..HEAD` and state the resolved base SHA in the report.
+
+## References
+
+- **`init-project-html/SKILL.md`** — semantic rulebook, two-layer rule, acceptance criteria, full subagent contract.
+- **`init-project-html/references/TEMPLATE_SPEC.md`** — schema cheat sheet (fields/enums).
+- **`spec-to-project-html/SKILL.md`** — overlay flow when work is still in spec form.
+- **`apltk architecture --help`** — live CLI reference; trust this over any prose.

package/update-project-html/agents/openai.yaml

@@ -0,0 +1,11 @@
+interface:
+  display_name: "update-project-html"
+  short_description: "Refresh the project HTML architecture atlas to reflect the latest code changes via `apltk architecture`"
+  default_prompt: >-
+    Use $update-project-html. Semantic rules + acceptance criteria live in $init-project-html SKILL.md; **exact verb/subverb/flag spelling MUST come from `apltk architecture --help`** — never memorize commands from prose.
+    NEVER hand-edit `resources/project-architecture/**/*.html`. State is YAML under `resources/project-architecture/atlas/`; every mutation goes through the CLI; the renderer owns layout, CSS, ARIA, pan/zoom on macro + sub-module dataflow SVGs.
+    STEP 1 — open the current atlas index + per-feature YAMLs (no source reads yet); if no atlas exists, redirect to $init-project-html. STEP 2 — resolve the diff scope explicitly: working tree + staged (`git diff --stat` + `git diff --cached --stat`) by default, or `git diff --stat <base>..HEAD` when the user names a ref. Print the chosen command(s) before delegating. STEP 3 — filter to code-affecting hunks and group them into affected features using existing per-feature YAML + folder layout; record path → feature mapping.
+    **Subagents only:** dispatch ONE write-capable subagent per AFFECTED feature; each deep-reads only its own changed files and declares EVERY intra-feature mutation (`feature`/`submodule`/`function`/`variable`/`dataflow`/`error`/intra-feature `edge` add|set|remove|reorder) via `apltk architecture` (NO `--spec` — this is the base atlas). Each returns ONLY (i) sub-module change list and (ii) outbound boundary deltas for OTHER features.
+    **HARD GATE:** main agent MUST wait until EVERY subagent finishes before declaring ANY cross-feature `edge`, shared `meta` that stitches multiple features, or `actor` that exists only for cross-feature context. Then `apltk architecture render` (if subagents used `--no-render`) and `apltk architecture validate`.
+    Sub-module pages stay self-only — cross-boundary behavior is ALWAYS `edge` with kind call|return|data-row|failure. Internal `dataflow` steps may reference a declared function plus reads/writes of declared variables on the SAME sub-module or validate fails.
+    Anchor every mutation to the actual diff; preserve existing atlas structure for parts the diff did not touch; for spec-driven overlays use $spec-to-project-html instead and for first-time bootstrap use $init-project-html. Report completion only after validate is OK; cite chosen diff scope, per-feature mutation counts, skipped diff buckets, and the location of the rendered atlas.

package/version-release/README.md

@@ -34,8 +34,6 @@ When the release includes code changes, `review-change-set` is still a condition
 
 Apply the same rule to every other conditional gate: if its scenario is met during release classification, it becomes blocking before version bumping, tagging, or release publication.
 
-That includes risk-driven review gates such as `discover-edge-cases` and `discover-security-issues` whenever the release surface makes them applicable.
-
 Do not report release completion after only bumping versions or pushing a commit: the matching tag and GitHub release are part of done criteria unless the user explicitly says to skip publication.
 
 If the user only wants commit + push, use `commit-and-push`.

package/version-release/SKILL.md

@@ -10,7 +10,7 @@ description: >-
 ## Dependencies
 
 - Required: **`commit-and-push`** (shared inspect/classify/readiness/commit/push mechanics); **`submission-readiness-check`** **before** version files, tags, or publication mutate.
-- Conditional: **`archive-specs`** when specs/docs need alignment; **`review-change-set`** (+ **`discover-edge-cases`** / **`discover-security-issues`** when risk triggers) on **code-affecting** release scope **before** version churn—blocking while findings open.
+- Conditional: **`archive-specs`** when specs/docs need alignment; **`review-change-set`** on **code-affecting** release scope **before** version churn—blocking while findings open.
 - Optional: none.
 - Fallback: Missing required skill ⇒ stop and report.
 
@@ -26,7 +26,7 @@ description: >-
 - **MUST** verify **remote** has commit + tag before calling release **done**; **MUST NOT** trust UI git shortcuts.
 - **Done** = version files + changelog section + **pushed** commit + **remote** tag + **published** GitHub release (unless user explicitly skips publication—then say so).
 
-**Repository regression checks:** Before creating release metadata, inspect existing local and remote tags plus any existing GitHub Release for the target version so duplicates are caught early. Do not continue until you can state the current version, the intended next version, and the exact tag name that will be created. **`review-change-set` is required for code-affecting releases**—run `review-change-set` for the same release scope before continuing; treat unresolved review findings as blocking. Any conditional gate whose trigger is confirmed by this classification becomes mandatory before version bumping, tagging, or release publication. Treat every scenario-matched gate as blocking before versioning or release publication. **`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. Never stop after the release commit or tag alone; creating the matching GitHub release is part of done criteria unless the user explicitly says to skip release publication.
+**Repository regression checks:** Before creating release metadata, inspect existing local and remote tags plus any existing GitHub Release for the target version so duplicates are caught early. Do not continue until you can state the current version, the intended next version, and the exact tag name that will be created. **`review-change-set` is required for code-affecting releases**—run `review-change-set` for the same release scope before continuing; treat unresolved review findings as blocking. Any conditional gate whose trigger is confirmed by this classification becomes mandatory before version bumping, tagging, or release publication. Treat every scenario-matched gate as blocking before versioning or release publication. Never stop after the release commit or tag alone; creating the matching GitHub release is part of done criteria unless the user explicitly says to skip release publication.
 
 ## Standards (summary)
 
@@ -58,7 +58,7 @@ description: >-
 
 ### 3) Gates before version churn
 
-- Classify scope; code-affecting ⇒ `review-change-set` (+ conditional edge/security same as **`commit-and-push`**); **`submission-readiness-check`** (+ **`archive-specs`** when indicated). All blocking items closed.
+- Classify scope; code-affecting ⇒ `review-change-set`; **`submission-readiness-check`** (+ **`archive-specs`** when indicated). All blocking items closed.
    - **Pause →** Am I versioning while `Unreleased`/readiness still wrong?
 
 ### 4) Decide version & tag

package/version-release/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Version Release"
   short_description: "Prepare a versioned release with bump, changelog, tag, GitHub release, and push"
-  default_prompt: "Use $version-release only for explicit release/version/tag requests, including direct semver wording like patch/minor/major update or requests to trigger release-published automation: inspect the current repository state, read the current version plus existing tag/release state, and inspect root CHANGELOG.md Unreleased content. Treat every conditional gate whose scenario is met as blocking before any version bump, tag, or release step: if the release 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 completed plan archives, project docs, AGENTS.md/CLAUDE.md, and changelog readiness are settled before any version bump or tag, confirm CHANGELOG.md Unreleased is release-ready, update version files, cut the release directly from CHANGELOG.md Unreleased, create the release commit and matching tag, push commits and tags, and publish the matching GitHub release before reporting success."
+  default_prompt: "Use $version-release only for explicit release/version/tag requests, including direct semver wording like patch/minor/major update or requests to trigger release-published automation: inspect the current repository state, read the current version plus existing tag/release state, and inspect root CHANGELOG.md Unreleased content. Treat every conditional gate whose scenario is met as blocking before any version bump, tag, or release step: if the release 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 completed plan archives, project docs, AGENTS.md/CLAUDE.md, and changelog readiness are settled before any version bump or tag, confirm CHANGELOG.md Unreleased is release-ready, update version files, cut the release directly from CHANGELOG.md Unreleased, create the release commit and matching tag, push commits and tags, and publish the matching GitHub release before reporting success."