@laitszkin/apollo-toolkit 3.11.3 → 3.11.5

package/AGENTS.md

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

package/CHANGELOG.md

@@ -10,6 +10,36 @@ All notable changes to this repository are documented in this file.
 
 ### Fixed
 
+## [v3.11.5] - 2026-05-12
+
+### Added
+
+- New skill `update-project-html`: refreshes the base project HTML architecture atlas (`resources/project-architecture/`) to reflect the latest code changes by reading the existing atlas, resolving the diff scope (`git diff --stat` + staged by default, or against a user-named ref), filtering to code-affecting hunks, and dispatching one write-capable subagent per affected feature to update declarations through `apltk architecture` (no `--spec`); the main agent waits until every subagent finishes before declaring cross-feature edges, then runs `apltk architecture render` and `apltk architecture validate`.
+- README: notes for `update-project-html`, the `commit-and-push` / `version-release` decoupling, the `review-change-set` decoupling + subagent guidance, and the `review-spec-related-changes` parallel secondary-subagent pattern. AGENTS.md: new business-flow bullet for `update-project-html`.
+- Tests (`test/skill-workflows.test.js`): assertions for the four behavior changes above (decoupling and subagent recommendations).
+
+### Changed
+
+- `commit-and-push` and `version-release` no longer chain `discover-edge-cases` or `discover-security-issues` automatically. The `review-change-set` gate stays mandatory for code-affecting scope, and other conditional gates (e.g. `archive-specs`) remain unchanged. Invoke security or edge-case skills explicitly when their scenario applies.
+- `review-change-set` no longer chains `discover-security-issues` and now recommends dispatching one read-only subagent per coherent scope cluster for multi-file diffs; the main agent aggregates structured architecture + simplification findings without re-reading delegated files. Tiny diffs are still reviewed inline.
+- `review-spec-related-changes` keeps its three secondary dependencies (`review-change-set`, `discover-edge-cases`, `discover-security-issues`) but now prefers running each one in its own read-only subagent in parallel, and may also fan out independent business-goal requirement clusters to read-only subagents.
+
+### Fixed
+
+## [v3.11.4] - 2026-05-12
+
+### Added
+
+- Macro atlas: `measureEdgeLabel` wraps long edge labels (including CJK) with honest width/height for elkjs so orthogonal routes reserve space proportional to label size; `renderMacroSvg` paints wrapped labels as stacked `<tspan>` lines on one anchor.
+- Macro atlas: isolated feature clusters (no intra-feature edges and not an endpoint of a root-level cross-feature edge) use elk **rectpacking** with aspect-ratio hint for a grid-like pack instead of a tall vertical column of sub-modules.
+- Tests: CJK submodule sizing, edge-label wrapping, rectpacking vs layered cluster selection, compact rectpack geometry, `m-edge--cross` markup, and cross-edge CSS dim/hover rules.
+
+### Changed
+
+- Macro layout (`layout.js`): CJK-aware text width and visual-width wrapping for sub-module **role** lines; raised `SUB_WIDTH_MAX` / `SUB_HEIGHT_MAX` and `MAX_ROLE_LINES`; sub-module boxes prefer fewer wrapped lines when content allows.
+- Root ELK graph: `elk.aspectRatio` 16:9, tighter node/layer spacing and padding, `BALANCED` node placement, `EDGE_LENGTH` post-compaction; cluster padding and internal spacing reduced.
+- Cross-feature edges: root-level edges render with `m-edge--cross`; default lower opacity/thinner stroke, full strength on hover/focus so intra-feature flow reads first.
+
 ## [v3.11.3] - 2026-05-11
 
 ### Added

package/README.md

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

package/commit-and-push/README.md

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

package/commit-and-push/SKILL.md

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

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

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

package/init-project-html/lib/atlas/assets/architecture.css

@@ -433,8 +433,23 @@ p { line-height: 1.6; color: var(--vellum-soft); }
   font-family: var(--font-mono);
   font-size: 11px;
   letter-spacing: 0.02em;
+  paint-order: stroke fill;
+  stroke: var(--ink);
+  stroke-width: 3.5;
+  stroke-linejoin: round;
+  pointer-events: none;
 }
 
