@laitszkin/apollo-toolkit 3.9.6 → 3.10.0

package/merge-changes-from-local-branches/SKILL.md

@@ -1,167 +1,114 @@
 ---
 name: merge-changes-from-local-branches
 description: >-
-  Read changes from local branches identified by branch name and merge them back
-  into the current local branch. When conflicts arise, auto-resolve them by
-  keeping correct functionality (preferring the more recent change on the same
-  line, or the change that preserves working behavior). After merge verification,
-  run `archive-specs` so completed plan sets are archived and durable project
-  docs are synchronized, then hand the current branch state to `commit-and-push`
-  so the final submit workflow commits and pushes on that same local branch.
-  Use when the user asks to consolidate local branch work, merge named branches
-  into the current branch, or prepare the current branch for integration.
+  Read changes from local branches identified by branch name and merge them back into the current local branch. Resolve conflicts by composing correct behavior (prefer the more recent change on the same line or the variant that preserves working behavior), using **`merge-conflict-resolver`** when needed. Verify after merges; remove successfully merged source branches and detached worktrees only after merge + verification succeed. Finalize through **`commit-and-push`** for submission-readiness gates and the **final local commit** on the same branch—**do not** push unless the user explicitly requested remote update in this thread (**`commit-and-push`** step 7). **Does not** run **`archive-specs`** as part of this skill.
+  Use when consolidating named local branch work into the current branch or preparing integration on that branch.
 ---
 
 # Merge Changes from Local Branches
 
 ## Dependencies
 
-- Required: `archive-specs` to archive completed plan sets and synchronize durable project docs after merge verification, and `commit-and-push` for the final current-branch submission flow.
-- Conditional: `merge-conflict-resolver` to resolve merge conflicts deterministically when conflicts arise.
+- Required: **`commit-and-push`** for submission-readiness, mandated reviews, and the **final** commit on the original current branch (push **only** when the user explicitly asked for remote update in this thread—otherwise stop after commit).
+- Conditional: **`merge-conflict-resolver`** when merge conflicts require deterministic resolution.
 - Optional: none.
-- Fallback: If git operations fail, stop and report the error.
+- Fallback: If **`commit-and-push`** is unavailable, **MUST** stop and report—**MUST NOT** improvise readiness or use a bare `git commit` shortcut. If git merge operations fail irreparably, stop and report.
 
-## Standards
+## Non-negotiables
 
-- Evidence: Inspect the original current branch, local branches, branch-name matches provided by the user or active spec names, actual conflicting files, and any active batch-spec `coordination.md` merge-order guidance before deciding what to merge.
-- Execution: Merge only the relevant named branches back into the original current branch, read any active batch-spec `coordination.md` and honor its documented merge order when present, resolve conflicts by reading both sides and editing the merged result to preserve shipped behavior, verify the merged state, delete each successfully merged source branch and its detached worktree only after the merged result is confirmed, run `archive-specs` after merge verification so completed plan sets are archived and durable docs are synchronized, then hand the final current-branch state to `commit-and-push` so changelog/readiness/commit/push work happens through the shared submission workflow on the same branch.
-- Quality: Never use blanket timestamp rules or default `-X ours/theirs` conflict resolution as the primary merge strategy, never infer in-scope branches from ancestry heuristics when branch names already define the target set, and do not declare success until the final current-branch state has been checked, verified, and cleared for post-merge archival/doc-sync work.
-- Output: Produce a clean current branch with all relevant named-branch changes integrated and ready for the shared submit workflow.
+- **MUST** treat the branch that was current at workflow start as the **authoritative merge target** for the whole workflow; **MUST NOT** silently switch the destination to **`main`** or another branch unless the user explicitly rescopes.
+- **MUST** determine in-scope branches from **explicit branch names** the user gives **or** from unambiguous mappings from active spec / `coordination.md` context—**MUST NOT** infer the merge set from ancestry heuristics alone when names already define intent.
+- **MUST** read active batch **`coordination.md`** when present and honor a documented **`Merge order` / landing order**; if multiple batches conflict or branch-to-spec mapping is ambiguous, **MUST** stop and report instead of guessing order.
+- **MUST** resolve conflicts by reading both sides and editing merged results that preserve shipped behavior—**MUST NOT** rely on blanket **`-X ours` / `-X theirs`** or timestamp guesses as the primary strategy.
+- **`archive-specs`**: **MUST NOT** invoke **`archive-specs`** from this skill. Any archival or doc-sync routing belongs to **`commit-and-push`** (via **`submission-readiness-check`**) when that workflow’s gates require it—not a separate mandated step immediately after merges here.
+- **MUST** verify the merged tree (targeted checks after conflictful merges; broader **`npm test` / equivalent** when the repo provides a standard command) before deleting source branches or handing off to **`commit-and-push`**.
+- **MUST NOT** **`git push`**, tag, or release **from this skill**; **`commit-and-push`** owns push **only** when the user explicitly requested remote publication in this thread (**same rule as **`commit-and-push`** step 7**).
+- **MUST** finalize through **`commit-and-push`** after staging the post-merge intent—**MUST NOT** bypass **`submission-readiness-check`** / mandated gates with a stray local commit path.
+- **MUST NOT** force-delete merged branches (**`-D`**) when **`-d`** refuses; **MUST** stop and report branches that are not actually merged into the target.
 
