@xulthekl/team-flow 0.22.4

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 (405) hide show
  1. package/.agents/plugins/marketplace.json +20 -0
  2. package/.agents/skills +1 -0
  3. package/.claude/always/phase-guard.md +3 -0
  4. package/.claude-plugin/marketplace.json +20 -0
  5. package/.claude-plugin/plugin.json +31 -0
  6. package/.codex-plugin/plugin.json +45 -0
  7. package/.codexignore +6 -0
  8. package/.cursor-plugin/marketplace.json +17 -0
  9. package/.cursor-plugin/plugin.json +31 -0
  10. package/.github/copilot-instructions.md +15 -0
  11. package/.github/dependabot.yml +10 -0
  12. package/.github/plugin/marketplace.json +42 -0
  13. package/.github/workflows/ci.yml +98 -0
  14. package/.github/workflows/hol-plugin-scanner.yml +17 -0
  15. package/.opencode/INSTALL.md +61 -0
  16. package/.opencode/plugins/team-flow.js +70 -0
  17. package/AGENTS.md +280 -0
  18. package/CHANGELOG.md +635 -0
  19. package/CONTRIBUTING.md +115 -0
  20. package/GEMINI.md +14 -0
  21. package/HANDOFF.md +219 -0
  22. package/INSTALL.md +810 -0
  23. package/LICENSE +21 -0
  24. package/README.md +185 -0
  25. package/SECURITY.md +37 -0
  26. package/agents/bug-investigator.md +180 -0
  27. package/agents/change-split-auditor.md +257 -0
  28. package/agents/code-reviewer.md +171 -0
  29. package/agents/cross-change-consistency-checker.md +215 -0
  30. package/agents/prd-completeness-reviewer.md +197 -0
  31. package/agents/prototype-builder.md +230 -0
  32. package/agents/prototype-env-scout.md +156 -0
  33. package/agents/prototype-reviewer.md +226 -0
  34. package/assets/icon.svg +6 -0
  35. package/dist/index.d.ts +13 -0
  36. package/dist/index.js +5 -0
  37. package/dist/parsing/change-parser.d.ts +12 -0
  38. package/dist/parsing/change-parser.js +54 -0
  39. package/dist/parsing/requirement-blocks.d.ts +31 -0
  40. package/dist/parsing/requirement-blocks.js +192 -0
  41. package/dist/schema/base.d.ts +7 -0
  42. package/dist/schema/base.js +1 -0
  43. package/dist/schema/change.d.ts +25 -0
  44. package/dist/schema/change.js +1 -0
  45. package/dist/schema/index.d.ts +3 -0
  46. package/dist/schema/index.js +1 -0
  47. package/dist/schema/spec.d.ts +11 -0
  48. package/dist/schema/spec.js +1 -0
  49. package/dist/validation/constants.d.ts +42 -0
  50. package/dist/validation/constants.js +42 -0
  51. package/dist/validation/tokenizer.d.ts +17 -0
  52. package/dist/validation/tokenizer.js +173 -0
  53. package/dist/validation/types.d.ts +40 -0
  54. package/dist/validation/types.js +1 -0
  55. package/dist/validation/validator.d.ts +21 -0
  56. package/dist/validation/validator.js +489 -0
  57. package/docs/README_en.md +358 -0
  58. package/docs/artifact-contract.md +96 -0
  59. package/docs/decision-points.md +88 -0
  60. package/docs/e2e-integration-design.md +207 -0
  61. package/docs/examples/README.md +25 -0
  62. package/docs/examples/add-dark-mode/README.md +13 -0
  63. package/docs/examples/add-dark-mode/design.md +49 -0
  64. package/docs/examples/add-dark-mode/execution-contract.md +56 -0
  65. package/docs/examples/add-dark-mode/proposal.md +46 -0
  66. package/docs/examples/add-dark-mode/specs/ui-theme/spec.md +35 -0
  67. package/docs/examples/add-dark-mode/tasks.md +26 -0
  68. package/docs/examples/refactor-auth-boundary/README.md +15 -0
  69. package/docs/examples/refactor-auth-boundary/design.md +41 -0
  70. package/docs/examples/refactor-auth-boundary/execution-contract.md +61 -0
  71. package/docs/examples/refactor-auth-boundary/proposal.md +47 -0
  72. package/docs/examples/refactor-auth-boundary/specs/auth-boundary/spec.md +45 -0
  73. package/docs/examples/refactor-auth-boundary/tasks.md +25 -0
  74. package/docs/plans/2026-07-07-fix-batch-design.md +68 -0
  75. package/docs/plans/2026-07-20-001-refactor-skill-collaboration-protocol-plan.md +128 -0
  76. package/docs/platform-matrix.md +45 -0
  77. package/docs/prototype-design-research.md +206 -0
  78. package/docs/release-checklist.md +96 -0
  79. package/docs/showcase.html +699 -0
  80. package/docs/skill-rename-v0.8.0.md +49 -0
  81. package/docs/state-machine.md +162 -0
  82. package/gemini-extension.json +6 -0
  83. package/hooks/hooks-cursor.json +8 -0
  84. package/hooks/hooks.json +26 -0
  85. package/hooks/pre-tool-use-guard +116 -0
  86. package/hooks/session-start +14 -0
  87. package/llms.txt +51 -0
  88. package/package.json +48 -0
  89. package/plugin.json +27 -0
  90. package/prd/v1/plan.md +443 -0
  91. package/prd/v1/prd.md +580 -0
  92. package/scripts/check-update.mjs +91 -0
  93. package/scripts/check-version-consistency.mjs +345 -0
  94. package/scripts/ensure-branch.mjs +71 -0
  95. package/scripts/get-config +31 -0
  96. package/scripts/guard/checks/artifacts-exist.mjs +36 -0
  97. package/scripts/guard/checks/contract-current.mjs +33 -0
  98. package/scripts/guard/checks/contract-fresh.mjs +17 -0
  99. package/scripts/guard/checks/dp-gate-passed.mjs +35 -0
  100. package/scripts/guard/checks/dp3-approved.mjs +22 -0
  101. package/scripts/guard/checks/execution-plan-ready.mjs +40 -0
  102. package/scripts/guard/checks/execution-reviews-passed.mjs +36 -0
  103. package/scripts/guard/checks/schema-valid.mjs +63 -0
  104. package/scripts/guard/checks/specs-merged.mjs +51 -0
  105. package/scripts/guard/checks/tasks-complete.mjs +31 -0
  106. package/scripts/guard/checks/tests-passing.mjs +31 -0
  107. package/scripts/guard/design-token-guard.mjs +237 -0
  108. package/scripts/guard/guard.mjs +205 -0
  109. package/scripts/infer-workflow.mjs +136 -0
  110. package/scripts/install-amazon-q.mjs +9 -0
  111. package/scripts/install-cline.mjs +9 -0
  112. package/scripts/install-continue.mjs +9 -0
  113. package/scripts/install-cursor.mjs +265 -0
  114. package/scripts/install-git-hooks.mjs +82 -0
  115. package/scripts/install-kiro.mjs +9 -0
  116. package/scripts/install-pi.mjs +9 -0
  117. package/scripts/install-qoder.mjs +9 -0
  118. package/scripts/install-qwen.mjs +9 -0
  119. package/scripts/install-roocode.mjs +9 -0
  120. package/scripts/install-windsurf.mjs +9 -0
  121. package/scripts/install-zcode.mjs +265 -0
  122. package/scripts/lib/cmd-audit.mjs +127 -0
  123. package/scripts/lib/cmd-checkpoint.mjs +118 -0
  124. package/scripts/lib/cmd-config.mjs +88 -0
  125. package/scripts/lib/cmd-doctor.mjs +267 -0
  126. package/scripts/lib/cmd-execution.mjs +206 -0
  127. package/scripts/lib/cmd-handoff.mjs +94 -0
  128. package/scripts/lib/cmd-inject.mjs +310 -0
  129. package/scripts/lib/cmd-install-amazon-q.mjs +11 -0
  130. package/scripts/lib/cmd-install-cline.mjs +11 -0
  131. package/scripts/lib/cmd-install-continue.mjs +11 -0
  132. package/scripts/lib/cmd-install-cursor.mjs +14 -0
  133. package/scripts/lib/cmd-install-kiro.mjs +11 -0
  134. package/scripts/lib/cmd-install-pi.mjs +11 -0
  135. package/scripts/lib/cmd-install-qoder.mjs +11 -0
  136. package/scripts/lib/cmd-install-qwen.mjs +11 -0
  137. package/scripts/lib/cmd-install-roocode.mjs +11 -0
  138. package/scripts/lib/cmd-install-windsurf.mjs +11 -0
  139. package/scripts/lib/cmd-install-workbuddy.mjs +359 -0
  140. package/scripts/lib/cmd-install-zcode.mjs +14 -0
  141. package/scripts/lib/cmd-isolate.mjs +37 -0
  142. package/scripts/lib/cmd-list.mjs +71 -0
  143. package/scripts/lib/cmd-runtime.mjs +85 -0
  144. package/scripts/lib/cmd-solutions.mjs +71 -0
  145. package/scripts/lib/cmd-state.mjs +231 -0
  146. package/scripts/lib/cmd-sync.mjs +102 -0
  147. package/scripts/lib/cmd-validate.mjs +105 -0
  148. package/scripts/lib/cmd-version.mjs +148 -0
  149. package/scripts/lib/config-loader.mjs +107 -0
  150. package/scripts/lib/execution-plan.mjs +492 -0
  151. package/scripts/lib/execution-recommendation.mjs +221 -0
  152. package/scripts/lib/hash.mjs +74 -0
  153. package/scripts/lib/install.mjs +267 -0
  154. package/scripts/lib/platform-runtime-inventory.mjs +27 -0
  155. package/scripts/lib/platforms.mjs +165 -0
  156. package/scripts/lib/prototype-sync.mjs +192 -0
  157. package/scripts/lib/sdd-overlay.mjs +262 -0
  158. package/scripts/lib/shell-quote.mjs +4 -0
  159. package/scripts/lib/solutions-capture.mjs +102 -0
  160. package/scripts/lib/solutions-index-gen.mjs +112 -0
  161. package/scripts/lib/solutions-inject.mjs +77 -0
  162. package/scripts/lib/solutions-promote.mjs +145 -0
  163. package/scripts/lib/spec-paths.mjs +85 -0
  164. package/scripts/lib/state-loader.mjs +154 -0
  165. package/scripts/lint/lint-skills.mjs +149 -0
  166. package/scripts/lint/rules/behavior-consistency.mjs +56 -0
  167. package/scripts/lint/rules/dp-trigger-points.mjs +60 -0
  168. package/scripts/lint/rules/exception-handling.mjs +59 -0
  169. package/scripts/lint/rules/no-contradictory-instructions.mjs +67 -0
  170. package/scripts/lint/rules/no-redundant-checks.mjs +50 -0
  171. package/scripts/lint/rules/token-rules.mjs +122 -0
  172. package/scripts/review-package +44 -0
  173. package/scripts/task-brief +40 -0
  174. package/scripts/team-flow.mjs +164 -0
  175. package/scripts/token-baseline.mjs +158 -0
  176. package/scripts/validate-artifacts +96 -0
  177. package/scripts/verify-marketplace-release.mjs +59 -0
  178. package/skills/architecture-design/SKILL.md +140 -0
  179. package/skills/architecture-design/chapters/ch01-4a-domains.md +27 -0
  180. package/skills/architecture-design/chapters/ch02-change-cascade.md +27 -0
  181. package/skills/architecture-design/chapters/ch03-architecture-outputs.md +25 -0
  182. package/skills/architecture-design/chapters/ch04-entity-to-aggregate.md +27 -0
  183. package/skills/architecture-design/chapters/ch05-cqrs.md +32 -0
  184. package/skills/architecture-design/chapters/ch06-integration.md +54 -0
  185. package/skills/architecture-design/cheatsheet.md +51 -0
  186. package/skills/architecture-design/glossary.md +23 -0
  187. package/skills/architecture-design/patterns.md +32 -0
  188. package/skills/bug-investigator/SKILL.md +77 -0
  189. package/skills/build-executor/SKILL.md +163 -0
  190. package/skills/build-executor/implementer-prompt.md +162 -0
  191. package/skills/build-executor/references/execution-modes.md +86 -0
  192. package/skills/build-executor/task-reviewer-prompt.md +195 -0
  193. package/skills/ce-brainstorm/SKILL.md +415 -0
  194. package/skills/ce-brainstorm/references/agents/slack-researcher.md +127 -0
  195. package/skills/ce-brainstorm/references/blindspot-pass.md +70 -0
  196. package/skills/ce-brainstorm/references/brainstorm-sections.md +285 -0
  197. package/skills/ce-brainstorm/references/handoff.md +168 -0
  198. package/skills/ce-brainstorm/references/html-rendering.md +634 -0
  199. package/skills/ce-brainstorm/references/markdown-rendering.md +241 -0
  200. package/skills/ce-brainstorm/references/model-tiers.md +9 -0
  201. package/skills/ce-brainstorm/references/prd-mapping.md +71 -0
  202. package/skills/ce-brainstorm/references/product-pressure-test.md +42 -0
  203. package/skills/ce-brainstorm/references/reasoning-elevation.md +63 -0
  204. package/skills/ce-brainstorm/references/settled-decisions.md +45 -0
  205. package/skills/ce-brainstorm/references/synthesis-summary.md +282 -0
  206. package/skills/ce-brainstorm/references/universal-brainstorming.md +73 -0
  207. package/skills/ce-brainstorm/references/verdict-routing.md +26 -0
  208. package/skills/ce-brainstorm/references/visual-probes.md +158 -0
  209. package/skills/ce-brainstorm/scripts/visual-probe-server.js +418 -0
  210. package/skills/ce-compound/SKILL.md +114 -0
  211. package/skills/ce-compound/assets/resolution-template.md +94 -0
  212. package/skills/ce-compound/references/agents/best-practices-researcher.md +115 -0
  213. package/skills/ce-compound/references/agents/data-integrity-guardian.md +68 -0
  214. package/skills/ce-compound/references/agents/framework-docs-researcher.md +93 -0
  215. package/skills/ce-compound/references/agents/pattern-recognition-specialist.md +55 -0
  216. package/skills/ce-compound/references/agents/performance-oracle.md +108 -0
  217. package/skills/ce-compound/references/agents/security-sentinel.md +91 -0
  218. package/skills/ce-compound/references/agents/session-historian.md +83 -0
  219. package/skills/ce-compound/references/concepts-vocabulary.md +78 -0
  220. package/skills/ce-compound/references/full-mode-workflow.md +413 -0
  221. package/skills/ce-compound/references/grounding-validation.md +84 -0
  222. package/skills/ce-compound/references/lightweight-mode.md +53 -0
  223. package/skills/ce-compound/references/output-standards.md +182 -0
  224. package/skills/ce-compound/references/promotion-rules.md +38 -0
  225. package/skills/ce-compound/references/schema.yaml +231 -0
  226. package/skills/ce-compound/references/three-tier-index.md +55 -0
  227. package/skills/ce-compound/references/v0.5-upgrade.md +32 -0
  228. package/skills/ce-compound/references/write-flow.md +36 -0
  229. package/skills/ce-compound/references/yaml-schema.md +118 -0
  230. package/skills/ce-compound/scripts/session-history/discover-sessions.sh +130 -0
  231. package/skills/ce-compound/scripts/session-history/extract-errors.py +254 -0
  232. package/skills/ce-compound/scripts/session-history/extract-metadata.py +456 -0
  233. package/skills/ce-compound/scripts/session-history/extract-skeleton.py +575 -0
  234. package/skills/ce-compound/scripts/validate-doc-claims.py +346 -0
  235. package/skills/ce-compound/scripts/validate-frontmatter.py +137 -0
  236. package/skills/ce-ideate/SKILL.md +402 -0
  237. package/skills/ce-ideate/references/agents/issue-intelligence-analyst.md +200 -0
  238. package/skills/ce-ideate/references/agents/learnings-researcher.md +247 -0
  239. package/skills/ce-ideate/references/agents/slack-researcher.md +127 -0
  240. package/skills/ce-ideate/references/agents/web-researcher.md +121 -0
  241. package/skills/ce-ideate/references/divergent-ideation.md +89 -0
  242. package/skills/ce-ideate/references/html-rendering.md +634 -0
  243. package/skills/ce-ideate/references/ideation-sections.md +191 -0
  244. package/skills/ce-ideate/references/markdown-rendering.md +238 -0
  245. package/skills/ce-ideate/references/post-ideation-workflow.md +167 -0
  246. package/skills/ce-ideate/references/universal-ideation.md +107 -0
  247. package/skills/ce-ideate/references/web-research-cache.md +56 -0
  248. package/skills/ce-plan/SKILL.md +137 -0
  249. package/skills/ce-plan/references/agents/agent-native-planning-strategist.md +62 -0
  250. package/skills/ce-plan/references/agents/architecture-strategist.md +46 -0
  251. package/skills/ce-plan/references/agents/best-practices-researcher.md +114 -0
  252. package/skills/ce-plan/references/agents/data-integrity-guardian.md +68 -0
  253. package/skills/ce-plan/references/agents/data-migration-reviewer.md +103 -0
  254. package/skills/ce-plan/references/agents/deployment-verification-agent.md +157 -0
  255. package/skills/ce-plan/references/agents/framework-docs-researcher.md +93 -0
  256. package/skills/ce-plan/references/agents/git-history-analyzer.md +40 -0
  257. package/skills/ce-plan/references/agents/learnings-researcher.md +247 -0
  258. package/skills/ce-plan/references/agents/pattern-recognition-specialist.md +55 -0
  259. package/skills/ce-plan/references/agents/performance-oracle.md +108 -0
  260. package/skills/ce-plan/references/agents/repo-research-analyst.md +258 -0
  261. package/skills/ce-plan/references/agents/security-sentinel.md +91 -0
  262. package/skills/ce-plan/references/agents/slack-researcher.md +127 -0
  263. package/skills/ce-plan/references/agents/spec-flow-analyzer.md +80 -0
  264. package/skills/ce-plan/references/agents/web-researcher.md +121 -0
  265. package/skills/ce-plan/references/approach-altitude.md +55 -0
  266. package/skills/ce-plan/references/change-splitting.md +65 -0
  267. package/skills/ce-plan/references/completion-contract.md +33 -0
  268. package/skills/ce-plan/references/core-principles.md +40 -0
  269. package/skills/ce-plan/references/deepening-workflow.md +263 -0
  270. package/skills/ce-plan/references/dependency-graph.md +36 -0
  271. package/skills/ce-plan/references/html-rendering.md +634 -0
  272. package/skills/ce-plan/references/intake-routing.md +189 -0
  273. package/skills/ce-plan/references/markdown-rendering.md +238 -0
  274. package/skills/ce-plan/references/plan-handoff.md +150 -0
  275. package/skills/ce-plan/references/plan-sections.md +427 -0
  276. package/skills/ce-plan/references/plan-structure.md +120 -0
  277. package/skills/ce-plan/references/planning-modes.md +69 -0
  278. package/skills/ce-plan/references/reasoning-elevation.md +63 -0
  279. package/skills/ce-plan/references/research-workflow.md +165 -0
  280. package/skills/ce-plan/references/review-and-write.md +127 -0
  281. package/skills/ce-plan/references/settled-decisions.md +45 -0
  282. package/skills/ce-plan/references/synthesis-summary.md +418 -0
  283. package/skills/ce-plan/references/universal-planning.md +168 -0
  284. package/skills/ce-proof/SKILL.md +346 -0
  285. package/skills/ce-strategy/SKILL.md +97 -0
  286. package/skills/ce-strategy/references/interview.md +143 -0
  287. package/skills/ce-strategy/references/strategy-template.md +89 -0
  288. package/skills/code-reviewer/SKILL.md +84 -0
  289. package/skills/code-reviewer/code-reviewer-prompt.md +195 -0
  290. package/skills/contract-builder/SKILL.md +72 -0
  291. package/skills/design-system/SKILL.md +75 -0
  292. package/skills/design-system/references/agents/design-system-architect.md +138 -0
  293. package/skills/design-system/references/creation-flow.md +170 -0
  294. package/skills/design-system/references/preview-template.html +319 -0
  295. package/skills/design-system/references/token-derivation.md +115 -0
  296. package/skills/design-system/references/variant-schema.md +60 -0
  297. package/skills/e2e/SKILL.md +56 -0
  298. package/skills/e2e/references/test-verifier.md +40 -0
  299. package/skills/need-explorer/SKILL.md +79 -0
  300. package/skills/prototype/SKILL.md +98 -0
  301. package/skills/prototype/references/agents/design-system-architect.md +122 -0
  302. package/skills/prototype/references/checklist.md +82 -0
  303. package/skills/prototype/references/craft/accessibility-baseline.md +71 -0
  304. package/skills/prototype/references/craft/anti-ai-slop.md +87 -0
  305. package/skills/prototype/references/craft/laws-of-ux.md +60 -0
  306. package/skills/prototype/references/craft/state-coverage.md +81 -0
  307. package/skills/prototype/references/craft/typography-hierarchy.md +50 -0
  308. package/skills/prototype/references/layouts.md +223 -0
  309. package/skills/prototype/references/orchestration-flow.md +101 -0
  310. package/skills/prototype/references/prototype-scaffold/assets/design-tokens.css +19 -0
  311. package/skills/prototype/references/prototype-scaffold/components/button.html +3 -0
  312. package/skills/prototype/references/prototype-scaffold/design-system.md +7 -0
  313. package/skills/prototype/references/prototype-scaffold/flow.md +11 -0
  314. package/skills/prototype/references/prototype-scaffold/index.html +20 -0
  315. package/skills/prototype/references/prototype-scaffold/pages/index.html +11 -0
  316. package/skills/prototype/references/template.html +396 -0
  317. package/skills/release-archivist/SKILL.md +166 -0
  318. package/skills/release-archivist/references/closing-procedures.md +81 -0
  319. package/skills/session-handoff/SKILL.md +110 -0
  320. package/skills/session-handoff/references/context-extraction.md +70 -0
  321. package/skills/session-handoff/references/handoff-template.md +90 -0
  322. package/skills/session-handoff/references/skill-recommendation.md +43 -0
  323. package/skills/spec-merger/SKILL.md +66 -0
  324. package/skills/spec-writer/SKILL.md +149 -0
  325. package/skills/workflow-bootstrap/SKILL.md +148 -0
  326. package/skills/workflow-bootstrap/references/agents/codebase-recon-analyst.md +121 -0
  327. package/skills/workflow-bootstrap/references/b1-reconnaissance.md +80 -0
  328. package/skills/workflow-bootstrap/scripts/recon-probe.sh +328 -0
  329. package/skills/workflow-feedback/SKILL.md +120 -0
  330. package/skills/workflow-feedback/references/category-guide.md +121 -0
  331. package/skills/workflow-feedback/references/feedback-template.md +73 -0
  332. package/skills/workflow-feedback/references/review-mode.md +92 -0
  333. package/skills/workflow-orchestrator/SKILL.md +94 -0
  334. package/skills/workflow-orchestrator/references/feedback-loops.md +56 -0
  335. package/skills/workflow-orchestrator/references/s1-path-router.md +81 -0
  336. package/skills/workflow-orchestrator/references/s2-prd-prototype-loop.md +96 -0
  337. package/skills/workflow-orchestrator/references/s3-plan-pipeline.md +50 -0
  338. package/skills/workflow-orchestrator/references/s4-split-validate.md +108 -0
  339. package/skills/workflow-orchestrator/references/s5-monitoring.md +61 -0
  340. package/skills/workflow-orchestrator/references/state-model.md +185 -0
  341. package/skills/workflow-start/SKILL.md +147 -0
  342. package/skills/workflow-start/references/routing-rules.md +155 -0
  343. package/src/index.ts +16 -0
  344. package/src/parsing/change-parser.ts +79 -0
  345. package/src/parsing/requirement-blocks.ts +244 -0
  346. package/src/schema/base.ts +8 -0
  347. package/src/schema/change.ts +29 -0
  348. package/src/schema/index.ts +3 -0
  349. package/src/schema/spec.ts +12 -0
  350. package/src/validation/constants.ts +53 -0
  351. package/src/validation/tokenizer.ts +180 -0
  352. package/src/validation/types.ts +47 -0
  353. package/src/validation/validator.ts +552 -0
  354. package/templates/abandonment-summary.md +29 -0
  355. package/templates/design.md +37 -0
  356. package/templates/execution-contract.md +99 -0
  357. package/templates/plan.md +86 -0
  358. package/templates/prd.md +468 -0
  359. package/templates/proposal.md +37 -0
  360. package/templates/spec.md +31 -0
  361. package/templates/tasks.md +47 -0
  362. package/tests/e2e.test.mjs +266 -0
  363. package/tests/lib/cmd-audit.test.mjs +202 -0
  364. package/tests/lib/cmd-checkpoint.test.mjs +98 -0
  365. package/tests/lib/cmd-config.test.mjs +101 -0
  366. package/tests/lib/cmd-doctor.test.mjs +450 -0
  367. package/tests/lib/cmd-execution.test.mjs +647 -0
  368. package/tests/lib/cmd-handoff.test.mjs +137 -0
  369. package/tests/lib/cmd-inject.test.mjs +218 -0
  370. package/tests/lib/cmd-install-workbuddy.test.mjs +113 -0
  371. package/tests/lib/cmd-install-zcode.test.mjs +42 -0
  372. package/tests/lib/cmd-isolate.test.mjs +68 -0
  373. package/tests/lib/cmd-list.test.mjs +127 -0
  374. package/tests/lib/cmd-runtime.test.mjs +83 -0
  375. package/tests/lib/cmd-state-missing.test.mjs +65 -0
  376. package/tests/lib/cmd-state.test.mjs +365 -0
  377. package/tests/lib/cmd-sync-paths.test.mjs +84 -0
  378. package/tests/lib/cmd-validate-paths.test.mjs +90 -0
  379. package/tests/lib/config-loader.test.mjs +175 -0
  380. package/tests/lib/ensure-branch.test.mjs +59 -0
  381. package/tests/lib/execution-control-plane.test.mjs +168 -0
  382. package/tests/lib/execution-plan.test.mjs +474 -0
  383. package/tests/lib/guard-specs-merged.test.mjs +108 -0
  384. package/tests/lib/guard-tests-passing.test.mjs +112 -0
  385. package/tests/lib/guard-transitions.test.mjs +262 -0
  386. package/tests/lib/guard.test.mjs +611 -0
  387. package/tests/lib/hash.test.mjs +138 -0
  388. package/tests/lib/infer-workflow.test.mjs +161 -0
  389. package/tests/lib/install-git-hooks.test.mjs +20 -0
  390. package/tests/lib/marketplace-release-docs.test.mjs +31 -0
  391. package/tests/lib/minimality-discipline.test.mjs +37 -0
  392. package/tests/lib/model-profiles-docs.test.mjs +33 -0
  393. package/tests/lib/node20-compatibility.test.mjs +73 -0
  394. package/tests/lib/node20-test-entry.test.mjs +17 -0
  395. package/tests/lib/platform-runtime-distribution.test.mjs +150 -0
  396. package/tests/lib/raw-mode-smoke.test.mjs +42 -0
  397. package/tests/lib/sdd-overlay.test.mjs +118 -0
  398. package/tests/lib/spec-paths.test.mjs +80 -0
  399. package/tests/lib/state-loader.test.mjs +251 -0
  400. package/tests/lib/token-baseline.test.mjs +72 -0
  401. package/tests/lib/token-rules.test.mjs +94 -0
  402. package/tests/lib/verify-marketplace-release.test.mjs +128 -0
  403. package/tests/tsconfig.json +12 -0
  404. package/token-baseline.json +95 -0
  405. package/tsconfig.json +14 -0
