@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/archive/iron-review-hardening.html ADDED
@@ -0,0 +1,1004 @@
1
+ <!DOCTYPE html>
2
+ <html lang="en">
3
+ <head>
4
+ <meta charset="UTF-8">
5
+ <title>Iron Review Hardening — Specialists Pipeline Redesign</title>
6
+ <style>
7
+ :root {
8
+ --bg: #0d1117;
9
+ --bg-elev: #161b22;
10
+ --bg-card: #1c232e;
11
+ --border: #30363d;
12
+ --fg: #e6edf3;
13
+ --fg-dim: #9da7b1;
14
+ --fg-mute: #6e7681;
15
+ --accent: #58a6ff;
16
+ --accent-2: #f0883e;
17
+ --green: #3fb950;
18
+ --red: #f85149;
19
+ --yellow: #d29922;
20
+ --purple: #bc8cff;
21
+ --mono: 'JetBrains Mono', 'Fira Code', ui-monospace, 'SF Mono', Menlo, monospace;
22
+ --sans: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
23
+ }
24
+ * { box-sizing: border-box; }
25
+ body { margin: 0; background: var(--bg); color: var(--fg); font-family: var(--sans); line-height: 1.6; font-size: 15px; }
26
+ .wrap { max-width: 1200px; margin: 0 auto; padding: 60px 40px; }
27
+ header.hero { border-bottom: 1px solid var(--border); padding-bottom: 40px; margin-bottom: 60px; }
28
+ .kicker { text-transform: uppercase; letter-spacing: 2px; font-size: 11px; color: var(--accent); font-weight: 600; margin-bottom: 12px; }
29
+ h1 {
30
+ font-size: 42px; margin: 0 0 16px; font-weight: 700; letter-spacing: -0.5px;
31
+ background: linear-gradient(135deg, var(--fg) 0%, var(--accent) 100%);
32
+ -webkit-background-clip: text; -webkit-text-fill-color: transparent; background-clip: text;
33
+ }
34
+ .lede { font-size: 19px; color: var(--fg-dim); max-width: 800px; margin: 0; }
35
+ .meta { display: flex; gap: 24px; margin-top: 24px; font-family: var(--mono); font-size: 12px; color: var(--fg-mute); flex-wrap: wrap; }
36
+ .meta span strong { color: var(--fg); }
37
+ h2 { font-size: 28px; margin: 80px 0 24px; font-weight: 700; letter-spacing: -0.3px; border-bottom: 1px solid var(--border); padding-bottom: 12px; }
38
+ h2::before { content: '§ '; color: var(--accent); font-weight: 400; }
39
+ h3 { font-size: 20px; margin: 40px 0 16px; color: var(--fg); }
40
+ p { color: var(--fg-dim); }
41
+ p strong, li strong { color: var(--fg); }
42
+ code { font-family: var(--mono); background: var(--bg-elev); padding: 2px 6px; border-radius: 4px; font-size: 13px; color: var(--accent-2); }
43
+ pre { background: var(--bg-elev); border: 1px solid var(--border); border-radius: 8px; padding: 20px; overflow-x: auto; font-family: var(--mono); font-size: 13px; line-height: 1.5; }
44
+ pre code { background: none; padding: 0; color: var(--fg); }
45
+ .grid { display: grid; gap: 20px; }
46
+ .grid-2 { grid-template-columns: 1fr 1fr; }
47
+ @media (max-width: 900px) { .grid-2 { grid-template-columns: 1fr; } }
48
+ .card { background: var(--bg-card); border: 1px solid var(--border); border-radius: 12px; padding: 24px; }
49
+ .card-title { font-weight: 600; font-size: 16px; margin: 0 0 8px; color: var(--fg); }
50
+ .card-desc { color: var(--fg-dim); font-size: 14px; margin: 0; }
51
+ table { width: 100%; border-collapse: collapse; margin: 20px 0; font-size: 14px; }
52
+ th, td { text-align: left; padding: 12px 16px; border-bottom: 1px solid var(--border); }
53
+ th { background: var(--bg-elev); font-weight: 600; color: var(--fg); font-size: 12px; text-transform: uppercase; letter-spacing: 0.5px; }
54
+ td { color: var(--fg-dim); }
55
+ td code { font-size: 12px; }
56
+ tr:hover td { background: rgba(88, 166, 255, 0.04); }
57
+ .badge { display: inline-block; padding: 3px 10px; border-radius: 12px; font-size: 11px; font-weight: 600; font-family: var(--mono); text-transform: uppercase; letter-spacing: 0.5px; }
58
+ .badge-low { background: rgba(63,185,80,.15); color: var(--green); border:1px solid rgba(63,185,80,.3); }
59
+ .badge-medium { background: rgba(210,153,34,.15); color: var(--yellow); border:1px solid rgba(210,153,34,.3); }
60
+ .badge-high { background: rgba(240,136,62,.15); color: var(--accent-2); border:1px solid rgba(240,136,62,.3); }
61
+ .badge-crit { background: rgba(248,81,73,.15); color: var(--red); border:1px solid rgba(248,81,73,.3); }
62
+ .badge-new { background: rgba(188,140,255,.15);color: var(--purple); border:1px solid rgba(188,140,255,.3); }
63
+ .badge-edit { background: rgba(88,166,255,.15); color: var(--accent); border:1px solid rgba(88,166,255,.3); }
64
+ .pipeline { background: var(--bg-elev); border: 1px solid var(--border); border-radius: 12px; padding: 32px; margin: 24px 0; overflow-x: auto; }
65
+ .pipeline svg { display: block; margin: 0 auto; }
66
+ .scrutiny-stack { display: flex; flex-direction: column; gap: 4px; margin: 24px 0; }
67
+ .scrutiny-row { display: grid; grid-template-columns: 120px 1fr; align-items: stretch; gap: 12px; }
68
+ .scrutiny-label { display: flex; align-items: center; justify-content: center; font-family: var(--mono); font-weight: 700; font-size: 13px; border-radius: 8px; text-transform: uppercase; letter-spacing: 1px; }
69
+ .scrutiny-bar { padding: 14px 20px; border-radius: 8px; font-size: 13px; line-height: 1.5; }
70
+ .row-low .scrutiny-label, .row-low .scrutiny-bar { background: rgba(63,185,80,.10); border: 1px solid rgba(63,185,80,.3); }
71
+ .row-low .scrutiny-label { color: var(--green); }
72
+ .row-med .scrutiny-label, .row-med .scrutiny-bar { background: rgba(210,153,34,.10); border: 1px solid rgba(210,153,34,.3); }
73
+ .row-med .scrutiny-label { color: var(--yellow); }
74
+ .row-high .scrutiny-label, .row-high .scrutiny-bar { background: rgba(240,136,62,.10); border: 1px solid rgba(240,136,62,.3); }
75
+ .row-high .scrutiny-label { color: var(--accent-2); }
76
+ .row-crit .scrutiny-label, .row-crit .scrutiny-bar { background: rgba(248,81,73,.10); border: 1px solid rgba(248,81,73,.3); }
77
+ .row-crit .scrutiny-label { color: var(--red); }
78
+ .waves { display: grid; grid-template-columns: 80px 1fr; gap: 16px; margin: 24px 0; }
79
+ .wave-label { display: flex; align-items: center; justify-content: center; font-family: var(--mono); font-weight: 700; background: var(--bg-elev); border: 1px solid var(--border); border-radius: 8px; color: var(--accent); }
80
+ .wave-content { display: flex; gap: 12px; flex-wrap: wrap; }
81
+ .chain-pill { background: var(--bg-card); border: 1px solid var(--border); border-radius: 8px; padding: 12px 16px; flex: 1; min-width: 220px; }
82
+ .chain-pill .chain-id { font-family: var(--mono); color: var(--purple); font-weight: 600; font-size: 12px; }
83
+ .chain-pill .chain-title { font-size: 13px; color: var(--fg); margin: 4px 0; }
84
+ .chain-pill .chain-file { font-family: var(--mono); font-size: 11px; color: var(--fg-mute); }
85
+ .callout { border-left: 3px solid var(--accent); background: rgba(88,166,255,.05); padding: 16px 20px; margin: 20px 0; border-radius: 0 8px 8px 0; }
86
+ .callout-good { border-color: var(--green); background: rgba(63,185,80,.05); }
87
+ ul, ol { color: var(--fg-dim); padding-left: 20px; }
88
+ li { margin: 6px 0; }
89
+ li code { font-size: 12px; }
90
+ .diff-block { background: var(--bg-elev); border: 1px solid var(--border); border-radius: 8px; overflow: hidden; margin: 16px 0; }
91
+ .diff-header { background: var(--bg-card); padding: 10px 16px; font-family: var(--mono); font-size: 12px; color: var(--fg); border-bottom: 1px solid var(--border); }
92
+ .diff-body { padding: 16px 20px; font-family: var(--mono); font-size: 12px; line-height: 1.6; white-space: pre; overflow-x: auto; }
93
+ .diff-add { color: var(--green); }
94
+ .diff-ctx { color: var(--fg-mute); }
95
+ footer { margin-top: 80px; padding-top: 24px; border-top: 1px solid var(--border); color: var(--fg-mute); font-size: 13px; text-align: center; }
96
+ </style>
97
+ </head>
98
+ <body>
99
+ <div class="wrap">
100
+
101
+ <div style="background:#7A1F1B;color:#F5F2E9;padding:18px 28px;margin:-1px -1px 32px;border-radius:0;font-family:'JetBrains Mono','SF Mono',monospace;font-size:13px;line-height:1.6">
102
+ <strong style="font-size:11px;letter-spacing:0.15em;text-transform:uppercase">⚠ Archived — superseded 2026-05-30</strong><br>
103
+ This document is preserved for historical reference. Its content has been absorbed into the canonical chain-templates design as <strong>§3.1 Iron overlay</strong>. For current Iron pipeline framing, scrutiny taxonomy, auto-escalation rules, and per-template applicability, consult:
104
+ <ul style="margin:10px 0 0 18px;padding:0">
105
+ <li><a href="../design/chain-templates.html" style="color:#F5F2E9;border-bottom:1px solid #F5F2E9">docs/design/chain-templates.html</a> — editorial canon</li>
106
+ <li><a href="../design/chain-templates.md" style="color:#F5F2E9;border-bottom:1px solid #F5F2E9">docs/design/chain-templates.md</a> §3.1 — referential canon</li>
107
+ </ul>
108
+ </div>
109
+
110
+ <header class="hero">
111
+ <div class="kicker">Specialists Epic Proposal · iron-review-hardening · ARCHIVED</div>
112
+ <h1>Iron-Inspired Review Pipeline Hardening</h1>
113
+ <p class="lede">
114
+ Adopt Jane Street's <strong>Iron</strong> code review concepts — scrutiny profiles,
115
+ ddiff re-reviews, mandatory seconders, obligations tracking, formal release
116
+ gates — into the specialists pipeline. Six tightly-scoped child chains
117
+ delivered in three waves. Pipeline becomes risk-aware instead of
118
+ one-size-fits-all.
119
+ </p>
120
+ <div class="meta">
121
+ <span><strong>Epic</strong> iron-review-hardening</span>
122
+ <span><strong>Priority</strong> P1</span>
123
+ <span><strong>Targets</strong> reviewer · code-sanity · executor · debugger · NEW obligations-scanner · skill + CLAUDE.md</span>
124
+ <span><strong>Execution</strong> manual orchestrator (no dispatch)</span>
125
+ </div>
126
+ <div class="callout callout-warn" style="margin-top:32px">
127
+ <strong>Execution mode for this epic: manual orchestrator-direct edits.</strong>
128
+ Explicit exception to skill rule #13 ("orchestrator NEVER edits code directly").
129
+ Rationale: the epic restructures the very specialists used for normal
130
+ dispatch, so bootstrapping via those specialists is circular. All other
131
+ epics continue to use the dispatch model.
132
+ </div>
133
+ </header>
134
+
135
+ <h2>Why this exists</h2>
136
+ <p>
137
+ Our current pipeline applies the same review depth to a 2-line test tweak and
138
+ a payment-flow rewrite. <code>code-sanity</code> is advisory and frequently
139
+ skipped. After a <code>PARTIAL</code> verdict, reviewers re-audit the entire
140
+ diff instead of just the delta. In-code obligations
141
+ (<code>TODO</code>/<code>HACK</code>/<code>FIXME</code>) land in production
142
+ without a gate. Files like <code>src/specialist/runner.ts</code> or
143
+ <code>config/specialists/*.json</code> inherit whatever scrutiny the bead author
144
+ requested — not what the <em>content</em> demands.
145
+ </p>
146
+ <p>
147
+ Iron solved exactly this set of problems with a small set of orthogonal
148
+ primitives. We adopt the concepts directly. We do not import any Iron code;
149
+ we restructure prompts, add one cheap specialist, and rewrite the pipeline
150
+ skill.
151
+ </p>
152
+
153
+ <h2>Old vs. New pipeline</h2>
154
+
155
+ <div class="pipeline">
156
+ <svg viewBox="0 0 1100 360" width="100%" style="max-width:1100px">
157
+ <defs>
158
+ <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="6" markerHeight="6" orient="auto">
159
+ <path d="M0,0 L10,5 L0,10 z" fill="#6e7681"/>
160
+ </marker>
161
+ <marker id="arrowAccent" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="6" markerHeight="6" orient="auto">
162
+ <path d="M0,0 L10,5 L0,10 z" fill="#58a6ff"/>
163
+ </marker>
164
+ </defs>
165
+
166
+ <text x="20" y="30" fill="#9da7b1" font-family="JetBrains Mono, monospace" font-size="13" font-weight="700">OLD — uniform depth, advisory gates</text>
167
+
168
+ <g font-family="Inter, sans-serif" font-size="13" fill="#e6edf3" font-weight="600">
169
+ <rect x="20" y="60" width="120" height="48" rx="8" fill="#1c232e" stroke="#30363d"/>
170
+ <text x="80" y="89" text-anchor="middle">executor</text>
171
+
172
+ <rect x="180" y="60" width="120" height="48" rx="8" fill="#1c232e" stroke="#30363d" stroke-dasharray="4,3"/>
173
+ <text x="240" y="83" text-anchor="middle" font-size="12">code-sanity</text>
174
+ <text x="240" y="100" text-anchor="middle" font-size="10" fill="#9da7b1">(if smell)</text>
175
+
176
+ <rect x="340" y="60" width="140" height="48" rx="8" fill="#1c232e" stroke="#30363d" stroke-dasharray="4,3"/>
177
+ <text x="410" y="83" text-anchor="middle" font-size="12">security-auditor</text>
178
+ <text x="410" y="100" text-anchor="middle" font-size="10" fill="#9da7b1">(if surface)</text>
179
+
180
+ <rect x="520" y="60" width="120" height="48" rx="8" fill="#1c232e" stroke="#30363d"/>
181
+ <text x="580" y="89" text-anchor="middle">reviewer</text>
182
+
183
+ <rect x="680" y="60" width="100" height="48" rx="8" fill="#1c232e" stroke="#30363d"/>
184
+ <text x="730" y="89" text-anchor="middle">sp merge</text>
185
+ </g>
186
+
187
+ <g stroke="#6e7681" stroke-width="2" fill="none" marker-end="url(#arrow)">
188
+ <line x1="140" y1="84" x2="180" y2="84"/>
189
+ <line x1="300" y1="84" x2="340" y2="84"/>
190
+ <line x1="480" y1="84" x2="520" y2="84"/>
191
+ <line x1="640" y1="84" x2="680" y2="84"/>
192
+ </g>
193
+
194
+ <path d="M 580 108 Q 580 150 80 150 Q 80 108 80 108" stroke="#f85149" stroke-width="1.5" fill="none" stroke-dasharray="3,3" marker-end="url(#arrow)"/>
195
+ <text x="330" y="145" fill="#f85149" font-family="JetBrains Mono, monospace" font-size="11">PARTIAL → full re-audit on resume</text>
196
+
197
+ <text x="20" y="200" fill="#58a6ff" font-family="JetBrains Mono, monospace" font-size="13" font-weight="700">NEW — scrutiny-aware, mandatory seconder + obligations gate</text>
198
+
199
+ <g font-family="Inter, sans-serif" font-size="13" fill="#e6edf3" font-weight="600">
200
+ <rect x="20" y="230" width="100" height="48" rx="8" fill="#1c232e" stroke="#58a6ff"/>
201
+ <text x="70" y="259" text-anchor="middle">executor</text>
202
+
203
+ <rect x="150" y="230" width="120" height="48" rx="8" fill="#1c232e" stroke="#58a6ff"/>
204
+ <text x="210" y="253" text-anchor="middle" font-size="12">code-sanity</text>
205
+ <text x="210" y="270" text-anchor="middle" font-size="10" fill="#bc8cff">SECONDER · mandatory</text>
206
+
207
+ <rect x="300" y="230" width="140" height="48" rx="8" fill="#1c232e" stroke="#30363d" stroke-dasharray="4,3"/>
208
+ <text x="370" y="253" text-anchor="middle" font-size="12">security-auditor</text>
209
+ <text x="370" y="270" text-anchor="middle" font-size="10" fill="#9da7b1">(if surface)</text>
210
+
211
+ <rect x="470" y="230" width="160" height="48" rx="8" fill="#1c232e" stroke="#bc8cff"/>
212
+ <text x="550" y="253" text-anchor="middle" font-size="12">obligations-scanner</text>
213
+ <text x="550" y="270" text-anchor="middle" font-size="10" fill="#bc8cff">NEW · mandatory</text>
214
+
215
+ <rect x="660" y="230" width="160" height="48" rx="8" fill="#1c232e" stroke="#58a6ff"/>
216
+ <text x="740" y="253" text-anchor="middle" font-size="12">reviewer</text>
217
+ <text x="740" y="270" text-anchor="middle" font-size="10" fill="#58a6ff">scrutiny-aware · ddiff</text>
218
+
219
+ <rect x="850" y="230" width="120" height="48" rx="8" fill="#1c232e" stroke="#58a6ff"/>
220
+ <text x="910" y="253" text-anchor="middle" font-size="12">sp merge</text>
221
+ <text x="910" y="270" text-anchor="middle" font-size="10" fill="#58a6ff">+ Release Checklist</text>
222
+ </g>
223
+
224
+ <g stroke="#58a6ff" stroke-width="2" fill="none" marker-end="url(#arrowAccent)">
225
+ <line x1="120" y1="254" x2="150" y2="254"/>
226
+ <line x1="270" y1="254" x2="300" y2="254"/>
227
+ <line x1="440" y1="254" x2="470" y2="254"/>
228
+ <line x1="630" y1="254" x2="660" y2="254"/>
229
+ <line x1="820" y1="254" x2="850" y2="254"/>
230
+ </g>
231
+
232
+ <path d="M 740 278 Q 740 330 70 330 Q 70 278 70 278" stroke="#3fb950" stroke-width="1.5" fill="none" stroke-dasharray="3,3" marker-end="url(#arrowAccent)"/>
233
+ <text x="350" y="325" fill="#3fb950" font-family="JetBrains Mono, monospace" font-size="11">PARTIAL → ddiff-only re-review (prior approvals carry)</text>
234
+ </svg>
235
+ </div>
236
+
237
+ <div class="callout">
238
+ <strong>What changed structurally:</strong> two boxes got a solid border
239
+ (mandatory, not advisory). One box was added (obligations-scanner). The
240
+ PARTIAL loop went from dashed-red (re-audit everything) to dashed-green
241
+ (ddiff scope only). Reviewer became risk-aware and emits a machine-readable
242
+ Release Checklist that future <code>sp merge</code> can enforce.
243
+ </div>
244
+
245
+ <h2>SCRUTINY taxonomy</h2>
246
+ <p>
247
+ A first-class bead-contract field. Reviewer reads it and tiers its behavior.
248
+ Beads without the field default to <code>medium</code> (backwards compatible).
249
+ Reviewer can <strong>auto-escalate</strong> the floor based on the diff
250
+ surface — author's stated level is a floor, not a ceiling.
251
+ </p>
252
+
253
+ <div class="scrutiny-stack">
254
+ <div class="scrutiny-row row-low">
255
+ <div class="scrutiny-label">low</div>
256
+ <div class="scrutiny-bar">
257
+ <strong>Seconder-only.</strong> code-sanity OK is sufficient. Reviewer
258
+ checks contract compliance + spot-checks 2–3 files. No blast-radius
259
+ requirement. → Test-only diffs · docs · isolated config tweaks.
260
+ </div>
261
+ </div>
262
+ <div class="scrutiny-row row-med">
263
+ <div class="scrutiny-label">medium</div>
264
+ <div class="scrutiny-bar">
265
+ <strong>Default.</strong> Current reviewer behavior. code-sanity required.
266
+ security-auditor required if sensitive surface. → Most production diffs.
267
+ </div>
268
+ </div>
269
+ <div class="scrutiny-row row-high">
270
+ <div class="scrutiny-label">high</div>
271
+ <div class="scrutiny-bar">
272
+ <strong>File-by-file sign-off.</strong> Mandatory <code>gitnexus_impact</code>
273
+ evidence. code-sanity + security-auditor both required. Ddiff re-review
274
+ enforced. → Auth · payments · schema · migrations · agent core.
275
+ </div>
276
+ </div>
277
+ <div class="scrutiny-row row-crit">
278
+ <div class="scrutiny-label">critical</div>
279
+ <div class="scrutiny-bar">
280
+ <strong>High + second opinion.</strong> Mandatory obligations-scanner +
281
+ at least one independent reviewer turn (or overthinker premortem). →
282
+ Credential storage · model routing · specialist permission boundaries.
283
+ </div>
284
+ </div>
285
+ </div>
286
+
287
+ <h3>Auto-escalation surfaces</h3>
288
+ <p>The reviewer raises the floor regardless of the bead's stated level when the
289
+ diff touches:</p>
290
+
291
+ <table>
292
+ <thead>
293
+ <tr><th>Surface pattern</th><th>Floor</th><th>Additional gates</th></tr>
294
+ </thead>
295
+ <tbody>
296
+ <tr><td><code>auth/*</code> · <code>**/credentials*</code> · <code>**/token*</code></td><td><span class="badge badge-high">high</span></td><td>security-auditor required</td></tr>
297
+ <tr><td><code>config/specialists/*.json</code> · <code>.specialists/user/*</code></td><td><span class="badge badge-high">high</span></td><td>schema validation evidence</td></tr>
298
+ <tr><td><code>src/specialist/runner.ts</code> · <code>src/specialist/schema.ts</code></td><td><span class="badge badge-high">high</span></td><td>gitnexus_impact required</td></tr>
299
+ <tr><td><code>**/*.lock</code> · <code>package-lock.json</code> · <code>yarn.lock</code></td><td><span class="badge badge-medium">medium</span></td><td>security-auditor required</td></tr>
300
+ <tr><td><code>migrations/**</code> · <code>**/schema.sql</code> · <code>**/schema.prisma</code></td><td><span class="badge badge-high">high</span></td><td>backwards-compat note</td></tr>
301
+ <tr><td><code>src/permissions/*</code> · <code>hooks/**</code></td><td><span class="badge badge-crit">critical</span></td><td>full critical pipeline</td></tr>
302
+ </tbody>
303
+ </table>
304
+
305
+ <h2>Iron concept → our adoption</h2>
306
+
307
+ <table>
308
+ <thead>
309
+ <tr>
310
+ <th style="width:25%">Iron primitive</th>
311
+ <th style="width:35%">What it does</th>
312
+ <th style="width:40%">Our adoption (this epic)</th>
313
+ </tr>
314
+ </thead>
315
+ <tbody>
316
+ <tr><td><strong>Scrutiny profiles</strong></td><td>Named intensity levels per file/area; required reviewer count and depth differ.</td><td><code>SCRUTINY: low|medium|high|critical</code> bead field → reviewer behavior tiers.</td></tr>
317
+ <tr><td><strong>Seconder role</strong></td><td>Mandatory style/sanity reviewer, distinct from file reviewer.</td><td><code>code-sanity</code> promoted from advisory to mandatory gate for production diffs.</td></tr>
318
+ <tr><td><strong>Ddiff (diff-of-diffs)</strong></td><td>Re-review sees only delta since prior verdict; prior approvals carry forward.</td><td>Reviewer prompt adds "Ddiff mode" for PARTIAL re-reviews; cites prior findings only.</td></tr>
319
+ <tr><td><strong>Semantic approval continuity</strong></td><td>Reviewer's prior sign-off survives rebase/conflict resolution.</td><td>Ddiff mode explicitly instructs: "do NOT re-audit code paths previously marked met".</td></tr>
320
+ <tr><td><strong>Obligations tracking</strong></td><td>In-source markers block release until cleared or explicitly accepted.</td><td>NEW <code>obligations-scanner</code> specialist; reviewer enforces unless bead NON_GOALS accepts.</td></tr>
321
+ <tr><td><strong>Dynamic scrutiny escalation</strong></td><td>If file's scrutiny rises, prior approvals must be re-evaluated at higher bar.</td><td>Reviewer's auto-escalation pattern table raises floor regardless of bead's stated level.</td></tr>
322
+ <tr><td><strong>Releasability criteria</strong></td><td>Releasable = base correct + review complete + no obligations + scrutiny met.</td><td>Reviewer emits machine-readable <strong>Release Checklist</strong> in every verdict.</td></tr>
323
+ <tr><td><strong>Feature hierarchy ddiffs</strong></td><td>Dependent features show only their incremental contribution to reviewer.</td><td><em>Deferred.</em> <code>sp epic merge</code> already linearizes; future epic if needed.</td></tr>
324
+ </tbody>
325
+ </table>
326
+
327
+ <h2>Epic structure</h2>
328
+
329
+ <svg viewBox="0 0 1100 380" width="100%" style="max-width:1100px; margin:24px 0;">
330
+ <defs>
331
+ <marker id="arrowDep" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="6" markerHeight="6" orient="auto">
332
+ <path d="M0,0 L10,5 L0,10 z" fill="#58a6ff"/>
333
+ </marker>
334
+ </defs>
335
+
336
+ <rect x="430" y="20" width="240" height="58" rx="10" fill="#1c232e" stroke="#bc8cff" stroke-width="2"/>
337
+ <text x="550" y="45" text-anchor="middle" font-family="JetBrains Mono, monospace" font-size="12" fill="#bc8cff" font-weight="700">EPIC</text>
338
+ <text x="550" y="65" text-anchor="middle" font-family="Inter, sans-serif" font-size="13" fill="#e6edf3">iron-review-hardening</text>
339
+
340
+ <g font-family="Inter, sans-serif">
341
+ <rect x="20" y="150" width="255" height="80" rx="10" fill="#1c232e" stroke="#58a6ff"/>
342
+ <text x="147" y="172" text-anchor="middle" font-family="JetBrains Mono, monospace" font-size="11" fill="#58a6ff" font-weight="700">child.1 · WAVE A</text>
343
+ <text x="147" y="193" text-anchor="middle" font-size="13" fill="#e6edf3" font-weight="600">Reviewer prompt overhaul</text>
344
+ <text x="147" y="212" text-anchor="middle" font-size="11" fill="#9da7b1">SCRUTINY · ddiff · obligations · checklist</text>
345
+
346
+ <rect x="290" y="150" width="255" height="80" rx="10" fill="#1c232e" stroke="#58a6ff"/>
347
+ <text x="417" y="172" text-anchor="middle" font-family="JetBrains Mono, monospace" font-size="11" fill="#58a6ff" font-weight="700">child.2 · WAVE A</text>
348
+ <text x="417" y="193" text-anchor="middle" font-size="13" fill="#e6edf3" font-weight="600">code-sanity → seconder gate</text>
349
+ <text x="417" y="212" text-anchor="middle" font-size="11" fill="#9da7b1">advisory → mandatory</text>
350
+
351
+ <rect x="560" y="150" width="255" height="80" rx="10" fill="#1c232e" stroke="#bc8cff"/>
352
+ <text x="687" y="172" text-anchor="middle" font-family="JetBrains Mono, monospace" font-size="11" fill="#bc8cff" font-weight="700">child.3 · WAVE A · NEW</text>
353
+ <text x="687" y="193" text-anchor="middle" font-size="13" fill="#e6edf3" font-weight="600">obligations-scanner specialist</text>
354
+ <text x="687" y="212" text-anchor="middle" font-size="11" fill="#9da7b1">cheap READ_ONLY marker scan</text>
355
+
356
+ <rect x="830" y="150" width="255" height="80" rx="10" fill="#1c232e" stroke="#58a6ff"/>
357
+ <text x="957" y="172" text-anchor="middle" font-family="JetBrains Mono, monospace" font-size="11" fill="#58a6ff" font-weight="700">child.6 · WAVE A</text>
358
+ <text x="957" y="193" text-anchor="middle" font-size="13" fill="#e6edf3" font-weight="600">executor + debugger obligations</text>
359
+ <text x="957" y="212" text-anchor="middle" font-size="11" fill="#9da7b1">codegen discipline · marker format</text>
360
+ </g>
361
+
362
+ <rect x="290" y="270" width="525" height="58" rx="10" fill="#1c232e" stroke="#f0883e"/>
363
+ <text x="552" y="291" text-anchor="middle" font-family="JetBrains Mono, monospace" font-size="11" fill="#f0883e" font-weight="700">child.4 · WAVE B</text>
364
+ <text x="552" y="312" text-anchor="middle" font-family="Inter, sans-serif" font-size="13" fill="#e6edf3">skill update + sp merge removal + CLAUDE.md gotchas rewrite</text>
365
+
366
+ <rect x="442" y="350" width="220" height="20" rx="6" fill="#1c232e" stroke="#3fb950"/>
367
+ <text x="552" y="365" text-anchor="middle" font-family="JetBrains Mono, monospace" font-size="11" fill="#3fb950" font-weight="700">child.5 · WAVE C · smoke test</text>
368
+
369
+ <g stroke="#58a6ff" stroke-width="1.5" fill="none" marker-end="url(#arrowDep)">
370
+ <line x1="550" y1="78" x2="147" y2="150"/>
371
+ <line x1="550" y1="78" x2="417" y2="150"/>
372
+ <line x1="550" y1="78" x2="687" y2="150"/>
373
+ <line x1="550" y1="78" x2="957" y2="150"/>
374
+ </g>
375
+ <g stroke="#f0883e" stroke-width="1.5" fill="none" marker-end="url(#arrowDep)" stroke-dasharray="4,3">
376
+ <line x1="147" y1="230" x2="380" y2="270"/>
377
+ <line x1="417" y1="230" x2="500" y2="270"/>
378
+ <line x1="687" y1="230" x2="600" y2="270"/>
379
+ <line x1="957" y1="230" x2="720" y2="270"/>
380
+ </g>
381
+ <line x1="552" y1="328" x2="552" y2="350" stroke="#3fb950" stroke-width="1.5" marker-end="url(#arrowDep)" stroke-dasharray="4,3"/>
382
+ </svg>
383
+
384
+ <h3>Wave timeline</h3>
385
+
386
+ <div class="waves">
387
+ <div class="wave-label">WAVE A</div>
388
+ <div class="wave-content">
389
+ <div class="chain-pill">
390
+ <div class="chain-id">child.1 <span class="badge badge-edit">EDIT</span></div>
391
+ <div class="chain-title">Reviewer prompt overhaul</div>
392
+ <div class="chain-file">config/specialists/reviewer.specialist.json</div>
393
+ </div>
394
+ <div class="chain-pill">
395
+ <div class="chain-id">child.2 <span class="badge badge-edit">EDIT</span></div>
396
+ <div class="chain-title">code-sanity → seconder</div>
397
+ <div class="chain-file">config/specialists/code-sanity.specialist.json</div>
398
+ </div>
399
+ <div class="chain-pill">
400
+ <div class="chain-id">child.3 <span class="badge badge-new">NEW</span></div>
401
+ <div class="chain-title">obligations-scanner</div>
402
+ <div class="chain-file">config/specialists/obligations-scanner.specialist.json</div>
403
+ </div>
404
+ <div class="chain-pill">
405
+ <div class="chain-id">child.6 <span class="badge badge-edit">EDIT</span></div>
406
+ <div class="chain-title">executor + debugger obligations</div>
407
+ <div class="chain-file">config/specialists/{executor,debugger}.specialist.json</div>
408
+ </div>
409
+ </div>
410
+
411
+ <div class="wave-label">WAVE B</div>
412
+ <div class="wave-content">
413
+ <div class="chain-pill" style="flex: 1 1 100%">
414
+ <div class="chain-id">child.4 <span class="badge badge-edit">EDIT</span></div>
415
+ <div class="chain-title">Pipeline skill update — document new chain shape, SCRUTINY field, obligations integration</div>
416
+ <div class="chain-file">.claude/skills/using-specialists-v3/SKILL.md</div>
417
+ </div>
418
+ </div>
419
+
420
+ <div class="wave-label">WAVE C</div>
421
+ <div class="wave-content">
422
+ <div class="chain-pill" style="flex: 1 1 100%">
423
+ <div class="chain-id">child.5 <span class="badge badge-edit">VALIDATE</span></div>
424
+ <div class="chain-title">End-to-end smoke: SCRUTINY · ddiff · obligations</div>
425
+ <div class="chain-file">synthetic disposable beads</div>
426
+ </div>
427
+ </div>
428
+ </div>
429
+
430
+ <div class="callout callout-good">
431
+ <strong>Why Wave A can parallelize:</strong> four chains touch five distinct
432
+ specialist JSON files (reviewer, code-sanity, obligations-scanner-NEW,
433
+ executor, debugger) with zero overlap. Per the file-overlap matrix rule
434
+ (3+ chains on same file = serial), distinct-file chains are safely parallel.
435
+ Were this dispatched (it is not — see execution mode), all four could launch
436
+ in one batch.
437
+ </div>
438
+
439
+ <h2>Per-specialist change summary</h2>
440
+
441
+ <div class="grid grid-2">
442
+
443
+ <div class="card">
444
+ <div class="card-title"><span class="badge badge-edit">EDIT</span> &nbsp;reviewer</div>
445
+ <p class="card-desc">Five new system-prompt sections, additions only:</p>
446
+ <ol>
447
+ <li><strong>SCRUTINY tier behavior</strong> — reads field, applies tier</li>
448
+ <li><strong>Auto-escalation</strong> — surface-pattern table raises floor</li>
449
+ <li><strong>Ddiff mode</strong> — PARTIAL re-review scopes to delta</li>
450
+ <li><strong>Obligations scan</strong> — reads obligations-scanner output</li>
451
+ <li><strong>Release Checklist</strong> — required machine-readable block</li>
452
+ </ol>
453
+ <p class="card-desc">Model · permission · template_sets unchanged.</p>
454
+ </div>
455
+
456
+ <div class="card">
457
+ <div class="card-title"><span class="badge badge-edit">EDIT</span> &nbsp;code-sanity</div>
458
+ <p class="card-desc">Reframed as mandatory <strong>seconder gate</strong>:</p>
459
+ <ul>
460
+ <li>Description: "advisory" → "mandatory seconder, blocks reviewer dispatch"</li>
461
+ <li>Prompt: explicit pre-condition note for reviewer</li>
462
+ <li>Skip semantics: explicitly only test-only or new-file-only</li>
463
+ <li>Output schema unchanged (<code>OK | FINDINGS | BLOCKED</code>)</li>
464
+ </ul>
465
+ <p class="card-desc">Permission · model · tool ceiling unchanged.</p>
466
+ </div>
467
+
468
+ <div class="card">
469
+ <div class="card-title"><span class="badge badge-new">NEW</span> &nbsp;obligations-scanner</div>
470
+ <p class="card-desc">Cheap READ_ONLY pre-review marker scan:</p>
471
+ <ul>
472
+ <li>Model: <code>openai-codex/gpt-5.4-mini</code> · thinking: low · bare: true</li>
473
+ <li>Scans diff for <code>TODO · FIXME · HACK · XXX · TEMP · NOTE(release) · WIP</code></li>
474
+ <li>Distinguishes production vs test/fixture paths</li>
475
+ <li>JSON output: <code>{file, line, marker_type, surface}</code></li>
476
+ <li>Verdict: <code>CLEAN | OBLIGATIONS_FOUND | BLOCKED</code></li>
477
+ <li>Target wall clock: &lt;30s</li>
478
+ </ul>
479
+ </div>
480
+
481
+ <div class="card">
482
+ <div class="card-title"><span class="badge badge-edit">EDIT</span> &nbsp;executor + debugger</div>
483
+ <p class="card-desc">Obligations-aware codegen discipline:</p>
484
+ <ul>
485
+ <li>Default: do NOT introduce in-code obligation markers</li>
486
+ <li>Deferred work → file follow-up bead via <code>discovered-from</code></li>
487
+ <li>If marker required: structured format <code>// TODO(&lt;bead-id&gt;): reason</code></li>
488
+ <li>Linked bead must exist and be listed in current bead NON_GOALS</li>
489
+ <li>Test/fixture code: markers acceptable (scanner ignores)</li>
490
+ </ul>
491
+ <p class="card-desc">Prevents PARTIAL loops from obligations-scanner gate.</p>
492
+ </div>
493
+
494
+ <div class="card" style="grid-column: 1 / -1">
495
+ <div class="card-title"><span class="badge badge-edit">EDIT</span> &nbsp;using-specialists-v3 skill <span style="color:var(--fg-mute); font-weight:400">+ CLAUDE.md gotchas</span></div>
496
+ <p class="card-desc">Surgical edits, additions preserve structure. <strong>Expanded scope:</strong></p>
497
+ <div class="grid grid-2" style="margin-top:12px">
498
+ <div>
499
+ <h4>Iron concept integration</h4>
500
+ <ul>
501
+ <li>SCRUTINY field added to <strong>all</strong> bead contract templates</li>
502
+ <li>"Advisory Passes" → "Seconder Gate" + "Obligations Gate"</li>
503
+ <li>Default chain diagram updated</li>
504
+ <li>Choosing the Specialist table adds obligations-scanner row</li>
505
+ <li>Escalation Matrix: skipping code-sanity now "always escalate"</li>
506
+ <li>SCRUTINY taxonomy block added near "Writing Bead Contracts Well"</li>
507
+ <li>NEW: "Git state precondition before dispatch" section</li>
508
+ </ul>
509
+ </div>
510
+ <div>
511
+ <h4>sp merge / sp epic merge removal</h4>
512
+ <ul>
513
+ <li><strong>Remove</strong> all <code>sp merge</code> / <code>sp epic merge</code> mentions</li>
514
+ <li><strong>Promote</strong> existing Cherry-Pick Playbook to canonical merge path</li>
515
+ <li><strong>Invert</strong> Non-Negotiable Rule #9: manual git is now canonical; sp merge commands are explicitly prohibited (known broken, awaiting separate rework)</li>
516
+ <li><strong>Remove</strong> sp-merge rows from Failure Recovery + Escalation Matrix</li>
517
+ <li><strong>Update</strong> CLAUDE.md "Common gotchas" — six sp-merge bullets become wrong; rewrite to reflect manual git as canonical</li>
518
+ <li><strong>Note</strong>: stale-base guard gone; orchestrator owns rebase discipline + worktree cleanup</li>
519
+ </ul>
520
+ </div>
521
+ </div>
522
+ </div>
523
+
524
+ </div>
525
+
526
+ <h2>Reviewer prompt — new sections (illustrative)</h2>
527
+
528
+ <div class="diff-block">
529
+ <div class="diff-header">config/specialists/reviewer.specialist.json &mdash; prompt.system (excerpt)</div>
530
+ <div class="diff-body"><span class="diff-ctx"> [...existing source-of-truth priority and AUTHORITATIVE REVIEW CONTEXT...]</span>
531
+
532
+ <span class="diff-add">+ ## SCRUTINY tier behavior
533
+ +
534
+ + Read `SCRUTINY: low|medium|high|critical` from the bead contract.
535
+ + Default to `medium` if absent. Apply tier-specific depth before
536
+ + scoring requirement coverage.
537
+ +
538
+ + - low → seconder-only mode. Spot-check 2-3 files. No blast-radius required.
539
+ + - medium → current behavior. code-sanity OK pre-required.
540
+ + - high → file-by-file sign-off. gitnexus_impact mandatory. Ddiff enforced.
541
+ + - critical → high + obligations-scanner CLEAN + independent second opinion required.
542
+
543
+ + ## Scrutiny auto-escalation
544
+ +
545
+ + Before applying stated SCRUTINY, scan diff paths against floor table:
546
+ + auth|credentials|token → floor=high
547
+ + config/specialists/* → floor=high
548
+ + src/specialist/{runner,schema}.ts → floor=high
549
+ + **/*.lock → floor=medium + security-auditor
550
+ + migrations/** | schema.{sql,prisma}→ floor=high
551
+ + src/permissions/* | hooks/** → floor=critical
552
+ + Apply max(stated, floor). Log escalation reason in verdict.
553
+
554
+ + ## Re-review after PARTIAL (Ddiff mode)
555
+ +
556
+ + When this is a re-review after a prior PARTIAL verdict:
557
+ + 1. Identify which findings you flagged in your last turn.
558
+ + 2. For each finding: did the executor's new diff address it? Score only the delta.
559
+ + 3. Do NOT re-audit code paths you already marked as met.
560
+ + 4. Audit fully only symbols/files touched since your last verdict.
561
+ + 5. Carry forward prior approval for unchanged sections.
562
+
563
+ + ## Obligations scan
564
+ +
565
+ + Read obligations-scanner output if present, or scan diff for markers:
566
+ + TODO | FIXME | HACK | XXX | TEMP | NOTE(release) | WIP
567
+ + Production markers → PARTIAL with "obligation: must resolve or accept".
568
+ + Accepted only if bead NON_GOALS explicitly lists them as follow-up.
569
+ + Test/fixture markers → note but do not block.
570
+
571
+ + ## Release Checklist (REQUIRED in every verdict)
572
+ +
573
+ + - [ ] reviewer PASS: yes|no
574
+ + - [ ] obligations cleared: yes|no|N/A
575
+ + - [ ] gitnexus_detect_changes ran: yes|no
576
+ + - [ ] security-auditor ran: yes|no|not-required (reason)
577
+ + - [ ] code-sanity ran: yes|no|not-required (reason)
578
+ + - [ ] scrutiny level applied: low|medium|high|critical
579
+ + - [ ] scrutiny auto-escalated: yes (reason) | no</span>
580
+ </div>
581
+ </div>
582
+
583
+ <h2>Git state precondition before chain dispatch</h2>
584
+
585
+ <p>
586
+ New skill rule. Before dispatching any specialist chain whose work depends on
587
+ prior chain output, the orchestrator MUST verify git state is clean and the
588
+ base branch contains the prior chain's commits. This is the most common cause
589
+ of "the chain forked off the OLD baseline" debugger-restitch loops documented
590
+ in the existing skill.
591
+ </p>
592
+
593
+ <p>
594
+ Specialist worktrees fork from the current HEAD of the orchestrator's branch
595
+ at dispatch time. If prior chain edits aren't merged in yet, the new chain
596
+ works on a stale base, will conflict at integration, and debugger-restitch
597
+ becomes mandatory. The fix is upstream: don't dispatch until prior work has
598
+ landed.
599
+ </p>
600
+
601
+ <h3>Required pre-dispatch checks</h3>
602
+
603
+ <pre><code><span class="diff-ctx"># 1. Working tree is clean (no uncommitted edits that would be inherited or lost)</span>
604
+ git status <span class="diff-ctx"># MUST report "working tree clean"</span>
605
+
606
+ <span class="diff-ctx"># 2. Latest commit on the dispatch branch contains prior chain work</span>
607
+ git log -1 --oneline <span class="diff-ctx"># confirm prior chain's commit is HEAD or in HEAD's history</span>
608
+ git log main..HEAD --oneline <span class="diff-ctx"># confirm prior chain's branch was merged in</span>
609
+
610
+ <span class="diff-ctx"># 3. No orphaned worktrees from prior chains</span>
611
+ git worktree list <span class="diff-ctx"># every chain worktree from prior dispatches should be removed</span>
612
+ git worktree prune <span class="diff-ctx"># drop stale metadata</span>
613
+
614
+ <span class="diff-ctx"># 4. If working on an integration branch:</span>
615
+ git log integration/&lt;date&gt;..HEAD <span class="diff-ctx"># MUST be empty (orchestrator's branch is in sync)</span>
616
+ </code></pre>
617
+
618
+ <div class="callout callout-warn">
619
+ <strong>Decision rule:</strong> if any of the four checks fail, finish the
620
+ merge / commit / cleanup first. Do not dispatch. A specialist forked from a
621
+ stale base produces conflict work that costs more turns than the time saved
622
+ by dispatching early.
623
+ </div>
624
+
625
+ <h3>When this rule applies</h3>
626
+
627
+ <table>
628
+ <thead>
629
+ <tr><th>Scenario</th><th>Precondition strictness</th></tr>
630
+ </thead>
631
+ <tbody>
632
+ <tr><td>Sequential chains in same epic where child.B depends on child.A's edits</td><td><strong>Strict.</strong> child.A must be merged before child.B dispatch.</td></tr>
633
+ <tr><td>Parallel chains in same epic with disjoint file scopes</td><td>Relaxed. Each dispatches off the shared base; integration phase reconciles.</td></tr>
634
+ <tr><td>Chain after orchestrator-direct edit (e.g., this epic)</td><td><strong>Strict.</strong> Orchestrator commits + pushes their direct edits before dispatching any chain that references them.</td></tr>
635
+ <tr><td>Standalone chain (no upstream dependency)</td><td>Relaxed. Just <code>git status</code> clean.</td></tr>
636
+ </tbody>
637
+ </table>
638
+
639
+ <h2>Worked example — high-scrutiny chain end-to-end</h2>
640
+
641
+ <div class="pipeline">
642
+ <svg viewBox="0 0 1100 280" width="100%" style="max-width:1100px">
643
+ <defs>
644
+ <marker id="arrowEx" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="6" markerHeight="6" orient="auto">
645
+ <path d="M0,0 L10,5 L0,10 z" fill="#58a6ff"/>
646
+ </marker>
647
+ </defs>
648
+
649
+ <text x="20" y="30" font-family="JetBrains Mono, monospace" font-size="13" fill="#f0883e" font-weight="700">
650
+ Bead: "Add token rotation endpoint" · SCRUTINY: high · touches src/auth/* + migrations/
651
+ </text>
652
+
653
+ <g font-family="Inter, sans-serif" font-size="12">
654
+ <rect x="20" y="60" width="140" height="56" rx="8" fill="#1c232e" stroke="#58a6ff"/>
655
+ <text x="90" y="82" text-anchor="middle" fill="#e6edf3" font-weight="600">executor</text>
656
+ <text x="90" y="100" text-anchor="middle" fill="#9da7b1" font-size="10">writes diff · auto-commits</text>
657
+
658
+ <rect x="190" y="60" width="140" height="56" rx="8" fill="#1c232e" stroke="#bc8cff"/>
659
+ <text x="260" y="82" text-anchor="middle" fill="#e6edf3" font-weight="600">code-sanity</text>
660
+ <text x="260" y="100" text-anchor="middle" fill="#bc8cff" font-size="10">seconder · OK required</text>
661
+
662
+ <rect x="360" y="60" width="160" height="56" rx="8" fill="#1c232e" stroke="#f0883e"/>
663
+ <text x="440" y="82" text-anchor="middle" fill="#e6edf3" font-weight="600">security-auditor</text>
664
+ <text x="440" y="100" text-anchor="middle" fill="#f0883e" font-size="10">auto-triggered: auth/* + .lock</text>
665
+
666
+ <rect x="550" y="60" width="180" height="56" rx="8" fill="#1c232e" stroke="#bc8cff"/>
667
+ <text x="640" y="82" text-anchor="middle" fill="#e6edf3" font-weight="600">obligations-scanner</text>
668
+ <text x="640" y="100" text-anchor="middle" fill="#bc8cff" font-size="10">CLEAN | OBLIGATIONS_FOUND</text>
669
+
670
+ <rect x="760" y="60" width="160" height="56" rx="8" fill="#1c232e" stroke="#58a6ff"/>
671
+ <text x="840" y="82" text-anchor="middle" fill="#e6edf3" font-weight="600">reviewer (high)</text>
672
+ <text x="840" y="100" text-anchor="middle" fill="#58a6ff" font-size="10">file-by-file sign-off</text>
673
+
674
+ <rect x="950" y="60" width="130" height="56" rx="8" fill="#1c232e" stroke="#3fb950"/>
675
+ <text x="1015" y="82" text-anchor="middle" fill="#e6edf3" font-weight="600">sp merge</text>
676
+ <text x="1015" y="100" text-anchor="middle" fill="#3fb950" font-size="10">checklist verified</text>
677
+ </g>
678
+
679
+ <g stroke="#58a6ff" stroke-width="2" fill="none" marker-end="url(#arrowEx)">
680
+ <line x1="160" y1="88" x2="190" y2="88"/>
681
+ <line x1="330" y1="88" x2="360" y2="88"/>
682
+ <line x1="520" y1="88" x2="550" y2="88"/>
683
+ <line x1="730" y1="88" x2="760" y2="88"/>
684
+ <line x1="920" y1="88" x2="950" y2="88"/>
685
+ </g>
686
+
687
+ <path d="M 840 116 Q 840 165 90 165 Q 90 116 90 116" stroke="#3fb950" stroke-width="1.5" fill="none" stroke-dasharray="3,3" marker-end="url(#arrowEx)"/>
688
+ <text x="465" y="160" fill="#3fb950" font-family="JetBrains Mono, monospace" font-size="11">PARTIAL → executor resume → reviewer ddiff (delta-only)</text>
689
+
690
+ <g font-family="JetBrains Mono, monospace" font-size="10" fill="#6e7681">
691
+ <text x="20" y="210">Auto-escalation: stated=high, surface=auth+migrations → floor=high (no change)</text>
692
+ <text x="20" y="226">Auto-escalation: lockfile detected → security-auditor becomes mandatory (not optional)</text>
693
+ <text x="20" y="242">Reviewer emits Release Checklist; sp merge in future will parse + enforce; today it is documentation evidence</text>
694
+ <text x="20" y="258">Each chain link is a separate sp run with its own bead; chain stays alive via keep-alive</text>
695
+ </g>
696
+ </svg>
697
+ </div>
698
+
699
+ <h2>Channels in an Iron review workflow</h2>
700
+ <p>
701
+ The channel substrate changes how specialists coordinate during a review chain.
702
+ Instead of the orchestrator passing outputs between jobs, each specialist
703
+ subscribes to the shared channel and wakes on the messages it cares about.
704
+ Prior verdicts from code-sanity and obligations-scanner stay in the channel
705
+ history — the reviewer reads them directly, no orchestrator forwarding.
706
+ On a <code>PARTIAL</code> verdict the executor wakes from the reviewer's
707
+ <code>verdict:PARTIAL</code> message, fixes only the flagged delta, and posts a
708
+ new <code>turn</code>; on re-review the reviewer reads the channel history to
709
+ identify prior approvals and audits the delta only. Ddiff mode emerges from
710
+ the channel naturally, not from orchestrator state.
711
+ </p>
712
+
713
+ <h3>Medium scrutiny — channel walkthrough</h3>
714
+
715
+ <div class="pipeline">
716
+ <svg viewBox="0 0 1060 310" width="100%" style="max-width:1060px">
717
+ <defs>
718
+ <marker id="arrowM" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="6" markerHeight="6" orient="auto"><path d="M0,0 L10,5 L0,10 z" fill="#58a6ff"/></marker>
719
+ <marker id="arrowMg" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="6" markerHeight="6" orient="auto"><path d="M0,0 L10,5 L0,10 z" fill="#3fb950"/></marker>
720
+ <marker id="arrowMp" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="6" markerHeight="6" orient="auto"><path d="M0,0 L10,5 L0,10 z" fill="#f0883e"/></marker>
721
+ <marker id="arrowMv" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="6" markerHeight="6" orient="auto"><path d="M0,0 L10,5 L0,10 z" fill="#bc8cff"/></marker>
722
+ </defs>
723
+
724
+ <text x="20" y="18" font-family="JetBrains Mono, monospace" font-size="11" fill="#58a6ff" font-weight="700">sp ch open executor code-sanity obligations-scanner reviewer --bead &lt;id&gt; --stop-on pass</text>
725
+
726
+ <g font-family="Inter, sans-serif" font-size="13" font-weight="600" fill="#e6edf3">
727
+ <rect x="20" y="30" width="115" height="50" rx="8" fill="#1c232e" stroke="#58a6ff"/>
728
+ <text x="77" y="52" text-anchor="middle">executor</text>
729
+ <text x="77" y="68" text-anchor="middle" font-size="9" font-family="JetBrains Mono, monospace" fill="#9da7b1">posts: turn</text>
730
+
731
+ <rect x="165" y="30" width="145" height="50" rx="8" fill="#1c232e" stroke="#bc8cff"/>
732
+ <text x="237" y="52" text-anchor="middle">code-sanity</text>
733
+ <text x="237" y="68" text-anchor="middle" font-size="9" font-family="JetBrains Mono, monospace" fill="#bc8cff">posts: verdict·OK</text>
734
+
735
+ <rect x="340" y="30" width="190" height="50" rx="8" fill="#1c232e" stroke="#bc8cff"/>
736
+ <text x="435" y="52" text-anchor="middle">obligations-scanner</text>
737
+ <text x="435" y="68" text-anchor="middle" font-size="9" font-family="JetBrains Mono, monospace" fill="#bc8cff">posts: verdict·CLEAN</text>
738
+
739
+ <rect x="560" y="30" width="145" height="50" rx="8" fill="#1c232e" stroke="#58a6ff"/>
740
+ <text x="632" y="52" text-anchor="middle">reviewer</text>
741
+ <text x="632" y="68" text-anchor="middle" font-size="9" font-family="JetBrains Mono, monospace" fill="#58a6ff">posts: verdict·PASS</text>
742
+
743
+ <rect x="735" y="30" width="110" height="50" rx="8" fill="#1c232e" stroke="#3fb950"/>
744
+ <text x="790" y="52" text-anchor="middle">sp merge</text>
745
+ <text x="790" y="68" text-anchor="middle" font-size="9" font-family="JetBrains Mono, monospace" fill="#3fb950">on stop-on:pass</text>
746
+ </g>
747
+
748
+ <line x1="705" y1="55" x2="735" y2="55" stroke="#3fb950" stroke-width="1.5" marker-end="url(#arrowMg)"/>
749
+
750
+ <rect x="20" y="108" width="940" height="46" rx="8" fill="#060f1a" stroke="#58a6ff" stroke-width="2"/>
751
+ <text x="36" y="124" font-family="JetBrains Mono, monospace" font-size="10" fill="#58a6ff" font-weight="700">CHANNEL chain:&lt;bead-id&gt;</text>
752
+
753
+ <rect x="48" y="128" width="58" height="18" rx="9" fill="rgba(88,166,255,0.18)" stroke="#58a6ff" stroke-width="1"/>
754
+ <text x="77" y="141" text-anchor="middle" font-family="JetBrains Mono, monospace" font-size="10" fill="#58a6ff">turn</text>
755
+ <rect x="194" y="128" width="86" height="18" rx="9" fill="rgba(188,140,255,0.18)" stroke="#bc8cff" stroke-width="1"/>
756
+ <text x="237" y="141" text-anchor="middle" font-family="JetBrains Mono, monospace" font-size="10" fill="#bc8cff">verdict·OK</text>
757
+ <rect x="387" y="128" width="96" height="18" rx="9" fill="rgba(188,140,255,0.18)" stroke="#bc8cff" stroke-width="1"/>
758
+ <text x="435" y="141" text-anchor="middle" font-family="JetBrains Mono, monospace" font-size="10" fill="#bc8cff">verdict·CLEAN</text>
759
+ <rect x="589" y="128" width="88" height="18" rx="9" fill="rgba(63,185,80,0.18)" stroke="#3fb950" stroke-width="1"/>
760
+ <text x="633" y="141" text-anchor="middle" font-family="JetBrains Mono, monospace" font-size="10" fill="#3fb950">verdict·PASS</text>
761
+
762
+ <line x1="77" y1="80" x2="77" y2="108" stroke="#58a6ff" stroke-width="1.5" marker-end="url(#arrowM)"/>
763
+ <line x1="237" y1="80" x2="237" y2="108" stroke="#bc8cff" stroke-width="1.5" marker-end="url(#arrowMv)"/>
764
+ <line x1="435" y1="80" x2="435" y2="108" stroke="#bc8cff" stroke-width="1.5" marker-end="url(#arrowMv)"/>
765
+ <line x1="632" y1="80" x2="632" y2="108" stroke="#3fb950" stroke-width="1.5" marker-end="url(#arrowMg)"/>
766
+
767
+ <line x1="230" y1="108" x2="230" y2="80" stroke="#58a6ff" stroke-width="1" stroke-dasharray="3,2" marker-end="url(#arrowM)"/>
768
+ <line x1="443" y1="108" x2="443" y2="80" stroke="#58a6ff" stroke-width="1" stroke-dasharray="3,2" marker-end="url(#arrowM)"/>
769
+ <line x1="624" y1="108" x2="624" y2="80" stroke="#bc8cff" stroke-width="1" stroke-dasharray="3,2" marker-end="url(#arrowMv)"/>
770
+ <line x1="68" y1="108" x2="68" y2="80" stroke="#f0883e" stroke-width="1" stroke-dasharray="3,2" marker-end="url(#arrowMp)"/>
771
+
772
+ <g font-family="JetBrains Mono, monospace" font-size="9" fill="#6e7681" text-anchor="middle">
773
+ <text x="77" y="170">wakes: verdict:me</text>
774
+ <text x="237" y="170">wakes: turn:peer</text>
775
+ <text x="435" y="170">wakes: turn:peer</text>
776
+ <text x="632" y="170">wakes: turn:peer + verdict:me×2</text>
777
+ </g>
778
+
779
+ <line x1="230" y1="178" x2="443" y2="178" stroke="#9da7b1" stroke-width="1"/>
780
+ <line x1="230" y1="174" x2="230" y2="182" stroke="#9da7b1" stroke-width="1"/>
781
+ <line x1="443" y1="174" x2="443" y2="182" stroke="#9da7b1" stroke-width="1"/>
782
+ <text x="336" y="191" text-anchor="middle" font-family="JetBrains Mono, monospace" font-size="9" fill="#9da7b1">wake in parallel from the same turn message</text>
783
+
784
+ <path d="M 632 154 Q 632 258 77 258 Q 77 210 77 154" stroke="#f0883e" stroke-width="1.5" fill="none" stroke-dasharray="4,3" marker-end="url(#arrowMp)"/>
785
+ <text x="354" y="252" text-anchor="middle" font-family="JetBrains Mono, monospace" font-size="10" fill="#f0883e">PARTIAL → executor wakes on verdict:me · fixes delta only · posts new turn</text>
786
+ <text x="354" y="266" text-anchor="middle" font-family="JetBrains Mono, monospace" font-size="10" fill="#6e7681">reviewer re-reads channel history → ddiff mode (prior-approved sections carry · no full re-audit)</text>
787
+ </svg>
788
+ </div>
789
+
790
+ <ol>
791
+ <li><strong>Open.</strong> <code>sp ch open executor code-sanity obligations-scanner reviewer --bead &lt;id&gt; --stop-on pass</code>. Channel <code>chain:&lt;bead-id&gt;</code> opens; subscriptions registered: executor (<code>verdict:me</code>), code-sanity and obligations-scanner (<code>turn:peer</code>), reviewer (<code>turn:peer + verdict:me×2</code>).</li>
792
+ <li><strong>executor</strong> writes diff, posts <code>kind=turn, summary="…", refs={result_id}</code> to channel.</li>
793
+ <li><strong>code-sanity</strong> and <strong>obligations-scanner</strong> wake in parallel from the same <code>turn:peer</code> event — no orchestrator coordination. Each runs independently and posts its <code>kind=verdict</code> targeted at reviewer.</li>
794
+ <li><strong>reviewer</strong> wakes once both targeted verdicts have arrived. Reads full channel history (turn + both verdicts). Applies medium depth. Posts <code>kind=verdict, verdict=PASS</code> with Release Checklist.</li>
795
+ <li>Stop condition <code>stop-on:pass</code> fires → channel closes → <code>sp merge</code>.</li>
796
+ </ol>
797
+
798
+ <div class="callout">
799
+ <strong>On PARTIAL (step 4):</strong> reviewer posts <code>verdict:PARTIAL, target=executor, findings=[…]</code>.
800
+ Executor wakes (<code>verdict:me</code>), reads <em>only its delta findings</em> from the channel message.
801
+ Fixes, posts a new <code>turn</code>. Reviewer wakes again; reads the channel history to identify what it
802
+ already approved in its prior verdict; audits only the new diff range. Ddiff is the reviewer
803
+ reading its own prior message — no orchestrator state needed.
804
+ </div>
805
+
806
+ <h3>High scrutiny — channel walkthrough with ddiff loop</h3>
807
+
808
+ <div class="pipeline">
809
+ <svg viewBox="0 0 1080 355" width="100%" style="max-width:1080px">
810
+ <defs>
811
+ <marker id="arrowH" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="6" markerHeight="6" orient="auto"><path d="M0,0 L10,5 L0,10 z" fill="#58a6ff"/></marker>
812
+ <marker id="arrowHg" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="6" markerHeight="6" orient="auto"><path d="M0,0 L10,5 L0,10 z" fill="#3fb950"/></marker>
813
+ <marker id="arrowHp" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="6" markerHeight="6" orient="auto"><path d="M0,0 L10,5 L0,10 z" fill="#f0883e"/></marker>
814
+ <marker id="arrowHv" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="6" markerHeight="6" orient="auto"><path d="M0,0 L10,5 L0,10 z" fill="#bc8cff"/></marker>
815
+ <marker id="arrowHr" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="6" markerHeight="6" orient="auto"><path d="M0,0 L10,5 L0,10 z" fill="#f85149"/></marker>
816
+ </defs>
817
+
818
+ <text x="20" y="16" font-family="JetBrains Mono, monospace" font-size="11" fill="#f0883e" font-weight="700">Bead: "Add token rotation" · SCRUTINY: high · diff touches src/auth/* + migrations/</text>
819
+ <text x="20" y="30" font-family="JetBrains Mono, monospace" font-size="10" fill="#6e7681">Auto-escalation: auth/* → floor=high confirmed · lockfile touched → security-auditor mandatory</text>
820
+
821
+ <g font-family="Inter, sans-serif" font-size="12" font-weight="600" fill="#e6edf3">
822
+ <rect x="20" y="44" width="108" height="52" rx="8" fill="#1c232e" stroke="#58a6ff"/>
823
+ <text x="74" y="66" text-anchor="middle">executor</text>
824
+ <text x="74" y="82" text-anchor="middle" font-size="9" font-family="JetBrains Mono, monospace" fill="#9da7b1">posts: turn</text>
825
+
826
+ <rect x="154" y="44" width="128" height="52" rx="8" fill="#1c232e" stroke="#bc8cff"/>
827
+ <text x="218" y="66" text-anchor="middle">code-sanity</text>
828
+ <text x="218" y="82" text-anchor="middle" font-size="9" font-family="JetBrains Mono, monospace" fill="#bc8cff">seconder gate</text>
829
+
830
+ <rect x="308" y="44" width="148" height="52" rx="8" fill="#1c232e" stroke="#f0883e"/>
831
+ <text x="382" y="66" text-anchor="middle">security-auditor</text>
832
+ <text x="382" y="82" text-anchor="middle" font-size="9" font-family="JetBrains Mono, monospace" fill="#f0883e">auto: auth/* + .lock</text>
833
+
834
+ <rect x="482" y="44" width="170" height="52" rx="8" fill="#1c232e" stroke="#bc8cff"/>
835
+ <text x="567" y="66" text-anchor="middle">obligations-scanner</text>
836
+ <text x="567" y="82" text-anchor="middle" font-size="9" font-family="JetBrains Mono, monospace" fill="#bc8cff">verdict·CLEAN</text>
837
+
838
+ <rect x="680" y="44" width="160" height="52" rx="8" fill="#1c232e" stroke="#58a6ff"/>
839
+ <text x="760" y="62" text-anchor="middle">reviewer (high)</text>
840
+ <text x="760" y="76" text-anchor="middle" font-size="9" font-family="JetBrains Mono, monospace" fill="#58a6ff">file-by-file sign-off</text>
841
+ <text x="760" y="89" text-anchor="middle" font-size="9" font-family="JetBrains Mono, monospace" fill="#58a6ff">gitnexus_impact req.</text>
842
+
843
+ <rect x="868" y="44" width="108" height="52" rx="8" fill="#1c232e" stroke="#3fb950"/>
844
+ <text x="922" y="66" text-anchor="middle">sp merge</text>
845
+ <text x="922" y="82" text-anchor="middle" font-size="9" font-family="JetBrains Mono, monospace" fill="#3fb950">checklist enforced</text>
846
+ </g>
847
+
848
+ <line x1="840" y1="70" x2="868" y2="70" stroke="#3fb950" stroke-width="1.5" marker-end="url(#arrowHg)"/>
849
+
850
+ <rect x="20" y="124" width="1042" height="46" rx="8" fill="#060f1a" stroke="#58a6ff" stroke-width="2"/>
851
+ <text x="36" y="140" font-family="JetBrains Mono, monospace" font-size="10" fill="#58a6ff" font-weight="700">CHANNEL chain:&lt;bead-id&gt;</text>
852
+
853
+ <rect x="44" y="142" width="58" height="18" rx="9" fill="rgba(88,166,255,0.18)" stroke="#58a6ff" stroke-width="1"/>
854
+ <text x="73" y="155" text-anchor="middle" font-family="JetBrains Mono, monospace" font-size="10" fill="#58a6ff">turn</text>
855
+ <rect x="172" y="142" width="86" height="18" rx="9" fill="rgba(188,140,255,0.18)" stroke="#bc8cff" stroke-width="1"/>
856
+ <text x="215" y="155" text-anchor="middle" font-family="JetBrains Mono, monospace" font-size="10" fill="#bc8cff">verdict·OK</text>
857
+ <rect x="332" y="142" width="96" height="18" rx="9" fill="rgba(240,136,62,0.18)" stroke="#f0883e" stroke-width="1"/>
858
+ <text x="380" y="155" text-anchor="middle" font-family="JetBrains Mono, monospace" font-size="10" fill="#f0883e">verdict·sec</text>
859
+ <rect x="516" y="142" width="96" height="18" rx="9" fill="rgba(188,140,255,0.18)" stroke="#bc8cff" stroke-width="1"/>
860
+ <text x="564" y="155" text-anchor="middle" font-family="JetBrains Mono, monospace" font-size="10" fill="#bc8cff">verdict·CLEAN</text>
861
+ <rect x="706" y="142" width="108" height="18" rx="9" fill="rgba(248,81,73,0.18)" stroke="#f85149" stroke-width="1"/>
862
+ <text x="760" y="155" text-anchor="middle" font-family="JetBrains Mono, monospace" font-size="10" fill="#f85149">verdict·PARTIAL</text>
863
+ <rect x="44" y="166" width="76" height="16" rx="8" fill="rgba(88,166,255,0.10)" stroke="#58a6ff" stroke-width="1" stroke-dasharray="3,2"/>
864
+ <text x="82" y="178" text-anchor="middle" font-family="JetBrains Mono, monospace" font-size="9" fill="#58a6ff">turn (Δ fix)</text>
865
+ <rect x="824" y="142" width="88" height="18" rx="9" fill="rgba(63,185,80,0.18)" stroke="#3fb950" stroke-width="1"/>
866
+ <text x="868" y="155" text-anchor="middle" font-family="JetBrains Mono, monospace" font-size="10" fill="#3fb950">verdict·PASS</text>
867
+
868
+ <line x1="74" y1="96" x2="74" y2="124" stroke="#58a6ff" stroke-width="1.5" marker-end="url(#arrowH)"/>
869
+ <line x1="218" y1="96" x2="218" y2="124" stroke="#bc8cff" stroke-width="1.5" marker-end="url(#arrowHv)"/>
870
+ <line x1="382" y1="96" x2="382" y2="124" stroke="#f0883e" stroke-width="1.5" marker-end="url(#arrowHp)"/>
871
+ <line x1="567" y1="96" x2="567" y2="124" stroke="#bc8cff" stroke-width="1.5" marker-end="url(#arrowHv)"/>
872
+ <line x1="760" y1="96" x2="760" y2="124" stroke="#58a6ff" stroke-width="1.5" marker-end="url(#arrowH)"/>
873
+
874
+ <line x1="208" y1="124" x2="208" y2="96" stroke="#58a6ff" stroke-width="1" stroke-dasharray="3,2" marker-end="url(#arrowH)"/>
875
+ <line x1="372" y1="124" x2="372" y2="96" stroke="#58a6ff" stroke-width="1" stroke-dasharray="3,2" marker-end="url(#arrowH)"/>
876
+ <line x1="557" y1="124" x2="557" y2="96" stroke="#58a6ff" stroke-width="1" stroke-dasharray="3,2" marker-end="url(#arrowH)"/>
877
+ <line x1="751" y1="124" x2="751" y2="96" stroke="#bc8cff" stroke-width="1" stroke-dasharray="3,2" marker-end="url(#arrowHv)"/>
878
+ <line x1="63" y1="124" x2="63" y2="96" stroke="#f85149" stroke-width="1" stroke-dasharray="3,2" marker-end="url(#arrowHr)"/>
879
+
880
+ <g font-family="JetBrains Mono, monospace" font-size="9" fill="#6e7681" text-anchor="middle">
881
+ <text x="74" y="200">wakes: verdict:me</text>
882
+ <text x="218" y="200">wakes: turn:peer</text>
883
+ <text x="382" y="200">wakes: turn:peer</text>
884
+ <text x="567" y="200">wakes: turn:peer</text>
885
+ <text x="760" y="200">wakes: turn:peer + verdict:me×3</text>
886
+ </g>
887
+
888
+ <line x1="208" y1="208" x2="577" y2="208" stroke="#9da7b1" stroke-width="1"/>
889
+ <line x1="208" y1="204" x2="208" y2="212" stroke="#9da7b1" stroke-width="1"/>
890
+ <line x1="577" y1="204" x2="577" y2="212" stroke="#9da7b1" stroke-width="1"/>
891
+ <text x="392" y="221" text-anchor="middle" font-family="JetBrains Mono, monospace" font-size="9" fill="#9da7b1">all three wake in parallel from the same turn message — no orchestrator coordination</text>
892
+
893
+ <path d="M 760 170 Q 760 298 74 298 Q 74 248 74 170" stroke="#f85149" stroke-width="1.5" fill="none" stroke-dasharray="4,3" marker-end="url(#arrowHr)"/>
894
+ <text x="416" y="290" text-anchor="middle" font-family="JetBrains Mono, monospace" font-size="10" fill="#f85149">PARTIAL → executor wakes · reads only flagged files from verdict message · fixes delta · posts turn(Δ)</text>
895
+ <text x="416" y="305" text-anchor="middle" font-family="JetBrains Mono, monospace" font-size="10" fill="#3fb950">reviewer wakes in DDIFF mode → reads prior verdict from channel history → audits new diff range only</text>
896
+ <text x="416" y="319" text-anchor="middle" font-family="JetBrains Mono, monospace" font-size="9" fill="#6e7681">prior-approved files carry forward · no full re-audit · PASS + Release Checklist → channel closes</text>
897
+ </svg>
898
+ </div>
899
+
900
+ <ol>
901
+ <li><strong>Open.</strong> <code>sp ch open executor code-sanity security-auditor obligations-scanner reviewer --bead &lt;id&gt; --scrutiny high --stop-on pass</code>. Reviewer's spec applies auto-escalation: <code>src/auth/*</code> → floor=high confirmed; lockfile change → security-auditor mandatory.</li>
902
+ <li><strong>executor</strong> writes diff (auth + migration), posts <code>kind=turn</code> with <code>refs={diff_range}</code> to channel.</li>
903
+ <li><strong>code-sanity</strong>, <strong>security-auditor</strong>, and <strong>obligations-scanner</strong> all wake in parallel from the same <code>turn:peer</code> subscription. No orchestrator coordination — the channel delivers the event to all three simultaneously.</li>
904
+ <li>Each posts its <code>kind=verdict</code> targeted at reviewer: <code>verdict:OK</code>, <code>verdict:sec={findings}</code>, <code>verdict:CLEAN</code>.</li>
905
+ <li><strong>reviewer</strong> wakes once all three targeted verdicts have arrived. Applies <strong>high</strong> mode: file-by-file sign-off, <code>gitnexus_impact</code> mandatory. Posts <code>verdict:PARTIAL, target=executor</code> with per-file findings. The partial verdict body records which files are already approved — this becomes the ddiff baseline.</li>
906
+ <li><strong>executor</strong> wakes (<code>verdict:me</code>), reads the partial findings from the channel message — sees exactly which files need work. Fixes those files only. Posts <code>kind=turn</code> with <code>refs={new_diff_range}</code> pointing at the fix commits.</li>
907
+ <li><strong>reviewer</strong> wakes in <strong>ddiff mode</strong>: reads the channel history to find its own prior <code>verdict:PARTIAL</code>, reconstructs the approved-file list, then audits only the new diff range from step 6. Prior-approved files carry forward.</li>
908
+ <li>Posts <code>verdict:PASS</code> + full Release Checklist → stop condition fires → channel closes → <code>sp merge</code>.</li>
909
+ </ol>
910
+
911
+ <div class="callout callout-good">
912
+ <strong>What the channel buys at high scrutiny:</strong>
913
+ the reviewer's step-5 partial verdict is a first-class message in the channel.
914
+ When it wakes in step 7, it reads its own prior message to reconstruct "what I already approved"
915
+ — no orchestrator state, no external memory, no re-audit of unchanged code.
916
+ The three parallel seconders also coordinate without the orchestrator: they all wake from
917
+ the same <code>turn</code> event and each posts independently to the channel.
918
+ The reviewer wakes only once all three have posted their targeted verdicts.
919
+ </div>
920
+
921
+ <h2>What's intentionally NOT in this epic</h2>
922
+
923
+ <div class="grid grid-2">
924
+ <div class="card">
925
+ <div class="card-title">parallel-review rework</div>
926
+ <p class="card-desc">Old design, no longer used, does not fit new sp shape. Leave alone.</p>
927
+ </div>
928
+ <div class="card">
929
+ <div class="card-title">sp merge enforcement of checklist</div>
930
+ <p class="card-desc">Reviewer outputs it; orchestrator reads it. Hard machine-side gate is a future infrastructure epic.</p>
931
+ </div>
932
+ <div class="card">
933
+ <div class="card-title">Retroactive scrutiny on existing beads</div>
934
+ <p class="card-desc">New beads start using SCRUTINY immediately. Old beads default to medium silently.</p>
935
+ </div>
936
+ <div class="card">
937
+ <div class="card-title">Iron's feature-hierarchy ddiff for chains</div>
938
+ <p class="card-desc"><code>sp epic merge</code> already linearizes chains. Ddiff-per-chain is a future epic if/when needed.</p>
939
+ </div>
940
+ </div>
941
+
942
+ <h2>Manual execution plan</h2>
943
+
944
+ <p>
945
+ This epic is executed by the orchestrator directly (not via specialist
946
+ dispatch — see execution-mode callout at the top). The wave structure still
947
+ organizes the work; commits-and-pushes between waves preserve the git-state
948
+ precondition for the next phase.
949
+ </p>
950
+
951
+ <table>
952
+ <thead>
953
+ <tr><th>Phase</th><th>Files</th><th>Manual orchestrator actions</th></tr>
954
+ </thead>
955
+ <tbody>
956
+ <tr>
957
+ <td><strong>Wave A</strong></td>
958
+ <td><code>reviewer · code-sanity · executor · debugger</code> .specialist.json + NEW <code>obligations-scanner</code>.specialist.json</td>
959
+ <td>For each file: read current state, apply targeted edits via <code>sp edit &lt;name&gt; --set ... --file ...</code>, validate JSON round-trip. Single commit per logical change. <code>git push</code>.</td>
960
+ </tr>
961
+ <tr>
962
+ <td><strong>Wave B</strong></td>
963
+ <td><code>.claude/skills/using-specialists-v3/SKILL.md</code> + <code>CLAUDE.md</code></td>
964
+ <td>Surgical edits — add new sections, invert rule #9, remove sp-merge surface, rewrite Common gotchas. Verify markdown lint. Commit + push.</td>
965
+ </tr>
966
+ <tr>
967
+ <td><strong>Wave C</strong></td>
968
+ <td>synthetic beads</td>
969
+ <td>Run the three smokes (SCRUTINY tiering, ddiff PARTIAL→re-review, obligations marker block). Document evidence. Close epic.</td>
970
+ </tr>
971
+ </tbody>
972
+ </table>
973
+
974
+ <div class="callout">
975
+ Between every wave: <strong>commit + push + verify git status clean</strong>
976
+ before starting the next. This is the git-state precondition rule applied to
977
+ the orchestrator's own work, not just to specialist dispatches.
978
+ </div>
979
+
980
+ <h3>Pre-existing file inventory (read these first)</h3>
981
+
982
+ <pre><code><span class="diff-ctx"># Files this epic edits — read each before touching</span>
983
+ config/specialists/reviewer.specialist.json <span class="diff-ctx"># child.1</span>
984
+ config/specialists/code-sanity.specialist.json <span class="diff-ctx"># child.2</span>
985
+ config/specialists/executor.specialist.json <span class="diff-ctx"># child.6 (also)</span>
986
+ config/specialists/debugger.specialist.json <span class="diff-ctx"># child.6 (also)</span>
987
+ .claude/skills/using-specialists-v3/SKILL.md <span class="diff-ctx"># child.4</span>
988
+ CLAUDE.md <span class="diff-ctx"># child.4 (gotchas section)</span>
989
+
990
+ <span class="diff-ctx"># Files this epic creates</span>
991
+ config/specialists/obligations-scanner.specialist.json <span class="diff-ctx"># child.3 NEW</span>
992
+
993
+ <span class="diff-ctx"># Pre-flight before each edit batch</span>
994
+ sp edit &lt;name&gt; --get specialist.prompt.system <span class="diff-ctx"># round-trip check</span>
995
+ specialists list --full | grep &lt;name&gt; <span class="diff-ctx"># confirm registry shows it</span>
996
+ </code></pre>
997
+
998
+ <footer>
999
+ <p>Generated 2026-05-24 · Inspired by Jane Street's Iron · Epic <code>iron-review-hardening</code></p>
1000
+ </footer>
1001
+
1002
+ </div>
1003
+ </body>
1004
+ </html>