-## Goal
+## Standards (summary)
 
-Consolidate the intended named local branches back into the original current branch with automatic conflict resolution that preserves correct functionality.
+- **Evidence**: `git branch`, `git log` / diff stats vs current branch, conflict file contents, `coordination.md` merge order when present.
+- **Execution**: Inventory → clean target branch → sequential merges → verify → prune merged branches/worktrees → **`commit-and-push`** through local commit (push only if user asked).
+- **Quality**: Scope strictly to named / mapped branches; no unrelated branch sweeps; no push-by-default from this workflow.
+- **Output**: Integrated current branch ready for **`commit-and-push`**; concise report of merged/skipped branches, conflicts resolved, verification commands.
 
 ## Workflow
 
+**Chain-of-thought:** Before each numbered step, answer the **`Pause →`** prompts. Validator or verification red **blocks** advancing to pruning or **`commit-and-push`**.
+
 ### 1) Inventory the current branch and in-scope named branches
 
-- Run `git branch` to list all local branches.
-- Check the current branch with `git branch --show-current` and capture `git status -sb`.
-- Inspect active planning artifacts under `docs/plans/` and look for batch roots that still contain live spec sets plus a `coordination.md`.
-- When an active batch is present, read its `coordination.md` before deciding merge order.
-- Treat the original current branch as the authoritative merge target for the whole workflow; do not silently switch that target to `main`.
-- Determine the in-scope branches directly from branch names:
-  - prefer the exact branch names the user provided
-  - otherwise map active spec-set names or documented merge-order entries to branch names
-  - otherwise stop and report the missing branch-name target instead of inferring from ancestry
-- Accept a branch as in scope only when its branch name can be matched unambiguously to the requested merge set; skip unrelated local branches.
-- Compare each in-scope candidate branch against the current branch with `git log --oneline <current-branch>..<candidate>`, `git diff --stat <current-branch>...<candidate>`, or equivalent evidence so empty or already-merged branches are skipped.
-- For each branch, note:
-  - Branch name
-  - How the branch name was matched to the requested merge set
-  - Commits ahead of the current branch
-  - Last commit message (via `git log -1 --oneline`)
+- Run `git branch`; capture `git branch --show-current` and `git status -sb`.
+- Inspect `docs/plans/` for active batch roots that include **`coordination.md`**; read merge-order guidance **before** choosing sequence.
+- Build the merge set from **user branch names**, else from unambiguous spec-name / **`coordination.md`** mappings—if a required name cannot be matched, stop and report.
+- For each candidate: `git log --oneline <current>..<candidate>` and `git diff --stat <current>...<candidate>` (or equivalent); skip empty / already-up-to-date branches and record why.
+- Per branch, note: name, match rationale, commits ahead, `git log -1 --oneline`.
+  - **Pause →** Is every in-scope branch matched **unambiguously**, not by “probably related” ancestry?
+  - **Pause →** If **`coordination.md`** gives a merge order, does my sequence match it literally?
 
 ### 1.5) Resolve merge order from active batch specs
 
-- Treat active batch specs as authoritative merge-order guidance when they include a concrete `Merge order / landing order` entry in `coordination.md`.
-- Map branch names to the corresponding spec sets or worktrees using the batch folder names, spec-set names, and documented merge-order entries; do not guess when the mapping is ambiguous.
-- Merge only the in-scope named branches in the documented order when that order is explicit.
-- If multiple active batches exist, reconcile their merge-order guidance before merging; if the orders conflict or the branch-to-spec mapping is unclear, stop and report the ambiguity instead of choosing an arbitrary sequence.
-- If no active batch spec provides an explicit merge order, fall back to the requested branch-name list and merge the relevant branches sequentially in that explicit name order.
+- When **`coordination.md`** defines **`Merge order` / landing order**, merge **only** in that order after mapping branch names to specs/worktrees without guessing.
+- When multiple active batches disagree or mapping is unclear, stop and report.
+- When no explicit order exists, use the user’s branch list order sequentially.
+  - **Pause →** Would merging in a different order violate a written batch plan?
 
 ### 2) Ensure clean state on the original current branch
 