package/skills/ce-brainstorm/references/html-rendering.md ADDED
@@ -0,0 +1,634 @@
1
+ # HTML Rendering
2
+
3
+ This is a format-rendering reference — it describes how to render any
4
+ artifact in HTML, independent of which skill is producing it.
5
+
6
+ It is paired with a section contract (`plan-sections.md`,
7
+ `brainstorm-sections.md`, etc.) that describes *what* the artifact contains.
8
+ This reference describes *how* HTML specifically presents it. The same
9
+ content rendered by different skills shares the same HTML principles.
10
+
11
+ The HTML artifact is the *only* artifact the skill produces for that run —
12
+ output mode is exclusive (markdown OR HTML, never both). Downstream
13
+ consumers that read HTML today (`ce-work`, human readers) do so directly;
14
+ the agent-consumability rules below make that work. `ce-doc-review` is
15
+ *not* currently an HTML consumer — its mutation mechanics are markdown-only,
16
+ so the ce-plan handoff gates the 5.3.8 doc-review pass to `OUTPUT_FORMAT=md`
17
+ runs and skips it for HTML.
18
+
19
+ ## Hard invariants
20
+
21
+ These hold regardless of which skill produced the artifact.
22
+
23
+ - **Single self-contained HTML5 file.** No companion `.css`, `.js`, or
24
+ `.svg` files. CSS lives in `<style>`. SVG lives inline. Images are
25
+ base64 data URIs or inline SVG. The one permitted exception is a
26
+ `<link rel="stylesheet">` to a CDN webfont CSS endpoint (Google Fonts,
27
+ Bunny Fonts, etc.), paired with an offline-readable fallback font stack
28
+ so the doc remains readable if the CDN is unreachable.
29
+ - **All metadata appears as visible text — single source of truth.**
30
+ The artifact's metadata (title, type, date, etc. — exact
31
+ fields per-skill, defined in the section contract) renders as visible
32
+ HTML elements that downstream agents and humans read. No hidden
33
+ machine-readable copy in any form: no `<script type="application/json">`
34
+ frontmatter block, no `data-*` attribute mirror, and no
35
+ `<meta name="created">` / `<meta name="origin">`
36
+ in `<head>` duplicating the same values that appear in the visible
37
+ header. One representation for each value — drift across two copies is
38
+ the failure this rule prevents.
39
+
40
+ The text-and-attribute redundancy in `<time datetime="2026-05-12">2026-05-12</time>`
41
+ is acceptable because the attribute is a parser hint, not a hidden copy.
42
+ - **Stable IDs as anchor IDs AND visible text.** Every ID-bearing item
43
+ (R-IDs, U-IDs, A-IDs, F-IDs, AE-IDs, KTDs) gets `id="r1"` on its
44
+ element AND appears as visible text inside the element (e.g., the
45
+ text "R1." inside the table cell or heading). Downstream agents find
46
+ the ID in source the same way they find it in markdown.
47
+ - **Source / composition signal.** A visible footer at the bottom of
48
+ the doc names the composition timestamp and the source identifier
49
+ (the user prompt context, the upstream brainstorm doc when one
50
+ exists, or just the composing skill name when there's no external
51
+ source). Example shape:
52
+ `<footer class="composition-signal">Composed 2026-05-17T14:23Z by ce-plan from <code>docs/brainstorms/...-requirements.md</code></footer>`.
53
+ Under exclusive output mode this signal is the artifact's own
54
+ provenance — there's no markdown sibling to reference. Omitting it
55
+ leaves readers unable to tell how stale the rendering is.
56
+ - **ASCII identifiers.** Class names, element IDs, data attribute names
57
+ are ASCII-only.
58
+ - **Unified plan navigation.** Unified plan artifacts include a visible
59
+ navigation region near the top of the document. It links to stable section
60
+ anchors for `goal-capsule`,
61
+ `product-contract`, `planning-contract`, `implementation-units`,
62
+ `verification-contract`, `definition-of-done`, and `appendix` when those
63
+ sections exist. Requirements-only artifacts omit links to absent
64
+ implementation sections.
65
+ - **Visible readiness metadata.** If the artifact has `artifact_contract`,
66
+ `artifact_readiness`, `product_contract_source`, or `execution`, render
67
+ those values in the visible header metadata. Do not hide a duplicate copy in
68
+ JSON, `data-*`, or `<meta>` tags.
69
+
70
+ ## Precedence stack for style preferences
71
+
72
+ Honor user style preferences in this order (highest to lowest):
73
+
74
+ 1. **In-session conversation** — explicit direction the user gave this run.
75
+ 2. **Preferred stylesheet reference** named in loaded agent-instruction
76
+ context (typically `AGENTS.md` / `CLAUDE.md`, but scan loaded context;
77
+ don't enumerate locations). The reference may be a file path
78
+ (`docs/style.css`), a URL, a named library ("Tailwind"), or a style
79
+ brand ("Stripe docs"). Agent-instruction files carry deliberate
80
+ agent-aware preferences, so this tier sits above DESIGN.md.
81
+ 3. **DESIGN.md** discovered on the filesystem (see "DESIGN.md discovery"
82
+ below).
83
+ 4. **Fallback default** — the opinionated palette / typography choices the
84
+ agent makes when no preference exists.
85
+
86
+ ### Active-recall at compose time
87
+
88
+ Before writing the CSS, scan loaded context for any stylesheet reference
89
+ the user has indicated for documents like this. If found and inlinable
90
+ (short local file, fetchable URL within budget), inline it into `<style>`.
91
+ If found but not inlinable (large framework, paywalled stylesheet, named
92
+ system without a fetchable source), compose CSS in its spirit — typography,
93
+ color, density cues drawn from the named system. Only fall back to the
94
+ default style when no preference signal exists.
95
+
96
+ The single-file invariant is preserved either way. External
97
+ `<link rel="stylesheet">` is permitted only for CDN webfont CSS (with the
98
+ offline fallback font stack); never link to an external stylesheet
99
+ carrying layout, color, or typography rules the doc cannot read offline.
100
+
101
+ ### DESIGN.md discovery
102
+
103
+ When tier 3 of the precedence stack applies, look for a DESIGN.md file in
104
+ these locations, first match wins:
105
+
106
+ 1. Worktree root (resolve via `git rev-parse --show-toplevel`).
107
+ 2. `docs/DESIGN.md`.
108
+ 3. `.compound-engineering/DESIGN.md`.
109
+
110
+ Read once at compose time. Absent → fall through to the fallback default.
111
+
112
+ Worktree-root only — do not fall through to a main checkout. Users
113
+ working from a worktree who want HTML defaults can add DESIGN.md to the
114
+ worktree.
115
+
116
+ **DESIGN.md is a partial override, not all-or-nothing.** Real DESIGN.md
117
+ files vary widely: some are token tables, some are CSS variables, some are
118
+ prose; most are authored for a *product or marketing surface*, not a
119
+ long-form doc. The governing split: **take the brand's scale-independent
120
+ identity literally, own the scale-dependent layout values yourself, and
121
+ skip decoration.**
122
+
123
+ - **Take literally (scale-independent identity):** the color palette
124
+ (under the contrast rule), font *weight* and *style*, OpenType features,
125
+ and radius *character* (sharp vs rounded). These carry the brand and are
126
+ safe at any size.
127
+ - **Own it yourself (scale-dependent layout):** the **type size scale**
128
+ and **spacing magnitudes**. DESIGN.md values are almost always
129
+ product/marketing-scaled (display headings at 48-80px, airy ~96px
130
+ section gaps); read them only as *hierarchy*, then set doc-appropriate
131
+ values (body ~14-16px, headings ~1.2-1.6× body, comfortable paragraph
132
+ spacing).
133
+ - **Skip decoration:** decorative or atmospheric brand voltage with no
134
+ content to attach to in a doc — gradient orbs, full-bleed hero
135
+ photography, motion. Take the palette and feel; do not reproduce the
136
+ decoration.
137
+
138
+ Specific cases:
139
+
140
+ - **Fonts: load only open webfonts; never attempt a proprietary brand
141
+ face.** A self-contained doc can only load an open webfont (Google Fonts
142
+ or an open CDN) via the permitted webfont `<link>` plus an offline
143
+ fallback stack. **Assume a bespoke brand face is proprietary and do not
144
+ attempt to load it** — Airbnb Cereal, Coinbase Display/Sans, BMW Type,
145
+ Waldenburg, Circular and the like will not render in a single file;
146
+ trying just produces a broken fallback. Use the DESIGN.md's own fallback
147
+ chain, or a family-matched system stack (serif↔serif, sans↔sans,
148
+ mono↔mono). Load a named face *only* when it is a known open webfont
149
+ (Inter, Geist, Cal Sans, Roboto…); when unsure whether a face is open,
150
+ do not try. Honor the DESIGN.md's declared roles (`body` / `display` /
151
+ `mono`) and never promote a display/decorative face into a body or
152
+ small-text role. Net: reproduce the brand's serif-vs-sans structure and
153
+ weight voice, not necessarily its exact faces.
154
+ - **Typography-scale mismatch.** DESIGN.md typography tokens are usually
155
+ sized for product UI — marketing pages, app screens, hero sections —
156
+ with display headings at 48-80px. A long-form doc needs body at ~14-16px
157
+ and headings at ~1.2-1.6× body. When the size scale looks
158
+ product-scaled (the common case), use the **family**, **weight**, and
159
+ **OpenType feature** assignments (these carry the design language) and
160
+ pick the agent's own size scale for the doc surface. Apply DESIGN.md
161
+ sizes literally only when they are clearly doc-scaled — body 14-16px,
162
+ headings under ~32px.
163
+ - **Scope mismatch (product UI vs doc surface).** A DESIGN.md aimed at
164
+ product marketing or app UI may name button states, input borders, or
165
+ hero backgrounds tied to *that* surface, not a generic doc. The page
166
+ surface is the case to judge: a **reading canvas** — white, off-white,
167
+ or a legible dark — transfers **literally** and should be the doc
168
+ background; a bright product/marketing-hero surface
169
+ (`--surface: #c0f0fb`) does not — extract the principle (the design
170
+ language uses a tinted surface) rather than the literal value when the
171
+ token is product-UI-scoped.
172
+ - **Partial coverage.** When DESIGN.md defines some categories but not
173
+ others (colors but no spacing scale, typography but no elevation), use
174
+ it for what it covers and the fallback default for the rest. Do not
175
+ require DESIGN.md to be complete before honoring it.
176
+
177
+ ## Format principles
178
+
179
+ These shape what "good" HTML looks like; the agent applies them per
180
+ artifact based on content.
181
+
182
+ ### Readable measure, not full bleed
183
+
184
+ Long-form text is unreadable at full viewport width — past ~80 characters
185
+ per line the eye loses the return sweep and scanning slows. As a
186
+ fallback-default (precedence tier 4, overridden by in-session direction or
187
+ DESIGN.md), center the document in a content container and hold prose to a
188
+ comfortable measure.
189
+
190
+ - **Page container.** A centered column with a max-width in the ~820-960px
191
+ band (`margin-inline: auto`) keeps the doc off the far edges of wide
192
+ monitors while leaving room for the format's richer shapes.
193
+ - **Prose measure.** Hold running paragraphs to roughly 65-80 characters
194
+ (`max-width: ~70ch` on text blocks). The named test: read a paragraph at
195
+ full window width on a wide display — if the return sweep to the next
196
+ line is effortful, the measure is too wide.
197
+ - **Let wide content break out.** Tables, diagrams, and side-by-side
198
+ columns may use the full container width (or wider) when the content
199
+ needs it — the measure constraint is for prose, not for everything.
200
+
201
+ Express the constraint in `ch`/`rem` rather than a single hardcoded pixel
202
+ value so it survives font-size and DESIGN.md overrides. DESIGN.md or an
203
+ in-session instruction overrides these values; this is the fallback when no
204
+ layout preference exists.
205
+
206
+ ### Markdown source is content, not design
207
+
208
+ When markdown (or markdown-shaped chat context) is part of the input, use
209
+ it for semantic content — what the doc is about, what sections exist,
210
+ what facts each section establishes. Do NOT treat its bullet-vs-table
211
+ presentation choices as authoritative; re-choose the rendering per
212
+ content shape in HTML's richer affordance space. If the markdown rendered
213
+ 13 requirements as a bulleted list, that does NOT mean HTML must render
214
+ them as a list — ask whether 13 items sharing `ID + body` shape deserve
215
+ a table.
216
+
217
+ ### Prose is authoritative
218
+
219
+ When a visualization disagrees with the surrounding prose, the prose
220
+ governs. If they diverge, the visualization is wrong.
221
+
222
+ ### Hyperlink the reference index
223
+
224
+ When the doc has a Sources & References (or equivalent reference-index)
225
+ section, hyperlink each entry to its canonical destination so readers
226
+ can open it directly. A long bare-text list of paths and ticket IDs is
227
+ the format's biggest unforced UX miss — the reader has to copy-paste
228
+ every entry into a browser or IDE.
229
+
230
+ Resolve the repo's GitHub URL once at compose time:
231
+
232
+ ```bash
233
+ git remote get-url origin
234
+ ```
235
+
236
+ Apply linking to three reference shapes:
237
+
238
+ - **Repo-relative code/doc paths** (`services/foo.ts`,
239
+ `docs/solutions/bar.md`) → `<repo-url>/blob/main/<path>`.
240
+ - **Named GitHub PRs/issues** (`PR #636`, `issue #1048`) →
241
+ `<repo-url>/pull/636` or `<repo-url>/issues/1048`.
242
+ - **Named external trackers** (Linear `ESP-1705`, Jira `PROJ-123`) →
243
+ link only when the workspace URL is established in loaded context
244
+ (e.g., a `linear.app/<workspace>/...` URL appeared earlier in the
245
+ session or in `AGENTS.md`); otherwise leave as text.
246
+
247
+ **Do not invent URLs.** If `origin` isn't a GitHub URL (GitLab,
248
+ Bitbucket, internal host) and the equivalent main-tree URL pattern
249
+ isn't obvious, leave entries as `<code>` text. If the external
250
+ tracker workspace isn't established, leave as text. A broken or
251
+ guessed link is worse than no link.
252
+
253
+ **Scope: reference index only, not inline prose.** Inline `<code>`
254
+ mentions of paths or PRs inside paragraph prose stay as code or text.
255
+ Linking every mention would clutter; readers expect clickable jumps
256
+ where the doc presents itself as a reference index.
257
+
258
+ ### Stable section anchors for unified plans
259
+
260
+ When rendering a unified plan, every major logical section gets a stable
261
+ anchor ID and visible heading text:
262
+
263
+ | Logical section | Required id |
264
+ |---|---|
265
+ | Goal Capsule | `goal-capsule` |
266
+ | Product Contract | `product-contract` |
267
+ | Product Requirements | `product-requirements` |
268
+ | Planning Contract | `planning-contract` |
269
+ | Implementation Units | `implementation-units` |
270
+ | Verification Contract | `verification-contract` |
271
+ | Definition of Done | `definition-of-done` |
272
+ | Appendix | `appendix` |
273
+
274
+ Long HTML plans are agent-consumed as source text as often as they are read in
275
+ a browser. Keep the heading text visible and adjacent to the `id`; do not rely
276
+ on a nav link alone to carry the section name.
277
+
278
+ ### Text contrast is local
279
+
280
+ Every text-on-background pairing must hold up on its own. A color that
281
+ works for prose on the page background does not automatically work for
282
+ a small label inside a tinted container. The most common violation:
283
+ applying a generic "muted" text variable (calibrated for prose-on-bg) to
284
+ secondary text inside an accent-soft / warn-soft / info-soft container.
285
+
286
+ Test by reading each filled shape's labels at the rendered scale. If the
287
+ subtitle or secondary text feels washed-out against the fill, the choice
288
+ is wrong for that local context — pick a color from the same family as
289
+ the fill (accent-text for accent-soft, etc.) or drop the muting entirely
290
+ and rely on font-size and weight for hierarchy.
291
+
292
+ ### Body bold not colored by default
293
+
294
+ Reserve accent text color for status chips, ID chips, links, and section
295
+ borders. Do NOT color `<strong>` in body content by default. Bold weight
296
+ already carries emphasis; applying accent color to every `<strong>` in a
297
+ long list overwhelms the eye, especially in dark mode. CSS should leave
298
+ `strong` at `color: inherit` unless a specific surface (status pill, ID
299
+ chip) is being styled.
300
+
301
+ ### Chips and pills: uniform shape, no one-sided accent
302
+
303
+ Status chips, ID chips, and metric pills in the same row share one shape
304
+ — same border-radius, border weight, and fill treatment. Differentiate
305
+ categories only by the chip's overall fill/text color (applied to the
306
+ whole pill, like a soft-tint badge), never by an accent on one edge. A
307
+ colored stripe or arc on a single side of a pill reads as broken and
308
+ asymmetric — as if a border half-failed to render — so avoid it. The same
309
+ holds for any element, not just chips: differentiate by a full tint, not
310
+ a colored stripe on one edge. If an ID chip should stand out from metric
311
+ chips, vary its fill/text color uniformly, not its edge treatment, and
312
+ keep every chip in the row a visual set.
313
+
314
+ ### No JS framework runtimes
315
+
316
+ A small inline `<script>` for active-section TOC tracking or anchor-
317
+ permalink behavior is acceptable. React, Vue, Svelte, or any framework
318
+ runtime is not. The single-file invariant doesn't permit framework
319
+ bundles, and the artifact's longevity doesn't warrant a build dependency.
320
+
321
+ ## Section anatomy
322
+
323
+ How section types commonly render in HTML. These are patterns, not
324
+ contracts — the agent picks shapes that fit the content.
325
+
326
+ - **Summary / Problem Frame** — semantic `<section>` with prose
327
+ paragraphs. Optionally precede with an eyebrow label (small-caps tag
328
+ above the title) for editorial polish.
329
+ - **Requirements** — `<table>` is the default at 5+ uniform items;
330
+ bullets at smaller counts. Concern-grouping takes precedence over the
331
+ flat-table default: when requirements span distinct concerns, group them
332
+ under bold inline headers (or per-group sections) first, then apply the
333
+ 5+ table default *within* each group rather than flattening the whole
334
+ section into one table. Each row has the R-ID as visible text in
335
+ its own column. Consider adding a "covered by" column for reverse
336
+ traceability when ID-anchored items have downstream references in
337
+ the same doc.
338
+ - **Implementation Units** — repeating `<article>` cards with a stable
339
+ ID chip (visible "U1" text), a metadata strip (`<dl>` with field
340
+ labels and values for Goal, Files, Dependencies), and secondary
341
+ content (Approach, Test Scenarios, Verification, Patterns to Follow)
342
+ inside `<details>` collapsibles, **default-closed**. At 3+ units the
343
+ default-closed rule is load-bearing — rendering all units fully
344
+ expanded turns the doc into one continuous scroll where the reader
345
+ can't see the unit list at a glance. The metadata strip is the
346
+ primary always-visible surface; subsection labels (`<summary>`) are
347
+ clickable affordances for readers to expand on demand. A single unit
348
+ with no secondary content can skip `<details>` entirely; the rule
349
+ fires when content exists to hide. The `<dl>` strip is for *descriptive*
350
+ fields (Goal, Files, Dependencies). A *directive* field — `Execution
351
+ note` is the canonical case, carrying a procedural instruction the
352
+ implementer must act on (e.g. "start with a failing integration test") —
353
+ does not belong in the strip, where it renders as a passive pair styled
354
+ like a date and gets skimmed past. Render it as an advisory callout (see
355
+ Tinted callout cards) so its visual weight matches its actionability. The
356
+ test: descriptive value -> metadata pair; something the reader must act
357
+ on -> callout.
358
+ - **Key Technical Decisions** — repeating cards with the decision ID,
359
+ bold decision title (often with inline code for technical
360
+ identifiers), and prose rationale. Flat cards (not collapsibles) —
361
+ these are reference material readers scan, not drill into. A
362
+ `session-settled:` annotation renders as visible text in the card —
363
+ never an attribute or hidden markup — stem preserved verbatim so
364
+ grep works on the HTML artifact.
365
+ - **Risks** — cards with a color-coded status eyebrow (e.g., "RISK ·
366
+ MITIGATED" / "OPEN · DEFERRED FOLLOW-UP") and prose body. Communicate
367
+ status through the eyebrow's color plus an optional subtle full-card
368
+ tint — not a colored stripe on one edge (see "Chips and pills").
369
+ - **Scope Boundaries** — callout cards distinguished (in-scope vs deferred
370
+ vs outside) by a colored eyebrow/label plus a subtle full-card tint when
371
+ the distinction is meaningful — not a one-edge colored stripe.
372
+
373
+ The agent picks more elaborate or simpler shapes based on what each
374
+ specific artifact's content needs.
375
+
376
+ ## Diagrams
377
+
378
+ When the section contract calls for a diagram (architecture, sequence,
379
+ flowchart, state machine, swim lane, data-flow, quantitative
380
+ comparison), HTML renders it as **inline SVG**. The agent picks the
381
+ shape that conveys the content fastest — there is no fixed catalog of
382
+ "approved" diagram types. If the content is quantitative comparison
383
+ across categories, a bar chart is the right shape; if it's component
384
+ relationships, a topology diagram; if it's process flow across
385
+ participants, a swim lane; etc.
386
+
387
+ **Conceptual diagrams are not wireframes.** The wireframe affordance below
388
+ is scoped to *UI-shaped requirements* and is excluded for non-visual
389
+ systems. That exclusion is about wireframes only —
390
+ a brainstorm about a data model, schema, agent workflow, or migration is
391
+ still free to use a conceptual diagram (a before/after field map, a
392
+ source-of-truth fan-out, a state diagram). Don't let the wireframe
393
+ exclusion suppress a conceptual diagram the content warrants.
394
+
395
+ **Diagrams complement prose; they never replace it.** A diagram is an
396
+ accelerant placed next to the prose it illustrates, not a substitute. The
397
+ IDed prose stays complete and standalone — a reader who ignores every
398
+ diagram still gets the full content in text, and a text-reading downstream
399
+ agent (which does not parse SVG geometry) is never left with a relationship
400
+ that exists only in the picture. This extends the prose-is-authoritative
401
+ rule above: prose governs not only on disagreement but on completeness, so
402
+ adding a diagram is not license to thin the prose it depicts.
403
+
404
+ ### Layout legibility for hand-authored SVG
405
+
406
+ The agent designs SVG coordinates without rendering — layouts that look
407
+ fine in source can collide in practice. Before emitting, trace each
408
+ labeled arrow, each shape edge, and each text label:
409
+
410
+ - **No stroke — arrow *or* shape edge/border — passes through a text
411
+ label.** If an arrow line/curve, or the border of a box, parallelogram,
412
+ or other shape, crosses a label's bounding box, the text reads as
413
+ struck-through and the stroke reads as terminating at the wrong element.
414
+ Fix by re-routing the arrow, moving the label clear of every edge, or
415
+ applying `paint-order: stroke fill` with a stroke color matching the
416
+ diagram background to halo the label. The halo width is a judgment call:
417
+ narrow enough not to bleed into glyph strokes (a halo whose width
418
+ approaches the glyph's own stroke width muddies the text color), wide
419
+ enough to mask the underlying stroke (at least its stroke width
420
+ plus a hairline). Verify by inspecting rendered text at the target
421
+ font size — if glyphs look thicker or more colored-toward-halo than
422
+ the same text outside the diagram, the halo is too wide.
423
+ - **Labels inside skewed or rotated shapes sit in the shape's true
424
+ interior, not its bounding box.** A parallelogram, isometric face, or
425
+ rotated rect has an interior offset from its bounding box, so a
426
+ box-aligned (e.g. left-aligned) label spills past the slanted edge.
427
+ Inset the label to fall inside the actual shape — account for the
428
+ skew/rotation offset at the label's vertical position — or place it
429
+ outside the shape with a short leader. This is the usual failure in the
430
+ **stacked-layers idiom** (offset parallelograms implying z-order), where
431
+ per-layer labels left-aligned to the container both overflow the lower
432
+ layers and get crossed by the neighbouring layer's edge. Prefer
433
+ labelling each layer in its own un-overlapped region, or to the side of
434
+ the stack.
435
+ - **Arrow labels sit adjacent to the arrow's midpoint** (typically
436
+ within ~10-15px above or beside the line they describe). A label
437
+ floating at the diagram's edge that readers have to trace back to an
438
+ arrow is broken — readers will misread.
439
+ - **Avoid long curves that traverse the diagram** to connect a
440
+ component on one side to one on the other. If A and D need a labeled
441
+ connection across a multi-component layout, prefer reordering boxes
442
+ so A and D are adjacent, numbered step badges next to each
443
+ participant that the caption ties together, or a short
444
+ labeled-channel notation — rather than one curve crossing multiple
445
+ unrelated elements.
446
+ - **Differentiate diagram shapes by geometry first, by fill semantics
447
+ second.** Geometry (diamond = decision, rect = step, oval =
448
+ start/end, parallelogram = data) carries the role unambiguously.
449
+ Fill semantics (accent-soft for highlighted path, warn-soft for
450
+ fallthrough) carry meaning. Resist introducing additional neutral-tint
451
+ tiers (a slightly-lighter grey to mark "decision shapes are different
452
+ from boxes") — when geometry already differentiates, an additional
453
+ luminance tier adds no information and creates fragility: small RGB
454
+ deltas survive native browser rendering but can be flattened or
455
+ inverted inconsistently by dark-mode extensions, accessibility
456
+ plugins, or printing.
457
+
458
+ ### Plan architecture diagrams are not directional sketches
459
+
460
+ Do not add hedging captions or section preambles to plan SVG diagrams —
461
+ phrases like "directional guidance for review, not implementation
462
+ specification" do not belong on plan diagrams or on unit-card
463
+ technical-design subsections. Plan diagrams render the same authoritative
464
+ content as the surrounding prose; the prose-is-authoritative rule
465
+ already governs disagreement. Hedging language is reserved for the
466
+ wireframe affordance below, which carries a *required* directional
467
+ caption because the wireframe is explicitly NOT a spec.
468
+
469
+ ## Wireframe mockups (requirements docs only)
470
+
471
+ When a brainstorm requirement describes a user-facing visual surface (UI
472
+ feature, screen layout, screen flow, component placement), the HTML
473
+ rendering may include a wireframe mockup. The trigger is the
474
+ **requirement**, not the document: any requirement (or requirements group)
475
+ with a UI/layout shape can carry a wireframe, whether or not the brainstorm
476
+ as a whole is "a visual product" — a backend-heavy brainstorm with one
477
+ screen change still earns a wireframe for that requirement. It still applies
478
+ to brainstorm **requirements** output — the requirements-only unified plan
479
+ `ce-brainstorm` writes (now under `docs/plans/`), not an implementation-ready
480
+ plan (`ce-plan`'s enriched output) — and only to UI-shaped requirements — a
481
+ non-visual requirement (API design, data model, agent workflow,
482
+ infrastructure) takes a conceptual diagram instead, not a
483
+ wireframe.
484
+
485
+ When a wireframe is included:
486
+
487
+ - **Fidelity ceiling: wireframe, not mockup.** Gray boxes for layout
488
+ regions, text labels for content placeholders, intentional placeholder
489
+ copy (`[Product name]`, `[CTA label]`, `[user avatar]`). No
490
+ pixel-perfect colors, no exact typography choices, no specific
491
+ component-library references. The wireframe communicates spatial
492
+ arrangement and structure, not visual style.
493
+ - **Static only.** Inline SVG or simple HTML/CSS for layout. No JS
494
+ interaction, no working form fields, no state changes, no live data.
495
+ - **Anti-padding.** One wireframe per distinct visual concept.
496
+ - **Mandatory directional caption.** Every wireframe carries an explicit
497
+ "directional, not the spec" note adjacent to it. Required wording (or
498
+ close paraphrase): *"Directional only — illustrates the intended
499
+ user-facing shape. Exact colors, spacing, copy, and component choices
500
+ are placeholders for review, not requirements."*
501
+
502
+ Without this caption the wireframe risks being read as a binding visual
503
+ spec, which the affordance is explicitly designed to avoid.
504
+
505
+ ## Affordance idioms
506
+
507
+ Common HTML affordances the agent can reach for when content benefits.
508
+ These are examples, not requirements — the agent picks what each
509
+ artifact's content warrants. Other affordances not listed here are
510
+ fine when the content suggests them.
511
+
512
+ - **Sticky TOC sidebar with active-section indicator** — available when
513
+ the agent judges navigation will materially help and the
514
+ implementation is reliable: two-column layout on desktop, collapsed
515
+ to top-of-page on mobile, paired with a small inline
516
+ `IntersectionObserver` script that toggles `.active` on the matching
517
+ nav anchor. Trade-off: a broken sticky TOC (layout collisions,
518
+ active-section state drift, dark-mode CSS issues) is worse than a
519
+ static top-of-doc TOC. For most long docs, default-closed `<details>`
520
+ on repeating cards (see Implementation Units anatomy) already cuts
521
+ the visible scroll length enough that a static TOC works — reach for
522
+ sticky only when collapsibles alone don't solve the navigation
523
+ problem.
524
+ - **Within-section sub-nav** for sections containing 6+ repeating cards
525
+ (Implementation Units, KTDs, Risks at large counts). A short list of
526
+ card-anchor links (`<ul>` of `<a href="#u1">U1. ...</a>`) rendered at
527
+ the top of the section gives readers a jump table — no JS needed.
528
+ Lower-complexity alternative to the sticky TOC for the specific case
529
+ of long card sections.
530
+ - **Eyebrow labels** (small-caps tag above section titles) for
531
+ editorial polish, especially when section titles are narrative
532
+ rather than literal.
533
+ - **Stats strip** at the top of the doc when the artifact has 3+
534
+ quantifiable signals worth surfacing at a glance.
535
+ - **`<details>` + `<summary>`** for collapsible secondary content
536
+ inside repeating cards. All collapsibles start closed — `open`
537
+ attribute should not appear on any `<details>` inside repeating
538
+ cards by default.
539
+ - **Side-by-side columns** for parallel content (Request / Response,
540
+ Before / After, Two alternatives).
541
+ - **Tinted callout cards** for content that is "different in kind"
542
+ (Deferred, Open Questions, advisory notes, unit-level execution notes)
543
+ — a subtle full-card background tint plus a colored eyebrow/label
544
+ communicates kind at a glance. Avoid a colored stripe on one edge; tint
545
+ the whole card instead.
546
+
547
+ ## Agent-consumability rules
548
+
549
+ Downstream agents that read HTML today (`ce-work`, a skill re-reading its
550
+ own prior artifact on a resume run, future consumers) reason over the HTML
551
+ as text — the way they reason over markdown, not via DOM extraction or a
552
+ script-style parse. `ce-doc-review` is not a current HTML consumer (see
553
+ opening note).
554
+
555
+ These rules are why such a consumer can locate one item (a single
556
+ requirement, unit, idea, or other ID-bearing entry) and reason over it from
557
+ source alone — its title, every labeled field, and any diagram's meaning —
558
+ with no hidden machine-readable copy to fall back on. The semantic structure
559
+ *is* the extraction contract: it is what makes the single-source-of-truth
560
+ invariant (no `data-*` or JSON metadata mirror) safe rather than lossy.
561
+ Weakening it — `<article>` item boundaries collapsed into `<div>` soup, a
562
+ field label demoted to an attribute, one item's content scattered across
563
+ distant parts of the doc — breaks that reasoning even when the rendered page
564
+ looks identical. Compose so semantic understanding is reachable in source:
565
+
566
+ - **Use semantic HTML over `<div>` soup.** `<article>` per unit card,
567
+ `<dl>` for metadata pairs, `<table>` for tabular content, `<details>`
568
+ / `<summary>` for collapsibles, `<section>` for top-level doc
569
+ sections. Structure markers carry meaning to a text-reading agent.
570
+ - **Render field labels as visible text, not as attributes.** Emit
571
+ `<dt>GOAL</dt><dd>...</dd>`, not `<dd data-field="goal">...</dd>`.
572
+ The label is the semantic anchor.
573
+ - **Keep U-IDs, R-IDs, and similar as visible text** in headings and
574
+ table cells, not only as `id=""` attributes. The agent finds "U1." in
575
+ source the same way it finds "U1." in markdown.
576
+ - **Match section heading vocabulary to what the section contract
577
+ defines.** When the section contract says "Implementation Units," the
578
+ HTML heading is "Implementation Units" — not "How we'll build it,"
579
+ even if the narrative version reads better. Section heading
580
+ vocabulary is the contract downstream consumers grep for. (Editorial
581
+ re-titles can appear as eyebrow labels, sub-headings, or visual
582
+ framing — but the load-bearing section heading matches the contract
583
+ name.)
584
+ - **All semantic content lives in actual HTML text.** No CSS `::before
585
+ { content: "..." }` carrying meaning, no background images as
586
+ content, no semantic info that only renders. Whatever the agent sees
587
+ in source is what it knows.
588
+ - **Stable structure is the public API.** Element types, the ID and
589
+ label scheme, and the field-label vocabulary do not break across
590
+ versions. Visual styling can change freely.
591
+
592
+ ## Post-compose audit
593
+
594
+ Before returning the artifact, scan it for common slips:
595
+
596
+ - **Single self-contained file.** No companion `.css` / `.js` / `.svg`.
597
+ - **No hidden machine-readable metadata copy.** No
598
+ `<script type="application/json">` frontmatter block, no `data-*`
599
+ attributes mirroring visible values, **no `<meta name="created">` /
600
+ `<meta name="origin">` etc. in `<head>`
601
+ duplicating the visible header**. Metadata lives in visible text;
602
+ one source of truth per value.
603
+ - **All stable IDs** appear as both `id=""` and visible text.
604
+ - **Section heading vocabulary** matches the section contract names
605
+ (downstream agents grep these).
606
+ - **Source / composition signal** is present as a visible footer at
607
+ the bottom of the doc (composition timestamp + source identifier).
608
+ - **Repeating cards with 3+ instances put secondary content inside
609
+ default-closed `<details>`.** Fully-expanded unit cards in a long
610
+ Implementation Units section is a failure mode — the reader can't see
611
+ the unit list at a glance. Verify by skimming the rendered units:
612
+ each `<article>` should render as its ID + title + metadata strip
613
+ with collapsibles below, not as one long block.
614
+ - **Within-section sub-nav** is present for sections with 6+ repeating
615
+ cards.
616
+ - **Body `<strong>`** is not colored with accent palette.
617
+ - **No one-edge colored accent** (a colored stripe/arc on a single side)
618
+ on chips, pills, or callout cards — differentiate by uniform fill +
619
+ colored eyebrow/label instead. A one-sided stripe reads as
620
+ broken/unintentional; chips in a row must be a uniform visual set.
621
+ - **`<details>`** inside repeating cards have no `open` attribute.
622
+ - **Diagram labels** are legible — no arrow paths crossing text,
623
+ halo width appropriate for font size.
624
+ - **Diagrams complement prose, not replace it.** Every relationship a
625
+ diagram conveys is also present in the surrounding IDed prose; no
626
+ content lives only in an SVG.
627
+ - **No JS framework runtimes** included. Small inline `<script>` for
628
+ active-section TOC tracking or anchor-permalink behavior is the only
629
+ acceptable JS.
630
+ - **Each heading level** is visually distinct from others and from
631
+ inline bold.
632
+ - **No template placeholders** (`{skill}`, `<value>`, `[plan title]`)
633
+ leaked into output.
634
+ - **No process exhaust** callouts in the artifact.