@laitszkin/apollo-toolkit 3.11.2 → 3.11.4

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

@@ -1,14 +1,14 @@
 ---
 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 just like the base atlas — so `apltk architecture diff` can pair before/after by path. Preserve the two-layer rule and the responsibility split: when subagents are available, each subagent reads ONE affected feature and declares EVERY intra-feature change itself (sub-modules, function / variable / dataflow / error rows, intra-feature edges including error and rollback flows); the main agent only aggregates outbound-boundary summaries and declares cross-feature edges. Without subagents, process features sequentially with the same split. 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>`. 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.
 ---
 
 # Spec To Project HTML
 
 ## Dependencies
 
-- Required: **`init-project-html`** — its `SKILL.md` is the rulebook for what each component declaration means and which verbs to call. Reuse the same CLI here with `--spec`.
+- Required: **`init-project-html`** — its `SKILL.md` is the semantic rulebook; **`apltk architecture --help`** is the verb/flag source of truth. Reuse the same CLI here with `--spec`.
 - Conditional: **`recover-missing-plan`** if a spec pointer is missing.
 - Conditional: **`generate-spec`** / **`implement-specs*`** terminology for requirement IDs.
 - Optional: **`review-spec-related-changes`** when verifying diagram updates against specs.
@@ -17,26 +17,26 @@ 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>`. 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`**). 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** obey the semantic rules from `init-project-html/SKILL.md`:
-  - Sub-module pages stay self-only — express cross-boundary interactions via `edge add` (cross-feature) or intra-feature `edge add`, never as sub-module page prose.
-  - Feature pages stay lightweight — declare cross-submodule choreography through edges, not through sub-module-internal `dataflow` steps that wander outside the sub-module.
-- **MUST** reconcile new requirements and design deltas through CLI verbs:
-  - Add a sub-module → `submodule add --spec ...`. Removing → `submodule remove --spec ...` (the CLI lists the removed page in `_removed.txt` automatically).
-  - Rename a sub-module → `submodule remove` then `submodule add` with the new slug; the CLI emits both the removal entry and the new HTML page so `apltk architecture diff` classifies it as remove + add.
-  - Function / variable / dataflow / error deltas → corresponding `add` or `remove` verbs scoped to the sub-module.
-  - Edge changes → `edge add` or `edge remove` (use the stable `--id` when available to make the remove unambiguous).
-- **MUST NOT** drop modules that are still present in code just because the spec omits them — keep them, or rewrite their role/purpose strings to flag "out of spec scope".
-- **MUST** scope reads to the **affected feature modules** identified from the spec/design diff (plus any feature owning a cross-feature edge into an affected one). Apply the same context-safe read strategy as `init-project-html` Rule 3 — **subagents own intra-feature overlay changes; the main agent owns cross-feature seams**:
-  - **With subagents (preferred)** — main agent lists affected features first, then dispatches **one write-capable subagent per affected feature**. Each subagent deep-reads its feature and applies every intra-feature overlay mutation itself via `apltk architecture ... --spec <spec_dir> --feature <slug>` (add/remove sub-modules, function / variable / dataflow / error deltas, intra-feature edges — including error / rollback edges and ordered dataflow steps that capture variable state transitions). It returns ONLY a structured change summary of outbound boundaries (cross-feature edges added / changed / removed, with direction and proposed labels) plus its sub-module change list. The main agent never re-reads the feature source; it batches **only cross-feature** `edge add|remove` verbs from the aggregated summaries, then runs `apltk architecture render --spec ...` and `apltk architecture validate --spec ...`.
-  - **Without subagents** — process features one at a time: read one affected feature, **immediately** drive the CLI verbs for that feature (with `--spec ...`). Drop function-level details from memory before reading the next feature.
-  - **Forbidden**: loading every affected feature's source into the main agent's context before declaring — early details get pushed out and overlay declarations contradict each other.
+  - 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.
+- **MUST** reconcile deltas through the CLI families described in **`--help`**:
+  - Structural changes → `feature` / `submodule` (**add** / **set** / **remove** as appropriate).
+  - Per-sub-module rows → `function`, `variable`, `dataflow`, `error` (**add** / **remove** / **reorder** for dataflow where supported).
+  - Seams → `edge` **add** / **remove** (prefer stable **`--id`** when you may remove the same edge later).
+  - **`submodule remove`** / **`feature remove`** in spec mode populate removal manifests so `diff` can show **removed** pages; renames are usually **remove old slug + add new slug** so the viewer shows remove + add rather than a silent overwrite.
+- **MUST NOT** drop modules that are still present in code just because the spec omits them — keep them, or rewrite role/purpose to flag “out of spec scope”.
+- **MUST** scope reads to the **affected feature modules** from the spec/design diff (plus any feature owning the other end of a cross-feature edge into an affected one). **Subagents own intra-feature overlay writes; the main agent owns cross-feature seams — after all subagents finish:**
+  - Dispatch **one write-capable subagent per affected feature**. Each applies every intra-feature overlay mutation via `apltk architecture ... --spec <spec_dir>` (exact flags: **`--help`**). Each returns **ONLY** a structured summary: sub-module change list, outbound boundary changes (cross-feature edges to add/change/remove), and any `planned` / `gap` markers.
+  - **MUST** wait until **every** dispatched subagent has completed before running any cross-feature **`edge`** mutation, overlay-wide **`meta`** that stitches multiple features, or shared **`actor`** that exists only for cross-feature context.
+  - **Forbidden:** loading every affected feature’s source into the main agent before delegating — that explodes context and produces contradictory overlays.
 - **MUST** run `apltk architecture validate --spec <spec_dir>` after the final mutation. Resolve every reported error before reporting completion.
 
 ## Standards (summary)
 
 - **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 → branch by environment (subagent fan-out OR sequential read-declare) → `apltk architecture validate --spec ...` → handover.
+- **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.
 
@@ -44,8 +44,8 @@ description: >-
 
 Open the proposed-after viewer (`apltk architecture diff`) and verify both criteria on the overlay pages before reporting completion:
 
-1. **The macro overlay clearly shows the proposed-after feature × sub-module relationships**, including data flow (`--kind data-row`), interaction logic (`--kind call` + `--kind return`), error handling and rollback (`--kind failure`). Any new / changed / removed cross-boundary path the spec implies MUST exist as an edge mutation in the overlay — not as sub-module prose.
-2. **Each touched sub-module's internal overlay diagram clearly shows the function-level interactions inside it**, including function-to-function flow (`dataflow add --fn <declared-fn>`), variable state transitions (`--reads` / `--writes` referencing declared variables), and the resulting local data flow. If the spec introduces a new function or variable that participates in the flow, declare it via `function add` / `variable add` first, then reference it from the new `dataflow` step so `validate --spec` passes.
+1. **The macro overlay clearly shows the proposed-after feature × sub-module relationships**, including data flow (**`data-row`**), interaction logic (**`call`** + **`return`**), error handling and rollback (**`failure`**). Any new / changed / removed cross-boundary path the spec implies **MUST** exist as an edge mutation in the overlay — not as sub-module prose.
+2. **Each touched sub-module’s internal overlay diagram clearly shows the function-level interactions inside it**, including function references and variable reads/writes on `dataflow` steps. Declare `function` / `variable` before referencing them so `validate --spec` passes.
 
 ## Workflow
 
@@ -55,69 +55,49 @@ User-pointed path wins; otherwise use the batch `coordination.md` or `recover-mi
 
 ### 2) List the affected feature modules (no function bodies yet)
 