-- Check `git status` on the original current branch.
-- If the current branch has uncommitted changes that are unrelated to the merge request, stop and report them instead of stashing automatically.
-- Never change the authoritative target branch unless the user explicitly asks for a different destination.
-- Only proceed once you can state which branch or branches actually need to be merged.
+- Inspect `git status`. If unrelated uncommitted changes block a safe merge, stop and report—**MUST NOT** stash or discard without user direction.
+  - **Pause →** Am I still on the **same** authoritative target branch I started with?
 
 ### 3) Merge branches sequentially in the resolved order
 
-For each in-scope named branch:
+For each in-scope branch:
+
+1. `git checkout <current-branch>`
+2. `git merge <branch-name> --no-ff -m "Merge branch '<branch-name>' into <current-branch>"`
+3. On conflicts: use **`merge-conflict-resolver`**; then `git add` resolved paths.
+4. If resolution is ambiguous, prefer behavior that preserves tests, documented intent, and minimal semantic drift.
+5. Complete the merge commit if Git did not auto-complete.
 
-1. Check out the original current branch:
-   ```bash
-   git checkout <current-branch>
-   ```
+### 4) Verify merged state
 
-2. Merge the branch:
-   ```bash
-   git merge <branch-name> --no-ff -m "Merge branch '<branch-name>' into <current-branch>"
-   ```
+- After conflictful merges, run the most relevant targeted tests or builds for touched areas.
+- After all merges, run the repo’s usual validation (`npm test`, `cargo test`, etc.) when applicable.
+  - **Pause →** Did verification fail? **MUST** fix on the current branch before pruning or **`commit-and-push`**—**do not** hide red tests behind a merge report.
 
-3. If conflicts occur, use $merge-conflict-resolver to resolve them deterministically.
+### 5) Prune merged sources (after verified success only)
 
-   After resolving files:
-   ```bash
-   git add <resolved-files>
-   ```
+- `git worktree list`; remove worktrees for successfully merged branches when safe.
+- `git branch -d <branch-name>` only for verified merges; refuse **`-D`** when **`-d`** fails—report instead.
+- **Never** delete the original target branch, the checked-out branch, or branches that failed / were skipped.
 
-4. If auto-resolution is ambiguous, prefer the change that:
-   - Does not break existing tests
-   - Preserves the documented feature intent
-   - Aligns with the code currently shipped on the source branch
-   - Minimizes hidden semantic drift between the merged modules
+### 6) Submit via **`commit-and-push`** (local commit; push optional)
 
-5. Complete the merge:
-   ```bash
-   git commit -m "Merge branch '<branch-name>' into <current-branch>"
-   ```
+- Stage the post-merge / fix-up intent per user scope.
+- Run **`commit-and-push`** through **commit**: inspect, classify gates, mandated reviews where applicable, **`submission-readiness-check`**, then commit with conventional message—**omit push** unless the user explicitly requested remote update in this thread ( **`commit-and-push`** step **7**).
+- **MUST NOT** reintroduce **`archive-specs`** as a sibling step controlled by **this** skill; if **`submission-readiness-check`** routes archival work, **`commit-and-push`** owns that decision.
+  - **Pause →** Am I about to push without an explicit user request for remote publication?
+  - **Pause →** Does `git diff --cached` match intended merge scope—no stray unrelated paths?
 
-### 4) Verify merged state
+### 7) Report
 