+/* Cross-feature edges are routed across the entire atlas and tend to
+   be the loudest lines on screen. Dim them so intra-feature flow
+   reads first; restore full strength on hover/focus. */
+.m-edge--cross path { opacity: 0.5; stroke-width: 1.1; }
+.m-edge--cross .m-edge__label { opacity: 0.7; }
+.m-edge--cross:hover path,
+.m-edge--cross:focus-within path { opacity: 1; stroke-width: 1.8; }
+.m-edge--cross:hover .m-edge__label,
+.m-edge--cross:focus-within .m-edge__label { opacity: 1; }
+
 /* =================================================================
    feature page
    ================================================================= */

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

@@ -17,11 +17,15 @@ const ELK = require('elkjs');
 const SUB_WIDTH = 240;
 const SUB_HEIGHT = 92;
 
-// Box-sizing knobs (intrinsic SVG coordinates).
+// Box-sizing knobs (intrinsic SVG coordinates). The width/height caps
+// are intentionally generous so CJK roles — which paint at ~1em per
+// character instead of ~0.55em — can grow into a readable rectangle
+// without spilling outside the box (the original ~360×220 cap was
+// only honest for Latin text).
 const SUB_WIDTH_MIN = 220;
-const SUB_WIDTH_MAX = 360;
+const SUB_WIDTH_MAX = 520;
 const SUB_HEIGHT_MIN = 92;
-const SUB_HEIGHT_MAX = 220;
+const SUB_HEIGHT_MAX = 360;
 const SUB_SIDE_PAD = 16;
 const SUB_TOP_PAD = 14;
 const SUB_BOTTOM_PAD = 14;
@@ -30,12 +34,22 @@ const KIND_LINE = 16;      // kind chip line
 const ROLE_LINE = 16;      // each role line
 const KIND_GAP = 4;
 const ROLE_GAP = 8;
-const MAX_ROLE_LINES = 4;
+const MAX_ROLE_LINES = 6;
 
