@jaggerxtrm/specialists 3.16.0 → 3.18.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (257) hide show
  1. package/README.md +268 -132
  2. package/config/mandatory-rules/json-only-final-output.md +13 -0
  3. package/config/mandatory-rules/research-tool-routing.md +4 -0
  4. package/config/mandatory-rules/service-skills-diff-scan-mandatory.md +26 -0
  5. package/config/mandatory-rules/service-skills-gitnexus-triage.md +5 -0
  6. package/config/mandatory-rules/test-runner-execution-scope.md +1 -1
  7. package/config/skills/setup-specialists/SKILL.md +556 -0
  8. package/config/skills/specialists-creator/SKILL.md +160 -5
  9. package/config/skills/specialists-creator/scripts/audit-spec-uniformity.mjs +1 -1
  10. package/config/skills/using-specialists-auto/SKILL.md +1 -1
  11. package/config/skills/using-specialists-v2/SKILL.md +7 -7
  12. package/config/skills/using-specialists-v3/SKILL.md +223 -147
  13. package/config/specialists/bare.specialist.json +3 -3
  14. package/config/specialists/changelog-drafter.specialist.json +9 -6
  15. package/config/specialists/changelog-keeper.specialist.json +10 -7
  16. package/config/specialists/debugger.specialist.json +8 -6
  17. package/config/specialists/executor.specialist.json +9 -7
  18. package/config/specialists/explorer.specialist.json +8 -6
  19. package/config/specialists/memory-processor.specialist.json +7 -5
  20. package/config/specialists/node-coordinator.specialist.json +7 -5
  21. package/config/specialists/obligations-scanner.specialist.json +149 -0
  22. package/config/specialists/overthinker.specialist.json +7 -5
  23. package/config/specialists/planner.specialist.json +8 -6
  24. package/config/specialists/quant-methodologist.specialist.json +145 -0
  25. package/config/specialists/quant-researcher.specialist.json +144 -0
  26. package/config/specialists/researcher.specialist.json +14 -9
  27. package/config/specialists/reviewer.specialist.json +11 -9
  28. package/config/specialists/seconder.specialist.json +170 -0
  29. package/config/specialists/security-auditor.specialist.json +6 -4
  30. package/config/specialists/service-skills-sync.specialist.json +93 -0
  31. package/config/specialists/specialists-creator.specialist.json +9 -7
  32. package/config/specialists/sync-docs.specialist.json +6 -4
  33. package/config/specialists/test-engineer.specialist.json +134 -0
  34. package/config/specialists/test-runner.specialist.json +11 -9
  35. package/config/specialists/transcriber.specialist.json +59 -0
  36. package/config/specialists/xt-merge.specialist.json +7 -5
  37. package/dist/asset-contract.json +39 -8
  38. package/dist/index.js +37083 -26912
  39. package/dist/lib.js +9850 -6147
  40. package/dist/types/cli/console/components.d.ts +83 -0
  41. package/dist/types/cli/console/components.d.ts.map +1 -0
  42. package/dist/types/cli/console/config-source.d.ts +58 -0
  43. package/dist/types/cli/console/config-source.d.ts.map +1 -0
  44. package/dist/types/cli/console/forensic.d.ts +11 -0
  45. package/dist/types/cli/console/forensic.d.ts.map +1 -0
  46. package/dist/types/cli/console/git.d.ts +28 -0
  47. package/dist/types/cli/console/git.d.ts.map +1 -0
  48. package/dist/types/cli/console/help.d.ts +2 -0
  49. package/dist/types/cli/console/help.d.ts.map +1 -0
  50. package/dist/types/cli/console/log.d.ts +13 -0
  51. package/dist/types/cli/console/log.d.ts.map +1 -0
  52. package/dist/types/cli/console/repo-config.d.ts +26 -0
  53. package/dist/types/cli/console/repo-config.d.ts.map +1 -0
  54. package/dist/types/cli/console/repo-discovery.d.ts +12 -0
  55. package/dist/types/cli/console/repo-discovery.d.ts.map +1 -0
  56. package/dist/types/cli/console/runtime.d.ts +12 -0
  57. package/dist/types/cli/console/runtime.d.ts.map +1 -0
  58. package/dist/types/cli/console/subscribe-prototype.d.ts +18 -0
  59. package/dist/types/cli/console/subscribe-prototype.d.ts.map +1 -0
  60. package/dist/types/cli/console/theme.d.ts +91 -0
  61. package/dist/types/cli/console/theme.d.ts.map +1 -0
  62. package/dist/types/cli/console/types.d.ts +231 -0
  63. package/dist/types/cli/console/types.d.ts.map +1 -0
  64. package/dist/types/cli/console/view-model.d.ts +252 -0
  65. package/dist/types/cli/console/view-model.d.ts.map +1 -0
  66. package/dist/types/cli/console.d.ts +2 -0
  67. package/dist/types/cli/console.d.ts.map +1 -0
  68. package/dist/types/cli/db.d.ts.map +1 -1
  69. package/dist/types/cli/doctor.d.ts.map +1 -1
  70. package/dist/types/cli/edit.d.ts.map +1 -1
  71. package/dist/types/cli/epic.d.ts.map +1 -1
  72. package/dist/types/cli/feed.d.ts.map +1 -1
  73. package/dist/types/cli/forensic.d.ts +2 -0
  74. package/dist/types/cli/forensic.d.ts.map +1 -0
  75. package/dist/types/cli/format-helpers.d.ts +4 -2
  76. package/dist/types/cli/format-helpers.d.ts.map +1 -1
  77. package/dist/types/cli/help.d.ts.map +1 -1
  78. package/dist/types/cli/init.d.ts +10 -0
  79. package/dist/types/cli/init.d.ts.map +1 -1
  80. package/dist/types/cli/list.d.ts.map +1 -1
  81. package/dist/types/cli/log.d.ts +2 -0
  82. package/dist/types/cli/log.d.ts.map +1 -0
  83. package/dist/types/cli/metrics.d.ts +2 -0
  84. package/dist/types/cli/metrics.d.ts.map +1 -0
  85. package/dist/types/cli/ps.d.ts.map +1 -1
  86. package/dist/types/cli/result.d.ts.map +1 -1
  87. package/dist/types/cli/resume.d.ts.map +1 -1
  88. package/dist/types/cli/run.d.ts +1 -0
  89. package/dist/types/cli/run.d.ts.map +1 -1
  90. package/dist/types/cli/script.d.ts +3 -0
  91. package/dist/types/cli/script.d.ts.map +1 -1
  92. package/dist/types/cli/serve.d.ts.map +1 -1
  93. package/dist/types/cli/setup.d.ts +19 -1
  94. package/dist/types/cli/setup.d.ts.map +1 -1
  95. package/dist/types/cli/status.d.ts.map +1 -1
  96. package/dist/types/cli/steer.d.ts.map +1 -1
  97. package/dist/types/cli/version-check.d.ts +1 -0
  98. package/dist/types/cli/version-check.d.ts.map +1 -1
  99. package/dist/types/index.d.ts +1 -1
  100. package/dist/types/pi/session.d.ts +11 -1
  101. package/dist/types/pi/session.d.ts.map +1 -1
  102. package/dist/types/server.d.ts +15 -0
  103. package/dist/types/server.d.ts.map +1 -1
  104. package/dist/types/specialist/benchmarks.d.ts +37 -0
  105. package/dist/types/specialist/benchmarks.d.ts.map +1 -0
  106. package/dist/types/specialist/chain-identity.d.ts +7 -1
  107. package/dist/types/specialist/chain-identity.d.ts.map +1 -1
  108. package/dist/types/specialist/control.d.ts.map +1 -1
  109. package/dist/types/specialist/forensic-events.d.ts +138 -0
  110. package/dist/types/specialist/forensic-events.d.ts.map +1 -0
  111. package/dist/types/specialist/forensic-renderer.d.ts +34 -0
  112. package/dist/types/specialist/forensic-renderer.d.ts.map +1 -0
  113. package/dist/types/specialist/git-diff-evidence.d.ts +28 -0
  114. package/dist/types/specialist/git-diff-evidence.d.ts.map +1 -0
  115. package/dist/types/specialist/global-config.d.ts +389 -0
  116. package/dist/types/specialist/global-config.d.ts.map +1 -0
  117. package/dist/types/specialist/job-file-output.d.ts +2 -0
  118. package/dist/types/specialist/job-file-output.d.ts.map +1 -1
  119. package/dist/types/specialist/launch.d.ts +1 -0
  120. package/dist/types/specialist/launch.d.ts.map +1 -1
  121. package/dist/types/specialist/live-aggregates.d.ts +46 -0
  122. package/dist/types/specialist/live-aggregates.d.ts.map +1 -0
  123. package/dist/types/specialist/loader.d.ts +50 -1
  124. package/dist/types/specialist/loader.d.ts.map +1 -1
  125. package/dist/types/specialist/model-chain.d.ts +7 -0
  126. package/dist/types/specialist/model-chain.d.ts.map +1 -0
  127. package/dist/types/specialist/model-probes.d.ts +28 -0
  128. package/dist/types/specialist/model-probes.d.ts.map +1 -0
  129. package/dist/types/specialist/node-contract.d.ts +18 -18
  130. package/dist/types/specialist/node-supervisor.d.ts.map +1 -1
  131. package/dist/types/specialist/observability-db.d.ts +1 -1
  132. package/dist/types/specialist/observability-db.d.ts.map +1 -1
  133. package/dist/types/specialist/observability-sqlite.d.ts +25 -0
  134. package/dist/types/specialist/observability-sqlite.d.ts.map +1 -1
  135. package/dist/types/specialist/preset-resolver.d.ts +56 -0
  136. package/dist/types/specialist/preset-resolver.d.ts.map +1 -0
  137. package/dist/types/specialist/prometheus-projection.d.ts +25 -0
  138. package/dist/types/specialist/prometheus-projection.d.ts.map +1 -0
  139. package/dist/types/specialist/runner.d.ts +29 -1
  140. package/dist/types/specialist/runner.d.ts.map +1 -1
  141. package/dist/types/specialist/schema.d.ts +181 -63
  142. package/dist/types/specialist/schema.d.ts.map +1 -1
  143. package/dist/types/specialist/script-runner.d.ts +5 -1
  144. package/dist/types/specialist/script-runner.d.ts.map +1 -1
  145. package/dist/types/specialist/snapshot-diff.d.ts +8 -0
  146. package/dist/types/specialist/snapshot-diff.d.ts.map +1 -0
  147. package/dist/types/specialist/source-queue.d.ts +13 -0
  148. package/dist/types/specialist/source-queue.d.ts.map +1 -0
  149. package/dist/types/specialist/supervisor.d.ts +39 -2
  150. package/dist/types/specialist/supervisor.d.ts.map +1 -1
  151. package/dist/types/specialist/timeline-events.d.ts +88 -2
  152. package/dist/types/specialist/timeline-events.d.ts.map +1 -1
  153. package/dist/types/tools/specialist/resume_specialist.tool.d.ts +4 -4
  154. package/dist/types/tools/specialist/specialist_status.tool.d.ts +1 -1
  155. package/dist/types/tools/specialist/steer_specialist.tool.d.ts +4 -4
  156. package/dist/types/tools/specialist/use_specialist.tool.d.ts +16 -16
  157. package/docs/ARCHITECTURE.md +1176 -0
  158. package/docs/TODO.md +9 -0
  159. package/docs/architecture.md +11 -0
  160. package/docs/archive/2026-03-13-bd-decision-context-template-plan.md +96 -0
  161. package/docs/archive/AGENT-HANDOFF.md +351 -0
  162. package/docs/archive/PARITY-ANALYSIS.md +296 -0
  163. package/docs/archive/SPECIALISTS_REFACTOR.md.md +30 -0
  164. package/docs/archive/cc-programmatic.md +216 -0
  165. package/docs/archive/claude-agent-sdk.md +594 -0
  166. package/docs/archive/decision-specialist-directory.md +41 -0
  167. package/docs/archive/discoveries.md +148 -0
  168. package/docs/archive/executor-benchmark-protocol.md +198 -0
  169. package/docs/archive/future-features.md +66 -0
  170. package/docs/archive/gzrx-completion-critique.md +183 -0
  171. package/docs/archive/gzrx-research-notes.md +401 -0
  172. package/docs/archive/gzrx-tool-catalog.md +760 -0
  173. package/docs/archive/iron-review-hardening-qa-chain-substrate.md +322 -0
  174. package/docs/archive/iron-review-hardening.html +1004 -0
  175. package/docs/archive/issuetracking.md +312 -0
  176. package/docs/archive/qa-v3.0.2.md +220 -0
  177. package/docs/archive/restructure.md +231 -0
  178. package/docs/archive/script-specialists.md +1254 -0
  179. package/docs/archive/spec-v3.md +792 -0
  180. package/docs/archive/specialist-stats.md +127 -0
  181. package/docs/archive/specialists-friction-audit.md +1347 -0
  182. package/docs/archive/specialists-runtime-critique.md +170 -0
  183. package/docs/archive/specialists-service-evaluation.md +713 -0
  184. package/docs/archive/specialists-substrate-alignment.md +255 -0
  185. package/docs/archive/substrate-review.md +1288 -0
  186. package/docs/archive/test-writer-specialist.md +254 -0
  187. package/docs/archive/using-specialists-v3-improvements-2026-05-09.md +600 -0
  188. package/docs/archive/xtrm-specialists-analysis.md +314 -0
  189. package/docs/authoring.md +701 -0
  190. package/docs/background-jobs.md +203 -0
  191. package/docs/bare-specialists.md +83 -0
  192. package/docs/benchmarks/executor-benchmark-runner.md +66 -0
  193. package/docs/bootstrap.md +161 -0
  194. package/docs/cli-reference.md +1645 -0
  195. package/docs/deploying-alongside.md +155 -0
  196. package/docs/design/README.md +36 -0
  197. package/docs/design/darth-feedor-migration.md +290 -0
  198. package/docs/design/roadmap/README.md +32 -0
  199. package/docs/design/roadmap/chain-templates/README.md +146 -0
  200. package/docs/design/roadmap/chain-templates/code-quick.formula.json +27 -0
  201. package/docs/design/roadmap/chain-templates/code-standard.formula.json +126 -0
  202. package/docs/design/roadmap/chain-templates/code-with-advisors.formula.json +128 -0
  203. package/docs/design/roadmap/chain-templates/code-with-tests.formula.json +76 -0
  204. package/docs/design/roadmap/chain-templates/debug.formula.json +128 -0
  205. package/docs/design/roadmap/chain-templates/doc-sync.formula.json +28 -0
  206. package/docs/design/roadmap/chain-templates/memory-hygiene.formula.json +27 -0
  207. package/docs/design/roadmap/chain-templates/planning.formula.json +27 -0
  208. package/docs/design/roadmap/chain-templates/premortem.formula.json +26 -0
  209. package/docs/design/roadmap/chain-templates/release-prep.formula.json +36 -0
  210. package/docs/design/roadmap/chain-templates/research-only.formula.json +28 -0
  211. package/docs/design/roadmap/chain-templates/restitch.formula.json +125 -0
  212. package/docs/design/roadmap/chain-templates/security-deep.formula.json +161 -0
  213. package/docs/design/roadmap/chain-templates/test-only.formula.json +52 -0
  214. package/docs/design/roadmap/chain-templates/triage.formula.json +35 -0
  215. package/docs/design/roadmap/history/handoff-from-substrate-design.md +87 -0
  216. package/docs/design/roadmap/history/substrate-reconciliation.md +105 -0
  217. package/docs/design/roadmap/specialists-roadmap.md +1193 -0
  218. package/docs/design/sp-console-subscribe-via-materializer.md +231 -0
  219. package/docs/design/sp-console-tui-mock-v2.html +293 -0
  220. package/docs/design/sp-console-tui-mock.html +120 -0
  221. package/docs/design/sp-console-tui.md +340 -0
  222. package/docs/design/specialist-agentops-suite.md +323 -0
  223. package/docs/design/substrate/channels.md +14 -0
  224. package/docs/design/substrate/devops-platform-engineering-prd.md +446 -0
  225. package/docs/design/substrate/html-design-example.md +339 -0
  226. package/docs/design/xtrm-tiers-architecture.svg +132 -0
  227. package/docs/devops/dependency-verdict-materialization.md +46 -0
  228. package/docs/epic-readiness.md +75 -0
  229. package/docs/examples/mercury-atomic-summarizer.specialist.json +26 -0
  230. package/docs/examples/smoke-echo-text-expected-keys.specialist.json +25 -0
  231. package/docs/examples/smoke-echo.specialist.json +25 -0
  232. package/docs/features.md +1577 -0
  233. package/docs/hooks.md +81 -0
  234. package/docs/installation.md +142 -0
  235. package/docs/manifest.md +184 -0
  236. package/docs/mcp-servers.md +73 -0
  237. package/docs/mcp-tools.md +71 -0
  238. package/docs/nodes.md +231 -0
  239. package/docs/observability-metrics.md +152 -0
  240. package/docs/operator/sp-console-v2-walkthrough.md +410 -0
  241. package/docs/overrides-guide.md +306 -0
  242. package/docs/pi-rpc-boundary.md +118 -0
  243. package/docs/pi-session.md +195 -0
  244. package/docs/release.md +22 -0
  245. package/docs/skills.md +132 -0
  246. package/docs/specialists/handoff-schema.md +181 -0
  247. package/docs/specialists-catalog.md +99 -0
  248. package/docs/specialists-service-install.md +226 -0
  249. package/docs/specialists-service.md +363 -0
  250. package/docs/surface-ownership.md +138 -0
  251. package/docs/upgrade-notes/kan-90-global-user-config.md +114 -0
  252. package/docs/upgrade-notes/kan-91-expanded-overrides.md +261 -0
  253. package/docs/workflow.md +114 -0
  254. package/docs/worktree.md +71 -0
  255. package/docs/worktrees.md +309 -0
  256. package/package.json +17 -12
  257. package/config/specialists/code-sanity.specialist.json +0 -108