-- After each conflictful merge, run the most relevant targeted tests or build checks for the files that changed.
-- After all merges complete, run the repository's broader validation command when one exists:
-  ```bash
-  npm test  # or yarn test, cargo test, etc.
-  ```
-- If verification fails, fix the merged state on the current branch before proceeding.
-
-### 5) Archive completed specs and sync durable project docs
-
-- After all in-scope merges succeed and the current-branch state has been verified, invoke `archive-specs`.
-- Let `archive-specs` convert and archive any completed `docs/plans/...` spec sets that now reflect the delivered outcome.
-- Let `archive-specs` synchronize durable project docs and `AGENTS.md/CLAUDE.md` when the merged result changed operator workflows, repository guidance, or user-visible behavior.
-- Do not proceed to the final submission commit while required archival or documentation updates remain unfinished.
-- If no completed spec sets or project-doc drift are present, record that evidence explicitly before moving on.
-
-### 6) Hand off the merged result for shared submission handling
-
-- After a source branch has been merged successfully and the merged current-branch state has been verified, remove the source branch worktree if one exists:
-  ```bash
-  git worktree list
-  git worktree remove <worktree-path>
-  ```
-- Delete only branches that were merged successfully:
-  ```bash
-  git branch -d <branch-name>
-  ```
-- If a branch still has an attached worktree, remove the worktree before deleting the branch.
-- Never delete:
-  - the original current branch
-  - the currently checked-out branch
-  - branches that were skipped, failed to merge, or still need manual follow-up
-- If `git branch -d` refuses deletion because the branch is not actually merged, stop and report the branch instead of forcing deletion with `-D`.
-- Once merge verification and archival/doc synchronization pass, invoke `commit-and-push` for the original current branch so the final submission flow owns:
-  - `CHANGELOG.md` readiness
-  - the final commit creation on the original current branch
-  - the user-requested push on that same branch
-- Do not duplicate commit-message or changelog-readiness logic inside this skill; post-merge archival must flow through `archive-specs`.
-- If a follow-up fix is required after verification or archival/doc sync, make that fix on the original current branch before handing off to `commit-and-push`.
-
-### 7) Report completion
-
-- List all named branches that were merged.
-- List any branches intentionally skipped because they were already merged, empty, or out of scope.
-- Confirm the original current branch is updated with all merged changes.
-- Note any conflicts that were resolved and the rationale.
-- Report the verification commands that were run.
-- Report whether `archive-specs` updated durable docs or found no archival/doc-sync work to do.
-- Confirm whether the workflow stopped at the local commit boundary or continued into a remote push because the user explicitly requested it.
+- List merged vs skipped branches and why.
+- Current branch name; confirmation merges landed on original target.
+- Conflicts resolved and brief rationale.
+- Verification commands executed.
+- State whether completion stopped at **local HEAD** (**no push**) or included push per explicit user ask.
+
+## Sample hints
+
+- **Skip**: candidate shows no commits ahead of current—record “already merged / empty”.
+- **`coordination.md`**: landing order **`api-layer`** then **`cli-wrapper`** ⇒ merge matching branches in that sequence even if creation dates differ.
+- **`commit-and-push` without push**: user said “merge and commit locally”—run **`commit-and-push`** gates and commit; report `HEAD` hash; **no** **`git push`**.
 
 ## Working Rules
 
-- Never force-push; use only merge or rebase with merge.
-- Prefer preserving functionality over keeping either branch's exact changes.
-- Do not push to remote from this skill directly; let `commit-and-push` own any later publish step only when the user explicitly requests it.
-- Never merge unrelated or ambiguously matched branches into the current branch; merge only branches whose names are explicitly requested or can be matched unambiguously from the active spec context.
-- If a branch contains no meaningful changes (empty merge), skip it.
-- Keep the current branch history clean and readable.
-- If a branch's merge breaks tests, resolve the conflict differently before committing.
-- Do not stash or discard unrelated work automatically; stop when the working tree state makes the merge ambiguous.
-- Delete merged source branches and their detached worktrees only after the merge commit and verification both succeed.
-- When active batch specs provide merge-order guidance for in-scope named branches, follow that order unless new evidence proves the plan is stale or inapplicable; if so, stop and report the mismatch instead of silently overriding the batch plan.
-
-Resolve conflicts using $merge-conflict-resolver.
+- Never force-push from this workflow.
+- Preserve functionality over winning either branch’s raw diff verbatim.
+- Do not merge ambiguously matched or unrelated branches.
+- Do not delete merged sources until merge commit **and** verification succeed.
+- When batch merge-order documentation applies, follow it unless you stop with evidence it is stale.
+
+Resolve conflicts using **`merge-conflict-resolver`**.

package/merge-changes-from-local-branches/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Merge Changes from Local Branches"
   short_description: "Merge named local branches back into the current branch with checked conflict resolution"