-const CLUSTER_PAD_TOP = 60;
-const CLUSTER_PAD_SIDE = 24;
-const CLUSTER_PAD_BOTTOM = 28;
-const EDGE_LABEL_HEIGHT = 18;
+const CLUSTER_PAD_TOP = 44;
+const CLUSTER_PAD_SIDE = 16;
+const CLUSTER_PAD_BOTTOM = 18;
+
+// Font sizes mirror architecture.css so the layout math agrees with
+// what the SVG actually paints.
+const SLUG_FONT_PX = 15;
+const KIND_FONT_PX = 10;
+const ROLE_FONT_PX = 11.5;
+const EDGE_LABEL_FONT_PX = 11;
+const EDGE_LABEL_LINE_PX = 14;
+const EDGE_LABEL_LINE_WIDTH_MAX = 220;
+const EDGE_LABEL_PAD_X = 18;
+const EDGE_LABEL_PAD_Y = 8;
 
 const KIND_LABELS = {
   ui: 'UI',
@@ -47,30 +61,128 @@ const KIND_LABELS = {
   external: 'external',
 };
 
-function estimateLabelWidth(text) {
-  if (!text) return 0;
-  return Math.min(220, Math.max(40, String(text).length * 7 + 16));
+// East-Asian Wide / Full-width detection. The ranges follow the
+// canonical "wide" / "fullwidth" code blocks (Unicode TR11) — we use
+// them to switch between a ~0.55em-per-char Latin metric and a
+// ~1.0em-per-char CJK metric so layout matches paint.
+function isWideChar(ch) {
+  const code = ch.codePointAt(0);
+  return (
+    (code >= 0x1100 && code <= 0x115F) ||
+    (code >= 0x2E80 && code <= 0x9FFF) ||
+    (code >= 0xA000 && code <= 0xA4CF) ||
+    (code >= 0xAC00 && code <= 0xD7A3) ||
+    (code >= 0xF900 && code <= 0xFAFF) ||
+    (code >= 0xFE30 && code <= 0xFE4F) ||
+    (code >= 0xFF00 && code <= 0xFF60) ||
+    (code >= 0xFFE0 && code <= 0xFFE6) ||
+    (code >= 0x20000 && code <= 0x2FFFD)
+  );
+}
+
+function charWidthFactor(ch) {
+  if (isWideChar(ch)) return 1.0;
+  if (ch === ' ') return 0.30;
+  if (/[A-Za-z0-9]/.test(ch)) return 0.55;
+  return 0.50;
 }
 
-// Approximate render width of a string in the target font. The 0.6
-// factor is a deliberate over-estimate for our sans-serif stack so
-// the chosen width almost always leaves a little breathing room.
 function approxTextWidth(text, fontPx) {
-  return String(text || '').length * fontPx * 0.6;
+  if (!text) return 0;
+  let w = 0;
+  for (const ch of String(text)) w += fontPx * charWidthFactor(ch);
+  return w;
 }
 
-function wrapToLines(text, maxChars) {
+// Greedy wrap by *visual* width. CJK characters break between any
+// two characters; ASCII words stay whole; whitespace is a soft break.
+function wrapByVisualWidth(text, maxWidthPx, fontPx) {
   if (!text) return [];
-  const words = String(text).split(/\s+/).filter(Boolean);
+  const str = String(text);
   const lines = [];
-  let current = '';
-  for (const word of words) {
-    if (!current) { current = word; continue; }
-    if ((current.length + 1 + word.length) <= maxChars) current = `${current} ${word}`;
-    else { lines.push(current); current = word; }
+  let line = '';
+  let lineW = 0;
+
+  function flush() {
+    if (line.length > 0) lines.push(line.replace(/\s+$/, ''));
+    line = '';
+    lineW = 0;
   }
-  if (current) lines.push(current);
-  return lines;
+
+  let i = 0;
+  while (i < str.length) {
+    const cp = str.codePointAt(i);
+    const ch = String.fromCodePoint(cp);
+    const advance = ch.length;
+
+    if (ch === '\n') {
+      flush();
+      i += advance;
+    } else if (isWideChar(ch)) {
+      const w = fontPx * 1.0;
+      if (line && lineW + w > maxWidthPx) flush();
+      line += ch;
+      lineW += w;
+      i += advance;
+    } else if (/\s/.test(ch)) {
+      const w = fontPx * 0.30;
+      if (line) {
+        if (lineW + w > maxWidthPx) flush();
+        else { line += ch; lineW += w; }
+      }
+      i += advance;
+    } else {
+      let word = '';
+      let wordW = 0;
+      while (i < str.length) {
+        const cp2 = str.codePointAt(i);
+        const ch2 = String.fromCodePoint(cp2);
+        if (isWideChar(ch2) || /\s/.test(ch2)) break;
+        word += ch2;
+        wordW += fontPx * charWidthFactor(ch2);
+        i += ch2.length;
+      }
+      if (line && lineW + wordW > maxWidthPx) flush();
+      line += word;
+      lineW += wordW;
+    }
+  }
+  flush();
+  return lines.filter((l) => l.length > 0);
+}
+
+// Short labels (feature title, sub-module slug) — single-line width
+// only. Capped so very long ASCII slugs do not blow up the cluster
+// header band; CJK titles still get an honest visual width.
+function estimateLabelWidth(text) {
+  if (!text) return 0;
+  return Math.min(320, Math.max(40, Math.ceil(approxTextWidth(text, 13)) + 16));
+}
+
+// Edge labels — wrap into a tall enough rectangle so elkjs reserves
+// proportional edge length (longer text ⇒ longer arrow). The wrapped
+// text is stored with '\n' separators so render.js can paint each
+// line as its own <tspan> centered on the same anchor.
+function measureEdgeLabel(text) {
+  if (!text) return { text: '', lines: [], width: 0, height: 0 };
+  const raw = String(text);
+  const singleW = approxTextWidth(raw, EDGE_LABEL_FONT_PX);
+  if (singleW <= EDGE_LABEL_LINE_WIDTH_MAX) {
+    return {
+      text: raw,
+      lines: [raw],
+      width: Math.max(40, Math.ceil(singleW) + EDGE_LABEL_PAD_X),
+      height: EDGE_LABEL_LINE_PX + EDGE_LABEL_PAD_Y,
+    };
+  }
+  const lines = wrapByVisualWidth(raw, EDGE_LABEL_LINE_WIDTH_MAX, EDGE_LABEL_FONT_PX);
+  const widestLine = lines.reduce((m, l) => Math.max(m, approxTextWidth(l, EDGE_LABEL_FONT_PX)), 0);
+  return {
+    text: lines.join('\n'),
+    lines,
+    width: Math.ceil(widestLine) + EDGE_LABEL_PAD_X,
+    height: lines.length * EDGE_LABEL_LINE_PX + EDGE_LABEL_PAD_Y,
+  };
 }
 
 // measureSubmodule picks a width + height that fit the slug, the kind
@@ -83,26 +195,33 @@ function measureSubmodule(sub) {
   const kindLabel = KIND_LABELS[sub && sub.kind] || (sub && sub.kind) || 'service';
   const role = (sub && sub.role) || '';
 
-  const slugW = approxTextWidth(slug, 14);
-  const kindW = approxTextWidth(kindLabel, 11);
+  const slugW = approxTextWidth(slug, SLUG_FONT_PX);
+  // Kind chip is upper-cased + letter-spaced in CSS (0.22em); add ~30% slack.
+  const kindW = approxTextWidth(kindLabel.toUpperCase(), KIND_FONT_PX) * 1.3;
   const baseInner = Math.max(slugW, kindW);
 
-  // Aim to keep the role within ~3 lines: choose a width whose text
-  // area can hold ceil(roleLen / 3) characters, then clamp.
-  const roleLen = role.length;
+  // Auto-expand the box to fit the role with as few lines as
+  // possible: prefer 1 line if it fits inside SUB_WIDTH_MAX, else 2,
+  // else 3 — and only wrap further when even 3 lines would exceed
+  // the cap. This is what "boxes auto-expand to their content" means
+  // for CJK roles whose glyphs are ~2× wider than Latin.
+  const roleVisualW = approxTextWidth(role, ROLE_FONT_PX);
+  const maxInner = SUB_WIDTH_MAX - SUB_SIDE_PAD * 2;
   let chosenInner;
   if (!role) {
     chosenInner = baseInner;
   } else {
-    const targetCharsPerLine = Math.max(20, Math.ceil(roleLen / 3));
-    chosenInner = Math.max(baseInner, targetCharsPerLine * 11 * 0.55);
+    let target;
+    if (roleVisualW <= maxInner) target = roleVisualW;
+    else if (Math.ceil(roleVisualW / 2) <= maxInner) target = Math.ceil(roleVisualW / 2);
+    else target = Math.ceil(roleVisualW / 3);
+    chosenInner = Math.max(baseInner, Math.max(180, target));
   }
   const width = Math.max(SUB_WIDTH_MIN, Math.min(SUB_WIDTH_MAX, Math.ceil(chosenInner + SUB_SIDE_PAD * 2)));
 
   // With the chosen width fixed, wrap the role for real and count lines.
   const innerW = width - SUB_SIDE_PAD * 2;
-  const charsPerLine = Math.max(12, Math.floor(innerW / (11 * 0.55)));
-  let roleLines = role ? wrapToLines(role, charsPerLine) : [];
+  let roleLines = role ? wrapByVisualWidth(role, innerW, ROLE_FONT_PX) : [];
   if (roleLines.length > MAX_ROLE_LINES) {
     roleLines = roleLines.slice(0, MAX_ROLE_LINES);
     const last = roleLines[MAX_ROLE_LINES - 1];
@@ -129,7 +248,53 @@ function endpointId(endpoint, ownerFeature) {
   return null;
 }
 
+function clusterLayoutOptions(feature, isCrossEdgeEndpoint) {
+  // If the feature declares intra-feature flow edges OR is an
+  // endpoint of any root-level cross-feature edge, the cluster must
+  // use a hierarchy-friendly directional algorithm (layered) so elk
+  // can route edges into/out of its children. Mixing rectpacking
+  // with layered hierarchy edges raises UnsupportedGraphException.
+  //
+  // Otherwise (truly isolated leaf cluster) pack sub-modules into a
+  // roughly square grid so a 10-sub-module feature does not become a
+  // tall column that wastes the rest of the viewport.
+  const hasInternalEdges = Array.isArray(feature.edges) && feature.edges.length > 0;
+  const common = {
+    'elk.padding': `[top=${CLUSTER_PAD_TOP},left=${CLUSTER_PAD_SIDE},bottom=${CLUSTER_PAD_BOTTOM},right=${CLUSTER_PAD_SIDE}]`,
+    'elk.spacing.nodeNode': '16',
+    'elk.nodeLabels.placement': '[H_CENTER, V_TOP, INSIDE]',
+  };
+  if (hasInternalEdges || isCrossEdgeEndpoint) {
+    return {
+      ...common,
+      'elk.algorithm': 'layered',
+      'elk.direction': 'DOWN',
+      'elk.layered.spacing.nodeNodeBetweenLayers': '28',
+      'elk.layered.nodePlacement.bk.fixedAlignment': 'BALANCED',
+    };
+  }
+  return {
+    ...common,
+    'elk.algorithm': 'rectpacking',
+    'elk.aspectRatio': '1.4',
+    'elk.rectpacking.optimizationGoal': 'MAX_SCALE_DRIVEN',
+  };
+}
+
+function collectCrossEdgeFeatures(state) {
+  const set = new Set();
+  function note(endpoint) {
+    if (endpoint && typeof endpoint === 'object' && endpoint.feature) set.add(endpoint.feature);
+  }
+  for (const edge of state.edges || []) {
+    note(edge.from);
+    note(edge.to);
+  }
+  return set;
+}
+
 function buildGraph(state) {
+  const crossEndpoints = collectCrossEdgeFeatures(state);
   const children = (state.features || []).map((feature) => ({
     id: `feature::${feature.slug}`,
     labels: [{
@@ -138,14 +303,7 @@ function buildGraph(state) {
       width: estimateLabelWidth(feature.title || feature.slug),
       height: 24,
     }],
-    layoutOptions: {
-      'elk.padding': `[top=${CLUSTER_PAD_TOP},left=${CLUSTER_PAD_SIDE},bottom=${CLUSTER_PAD_BOTTOM},right=${CLUSTER_PAD_SIDE}]`,
-      'elk.spacing.nodeNode': '24',
-      'elk.algorithm': 'layered',
-      'elk.direction': 'DOWN',
-      'elk.layered.spacing.nodeNodeBetweenLayers': '36',
-      'elk.nodeLabels.placement': '[H_CENTER, V_TOP, INSIDE]',
-    },
+    layoutOptions: clusterLayoutOptions(feature, crossEndpoints.has(feature.slug)),
     children: (feature.submodules || []).map((sub) => {
       const box = measureSubmodule(sub);
       return {
@@ -168,17 +326,18 @@ function buildGraph(state) {
 
   function pushEdge(list, raw, sourceId, targetId) {
     if (!sourceId || !targetId) return;
-    list.push({
-      id: raw.id || `e-${nextEdgeId++}`,
-      sources: [sourceId],
-      targets: [targetId],
-      labels: raw.label ? [{
-        id: `${raw.id || `e-${nextEdgeId}`}::label`,
-        text: raw.label,
-        width: estimateLabelWidth(raw.label),
-        height: EDGE_LABEL_HEIGHT,
-      }] : [],
-    });
+    const id = raw.id || `e-${nextEdgeId++}`;
+    let labels = [];
+    if (raw.label) {
+      const m = measureEdgeLabel(raw.label);
+      labels = [{
+        id: `${id}::label`,
+        text: m.text,
+        width: m.width,
+        height: m.height,
+      }];
+    }
+    list.push({ id, sources: [sourceId], targets: [targetId], labels });
   }
 
   for (const feature of state.features || []) {
@@ -203,12 +362,20 @@ function buildGraph(state) {
       'elk.algorithm': 'layered',
       'elk.direction': 'RIGHT',
       'elk.hierarchyHandling': 'INCLUDE_CHILDREN',
-      'elk.spacing.nodeNode': '60',
-      'elk.layered.spacing.nodeNodeBetweenLayers': '100',
-      'elk.padding': '[top=40,left=40,bottom=40,right=40]',
+      // 16:9 hint so elk stops sprawling along one axis and leaving
+      // the other half of the viewport empty.
+      'elk.aspectRatio': '1.778',
+      'elk.spacing.nodeNode': '32',
+      'elk.layered.spacing.nodeNodeBetweenLayers': '60',
+      'elk.padding': '[top=20,left=20,bottom=20,right=20]',
       'elk.edgeRouting': 'ORTHOGONAL',
       'elk.edgeLabels.inline': 'false',
       'elk.edgeLabels.placement': 'CENTER',
+      // Tighter post-layout placement: BALANCED keeps related nodes
+      // adjacent, EDGE_LENGTH compaction pulls disconnected
+      // sub-graphs in toward each other so unused columns collapse.
+      'elk.layered.nodePlacement.bk.fixedAlignment': 'BALANCED',
+      'elk.layered.compaction.postCompaction.strategy': 'EDGE_LENGTH',
     },
     children,
     edges: rootEdges,
@@ -327,4 +494,7 @@ module.exports = {
   assertNoOverlap,
   buildGraph,
   measureSubmodule,
+  measureEdgeLabel,
+  approxTextWidth,
+  wrapByVisualWidth,
 };

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

@@ -81,13 +81,13 @@ function edgeKindFor(stateEdge) {
 function findEdgeMeta(state, edgeId) {
   for (const feature of state.features || []) {
     for (const e of feature.edges || []) {
-      if (e.id === edgeId) return e;
+      if (e.id === edgeId) return { edge: e, scope: 'feature' };
     }
   }
   for (const e of state.edges || []) {
-    if (e.id === edgeId) return e;
+    if (e.id === edgeId) return { edge: e, scope: 'root' };
   }
-  return null;
+  return { edge: null, scope: 'feature' };
 }
 
 function renderMacroSvg(layout, state) {
@@ -144,17 +144,29 @@ function renderMacroSvg(layout, state) {
   }
 
   for (const edge of layout.edges) {
-    const meta = findEdgeMeta(state, edge.id);
+    const { edge: meta, scope } = findEdgeMeta(state, edge.id);
     const kind = edgeKindFor(meta);
     const d = renderEdgePath(edge);
     if (!d) continue;
-    parts.push(`    <g class="m-edge m-edge--${kind}" data-edge="${htmlEscape(edge.id)}">`);
+    const scopeClass = scope === 'root' ? ' m-edge--cross' : '';
+    parts.push(`    <g class="m-edge m-edge--${kind}${scopeClass}" data-edge="${htmlEscape(edge.id)}">`);
     parts.push(`      <path d="${d}" fill="none" marker-end="url(#arrow-${kind})" />`);
     for (const label of edge.labels || []) {
       if (!label.text) continue;
-      const lx = label.x + (label.width || 0) / 2;
-      const ly = label.y + (label.height || 0) / 2 + 4;
-      parts.push(`      <text class="m-edge__label" x="${lx.toFixed(2)}" y="${ly.toFixed(2)}" text-anchor="middle">${htmlEscape(label.text)}</text>`);
+      const lines = String(label.text).split('\n');
+      const cx = label.x + (label.width || 0) / 2;
+      const lineH = 14; // matches EDGE_LABEL_LINE_PX in layout.js
+      const blockH = lines.length * lineH;
+      const firstBaseline = label.y + ((label.height || 0) - blockH) / 2 + (lineH - 3);
+      parts.push(`      <text class="m-edge__label" x="${cx.toFixed(2)}" y="${firstBaseline.toFixed(2)}" text-anchor="middle">`);
+      lines.forEach((line, idx) => {
+        if (idx === 0) {
+          parts.push(`        <tspan x="${cx.toFixed(2)}">${htmlEscape(line)}</tspan>`);
+        } else {
+          parts.push(`        <tspan x="${cx.toFixed(2)}" dy="${lineH}">${htmlEscape(line)}</tspan>`);
+        }
+      });
+      parts.push('      </text>');
     }
     parts.push('    </g>');
   }

package/package.json

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

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/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."