package/docs/design/substrate/html-design-example.md ADDED
@@ -0,0 +1,339 @@
1
+ # HTML handoff — substrate-design.html update + channels.html creation
2
+
3
+ > **Audience.** The agent in the next session who will do the HTML/typesetting work. This is a self-contained brief: with this document and the four canonical files it references, you do not need the prior session's conversation history.
4
+ >
5
+ > **What's asked.** Two HTML deliverables, both styled identically: (1) bring `substrate-design.html` from its current state (~rev6/7) up to rev10, and (2) create a fresh `channels.html` from `channels.md` in the same style. Existing `substrate-design.html` is the visual reference; this handoff documents the style explicitly so you do not have to reverse-engineer it.
6
+ >
7
+ > **Operator.** Jaggerxtrm / dawid. Solopreneur, ~10 repos in parallel. Prefers honesty about scope and pushback over deference.
8
+
9
+ ---
10
+
11
+ ## 1. The four files you need
12
+
13
+ 1. **`substrate-design.md`** — the canonical English source, revision 10. 18 top-level sections, 1816 lines. This is what `substrate-design.html` must reflect.
14
+ 2. **`substrate-design.html`** — the existing visual reference. Hand-crafted typesetting, magazine-quality. Currently behind by 3-4 revisions: missing §3.1 (runtime alignment), §4.3 (chain coordinator, rev10), §6.2.1 (three classifiers, rev8), §6.4 (precondition gate, rev9), §6.9 chain templates entirely (rev9), §6.10 close flow (rev9), and §10.2 is the old "Memory curator" section that rev10 entirely replaced. Preserve the styling, replace the content where needed.
15
+ 3. **`channels.md`** — the source for `channels.html`. 640 lines, 15 sections. Already rev9-aligned with the §15 migration map.
16
+ 4. **`substrate-design-it.md`** — Italian translation. Mentioned only so you know it exists. Out of scope for HTML work; an Italian HTML is a separate future task.
17
+
18
+ ---
19
+
20
+ ## 2. What the existing substrate-design.html does well — do not break these
21
+
22
+ The existing HTML is a hand-crafted magazine-style document. Its strengths, all to preserve:
23
+
24
+ - **Magazine-typeset reading experience**: Newsreader serif for body, JetBrains Mono for code/labels, generous whitespace, dropcap on the first paragraph of `.lead` sections.
25
+ - **Restrained single-accent palette**: cream paper (`#F5F2E9`) on dark ink (`#15130E`) with one accent (deep oxblood, `#7A1F1B`) used sparingly for links, section numbers, dropcap, dingbat, code-block left border.
26
+ - **Section numbering as a typographic element**: each `<h2>` carries a `<span class="num">NN</span>` rendered as small monospace accent-colored — `00`, `01`, … — *separate from* the title text. Numbers are zero-padded.
27
+ - **The kicker / title / subtitle / meta-grid masthead** at the top: a small uppercase letter-spaced kicker, a large italic serif title, an italic serif subtitle, then a 4-column monospace metadata grid (status / scope / audience / version).
28
+ - **The dingbat**: a small italic accent-colored ornament (`§`, `❦`, or similar) positioned absolute top-right of the masthead, rotated slightly. Subtle, one per document.
29
+ - **Code blocks as a separate object**: dark background (`#1A1813`), cream text, monospace, with a 3px oxblood left border — visually distinct from prose.
30
+ - **Tables as quiet objects**: thin rules in `--paper-shade`, monospace uppercase column headers with letter-spacing, hoverable rows.
31
+ - **Long-form readability constraints**: paragraphs max 68ch, list items max 65ch, page max 1080px centered with 80px top padding and 56px sides. Do not let lines run edge-to-edge.
32
+ - **The faint paper-grain background**: a 32×32 radial-gradient dot pattern at 2.5% opacity on the body. Subtle texture; do not remove.
33
+
34
+ If anything about your output makes the document feel like a generic technical doc instead of a magazine, you've drifted from the style.
35
+
36
+ ---
37
+
38
+ ## 3. The style guide — inline CSS, fonts, structural pattern
39
+
40
+ You can copy the existing HTML's `<head>` (lines 1-180 of `substrate-design.html`) verbatim for both files; both share the same stylesheet. The complete style follows.
41
+
42
+ ### 3.1 Fonts (Google Fonts)
43
+
44
+ ```html
45
+ <link rel="preconnect" href="https://fonts.googleapis.com">
46
+ <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
47
+ <link href="https://fonts.googleapis.com/css2?family=Newsreader:ital,opsz,wght@0,6..72,400;0,6..72,500;0,6..72,600;1,6..72,400&family=JetBrains+Mono:wght@400;500;600&display=swap" rel="stylesheet">
48
+ ```
49
+
50
+ ### 3.2 CSS variables (the palette)
51
+
52
+ ```css
53
+ :root{
54
+ --ink:#15130E;
55
+ --paper:#F5F2E9;
56
+ --paper-shade:#EBE7DB;
57
+ --rule:#15130E;
58
+ --muted:#6B675C;
59
+ --faint:#A8A395;
60
+ --accent:#7A1F1B; /* deep oxblood, single accent */
61
+ --serif:'Newsreader','Iowan Old Style','Charter','Georgia',serif;
62
+ --mono:'JetBrains Mono','SF Mono','Consolas',monospace;
63
+
64
+ /* event class palette — used by the dashboard section, matches dashboard colors */
65
+ --c-life:#6B675C; /* lifecycle */
66
+ --c-mail:#3F2F86; /* channel messages */
67
+ --c-teth:#9A6A12; /* tether hints */
68
+ --c-coll:#8A2949; /* collisions */
69
+ --c-ctrc:#1A4D85; /* contract state */
70
+ --c-plan:#2C5F1F; /* plan/seed events */
71
+ }
72
+ ```
73
+
74
+ ### 3.3 Body & paper
75
+
76
+ ```css
77
+ *{box-sizing:border-box}
78
+ html,body{margin:0;padding:0;background:var(--paper);color:var(--ink);font-family:var(--serif);font-size:17px;line-height:1.55}
79
+ body{
80
+ background-image: radial-gradient(circle at 0 0, rgba(21,19,14,0.025) 1px, transparent 1px);
81
+ background-size:32px 32px;
82
+ }
83
+ .page{max-width:1080px;margin:0 auto;padding:80px 56px 120px}
84
+ ```
85
+
86
+ ### 3.4 Code, links, tables
87
+
88
+ ```css
89
+ .code, code, kbd, .mono{font-family:var(--mono);font-size:0.88em}
90
+ code{background:var(--paper-shade);padding:1px 5px;border-radius:2px}
91
+ pre{background:#1A1813;color:#E8E3D2;padding:18px 22px;overflow-x:auto;border-radius:0;
92
+ border-left:3px solid var(--accent);font-family:var(--mono);font-size:13px;line-height:1.55}
93
+ pre code{background:transparent;padding:0;color:inherit}
94
+ a{color:var(--accent);text-decoration:none;border-bottom:1px solid var(--accent)}
95
+ a:hover{background:var(--accent);color:var(--paper)}
96
+ table{width:100%;border-collapse:collapse;margin:18px 0;font-size:14px}
97
+ th,td{border-bottom:1px solid var(--paper-shade);padding:8px 10px;text-align:left;vertical-align:top}
98
+ th{font-family:var(--mono);text-transform:uppercase;letter-spacing:0.1em;font-size:10px;
99
+ color:var(--muted);border-bottom:1.5px solid var(--rule);font-weight:500}
100
+ tbody tr:hover{background:var(--paper-shade)}
101
+ ```
102
+
103
+ ### 3.5 Masthead — top-of-document block
104
+
105
+ ```css
106
+ .masthead{border-bottom:2px solid var(--rule);padding-bottom:36px;margin-bottom:48px;position:relative}
107
+ .kicker{font-family:var(--mono);font-size:11px;letter-spacing:0.22em;text-transform:uppercase;
108
+ color:var(--muted);margin-bottom:14px}
109
+ h1.title{font-family:var(--serif);font-weight:500;font-size:64px;line-height:1.02;
110
+ letter-spacing:-0.025em;margin:0 0 18px;font-style:italic}
111
+ h1.title span{font-style:normal;font-weight:400}
112
+ .subtitle{font-family:var(--serif);font-size:21px;font-style:italic;color:var(--ink);
113
+ font-weight:400;max-width:740px;line-height:1.4}
114
+ .meta{margin-top:32px;display:grid;grid-template-columns:repeat(4,1fr);gap:24px;
115
+ font-family:var(--mono);font-size:11px;letter-spacing:0.05em}
116
+ .meta dt{color:var(--muted);text-transform:uppercase;letter-spacing:0.15em;
117
+ font-size:10px;margin-bottom:4px}
118
+ .meta dd{margin:0;color:var(--ink)}
119
+ .dingbat{position:absolute;top:-8px;right:0;font-family:var(--serif);font-style:italic;
120
+ font-size:18px;color:var(--accent);transform:rotate(2deg)}
121
+ ```
122
+
123
+ Masthead HTML pattern:
124
+
125
+ ```html
126
+ <header class="masthead">
127
+ <div class="dingbat">§</div>
128
+ <div class="kicker">Design memo · revision 10 · 2026</div>
129
+ <h1 class="title"><span>Substrate:</span> Containers, Issues, and the Seed Lifecycle</h1>
130
+ <div class="subtitle">A runtime architecture for agent-native work. Replaces the orchestrator's tribal practices with named, observable, replayable entities.</div>
131
+ <dl class="meta">
132
+ <div><dt>Status</dt><dd>Draft, rev 10</dd></div>
133
+ <div><dt>Scope</dt><dd>xtrm project</dd></div>
134
+ <div><dt>Readers</dt><dd>Operator · Orchestrator · Coordinators</dd></div>
135
+ <div><dt>Source</dt><dd>substrate-design.md</dd></div>
136
+ </dl>
137
+ </header>
138
+ ```
139
+
140
+ ### 3.6 Sections — numbered, italic-serif headings
141
+
142
+ ```css
143
+ section{margin:64px 0;scroll-margin-top:24px}
144
+ section > h2{font-family:var(--serif);font-style:italic;font-weight:500;font-size:32px;
145
+ letter-spacing:-0.01em;margin:0 0 24px;padding-bottom:8px;
146
+ border-bottom:1px solid var(--rule);
147
+ display:flex;align-items:baseline;gap:14px}
148
+ section > h2 .num{font-family:var(--mono);font-style:normal;font-size:13px;
149
+ color:var(--accent);letter-spacing:0.1em;flex-shrink:0;width:38px}
150
+ h3{font-family:var(--serif);font-weight:500;font-size:22px;margin:36px 0 12px;
151
+ letter-spacing:-0.005em}
152
+ h4{font-family:var(--mono);text-transform:uppercase;letter-spacing:0.15em;
153
+ font-size:11px;color:var(--accent);margin:24px 0 10px;font-weight:600}
154
+ p{margin:0 0 16px;max-width:68ch}
155
+ ul,ol{padding-left:22px}
156
+ li{margin-bottom:6px;max-width:65ch}
157
+ strong{font-weight:600}
158
+ em{font-style:italic}
159
+ ```
160
+
161
+ Section HTML pattern (numbers zero-padded, `00` is allowed for layout/intro):
162
+
163
+ ```html
164
+ <section id="lifecycle">
165
+ <h2><span class="num">03</span>The container lifecycle</h2>
166
+ <p>...</p>
167
+ <h3>3.1 Runtime alignment</h3>
168
+ <p>...</p>
169
+ </section>
170
+ ```
171
+
172
+ ### 3.7 Dropcap (first-paragraph drop letter on `.lead` sections)
173
+
174
+ ```css
175
+ section.lead p:first-of-type::first-letter{
176
+ font-family:var(--serif); float:left;
177
+ font-size:64px; line-height:0.85;
178
+ padding:8px 10px 0 0;
179
+ font-weight:500; color:var(--accent);
180
+ font-style:italic;
181
+ }
182
+ ```
183
+
184
+ Apply `class="lead"` only to the first content section (the "Problem" intro for substrate, the "Problem" intro for channels). One per document. The dropcap is a magazine cue — don't sprinkle it.
185
+
186
+ ### 3.8 The page wrapper
187
+
188
+ ```html
189
+ <body>
190
+ <div class="page">
191
+ <header class="masthead">...</header>
192
+ <section id="...">...</section>
193
+ <section id="...">...</section>
194
+ ...
195
+ </div>
196
+ </body>
197
+ ```
198
+
199
+ ---
200
+
201
+ ## 4. Deliverable 1 — substrate-design.html rev6/7 → rev10
202
+
203
+ The existing HTML is preserved as visual reference. **Strategy: do not patch in place; rebuild the body content from `substrate-design.md` rev10, keeping the existing `<head>` and `<header class="masthead">` (updating only the rev number).** Patching a rev6/7 HTML to rev10 piecemeal produces internally incoherent prose with dangling forward-references.
204
+
205
+ ### Section mapping (rev10 markdown → HTML section numbers)
206
+
207
+ The markdown sections map to HTML sections roughly as follows. Use these as `<h2><span class="num">NN</span>Title</h2>`:
208
+
209
+ | HTML num | Title | Source in `substrate-design.md` |
210
+ |---|---|---|
211
+ | `00` | Project layout | top of doc (preamble + "Layout") |
212
+ | `01` | Problem | §1 |
213
+ | `02` | Conceptual model | §2 (and all subsections §2.1–§2.6) |
214
+ | `03` | The container lifecycle | §3 (and §3.1 runtime alignment as `<h3>`) |
215
+ | `04` | Container kinds | §4 (and §4.1 seed, §4.2 node, **§4.3 chain coordinator (NEW)**, §4.4 merge) |
216
+ | `05` | Seed: planning in depth | §5 (all subsections) |
217
+ | `06` | The new issue system | §6 (large — §6.1 through §6.10) |
218
+ | `07` | Channels (recap) | §7 |
219
+ | `08` | Tether | §8 |
220
+ | `09` | Collision matrix | §9 |
221
+ | `10` | Memory | §10 (note: was "Memory curator", rev10 retitled "Memory"; **§10.2 is entirely rewritten** — old "Memory curator" section is gone, replaced by "Memory access is a capability, not a role") |
222
+ | `11` | CLI surface | §11 |
223
+ | `12` | Dashboard | §12 |
224
+ | `13` | Data model / storage | §13 |
225
+ | `14` | Open questions | §14 + §14.1 questions-for-next-agent |
226
+ | `15` | Sequencing | §15 |
227
+ | `16` | Summary | §16 |
228
+ | `17` | API surface | §17 |
229
+
230
+ ### What's new since the existing HTML (priority order)
231
+
232
+ **Highest priority — entirely missing, must be added:**
233
+
234
+ 1. **§4.3 Chain coordinator** (rev10). Net-new section between §4.2 (Node coordinator) and §4.4 (Merge). Four roles: entry gate, borderline judge, hygiene coordinator via pulse, close-time judge. Model selection per chain_template. Lifecycle bounded. Source in `substrate-design.md` lines 199-218.
235
+ 2. **§6.9 Chain templates and composition** (rev9). Large — §6.9.1 through §6.9.10. The whole "workflow → chain_template" rework: two-layer templates, composition in three moments, worktree lease, two-axis git, deliberative issue types, six template archetypes. ~600 lines of source.
236
+ 3. **§6.10 Closing an issue — close is a derivation, not an imperative** (rev9, with rev10 coordinator addition). Close hierarchy, transactional close at merge, the new paragraph about the chain coordinator's close-time pass. ~150 lines of source.
237
+ 4. **§10.2 Memory access is a capability, not a role** (rev10). Complete rewrite of what was "Memory curator". Eliminates the dedicated memory-curator role; planner queries at seed-time, specialist at run-time, chain coordinator distills at close. Source lines 1210-1220.
238
+ 5. **§6.4 Precondition gate** (rev9). Distinct from §5.10 failure recovery — "we should not have started" vs "we started and stumbled". Refuses with the structured envelope.
239
+ 6. **§6.2.1 Three classifiers — class/type/role** (rev8). Stored not derived; gate-ness structurally enforced.
240
+
241
+ **Medium priority — additions/changes to existing sections:**
242
+
243
+ 7. **§3.1 Runtime alignment** (rev9, with rev10 chain refinement). Event-driven advancement on `turn_end`/pulse/`sb` command; the `verdict: ready` from chain coordinator as the dispatch precondition for step-1. Render as `<h3>` inside the §3 lifecycle section.
244
+ 8. **§5.10 Failure recovery — generic closing judge** (rev10 update). The "closing judge" language is generic now: chain coordinator for chain, node coordinator for node, operator for seed escalated.
245
+ 9. **§6.7 Issue relationships** — the nine-relationship model (rev8), with `informs`/`spawned_by` recorded as future splits.
246
+ 10. **§13.3 Schema** — additions: `autonomy_json` extended to chain (max_inserts, allowed_insertion_roles, max_followup_proposals, escalate_when), `chain_coordinator_model`, `resolved_chain_json`, `worktree_lease_json`, `fork_base`.
247
+ 11. **Status header + changelog** — update masthead `Status` metadata to "Draft, rev 10". The doc's status paragraph (just under the title) names the rev10 changes; render this as the `.subtitle` text or as a small section beneath the masthead.
248
+
249
+ **Low priority — likely already correct in the existing HTML but verify:**
250
+
251
+ - §1 Problem, §2 Conceptual model, §3 lifecycle (the upper part), §4.1/§4.2, §5 seed, §8 tether, §9 collisions, §11 CLI, §12 dashboard, §13.1/§13.2.
252
+
253
+ ### Tables in §10 and §6 — render as styled tables
254
+
255
+ The markdown has several reference tables that benefit from the `<table>` styling: the §10.1 three-lens memory table, the §6.7 nine-relationships table, the §6.9.10 six-templates table, the §6.2.1 class/type/role table. Render these as proper HTML tables, not as `<ul>`.
256
+
257
+ ### Code blocks
258
+
259
+ Several sections have JSON / DDL / pseudocode in fenced code blocks. Render as `<pre><code>` with the dark theme. Notable code blocks: §5.7 plan example, §5.10 recovery policy, §6.1 issue schema, §6.9.5 composition example, §13.3 full schema DDL.
260
+
261
+ ---
262
+
263
+ ## 5. Deliverable 2 — channels.html (new)
264
+
265
+ Build `channels.html` from `channels.md` using the same stylesheet and the same masthead/section pattern.
266
+
267
+ ### Masthead
268
+
269
+ ```html
270
+ <header class="masthead">
271
+ <div class="dingbat">¶</div>
272
+ <div class="kicker">Design memo · v0 → v3 · 2026</div>
273
+ <h1 class="title"><span>Channels:</span> A Reusable Inter-Specialist Communication Layer</h1>
274
+ <div class="subtitle">An append-only, subscribable, multi-party message stream per container. Rev-9 aligned with substrate; sequenced v0 → v3.</div>
275
+ <dl class="meta">
276
+ <div><dt>Status</dt><dd>Design draft, rev-9 aligned</dd></div>
277
+ <div><dt>Scope</dt><dd>Inter-specialist comms</dd></div>
278
+ <div><dt>Relationship</dt><dd>Subordinate to substrate</dd></div>
279
+ <div><dt>Source</dt><dd>channels.md</dd></div>
280
+ </dl>
281
+ </header>
282
+ ```
283
+
284
+ ### Section mapping
285
+
286
+ | HTML num | Title | Source in `channels.md` |
287
+ |---|---|---|
288
+ | `01` | Problem | §1 |
289
+ | `02` | Goals | §2 |
290
+ | `03` | Non-goals | §3 |
291
+ | `04` | Concepts | §4 (table renders well) |
292
+ | `05` | Architecture | §5 (and §5.1 storage, §5.1.1 store-now-and-later bridge, §5.2 lifecycle, §5.3 message kinds, §5.4 subscription, §5.5 runtime integration, §5.6 topologies, §5.7 stop conditions) |
293
+ | `06` | Spec schema | §6 |
294
+ | `07` | Node config | §7 |
295
+ | `08` | CLI surface | §8 |
296
+ | `09` | Self-managed node flow | §9 |
297
+ | `10` | Permission & safety | §10 (and §10.1 authority decision, §10.2 error envelope) |
298
+ | `11` | Sequenced implementation v0→v3 | §11 |
299
+ | `12` | Open questions | §12 |
300
+ | `13` | Risks & mitigations | §13 |
301
+ | `14` | Success criteria per version | §14 |
302
+ | `15` | Substrate relationship & migration map | §15 (and §15.1–§15.5) |
303
+
304
+ ### Render hints specific to channels.html
305
+
306
+ - **The §5.3 message-kinds table** is the visual centerpiece — render as a proper styled `<table>` with all columns visible.
307
+ - **The §15.4 concept-by-concept migration map** is a 13-row 3-column table — render carefully, this is the document's payoff.
308
+ - **The §5.1 SQL DDL** should be a `<pre><code>` block, dark theme.
309
+ - **The v0 / v0.5 / v1 / v2 / v3 sub-sections** in §11 are conceptually separate stages — render each with `<h3>` and consider a small versioned accent label (use the `--accent` color, monospace) to make the staging visible at a glance.
310
+ - **The §15.5 "Settled / Owed" bifurcation** at the end of §15 should be visually distinct — perhaps two side-by-side blocks or a clear `<h4>` separation. This is where the doc tells you what it owes substrate; it should not be lost in prose flow.
311
+
312
+ ---
313
+
314
+ ## 6. Method recommendations
315
+
316
+ - **Build from markdown, not by patching HTML.** Both files are likely cleaner to write fresh from the markdown source than to surgery the existing HTML. The CSS is reusable verbatim; the body content is the work.
317
+ - **A converter is OK but inspect the output.** A pandoc-style markdown→HTML pass gets you 80% there; the remaining 20% (masthead, section numbers as `<span class="num">`, table rendering, code block styling, dropcap class on the right section, paragraph break-up) needs hand tweaks.
318
+ - **Verify against `substrate-design.md` for content fidelity.** Do not summarize, do not skip subsections. The markdown is the canonical content.
319
+ - **One single-file HTML per deliverable.** All CSS inline in `<style>`, no external assets except the Google Fonts link. Both files should open in any browser without dependencies.
320
+ - **Hover-able section anchors.** Each `<h2>` and `<h3>` should have an `id` matching the section slug (e.g., `id="lifecycle"`, `id="chain-coordinator"`) so cross-references can link.
321
+
322
+ ---
323
+
324
+ ## 7. Quality bar — what "done" looks like
325
+
326
+ - `substrate-design.html` reads end-to-end as a magazine-typeset rev10 design memo. No dangling forward-references. The chain coordinator §4.3 is present and complete. §6.9 chain templates is present in full. §6.10 close flow is present. §10.2 is the new "Memory access is a capability" content, not the old "Memory curator" content. Status meta shows "rev 10".
327
+ - `channels.html` is a parallel artifact in the same style. The §15 migration map renders as the visual payoff at the end. The v0→v3 sequencing in §11 is visually scannable.
328
+ - Both render correctly at 1080px desktop and degrade gracefully at narrower widths (the page-wrapper has the max-width; line-length constraints already protect readability).
329
+ - Both validate as well-formed HTML. No console errors. Fonts load.
330
+
331
+ ---
332
+
333
+ ## 8. Open coordination notes
334
+
335
+ - **The operator (Jaggerxtrm/dawid) will likely review by reading the HTML side-by-side with the markdown.** Match the markdown semantics carefully; if you find a discrepancy where the markdown is unclear, ask before guessing.
336
+ - **Style decisions you may make on your own:** which dingbat character to use per document, the exact wording of `kicker` and `subtitle` if the existing isn't ideal, where to place a `.lead` dropcap (one per document, the first content section).
337
+ - **Style decisions to NOT make on your own:** palette changes, font swaps, removing the paper-grain background, restructuring the masthead grid, changing section-number style. These are the document's identity.
338
+
339
+ You have everything you need. Build.
package/docs/design/xtrm-tiers-architecture.svg ADDED
@@ -0,0 +1,132 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1040 770" font-family="Segoe UI, Helvetica, Arial, sans-serif">
2
+ <defs>
3
+ <marker id="arr" markerWidth="9" markerHeight="9" refX="7" refY="3" orient="auto" markerUnits="strokeWidth">
4
+ <path d="M0,0 L7,3 L0,6 Z" fill="#444"/>
5
+ </marker>
6
+ <marker id="arrG" markerWidth="9" markerHeight="9" refX="7" refY="3" orient="auto" markerUnits="strokeWidth">
7
+ <path d="M0,0 L7,3 L0,6 Z" fill="#0f9d58"/>
8
+ </marker>
9
+ <marker id="arrR" markerWidth="9" markerHeight="9" refX="7" refY="3" orient="auto" markerUnits="strokeWidth">
10
+ <path d="M0,0 L7,3 L0,6 Z" fill="#ea4b71"/>
11
+ </marker>
12
+ </defs>
13
+
14
+ <rect x="0" y="0" width="1040" height="770" fill="#ffffff"/>
15
+ <text x="40" y="34" font-size="22" font-weight="700" fill="#202124">Architettura xtrm — due livelli: runtime locale → tier condiviso / web</text>
16
+
17
+ <!-- USERS -->
18
+ <g>
19
+ <rect x="70" y="52" width="115" height="36" rx="8" fill="#fff" stroke="#5f6368"/>
20
+ <text x="127" y="75" font-size="14" fill="#202124" text-anchor="middle">👤 Solo</text>
21
+ <rect x="197" y="52" width="115" height="36" rx="8" fill="#fff" stroke="#5f6368"/>
22
+ <text x="254" y="75" font-size="14" fill="#202124" text-anchor="middle">👥 Team</text>
23
+ <rect x="324" y="52" width="115" height="36" rx="8" fill="#fff" stroke="#5f6368"/>
24
+ <text x="381" y="75" font-size="14" fill="#202124" text-anchor="middle">🏢 Azienda</text>
25
+ <path d="M127,88 L210,158" stroke="#444" fill="none" marker-end="url(#arr)"/>
26
+ <path d="M254,88 L252,158" stroke="#444" fill="none" marker-end="url(#arr)"/>
27
+ <path d="M381,88 L300,158" stroke="#444" fill="none" marker-end="url(#arr)"/>
28
+ </g>
29
+
30
+ <!-- SHARED / WEB TIER -->
31
+ <rect x="40" y="112" width="795" height="232" rx="14" fill="#e8f0fe" stroke="#4285f4" stroke-width="1.5"/>
32
+ <text x="56" y="134" font-size="15" font-weight="700" fill="#1a56c4">LIVELLO CONDIVISO / WEB — team · azienda (proiezione, non la sorgente di verità)</text>
33
+
34
+ <!-- Console -->
35
+ <rect x="70" y="158" width="360" height="158" rx="10" fill="#ede9fe" stroke="#7c3aed" stroke-width="1.5"/>
36
+ <text x="86" y="182" font-size="16" font-weight="700" fill="#5b21b6">Console Web</text>
37
+ <text x="86" y="208" font-size="13.5" fill="#3c1d8f">• Visualizzazione del lavoro</text>
38
+ <text x="86" y="230" font-size="13.5" fill="#3c1d8f">• DevOps</text>
39
+ <text x="86" y="252" font-size="13.5" fill="#3c1d8f">• AgentOps — suite di ottimizzazione</text>
40
+ <text x="86" y="274" font-size="13.5" fill="#3c1d8f">• Maturità specialist · coda proposte</text>
41
+ <text x="86" y="296" font-size="12" fill="#6b21a8" font-style="italic">stesso console per ogni livello</text>
42
+
43
+ <!-- Supabase -->
44
+ <rect x="460" y="158" width="375" height="158" rx="10" fill="#d1fae5" stroke="#10b981" stroke-width="1.5"/>
45
+ <text x="476" y="182" font-size="16" font-weight="700" fill="#047857">Supabase (Postgres)</text>
46
+ <text x="476" y="208" font-size="13.5" fill="#065f46">• Auth — chi vede cosa</text>
47
+ <text x="476" y="230" font-size="13.5" fill="#065f46">• Realtime → aggiorna il browser</text>
48
+ <text x="476" y="252" font-size="13.5" fill="#065f46">• API automatica (REST/GraphQL)</text>
49
+ <text x="476" y="274" font-size="13.5" fill="#065f46">• Storage</text>
50
+ <text x="476" y="296" font-size="12" fill="#059669" font-style="italic">serve solo da team in su</text>
51
+
52
+ <!-- realtime arrow Supabase -> Console -->
53
+ <path d="M460,224 L433,224" stroke="#0f9d58" stroke-width="1.6" fill="none" marker-end="url(#arrG)"/>
54
+ <text x="446" y="216" font-size="11.5" fill="#0f9d58" text-anchor="middle">dati + realtime</text>
55
+
56
+ <!-- n8n -->
57
+ <rect x="868" y="158" width="150" height="120" rx="10" fill="#fde2e7" stroke="#ea4b71" stroke-width="1.5"/>
58
+ <text x="884" y="182" font-size="15" font-weight="700" fill="#b3294e">n8n</text>
59
+ <text x="884" y="204" font-size="12.5" fill="#9d1f42">automazioni</text>
60
+ <text x="884" y="224" font-size="12" fill="#9d1f42" font-style="italic">glue, non</text>
61
+ <text x="884" y="240" font-size="12" fill="#9d1f42" font-style="italic">uno store</text>
62
+ <!-- n8n -> Supabase -->
63
+ <path d="M868,214 L838,214" stroke="#ea4b71" stroke-width="1.5" fill="none" marker-end="url(#arrR)"/>
64
+ <text x="852" y="206" font-size="10.5" fill="#ea4b71" text-anchor="middle">scrive</text>
65
+
66
+ <!-- SYNC SEAM -->
67
+ <line x1="40" y1="362" x2="835" y2="362" stroke="#9aa0a6" stroke-width="1.5" stroke-dasharray="7 5"/>
68
+ <text x="437" y="356" font-size="12.5" fill="#5f6368" text-anchor="middle" font-style="italic">proiezione / sync ↑ — ID opachi, niente FK cross-dominio · il runtime resta autoritativo in basso</text>
69
+
70
+ <!-- LOCAL RUNTIME TIER -->
71
+ <rect x="40" y="376" width="795" height="236" rx="14" fill="#f1f3f4" stroke="#5f6368" stroke-width="1.5"/>
72
+ <text x="56" y="398" font-size="15" font-weight="700" fill="#3c4043">LIVELLO RUNTIME LOCALE — sempre presente · autoritativo (la verità del lifecycle)</text>
73
+
74
+ <!-- machine template -->
75
+ <g>
76
+ <!-- Dev A -->
77
+ <rect x="62" y="412" width="235" height="180" rx="10" fill="#ffffff" stroke="#5f6368"/>
78
+ <text x="78" y="436" font-size="14.5" font-weight="700" fill="#202124">💻 Dev A (laptop)</text>
79
+ <rect x="78" y="448" width="203" height="30" rx="6" fill="#e8eaed" stroke="#9aa0a6"/>
80
+ <text x="180" y="468" font-size="12.5" fill="#202124" text-anchor="middle">daemon: sp · sb · channels</text>
81
+ <rect x="78" y="486" width="203" height="34" rx="6" fill="#fff7ed" stroke="#f59e0b"/>
82
+ <text x="180" y="507" font-size="12.5" font-weight="700" fill="#b45309" text-anchor="middle">state.db (SQLite WAL)</text>
83
+ <text x="180" y="540" font-size="12" fill="#5f6368" text-anchor="middle">worktrees · 1 socket</text>
84
+ <text x="180" y="562" font-size="11.5" fill="#80868b" text-anchor="middle" font-style="italic">routing per project_id</text>
85
+
86
+ <!-- Dev B -->
87
+ <rect x="310" y="412" width="235" height="180" rx="10" fill="#ffffff" stroke="#5f6368"/>
88
+ <text x="326" y="436" font-size="14.5" font-weight="700" fill="#202124">💻 Dev B</text>
89
+ <rect x="326" y="448" width="203" height="30" rx="6" fill="#e8eaed" stroke="#9aa0a6"/>
90
+ <text x="428" y="468" font-size="12.5" fill="#202124" text-anchor="middle">daemon: sp · sb · channels</text>
91
+ <rect x="326" y="486" width="203" height="34" rx="6" fill="#fff7ed" stroke="#f59e0b"/>
92
+ <text x="428" y="507" font-size="12.5" font-weight="700" fill="#b45309" text-anchor="middle">state.db (SQLite WAL)</text>
93
+ <text x="428" y="540" font-size="12" fill="#5f6368" text-anchor="middle">cattura locale →</text>
94
+ <text x="428" y="560" font-size="11.5" fill="#80868b" text-anchor="middle" font-style="italic">sp-improve beads + telemetria</text>
95
+
96
+ <!-- CI / Server -->
97
+ <rect x="558" y="412" width="235" height="180" rx="10" fill="#ffffff" stroke="#5f6368"/>
98
+ <text x="574" y="436" font-size="14.5" font-weight="700" fill="#202124">🖥 CI / Server</text>
99
+ <rect x="574" y="448" width="203" height="30" rx="6" fill="#e8eaed" stroke="#9aa0a6"/>
100
+ <text x="676" y="468" font-size="12.5" fill="#202124" text-anchor="middle">daemon + state.db</text>
101
+ <rect x="574" y="486" width="203" height="34" rx="6" fill="#e0f2fe" stroke="#0284c7"/>
102
+ <text x="676" y="507" font-size="12" font-weight="700" fill="#075985" text-anchor="middle">sp serve POST /v1/generate</text>
103
+ <text x="676" y="540" font-size="11.5" fill="#5f6368" text-anchor="middle">script specialists (READ_ONLY)</text>
104
+ <text x="676" y="560" font-size="11.5" fill="#80868b" text-anchor="middle" font-style="italic">il punto d'aggancio per n8n</text>
105
+ </g>
106
+
107
+ <!-- sync arrows machines -> Supabase -->
108
+ <path d="M180,412 L560,318" stroke="#0f9d58" stroke-width="1.4" fill="none" marker-end="url(#arrG)" opacity="0.85"/>
109
+ <path d="M428,412 L625,318" stroke="#0f9d58" stroke-width="1.4" fill="none" marker-end="url(#arrG)" opacity="0.85"/>
110
+ <path d="M676,412 L700,318" stroke="#0f9d58" stroke-width="1.4" fill="none" marker-end="url(#arrG)" opacity="0.85"/>
111
+
112
+ <!-- n8n -> sp serve -->
113
+ <path d="M944,278 L770,486" stroke="#ea4b71" stroke-width="1.4" fill="none" stroke-dasharray="6 4" marker-end="url(#arrR)"/>
114
+ <text x="892" y="392" font-size="11" fill="#ea4b71" text-anchor="middle" transform="rotate(-2 892 392)">chiama gli</text>
115
+ <text x="900" y="406" font-size="11" fill="#ea4b71" text-anchor="middle">script specialists</text>
116
+
117
+ <!-- LEGEND -->
118
+ <rect x="40" y="632" width="978" height="118" rx="12" fill="#fafafa" stroke="#dadce0"/>
119
+ <text x="58" y="656" font-size="14.5" font-weight="700" fill="#202124">Scelta dello store per livello</text>
120
+
121
+ <rect x="58" y="668" width="16" height="16" rx="3" fill="#fff7ed" stroke="#f59e0b"/>
122
+ <text x="82" y="681" font-size="13" fill="#202124"><tspan font-weight="700">SQLite + daemon</tspan> → Solo, una macchina (è il design di substrate · zero-ops)</text>
123
+
124
+ <rect x="58" y="692" width="16" height="16" rx="3" fill="#e0f2fe" stroke="#0284c7"/>
125
+ <text x="82" y="705" font-size="13" fill="#202124"><tspan font-weight="700">libSQL / Turso</tspan> → Solo, più macchine (SQLite condiviso/leggero · quasi drop-in · niente auth/web)</text>
126
+
127
+ <rect x="58" y="716" width="16" height="16" rx="3" fill="#d1fae5" stroke="#10b981"/>
128
+ <text x="82" y="729" font-size="13" fill="#202124"><tspan font-weight="700">Supabase (Postgres)</tspan> → Team · Azienda (auth + realtime + API per la console web)</text>
129
+
130
+ <rect x="560" y="716" width="16" height="16" rx="3" fill="#f3e8ff" stroke="#9333ea"/>
131
+ <text x="584" y="729" font-size="13" fill="#202124"><tspan font-weight="700">Dolt</tspan> → solo se vuoi versioning dei dati (branch/merge) — non ora</text>
132
+ </svg>
package/docs/devops/dependency-verdict-materialization.md ADDED
@@ -0,0 +1,46 @@
1
+ # Dependency verdict materialization
2
+
3
+ `node scripts/materialize-dependency-verdict.mjs --input <verdict.json>` converts a dependency verdict JSON into a substrate issue plan.
4
+
5
+ ## Defaults
6
+
7
+ - Dry-run is the default.
8
+ - `--apply` is required before any `bd` issue is created.
9
+ - Input must include a verdict, a source dependency-update bead id, and `case_json_path` evidence.
10
+
11
+ ## Mapping
12
+
13
+ | Verdict | Materialized class | Issue type | Priority | Linking |
14
+ |---|---|---:|---:|---|
15
+ | `PASS_WITH_NOTES` | `class:advisor` | `decision` | P3 | `discovered-from:<source>` |
16
+ | `COOLDOWN` | `class:followup` | `task` | P3 | `discovered-from:<source>` |
17
+ | `NEEDS_CHANGES` | `class:followup` | `task` | P2 | `discovered-from:<source>` |
18
+ | `BLOCKED` | `class:gate` | `task` | P1 | `discovered-from:<source>` plus `gate --blocks <source>` |
19
+ | `SECURITY_FORCED` | `class:gate` | `task` | P0 | `discovered-from:<source>` plus `gate --blocks <source>` |
20
+
21
+ ## Edge conventions
22
+
23
+ - Follow-ups use `discovered-from`, never `blocks`.
24
+ - Validation issues use `validates` when the verdict JSON supplies `validation_issue_ids`.
25
+ - Gate issues are the only materialized issues that add a blocking edge back to the source dependency-update bead.
26
+ - Advisor issues are non-blocking provenance artifacts; they still keep `discovered-from` so the dependency update remains the source context.
27
+
28
+ ## Evidence refs
29
+
30
+ The materialized description always includes:
31
+
32
+ - `case_json_path`
33
+ - `upgrade_dossier_ref` when present
34
+ - `pr_comment_ref` when present
35
+ - `external_ref` when present
36
+
37
+ ## Example
38
+
39
+ ```bash
40
+ node scripts/materialize-dependency-verdict.mjs \
41
+ --input /tmp/dependency-verdict.json
42
+
43
+ node scripts/materialize-dependency-verdict.mjs \
44
+ --input /tmp/dependency-verdict.json \
45
+ --apply
46
+ ```
package/docs/epic-readiness.md ADDED
@@ -0,0 +1,75 @@
1
+ ---
2
+ version: 2
3
+ updated: 2026-04-29
4
+ synced_at: 4395795d
5
+ ---
6
+
7
+ # Epic readiness evaluation
8
+
9
+ This document defines the canonical readiness evaluator used by:
10
+
11
+ - `sp epic status`
12
+ - `sp epic merge`
13
+ - `sp ps` (epic readiness projection)
14
+ - supervisor SQLite lifecycle synchronization/recovery paths
15
+
16
+ ## Inputs
17
+
18
+ Readiness is computed from persisted SQLite state for one epic:
19
+
20
+ - `specialist_jobs` rows tagged with `epic_id`
21
+ - `epic_chain_membership` rows (`chain_id`, optional `chain_root_bead_id`)
22
+ - `specialist_results` reviewer outputs (for PASS/PARTIAL/FAIL extraction)
23
+ - current persisted epic lifecycle state (`epic_runs.status`)
24
+
25
+ ## Chain semantics
26
+
27
+ For each chain:
28
+
29
+ - `failed` (dead-active): active jobs (`starting|running|waiting`) whose PIDs are no longer alive — evaluator detects zombie processes and immediately returns `failed` with `missing` verdict
30
+ - `pending`: chain has active jobs (`starting|running|waiting`) with live PIDs
31
+ - `blocked`:
32
+ - no persisted chain jobs (migration/orphan case), or
33
+ - no terminal reviewer verdict found, or
34
+ - fix-loop jobs completed after a non-PASS reviewer verdict but reviewer has not rerun
35
+ - `failed`: latest terminal reviewer verdict is `PARTIAL` or `FAIL` with no follow-up fix-loop progress
36
+ - `pass`: latest terminal reviewer verdict is `PASS`
37
+
38
+ Reviewer verdict detection is extracted from result text via `Verdict: PASS|PARTIAL|FAIL`.
39
+
40
+ ## Prep semantics
41
+
42
+ Prep jobs are epic-tagged jobs with `chain_kind !== 'chain'`.
43
+
44
+ - running prep jobs block merge readiness
45
+ - errored prep jobs fail the epic readiness state
46
+ - done prep jobs satisfy prep completion
47
+
48
+ ## Epic readiness states
49
+
50
+ Evaluator emits one machine-readable state:
51
+
52
+ - `unresolved` — open epic with active work still running
53
+ - `resolving` — resolving epic with active work or unresolved blockers
54
+ - `merge_ready` — prep terminal + every chain PASS (or prep-only epic with terminal prep)
55
+ - `blocked` — non-terminal but blocked on missing reviewer/fix-loop closure
56
+ - `failed` — prep error or failed chain review outcome
57
+ - `merged` / `abandoned` — terminal lifecycle passthrough
58
+
59
+ ## Lifecycle synchronization
60
+
61
+ Evaluator also computes `next_state` and transition intent:
62
+
63
+ - `open -> resolving` when unresolved work exists
64
+ - `resolving -> merge_ready` when all readiness conditions are met
65
+ - `merge_ready -> resolving` if blockers reappear
66
+ - `resolving|merge_ready -> failed` on fatal prep/chain failure
67
+
68
+ These transitions are persisted automatically whenever epic readiness is synchronized.
69
+
70
+ ## Edge cases
71
+
72
+ - **Prep-only epic**: no chains and all prep terminal => `merge_ready`
73
+ - **Standalone chain (non-epic)**: excluded; readiness evaluator runs only for jobs with `epic_id`
74
+ - **Missing reviewer verdict**: chain remains `blocked`, epic cannot become `merge_ready`
75
+ - **Migration rows with membership but missing chain jobs**: chain is `blocked` with explicit reason
package/docs/examples/mercury-atomic-summarizer.specialist.json ADDED
@@ -0,0 +1,26 @@
1
+ {
2
+ "specialist": {
3
+ "metadata": {
4
+ "name": "mercury-atomic-summarizer",
5
+ "version": "1.0.0",
6
+ "description": "Summarizes one news article into one structured row. Reference port of the legacy darth-feedor YAML — see docs/darth-feedor-migration.md for migration context.",
7
+ "category": "synthesis"
8
+ },
9
+ "execution": {
10
+ "mode": "auto",
11
+ "model": "anthropic/claude-haiku-4-5",
12
+ "fallback_model": "openai-codex/gpt-5.4-mini",
13
+ "timeout_ms": 60000,
14
+ "interactive": false,
15
+ "response_format": "json",
16
+ "output_type": "synthesis",
17
+ "permission_required": "READ_ONLY",
18
+ "requires_worktree": false,
19
+ "max_retries": 0
20
+ },
21
+ "prompt": {
22
+ "task_template": "Summarize the article below into JSON of shape {\"summary\": \"...\", \"controlled_tags\": [...]}.\n\nTitle: $title\n\nContent:\n$content",
23
+ "output_schema": { "required": ["summary", "controlled_tags"] }
24
+ }
25
+ }
26
+ }