@laitszkin/apollo-toolkit 3.9.7 → 3.10.0

package/init-project-html/scripts/architecture.js

@@ -0,0 +1,496 @@
+#!/usr/bin/env node
+// architecture.js — open the project HTML architecture atlas, or render
+// a paginated before/after diff viewer from every active spec's
+// architecture_diff/ directory under docs/plans/.
+//
+// Usage:
+//   architecture.js                                 # same as `open`
+//   architecture.js open  [--project <root>] [--no-open]
+//   architecture.js diff  [--project <root>] [--out <dir>] [--no-open]
+//   architecture.js --help
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawn } = require('node:child_process');
+
+const ATLAS_REL = path.join('resources', 'project-architecture', 'index.html');
+const RESOURCES_REL = path.join('resources', 'project-architecture');
+const PLANS_REL = path.join('docs', 'plans');
+const DIFF_DIRNAME = 'architecture_diff';
+const REMOVED_FILE = '_removed.txt';
+const DEFAULT_OUT_REL = path.join('.apollo-toolkit', 'architecture-diff');
+
+const USAGE = `apltk architecture — open the project architecture atlas or its diff viewer.
+
+Usage:
+  apltk architecture                      Open resources/project-architecture/index.html
+  apltk architecture open                 Same as above
+  apltk architecture diff                 Render every architecture_diff/ as one paginated viewer
+  apltk architecture --help               Show this help
+
+Options:
+  --project <root>   Override project root (default: nearest ancestor with resources/project-architecture/index.html)
+  --out <dir>        Override viewer output dir (default: <project>/${DEFAULT_OUT_REL})
+  --no-open          Skip launching the browser (CI/test friendly)
+  -h, --help         Show this help`;
+
+function parseArgs(argv) {
+  const args = [...argv];
+  const result = {
+    subcommand: 'open',
+    projectRoot: null,
+    out: null,
+    open: true,
+    help: false,
+  };
+
+  if (args.length > 0 && !args[0].startsWith('-')) {
+    const candidate = args[0];
+    if (candidate === 'open' || candidate === 'diff') {
+      result.subcommand = candidate;
+      args.shift();
+    }
+  }
+
+  while (args.length > 0) {
+    const arg = args.shift();
+    if (arg === '--help' || arg === '-h') {
+      result.help = true;
+    } else if (arg === '--project') {
+      const value = args.shift();
+      if (!value) throw new Error('Missing value for --project');
+      result.projectRoot = path.resolve(value);
+    } else if (arg === '--out') {
+      const value = args.shift();
+      if (!value) throw new Error('Missing value for --out');
+      result.out = path.resolve(value);
+    } else if (arg === '--no-open') {
+      result.open = false;
+    } else {
+      throw new Error(`Unexpected argument: ${arg}`);
+    }
+  }
+
+  return result;
+}
+
+function findProjectRoot(startDir) {
+  let dir = path.resolve(startDir);
+  while (true) {
+    if (fs.existsSync(path.join(dir, ATLAS_REL))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+function openInBrowser(filePath) {
+  const platform = process.platform;
+  let command;
+  let args;
+  if (platform === 'darwin') {
+    command = 'open';
+    args = [filePath];
+  } else if (platform === 'win32') {
+    command = 'cmd';
+    args = ['/c', 'start', '""', filePath];
+  } else {
+    command = 'xdg-open';
+    args = [filePath];
+  }
+  try {
+    const child = spawn(command, args, { stdio: 'ignore', detached: true });
+    child.on('error', () => { /* best effort */ });
+    child.unref();
+  } catch (_err) {
+    /* best effort */
+  }
+}
+
+function walkArchitectureDiffDirs(plansRoot) {
+  const result = [];
+  if (!fs.existsSync(plansRoot)) return result;
+
+  function recurse(dir) {
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch (_err) {
+      return;
+    }
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      if (entry.name === 'node_modules' || entry.name.startsWith('.')) continue;
+      const full = path.join(dir, entry.name);
+      if (entry.name === DIFF_DIRNAME) {
+        result.push(full);
+        continue;
+      }
+      recurse(full);
+    }
+  }
+  recurse(plansRoot);
+  return result;
+}
+
+function walkAfterStateHtml(diffDir) {
+  const out = [];
+  function recurse(dir, relParts) {
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch (_err) {
+      return;
+    }
+    for (const entry of entries) {
+      if (entry.name === 'assets') continue;
+      if (entry.name === REMOVED_FILE) continue;
+      if (entry.name.startsWith('.')) continue;
+      const full = path.join(dir, entry.name);
+      const nextRel = [...relParts, entry.name];
+      if (entry.isDirectory()) {
+        recurse(full, nextRel);
+      } else if (entry.isFile() && entry.name.toLowerCase().endsWith('.html')) {
+        out.push({ abs: full, rel: nextRel.join('/') });
+      }
+    }
+  }
+  recurse(diffDir, []);
+  return out;
+}
+
+function readRemovedManifest(diffDir) {
+  const manifestPath = path.join(diffDir, REMOVED_FILE);
+  if (!fs.existsSync(manifestPath)) return [];
+  return fs.readFileSync(manifestPath, 'utf8')
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter((line) => line && !line.startsWith('#'));
+}
+
+function collectChanges(projectRoot) {
+  const resourcesRoot = path.join(projectRoot, RESOURCES_REL);
+  const plansRoot = path.join(projectRoot, PLANS_REL);
+  const diffDirs = walkArchitectureDiffDirs(plansRoot);
+  const changes = [];
+
+  for (const diffDir of diffDirs) {
+    const specDir = path.dirname(diffDir);
+    const specLabel = path.relative(projectRoot, specDir);
+
+    for (const after of walkAfterStateHtml(diffDir)) {
+      const beforeAbs = path.join(resourcesRoot, after.rel);
+      const beforeExists = fs.existsSync(beforeAbs);
+      changes.push({
+        kind: beforeExists ? 'modified' : 'added',
+        rel: after.rel,
+        spec: specLabel,
+        beforePath: beforeExists ? path.relative(projectRoot, beforeAbs) : null,
+        afterPath: path.relative(projectRoot, after.abs),
+      });
+    }
+
+    for (const removedRel of readRemovedManifest(diffDir)) {
+      const beforeAbs = path.join(resourcesRoot, removedRel);
+      if (!fs.existsSync(beforeAbs)) continue;
+      changes.push({
+        kind: 'removed',
+        rel: removedRel,
+        spec: specLabel,
+        beforePath: path.relative(projectRoot, beforeAbs),
+        afterPath: null,
+      });
+    }
+  }
+
+  changes.sort((a, b) => {
+    if (a.spec !== b.spec) return a.spec.localeCompare(b.spec);
+    if (a.kind !== b.kind) return a.kind.localeCompare(b.kind);
+    return a.rel.localeCompare(b.rel);
+  });
+
+  return changes;
+}
+
+function htmlEscape(value) {
+  return String(value)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+function toViewerRel(outDir, projectRoot, projectRelPath) {
+  if (!projectRelPath) return null;
+  const absolute = path.resolve(projectRoot, projectRelPath);
+  const rel = path.relative(outDir, absolute);
+  return rel.split(path.sep).join('/');
+}
+
+function renderViewer({ changes, projectRoot, outDir }) {
+  const pages = changes.map((change) => ({
+    kind: change.kind,
+    rel: change.rel,
+    spec: change.spec,
+    beforeSrc: toViewerRel(outDir, projectRoot, change.beforePath),
+    afterSrc: toViewerRel(outDir, projectRoot, change.afterPath),
+  }));
+
+  const summary = {
+    total: pages.length,
+    modified: pages.filter((p) => p.kind === 'modified').length,
+    added: pages.filter((p) => p.kind === 'added').length,
+    removed: pages.filter((p) => p.kind === 'removed').length,
+    projectRoot,
+  };
+
+  const payload = JSON.stringify({ pages, summary });
+
+  return `<!DOCTYPE html>
+<html lang="en" data-atlas="diff-viewer">
+<head>
+  <meta charset="utf-8">
+  <title>Architecture diff — ${htmlEscape(path.basename(projectRoot))}</title>
+  <style>
+    :root {
+      color-scheme: light dark;
+      --bg: #0f172a;
+      --panel: #1e293b;
+      --text: #e2e8f0;
+      --muted: #94a3b8;
+      --accent: #38bdf8;
+      --added: #4ade80;
+      --removed: #f87171;
+      --modified: #facc15;
+    }
+    * { box-sizing: border-box; }
+    html, body { height: 100%; margin: 0; font-family: ui-sans-serif, system-ui, sans-serif; background: var(--bg); color: var(--text); }
+    body { display: flex; flex-direction: column; min-height: 100vh; }
+    header { padding: 12px 20px; background: var(--panel); border-bottom: 1px solid #334155; display: flex; flex-wrap: wrap; gap: 12px; align-items: center; justify-content: space-between; }
+    header .title { font-size: 14px; color: var(--muted); }
+    header .title strong { color: var(--text); }
+    header .summary { display: flex; gap: 12px; font-size: 12px; color: var(--muted); }
+    header .summary span.count { font-weight: 600; }
+    header .summary .modified { color: var(--modified); }
+    header .summary .added { color: var(--added); }
+    header .summary .removed { color: var(--removed); }
+    main { flex: 1; display: flex; flex-direction: column; }
+    .meta { padding: 10px 20px; background: var(--bg); border-bottom: 1px solid #334155; display: flex; flex-wrap: wrap; gap: 16px; align-items: center; justify-content: space-between; font-size: 13px; }
+    .meta .left { display: flex; align-items: center; gap: 12px; flex-wrap: wrap; }
+    .badge { display: inline-block; padding: 2px 8px; border-radius: 999px; font-size: 11px; font-weight: 700; text-transform: uppercase; letter-spacing: 0.06em; border: 1px solid currentColor; }
+    .badge.modified { color: var(--modified); }
+    .badge.added { color: var(--added); }
+    .badge.removed { color: var(--removed); }
+    .path { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; color: var(--text); }
+    .spec { color: var(--muted); font-size: 12px; }
+    .nav { display: flex; align-items: center; gap: 8px; }
+    .nav button { background: transparent; color: var(--text); border: 1px solid #475569; padding: 6px 12px; border-radius: 6px; cursor: pointer; font-size: 13px; }
+    .nav button:hover:not(:disabled) { border-color: var(--accent); color: var(--accent); }
+    .nav button:disabled { opacity: 0.4; cursor: not-allowed; }
+    .nav .counter { font-variant-numeric: tabular-nums; color: var(--muted); min-width: 72px; text-align: center; }
+    .frames { flex: 1; display: grid; gap: 1px; background: #334155; padding: 1px; min-height: 0; }
+    .frames.split { grid-template-columns: 1fr 1fr; }
+    .frames.single { grid-template-columns: 1fr; }
+    .pane { background: #ffffff; display: flex; flex-direction: column; min-height: 0; }
+    .pane h2 { margin: 0; padding: 8px 14px; font-size: 12px; text-transform: uppercase; letter-spacing: 0.08em; background: #f1f5f9; color: #1e293b; border-bottom: 1px solid #cbd5f5; display: flex; align-items: center; gap: 8px; }
+    .pane h2 .side-badge { font-size: 10px; padding: 1px 6px; border-radius: 4px; background: #cbd5f5; color: #1e293b; }
+    .pane h2.before .side-badge { background: #fee2e2; color: #991b1b; }
+    .pane h2.after .side-badge { background: #dcfce7; color: #166534; }
+    .pane iframe { flex: 1; width: 100%; border: 0; background: #ffffff; }
+    .empty { display: flex; align-items: center; justify-content: center; padding: 32px; font-size: 14px; color: var(--muted); }
+    footer { padding: 8px 20px; background: var(--panel); border-top: 1px solid #334155; font-size: 12px; color: var(--muted); }
+    footer kbd { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; background: #0f172a; padding: 1px 6px; border-radius: 4px; border: 1px solid #475569; }
+  </style>
+</head>
+<body>
+  <header>
+    <div class="title">Apollo Toolkit · <strong>architecture diff</strong> · ${htmlEscape(path.basename(projectRoot))}</div>
+    <div class="summary">
+      <span><span class="count">${summary.total}</span> change<span>${summary.total === 1 ? '' : 's'}</span></span>
+      <span class="modified"><span class="count">${summary.modified}</span> modified</span>
+      <span class="added"><span class="count">${summary.added}</span> added</span>
+      <span class="removed"><span class="count">${summary.removed}</span> removed</span>
+    </div>
+  </header>
+  <main>
+    <div class="meta">
+      <div class="left">
+        <span id="badge" class="badge modified">modified</span>
+        <span class="path" id="path">—</span>
+        <span class="spec" id="spec">—</span>
+      </div>
+      <div class="nav">
+        <button id="prev" type="button" aria-label="Previous change">← Prev</button>
+        <span class="counter" id="counter">0 / 0</span>
+        <button id="next" type="button" aria-label="Next change">Next →</button>
+      </div>
+    </div>
+    <div class="frames" id="frames">
+      <div class="empty" id="empty">No architecture diffs found under docs/plans/**/architecture_diff/.</div>
+    </div>
+  </main>
+  <footer>
+    Navigate with <kbd>←</kbd> / <kbd>→</kbd> or the buttons above. Each page pairs the current atlas (left) with the proposed-after HTML (right) for one affected page.
+  </footer>
+  <script id="__diff_payload" type="application/json">${payload.replace(/</g, '\\u003c')}</script>
+  <script>
+    (function () {
+      const data = JSON.parse(document.getElementById('__diff_payload').textContent);
+      const pages = data.pages || [];
+      const framesEl = document.getElementById('frames');
+      const emptyEl = document.getElementById('empty');
+      const badgeEl = document.getElementById('badge');
+      const pathEl = document.getElementById('path');
+      const specEl = document.getElementById('spec');
+      const counterEl = document.getElementById('counter');
+      const prevBtn = document.getElementById('prev');
+      const nextBtn = document.getElementById('next');
+
+      if (pages.length === 0) {
+        counterEl.textContent = '0 / 0';
+        prevBtn.disabled = true;
+        nextBtn.disabled = true;
+        return;
+      }
+
+      let index = 0;
+
+      function render() {
+        const page = pages[index];
+        badgeEl.className = 'badge ' + page.kind;
+        badgeEl.textContent = page.kind;
+        pathEl.textContent = page.rel;
+        specEl.textContent = page.spec;
+        counterEl.textContent = (index + 1) + ' / ' + pages.length;
+        prevBtn.disabled = index === 0;
+        nextBtn.disabled = index === pages.length - 1;
+
+        framesEl.innerHTML = '';
+        if (page.kind === 'modified') {
+          framesEl.className = 'frames split';
+          framesEl.appendChild(buildPane('Before', page.beforeSrc, 'before'));
+          framesEl.appendChild(buildPane('After', page.afterSrc, 'after'));
+        } else if (page.kind === 'added') {
+          framesEl.className = 'frames single';
+          framesEl.appendChild(buildPane('After (new)', page.afterSrc, 'after'));
+        } else if (page.kind === 'removed') {
+          framesEl.className = 'frames single';
+          framesEl.appendChild(buildPane('Before (removed)', page.beforeSrc, 'before'));
+        }
+      }
+
+      function buildPane(label, src, side) {
+        const pane = document.createElement('div');
+        pane.className = 'pane';
+        const heading = document.createElement('h2');
+        heading.className = side;
+        const sideBadge = document.createElement('span');
+        sideBadge.className = 'side-badge';
+        sideBadge.textContent = side;
+        heading.appendChild(sideBadge);
+        heading.appendChild(document.createTextNode(' ' + label));
+        pane.appendChild(heading);
+        const frame = document.createElement('iframe');
+        frame.src = src;
+        frame.loading = 'lazy';
+        frame.title = label;
+        pane.appendChild(frame);
+        return pane;
+      }
+
+      prevBtn.addEventListener('click', () => { if (index > 0) { index--; render(); } });
+      nextBtn.addEventListener('click', () => { if (index < pages.length - 1) { index++; render(); } });
+      document.addEventListener('keydown', (event) => {
+        if (event.key === 'ArrowLeft') { prevBtn.click(); }
+        else if (event.key === 'ArrowRight') { nextBtn.click(); }
+      });
+
+      emptyEl.remove();
+      render();
+    })();
+  </script>
+</body>
+</html>
+`;
+}
+
+function runOpen(opts, io) {
+  const projectRoot = opts.projectRoot || findProjectRoot(process.cwd());
+  if (!projectRoot) {
+    io.stderr.write(
+      `Could not find resources/project-architecture/index.html. Pass --project <root> or generate the atlas via the init-project-html skill.\n`,
+    );
+    return 1;
+  }
+  const atlas = path.join(projectRoot, ATLAS_REL);
+  if (!fs.existsSync(atlas)) {
+    io.stderr.write(`Atlas not found: ${atlas}\n`);
+    return 1;
+  }
+  io.stdout.write(`${atlas}\n`);
+  if (opts.open) openInBrowser(atlas);
+  return 0;
+}
+
+function runDiff(opts, io) {
+  const projectRoot = opts.projectRoot || findProjectRoot(process.cwd());
+  if (!projectRoot) {
+    io.stderr.write(
+      `Could not find resources/project-architecture/index.html. Pass --project <root> or generate the atlas via the init-project-html skill.\n`,
+    );
+    return 1;
+  }
+
+  const outDir = opts.out || path.join(projectRoot, DEFAULT_OUT_REL);
+  fs.mkdirSync(outDir, { recursive: true });
+
+  const changes = collectChanges(projectRoot);
+  const html = renderViewer({ changes, projectRoot, outDir });
+  const indexPath = path.join(outDir, 'index.html');
+  fs.writeFileSync(indexPath, html, 'utf8');
+
+  io.stdout.write(`${indexPath}\n`);
+  io.stdout.write(
+    `Diff pages: ${changes.length} (modified=${changes.filter((c) => c.kind === 'modified').length}, added=${changes.filter((c) => c.kind === 'added').length}, removed=${changes.filter((c) => c.kind === 'removed').length})\n`,
+  );
+  if (opts.open) openInBrowser(indexPath);
+  return 0;
+}
+
+function main(argv, io = { stdout: process.stdout, stderr: process.stderr }) {
+  let opts;
+  try {
+    opts = parseArgs(argv);
+  } catch (error) {
+    io.stderr.write(`${error.message}\n\n${USAGE}\n`);
+    return 1;
+  }
+  if (opts.help) {
+    io.stdout.write(`${USAGE}\n`);
+    return 0;
+  }
+  if (opts.subcommand === 'open') return runOpen(opts, io);
+  if (opts.subcommand === 'diff') return runDiff(opts, io);
+  io.stderr.write(`Unknown subcommand: ${opts.subcommand}\n\n${USAGE}\n`);
+  return 1;
+}
+
+if (require.main === module) {
+  const code = main(process.argv.slice(2));
+  process.exit(code);
+}
+
+module.exports = {
+  parseArgs,
+  findProjectRoot,
+  collectChanges,
+  renderViewer,
+  toViewerRel,
+  walkArchitectureDiffDirs,
+  walkAfterStateHtml,
+  readRemovedManifest,
+  main,
+};

package/lib/cli.js

@@ -158,6 +158,8 @@ function buildHelpText({ version, colorEnabled }) {
     '  apltk all',
     '  apltk filter-logs app.log --start 2026-03-24T10:00:00Z',
     '  apltk create-specs "Membership upgrade flow" --change-name membership-upgrade-flow',
+    '  apltk architecture                       # open resources/project-architecture/index.html',
+    '  apltk architecture diff                  # paginated before/after view of all docs/plans/.../architecture_diff/',
     '  apltk tools',
     '  apollo-toolkit all',
     '',

package/lib/tool-runner.js

@@ -3,6 +3,13 @@ const path = require('node:path');
 const { spawn } = require('node:child_process');
 
 const TOOL_COMMANDS = [
+  {
+    name: 'architecture',
+    skill: 'init-project-html',
+    script: 'init-project-html/scripts/architecture.js',
+    runner: 'node',
+    description: 'Open the project HTML architecture atlas, or render a paginated diff (`architecture diff`).',
+  },
   {
     name: 'filter-logs',
     skill: 'analyse-app-logs',

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.7",
+  "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.