-  default_prompt: "Use $merge-changes-from-local-branches to inventory the current branch plus the named local branches that should be merged, inspect active batch-spec `coordination.md` files under `docs/plans/` and follow their documented merge order when present, match the merge scope by branch name instead of branch ancestry, merge only those in-scope branches back into the same current branch, resolve conflicts by reading and composing the correct behavior instead of relying on blanket merge strategies, run targeted verification after conflictful merges, run `archive-specs` so completed plan sets are archived and durable docs are synchronized before the final submit step, delete successfully merged source branches and detached worktrees only after verification succeeds, and leave remote publication to `commit-and-push`."
+  default_prompt: "Use $merge-changes-from-local-branches to inventory the current branch plus the named local branches that should be merged, inspect active batch-spec `coordination.md` files under `docs/plans/` and follow their documented merge order when present, match the merge scope by branch name instead of branch ancestry, merge only those in-scope branches back into the same current branch, resolve conflicts by reading and composing the correct behavior instead of relying on blanket merge strategies, run targeted verification after conflictful merges, delete successfully merged source branches and detached worktrees only after verification succeeds, then run $commit-and-push for submission-readiness and the final local commit on that branch without pushing unless the user explicitly requested remote update in the same thread. Do not invoke $archive-specs from this skill."

package/merge-conflict-resolver/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "merge-conflict-resolver"
+  short_description: "Resolve git merge conflicts with deterministic, evidence-based rules"
+  default_prompt: >-
+    Use $merge-conflict-resolver to read both sides of conflict markers, apply scenario-specific resolution rules that preserve intended behavior, verify with the project’s tests or checks, and when the user needs persistence, hand off to $commit-and-push instead of ad-hoc git commands.

package/package.json

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

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