-Derive from the spec/design diff which feature modules change: new sub-modules, edge changes, variable changes, error changes, retired sub-modules… **Also** include any feature owning the other end of a cross-feature edge that is being changed (even if that feature's own spec is untouched). Record only `slug + change-kind`; do not enter function bodies yet.
+Derive from the spec/design diff which feature modules change: new sub-modules, edge changes, variable changes, error changes, retired sub-modules… **Also** include any feature owning the other end of a cross-feature edge that is being changed (even if that feature’s own spec is untouched). Record only `slug + change-kind`; do not enter function bodies yet.
 
-### 3) Branch the deep-read + declare by environment (mirrors `init-project-html` Rule 3)
+### 3) Subagents patch features; orchestrator patches cross-feature seams **after** all workers finish
 
-#### 3A) With subagents (preferred) — workers patch their feature; main agent patches only cross-feature edges
-
-Dispatch one **write-capable subagent per affected feature**, plus the main agent for the macro seams. Each subagent owns every intra-feature overlay write and reports outbound boundaries upward:
+Dispatch one **write-capable subagent per affected feature**. Each subagent owns every intra-feature overlay write and reports outbound boundaries upward. Use **`apltk architecture --help`** for exact `add|set|remove|reorder` spelling.
 
 > **Feature `<slug>` subagent contract (overlay)**
-> - Read this feature's affected sub-modules and the cited spec passages / requirement IDs.
-> - Apply every intra-feature overlay mutation via `apltk architecture ... --spec <spec_dir>`:
->   - `submodule add|set|remove` for added / renamed / retired / kind-or-role-changed sub-modules.
->   - `function add|remove`, `variable add|remove`, `dataflow add|remove|reorder`, `error add|remove` for per-sub-module deltas. Order `dataflow` steps so the **variable state transitions** through the new path are visible end-to-end.
->   - Intra-feature `edge add|remove` for every changed function-call / return / data-row / failure / rollback edge between the feature's own sub-modules.
-> - Run `apltk architecture validate --spec <spec_dir>` (scoped check) before returning.
-> - **Return ONLY**: (i) the sub-module change list (slug + change-kind + new kind/role when relevant), (ii) outbound boundary changes (cross-feature edges added / changed / removed, with the other-end `feature/sub` and the suggested `--kind` / `--label`), (iii) any `planned` / `gap` flags so the main agent can mirror them in `meta.summary` if needed.
+> - Read this feature’s affected sub-modules and the cited spec passages / requirement IDs.
+> - Apply every intra-feature overlay mutation with `--spec <spec_dir>`: structural (`feature` / `submodule`), rows (`function`, `variable`, `dataflow`, `error`), and intra-feature **`edge`** changes (including failure / rollback between this feature’s own sub-modules). Order `dataflow` so **variable state** reads end-to-end.
+> - Run `apltk architecture validate --spec <spec_dir>` before returning.
+> - **Return ONLY**: (i) sub-module change list, (ii) outbound boundary changes (cross-feature edges add/change/remove with endpoints and suggested kind/label), (iii) any `planned` / `gap` flags for `meta.summary`.
 
-Main agent — after every subagent returns — declares **only** the cross-feature seams and renders once:
+**After every subagent has completed**, the main agent declares **only** cross-feature seams, then renders and validates:
 
 ```bash
-# one verb per cross-feature edge reported by the subagents
+# exact flags per edge: see --help
 apltk architecture edge add --spec <spec_dir> --from <featA>/<subA> --to <featB>/<subB> --kind call|return|data-row|failure --label "..." --no-render
 apltk architecture edge remove --spec <spec_dir> --id <stable_id> --no-render
 apltk architecture render --spec <spec_dir>
 apltk architecture validate --spec <spec_dir>
 ```
 
-- **Pause →** Do every `planned` / `gap` declaration appear consistently across affected sub-modules (e.g. role text + variable purpose strings)? Inconsistency would mislead reviewers.
-- The main agent **MUST NOT** re-declare a subagent's intra-feature components, and **MUST NOT** open source files for any feature it delegated.
-
-#### 3B) Without subagents — feature-by-feature read-declare loop
-
-Process the step-2 list one feature at a time. Per feature:
-
-1. **Deep-read** this feature's affected sub-modules.
-2. **Run CLI verbs immediately** with `--spec ...`: `submodule add|set|remove`, `function add|remove`, `variable add|remove`, `dataflow add|remove|reorder`, `error add|remove`, intra-feature `edge add|remove`.
-3. **Cross-feature edges**: if the target feature has not been overlaid yet, add the edge anyway — the CLI accepts edges into features that exist in the base atlas without re-declaring them in the overlay.
-4. **Drop function-level memory** of this feature; keep only cluster id + edge notes.
-5. Move to the next feature.
-
-Final pass after every feature is patched:
-
-- `apltk architecture render --spec <spec_dir>` (if you used `--no-render`).
-- `apltk architecture validate --spec <spec_dir>`.
+- **Pause →** Do `planned` / `gap` markers read consistently across affected sub-modules?
+- 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 `apltk architecture diff` pair every changed page correctly? If a page shows up as add + remove instead of modified, you renamed a slug somewhere. Re-check.
+- **Pause →** Does `apltk architecture diff` pair every changed page correctly? If a page shows as add + remove instead of modified, you renamed a slug somewhere — re-check.
 
 ### 4) Traceability (suggested)
 
-Use `feature-trace` (or in `meta.summary` for spec-only changes) to map spec IDs to implementation status: `met` / `partial` / `planned` / `gap`.
+Use `feature-trace` (or `meta.summary` for spec-only changes) to map spec IDs to implementation status: `met` / `partial` / `planned` / `gap`.
 
 ### 5) Report
 
-List touched verbs (or the generated YAML files), the resulting diff counts (modified / added / removed) from `apltk architecture diff`, the read strategy used (3A or 3B), unresolved spec-vs-code gaps, and any follow-ups.
+List overlay files touched (or verb families used), the diff counts (`modified` / `added` / `removed`) from `apltk architecture diff`, confirmation that **all subagents finished before cross-feature wiring**, unresolved spec-vs-code gaps, and any follow-ups.
 
 ## Sample hints
 
-- **Batch merge**: when one domain has multiple specs, each member's `--spec <member_dir>` writes its own overlay; `apltk architecture diff` shows them as separate sections in the paginated viewer.
-- **Spec shrinks scope**: prefer `submodule set --role "deprecated: ..."` so reviewers see the planned retirement before issuing `submodule remove`.
-- **Design-only change**: still review edges — interaction order shifts even when no sub-module is added; verify with `apltk architecture validate` to surface dangling references.
+- **Batch merge**: each member spec’s `--spec <member_dir>` writes its own overlay; `diff` lists each spec’s section in the paginated viewer.
+- **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.
 
 ## References
 
-- `init-project-html/SKILL.md` — authoritative verb-by-verb rulebook.
-- `init-project-html/references/TEMPLATE_SPEC.md` — component schema cheat sheet (also linked from this skill's `references/TEMPLATE_SPEC.md`).
-- `apltk architecture --help` — live CLI reference.
+- `init-project-html/SKILL.md` — semantic contracts and acceptance criteria.
+- `init-project-html/references/TEMPLATE_SPEC.md` — schema cheat sheet (fields/enums), not a command list.
+- **`apltk architecture --help`** — live CLI reference.

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

@@ -2,17 +2,10 @@ interface:
   display_name: "spec-to-project-html"
   short_description: "Sync the project HTML architecture atlas with active planning specs via `apltk architecture --spec`"
   default_prompt: >-
-    Use $spec-to-project-html to read `docs/plans` (spec.md → design.md → contract.md), translate the spec/design delta into `apltk architecture --spec <spec_dir>` CLI verbs, and let the CLI write the overlay YAML under `<spec_dir>/architecture_diff/atlas/` plus the affected proposed-after HTML under `<spec_dir>/architecture_diff/`. The macro SVG and every sub-module's internal-dataflow diagram in the overlay output stay zoomable, just like the base atlas. NEVER hand-edit files under `architecture_diff/**` — the renderer (owned by $init-project-html) is the only writer. The base atlas under `resources/project-architecture/` is read-only in spec mode.
-    Read strategy (mirrors $init-project-html Rule 3 to avoid context loss AND to enforce a hard responsibility split). STEP 1: list AFFECTED feature modules from the spec/design diff (plus any feature owning a cross-feature edge into an affected one) — without diving into function bodies.
-    STEP 2: branch by environment.
-    (3A, preferred) with subagents, dispatch ONE write-capable subagent per affected feature. Each subagent deep-reads its own feature and applies every intra-feature overlay mutation itself via `apltk architecture ... --spec <spec_dir> --feature <slug>`: `submodule add|set|remove`, `function add|remove`, `variable add|remove`, `dataflow add|remove|reorder` (order the steps so the variable state transitions through the new path are visible end-to-end), `error add|remove`, and EVERY intra-feature `edge add|remove` (including failure / rollback edges between the feature's own sub-modules). The subagent returns ONLY a structured CHANGE summary of (i) sub-module changes (slug + change-kind + new kind/role when relevant), (ii) outbound boundary changes (cross-feature edges added / changed / removed with the other-end `feature/sub` and suggested `--kind` / `--label`), and (iii) any `planned` / `gap` flags. The main agent never re-reads source for a delegated feature and never re-declares its intra-feature components — it batches ONLY cross-feature `edge add|remove` from the aggregated summaries, then runs a single `apltk architecture render --spec <spec_dir>` and `apltk architecture validate --spec <spec_dir>`.
-    (3B, no subagents) handle affected features ONE AT A TIME — deep-read feature A, IMMEDIATELY drive the CLI verbs for A with `--spec ...`, drop A's function-level details from memory before moving on.
-    CLI verbs (always pass `--spec <spec_dir>`; kebab-case slugs):
-    `submodule add|set|remove --feature X --slug Y --kind ui|api|service|db|pure-fn|queue|external --role "..."`,
-    `function add|remove --feature X --submodule Y --name fn --in "..." --out "..." --side pure|io|write|tx|lock|network --purpose "..."`,
-    `variable add|remove --feature X --submodule Y --name v --type T --scope call|tx|persist|instance|loop --purpose "..."`,
-    `dataflow add|remove|reorder --feature X --submodule Y --step "..." [--fn <declared-fn>] [--reads "v1,v2"] [--writes "v3,v4"] [--at N]` (or `--from i --to j` for reorder; every `--fn` / `--reads` / `--writes` value MUST reference a function/variable declared in the merged state for the same sub-module or `validate --spec` fails),
-    `error add|remove --feature X --submodule Y --name ErrCode --when "..." --means "..."`,
-    `edge add|remove --from <feature>[/sub] --to <feature>[/sub] --kind call|return|data-row|failure --label "..." [--id <stable>]`.
-    Removals: `submodule remove` / `feature remove` writes `_removed.yaml`; the renderer emits `_removed.txt` and `apltk architecture diff` classifies the missing pages as `removed`. Rename = remove old slug + add new slug. After the final mutation run `apltk architecture validate --spec <spec_dir>` (must return OK) and `apltk architecture diff` to verify pairing.
-    Each sub-module page stays self-only — express any cross-boundary interaction as an edge via `edge add`, NEVER as sub-module page prose. For `planned` / `gap` items the spec mandates but code does not yet implement, surface the marker in the relevant field (e.g. `--role "planned: TOTP service"`, `--purpose "gap: not wired"`). Anchor every declaration to a concrete spec passage + code path. Report the read strategy used (3A or 3B), the resulting diff counts (`modified` / `added` / `removed`), and any unresolved spec-vs-code gaps.
+    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/**`.
+    **`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`.
+    Sub-module pages stay self-only — cross-boundary = `edge`. For removals/renames in overlay, follow SKILL.md (`submodule remove` / remove+add pattern) so `diff` classifies correctly.
+    After work: `validate --spec` MUST be OK; run `diff` and report modified/added/removed counts. Semantic rules: $init-project-html SKILL.md.