@@ -0,0 +1,116 @@
+---
+name: spec-to-project-html
+description: >-
+  Sync HTML architecture pages to active planning specs. **MUST** preserve the two-layer rule: macro `index.html` stays ONE SVG showing both feature-module and sub-module interactions (multi-edge, producer/consumer loops, cross-feature data-row); each sub-module page stays self-only (function I/O + variables-with-business-purpose + internal data flow + local errors). Feature `index.html` stays lightweight (story + submodule-nav). Read strategy mirrors `init-project-html`: list affected feature modules first; with subagents, dispatch one read-only subagent per affected feature to return summaries before patching; without subagents, patch one feature's pages plus its macro slice before moving to the next — never load every affected feature's code into the main context at once. Ground in repo evidence; mark `TBD` when code is missing.
+---
+
+# Spec To Project HTML
+
+## Dependencies
+
+- Required: **`init-project-html`** — its `SKILL.md` is the binding rulebook for page contracts (Rules 1–7), and its `references/architecture.css` is the shared asset to copy. Local cheat sheet (same vocabulary + class hooks + DOM snippets) lives in this skill's own `references/TEMPLATE_SPEC.md`.
+- 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.
+- Fallback: spec demands components that are absent from code → label **planned / gap** in macro summary and on affected nodes; **MUST NOT** mark them as implemented.
+
+## Non-negotiables
+
+- **MUST** read specs in order unless the user directs otherwise: `spec.md` → `design.md` → `contract.md` → coordination notes.
+- **MUST** open and parse the existing macro `index.html`, every `features/<slug>/index.html`, **and every sub-module HTML** before editing — preserve `data-feature-id` / `data-submodule-id` / `data-edge-id` unless a rename is explicit and propagated everywhere (including the macro SVG nav and the macro manifest).
+- **MUST** obey `init-project-html/SKILL.md` Rules 1–7 (page contracts, naming, assets, accessibility, forbidden shortcuts). Two reminders that this skill violates most often:
+  - **Rule 1** — cross-submodule interactions live only in the macro SVG (multi-edge, producer/consumer, cross-feature data-row); the macro **MUST** index every sub-module page.
+  - **Rule 2** — sub-module pages contain only `sub-io` + `sub-vars` (variables-with-business-purpose) + `sub-dataflow` + `sub-errors`; no cross-boundary narrative.
+- **MUST** reconcile new requirements and design deltas:
+  - In the macro SVG, add/remove/relabel sub-module nodes and edges; every new node also gets a sub-module HTML and a manifest row.
+  - On sub-module pages, add/remove/update function I/O and internal data flow; **never** describe cross-boundary interactions here — update the macro edges instead.
+- **MUST** migrate any leftover legacy structure during the same edit pass:
+  - feature index `flow-chart--submodules` / `flow-edge-manifest` / `flow-return-row` → move to the macro; feature index reverts to lightweight.
+  - sub-module page `submodule-role` cross-boundary prose or cross-boundary manifests → delete or compress into a single "see macro" link.
+  - legacy single-file `features/<slug>.html` → migrate to the directory layout.
+- **MUST NOT** shrink the macro into prose-only or feature-only diagrams: the multi-edge + sub-module layer must remain visible in the SVG.
+- **MUST NOT** drop modules that are still present in code just because the spec omits them — keep them, or annotate as "out of spec scope" with a reason.
+- **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:
+  - **With subagents** — main agent lists affected features first, then dispatches **one read-only subagent per affected feature** to deep-read and return a structured change summary (affected sub-modules, variable / I/O / boundary deltas). Main agent **only** receives summaries, and only after every subagent reports does it patch the macro and pages in one pass.
+  - **Without subagents** — process features one at a time: read one affected feature, **immediately** patch its `features/<slug>/` tree plus the macro cluster/nodes/edges (mark edges pointing at unread affected features with `data-edge-target-pending`). Drop function-level details from memory before reading the next feature. After all features are patched, resolve every pending edge in a final pass.
+  - **Forbidden**: loading every affected feature's source into the main agent's context before patching — early details get pushed out and macro/sub-module pages contradict each other.
+
+## Standards (summary)
+
+- **Evidence**: cite the spec passage (design subsystem entry) alongside the code path.
+- **Execution**: locate the plan set → read the existing HTML tree → list affected feature modules → branch by environment (subagent fan-out OR sequential read-patch-write; resolve macro pending edges last) → link check.
+- **Quality**: the macro SVG keeps "≥2 edges on one node pair", "at least one producer/consumer loop", and "at least one cross-feature data-row" (when the spec still requires it); sub-module pages stay self-only; CSS paths correct; no pending edges left.
+- **Output**: touches only `resources/project-architecture/**`. If files are missing, scaffold via `init-project-html` first, then merge spec deltas.
+
+## Workflow
+
+### 1) Resolve spec inputs
+
+User-pointed path wins; otherwise use the batch `coordination.md` or `recover-missing-plan` to find the most recent plan; collect `R…` / `INT-…` IDs for traceability.
+
+### 2) List the affected feature modules (no function bodies yet)
+
+Derive from the spec/design diff which feature modules change: new nodes, edge changes, variable changes, error changes, retired sub-modules… **Also** include any feature that owns 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) Read the current HTML atlas (scoped to affected features)
+
+Load the macro `index.html` + every affected feature directory + that directory's sub-module pages; list existing node/edge IDs; lock the IDs to preserve (so steps 4/5 do not silently rename).
+
+### 4) Branch the deep-read + patch by environment (mirrors `init-project-html` Rule 3)
+
+#### 4A) With subagents (preferred)
+
+Dispatch one **read-only subagent per affected feature**, requiring this summary:
+
+> **Feature `<slug>` change summary**
+> - Matching spec passages / requirement IDs.
+> - Affected sub-modules (added / renamed / retired / I/O changed).
+> - Per sub-module: function I/O, variables-with-business-purpose (additions / removals / renames), internal flow, errors raised.
+> - Boundary changes: new / changed / removed call edges and data-row edges (name the other-end feature / sub-module).
+> - Spec items the code does not yet scaffold: mark as `planned` / `gap`.
+
+Main agent collects summaries and patches in one pass:
+
+1. Patch the macro `index.html`: add/change/remove `<a><g class="m-sub">` nodes; add/change/remove `<path class="m-edge ...">`; mirror in `flow-edge-manifest--macro`; preserve multi-edge, call/return pairs, cross-feature data-row.
+2. Patch each affected `features/<slug>/index.html` (still lightweight) and each affected sub-module page (self-only: `sub-io`, `sub-vars`, `sub-dataflow`, `sub-errors` all in sync).
+3. Update `<nav class="atlas-submodule-index">`: link new pages; remove retired pages.
+
+- **Pause →** Do `planned` / `gap` nodes appear consistently in both the macro and `atlas-summary` as "not yet implemented"? Inconsistency would mislead readers.
+
+#### 4B) Without subagents — feature-by-feature read-patch-write
+
+Process the step-2 list one feature at a time. Per feature, run the full inner loop:
+
+1. **Deep-read** this feature's affected sub-modules (functions, variables, boundaries).
+2. **Patch immediately**:
+   - `features/<slug>/index.html` (refresh user story; add/remove rows in `submodule-nav`; do NOT re-introduce a cross-submodule flowchart).
+   - Each affected sub-module page:
+     - Function I/O table updated (additions / renames / signature changes).
+     - `sub-vars`: add, remove, or rename variables (including DB columns, config knobs, counters, time anchors) introduced by the spec/design; rewrite the business-purpose column to match the new branches.
+     - `sub-dataflow` steps + small SVG refreshed.
+     - `sub-errors` updated with any new error types.
+     - Any leftover "who I talk to" text → move into a macro edge, or delete.
+3. **Incremental macro patch**: sync this feature's nodes/edges/manifest rows; mark edges pointing at **unread** affected features as `data-edge-target-pending="<future-slug>"`.
+4. **Drop function-level memory** of this feature; keep only cluster id and pending-edge notes.
+5. Return to step 1 for the next feature.
+
+Final pass after every feature is patched:
+
+- Resolve every macro `pending` edge; none may remain.
+- Verify `<nav class="atlas-submodule-index">` matches the final set of sub-module pages.
+
+- **Pause →** Pending edges left? Step 2 missed an affected feature — re-read and patch.
+
+### 5) Traceability (suggested)
+
+Use `feature-trace` to map spec IDs to implementation status: `met` / `partial` / `planned` / `gap`.
+
+### 6) Report
+
+List touched files, new edges / nodes, the read strategy used (4A or 4B), unresolved spec-vs-code gaps, and any follow-ups.
+
+## Sample hints
+
+- **Batch merge**: when one domain has multiple specs, decide first whether sub-modules merge; keep node IDs unique.
+- **Spec shrinks scope**: soften or remove nodes, but keep a `figcaption` footnote in the macro explaining the retired requirement.
+- **Design-only change**: still re-review macro edges — interaction order shifts even when no module is added.

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

@@ -0,0 +1,12 @@
+interface:
+  display_name: "spec-to-project-html"
+  short_description: "Sync HTML architecture pages with active planning specs"
+  default_prompt: >-
+    Use $spec-to-project-html to read docs/plans (spec.md → design.md → contract.md), diff against `resources/project-architecture/` produced by $init-project-html, and patch HTML per `init-project-html/SKILL.md` Rules 1–7 (the authoritative rulebook). Local vocabulary + class-hook + DOM cheat sheet lives in this skill's own `references/TEMPLATE_SPEC.md`. Preserve the two-layer rule throughout.
+    The macro `index.html` stays ONE SVG with feature-module clusters AND every sub-module node drawn together, including many-to-many edges, producer/consumer loops, and cross-feature `m-edge--cross` data-row edges; the macro `flow-edge-manifest--macro` mirrors every SVG edge.
+    Read strategy (mirrors $init-project-html Rule 3 to avoid context loss). 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.
+    (4A, preferred) with subagents, dispatch ONE read-only subagent per affected feature; each returns a structured CHANGE summary (added/renamed/retired sub-modules, function I/O deltas, variables-with-business-purpose deltas, error deltas, outbound edge changes, `planned` / `gap` markers). The main agent collects every summary first, then patches the macro and pages in one pass.
+    (4B, no subagents) handle affected features ONE AT A TIME — deep-read feature A, IMMEDIATELY patch `features/A/index.html` + affected sub-module pages, incrementally patch the macro for A's cluster / nodes / edges (mark edges pointing at unread affected features with `data-edge-target-pending="<future-slug>"`), drop A's function-level details from memory, then move on. After every affected feature is patched, resolve every pending placeholder in a final macro pass. NEVER load every affected feature's source into the main agent context at once.
+    Each `features/<slug>/<sub-module>.html` stays self-only: update `sub-io` function table + `sub-vars` variables-with-business-purpose table (sync every renamed / added / removed parameter, local state, struct field, DB column, config knob, counter, or time anchor that influences a business branch, using scope chips `sub-vars__scope--call|tx|persist|instance|loop`) + `sub-dataflow` internal value flow + `sub-errors`. FORBIDDEN on sub-module pages: cross-submodule narrative, `flow-return-row`, or cross-boundary `flow-edge-manifest`.
+    Feature `index.html` stays lightweight (story + submodule-nav). Migrate legacy `arch-diagram` or feature-level cross-submodule flowcharts onto the macro when you touch them; keep CSS paths (`assets/` for root, `../../assets/` under features); scaffold via $init-project-html if files are missing. Report which read strategy (4A or 4B) was actually used.

package/spec-to-project-html/references/TEMPLATE_SPEC.md

@@ -0,0 +1,98 @@
+# HTML architecture atlas — reference cheat sheet (spec-to-project-html copy)
+
+> Reference material only. The **binding rules** (page contracts, naming, assets, accessibility, forbidden shortcuts) live in `init-project-html/SKILL.md` (the atlas authority). `spec-to-project-html/SKILL.md` follows those same Rules 1–7 when patching pages to match active specs. This file is a local glossary + class-hook table + DOM snippets so this skill can stay self-contained when installed alone.
+
+## Vocabulary
+
+- **Feature module** — one **user-visible end-to-end capability** (e.g. "invite-code registration", "get-invite-codes"). One directory `features/<feature-slug>/`. It is **not** a single web layer or a single database.
+- **Sub-module** — an implementation boundary inside that capability (front-end page, public API, domain service, PostgreSQL, pure helpers, message queues…). One HTML page per sub-module, sibling to the feature's `index.html`.
+
+## Directory layout (target output)
+
+```text
+resources/project-architecture/
+  index.html                           # macro: feature × sub-module in one SVG with multi-edge + data-row flow
+  assets/
+    architecture.css
+  features/
+    <feature-slug>/                    # one feature module = one directory
+      index.html                       # lightweight overview (story + submodule nav)
+      <sub-module-slug>.html           # one HTML per sub-module (own I/O + internal flow)
+```
+
+## Macro SVG — CSS class hooks
+
+| Element | class |
+|---|---|
+| Actor block | `m-actor` |
+| Feature cluster frame | `m-cluster` / `m-cluster__rect` / `m-cluster__title` |
+| Sub-module node | `m-sub` (add `m-sub--db` for databases) |
+| Edge | `m-edge` + modifier `m-edge--call` / `m-edge--return` / `m-edge--cross` |
+| Edge label | `m-edge__label` (cross-feature labels add `m-edge__label--cross`) |
+
+## DOM snippets
+
+### `sub-io` function I/O table
+
+```html
+<section class="sub-io">
+  <h2>Function I/O</h2>
+  <table>
+    <thead><tr><th>Function</th><th>Signature</th><th>Side effects</th><th>Purpose</th></tr></thead>
+    <tbody>
+      <tr>
+        <td><code>FunctionName</code></td>
+        <td class="sub-io__signature">
+          <strong>in:</strong> <code>T1</code>, <code>T2</code><br>
+          <strong>out:</strong> <code>R</code> | <code>ErrX</code>
+        </td>
+        <td><span class="sub-io__side sub-io__side--pure">pure</span></td>
+        <td>One-line purpose.</td>
+      </tr>
+    </tbody>
+  </table>
+</section>
+```
+
+### `sub-vars` variables-with-business-purpose table
+
+```html
+<section class="sub-vars">
+  <h2>Variables &amp; business purpose</h2>
+  <p class="sub-vars__intro">Identifiers this sub-module holds or threads through. Types align readers; business purpose comes first.</p>
+  <table>
+    <thead>
+      <tr><th>Variable</th><th>Type</th><th>Scope</th><th>Business purpose</th></tr>
+    </thead>
+    <tbody>
+      <tr>
+        <td class="sub-vars__name">someVar</td>
+        <td class="sub-vars__type">SomeType</td>
+        <td><span class="sub-vars__scope sub-vars__scope--call">call</span></td>
+        <td>One line: this value decides branch X; without it Y breaks.</td>
+      </tr>
+    </tbody>
+  </table>
+</section>
+```
+
+Scope chip vocabulary: `sub-vars__scope--call` (single call), `--tx` (transaction-bound), `--persist` (persisted), `--instance` (fixed at construction; lifetime-shared), `--loop` (retry/loop).
+
+### `sub-dataflow` small SVG sizing
+
+- Node class: `d-node`; edge class: `d-edge` (side-effect edges use `d-edge--side`).
+- Recommended viewBox: height ≤ 240, width ≤ 720.
+- Nodes are this sub-module's internal variables/functions only.
+
+## Edge-kind vocabulary (for macro `flow-edge-manifest`)
+
+| `data-edge-kind` | meaning | typical visual |
+|---|---|---|
+| `call` | function call / HTTP request | solid arrow |
+| `return` | return value / response | thin dashed arrow |
+| `data-row` | cross-feature hand-off via data rows (not a function call) | warm-tone heavy dashed |
+| `failure` | failure branch | red solid arrow with `failure` chip in the manifest row |
+
+## Typography hint
+
+Pair a recognisable display face (e.g. `Fraunces`) with `Plus Jakarta Sans`. Avoid the "AI-default purple gradient" and Inter look-alike. Detailed rules live in `init-project-html/SKILL.md` § Rule 6.