@adia-ai/adia-ui-forge 0.1.3 → 0.8.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 (259) hide show
  1. package/.claude-plugin/plugin.json +3 -6
  2. package/CHANGELOG.md +27 -34
  3. package/README.md +35 -40
  4. package/agents/a2ui-engineer.md +22 -53
  5. package/agents/component-author.md +29 -0
  6. package/agents/framework-verifier.md +26 -0
  7. package/agents/release-engineer.md +21 -81
  8. package/agents/routing-corpus.json +293 -64
  9. package/bin/demo-postwrite-pattern-gate +94 -0
  10. package/bin/forge-lint +17 -2
  11. package/bin/sidecar-prewrite-guard +104 -0
  12. package/commands/deploy.md +9 -0
  13. package/commands/dogfood.md +10 -0
  14. package/commands/gen-review.md +9 -0
  15. package/commands/release.md +10 -0
  16. package/hooks/hooks.json +15 -0
  17. package/package.json +3 -6
  18. package/references/contracts/a2ui-mcp-surface.md +35 -0
  19. package/references/contracts/migration-guide-format.md +34 -0
  20. package/references/shared/content-trust.md +19 -74
  21. package/skills/adia-a2ui/SKILL.md +99 -0
  22. package/skills/{adia-ui-a2ui → adia-a2ui}/evals/routing-corpus.json +10 -10
  23. package/skills/adia-a2ui/references/anti-patterns.md +27 -0
  24. package/skills/adia-a2ui/references/chunk-authoring.md +71 -0
  25. package/skills/adia-a2ui/references/corpus-discipline.md +68 -0
  26. package/skills/adia-a2ui/references/eval-diagnostics.md +86 -0
  27. package/skills/adia-a2ui/references/format-extension-decisions.md +66 -0
  28. package/skills/adia-a2ui/references/leverage-rules.md +52 -0
  29. package/skills/adia-a2ui/references/mcp-pipeline-ops.md +83 -0
  30. package/skills/adia-a2ui/references/mcp-tool-reference.md +59 -0
  31. package/skills/adia-a2ui/references/pipeline-overview.md +115 -0
  32. package/skills/adia-a2ui/references/semantic-fail-lifting.md +74 -0
  33. package/skills/adia-a2ui/references/strategy-engines.md +109 -0
  34. package/skills/adia-a2ui/references/zettel-calibration.md +104 -0
  35. package/skills/adia-author/SKILL.md +112 -0
  36. package/skills/adia-author/evals/routing-corpus.json +222 -0
  37. package/skills/{adia-ui-authoring → adia-author}/references/anti-patterns.md +33 -4
  38. package/skills/{adia-ui-authoring → adia-author}/references/authoring-cycle.md +9 -11
  39. package/skills/adia-author/references/canonical-pattern-index.md +243 -0
  40. package/skills/{adia-ui-authoring → adia-author}/references/code-style.md +19 -21
  41. package/skills/adia-author/references/common-gotchas.md +129 -0
  42. package/skills/adia-author/references/composite-demo-protocol.md +271 -0
  43. package/skills/{adia-ui-authoring → adia-author}/references/css-patterns.md +19 -6
  44. package/skills/{adia-ui-authoring → adia-author}/references/lifecycle-patterns.md +1 -0
  45. package/skills/{adia-ui-authoring → adia-author}/references/llm-bridge.md +3 -5
  46. package/skills/{adia-ui-authoring → adia-author}/references/module-promotion.md +20 -38
  47. package/skills/{adia-ui-authoring → adia-author}/references/primitive-audit.md +2 -4
  48. package/skills/{adia-ui-authoring → adia-author}/references/shell-patterns.md +12 -18
  49. package/skills/{adia-ui-authoring → adia-author}/references/token-contract.md +5 -7
  50. package/skills/{adia-ui-authoring → adia-author}/references/worked-example.md +3 -3
  51. package/skills/{adia-ui-authoring → adia-author}/references/yaml-contract.md +3 -3
  52. package/skills/{adia-ui-authoring → adia-author}/scripts/build-canonical-pattern-index.mjs +3 -3
  53. package/skills/adia-deploy/SKILL.md +128 -0
  54. package/skills/{adia-ui-ops → adia-deploy}/references/deploy-playbooks.md +47 -30
  55. package/skills/adia-dogfood/SKILL.md +124 -0
  56. package/skills/adia-dogfood/references/admin-shell-anatomy.md +77 -0
  57. package/skills/adia-dogfood/references/app-shell-pitfalls.md +66 -0
  58. package/skills/adia-dogfood/references/card-anatomy-sweep.md +66 -0
  59. package/skills/adia-dogfood/references/html-attr-sweep.md +63 -0
  60. package/skills/adia-dogfood/references/native-leak-annotations.md +73 -0
  61. package/skills/adia-dogfood/references/visual-probe-triage.md +80 -0
  62. package/skills/{adia-ui-dogfood → adia-dogfood}/scripts/analyze.mjs +30 -14
  63. package/skills/adia-gen-review/SKILL.md +127 -0
  64. package/skills/adia-gen-review/references/corpus-html-patterns.md +279 -0
  65. package/skills/adia-gen-review/references/loop-protocol.md +216 -0
  66. package/skills/adia-gen-review/references/rubric-cosmetic.md +100 -0
  67. package/skills/adia-gen-review/references/rubric-decompose.md +101 -0
  68. package/skills/adia-gen-review/references/rubric-score.md +214 -0
  69. package/skills/{adia-ui-gen-review → adia-gen-review}/references/scores.schema.json +2 -2
  70. package/skills/{adia-ui-gen-review → adia-gen-review}/scripts/gen-review-coverage-audit.mjs +4 -4
  71. package/skills/{adia-ui-gen-review → adia-gen-review}/scripts/gen-review-decompose.mjs +10 -6
  72. package/skills/{adia-ui-gen-review → adia-gen-review}/scripts/gen-review-status.mjs +5 -5
  73. package/skills/{adia-ui-gen-review → adia-gen-review}/scripts/validate-cycle-scores.mjs +5 -5
  74. package/skills/adia-llm-internals/SKILL.md +77 -0
  75. package/skills/{adia-ui-llm → adia-llm-internals}/references/adapter-contract.md +4 -2
  76. package/skills/{adia-ui-llm → adia-llm-internals}/references/add-a-provider.md +4 -5
  77. package/skills/{adia-ui-llm → adia-llm-internals}/references/bridge-facade.md +10 -3
  78. package/skills/{adia-ui-llm → adia-llm-internals}/references/browser-proxy-boundary.md +1 -1
  79. package/skills/{adia-ui-llm → adia-llm-internals}/references/model-registry.md +5 -3
  80. package/skills/{adia-ui-llm → adia-llm-internals}/references/streaming-sse.md +2 -2
  81. package/skills/adia-release/SKILL.md +72 -0
  82. package/skills/adia-release/references/changelog-discipline.md +119 -0
  83. package/skills/adia-release/references/cut-procedure.md +247 -0
  84. package/skills/adia-release/references/gates-catalog.md +222 -0
  85. package/skills/adia-release/references/independent-package-release.md +52 -0
  86. package/skills/adia-release/references/migration-guide-authoring.md +86 -0
  87. package/skills/adia-release/references/notes-authoring.md +90 -0
  88. package/skills/adia-release/references/recovery-paths.md +106 -0
  89. package/skills/{adia-ui-release → adia-release}/scripts/bump.mjs +27 -2
  90. package/skills/{adia-ui-release → adia-release}/scripts/dispatch-publish.mjs +4 -1
  91. package/skills/{adia-ui-release → adia-release}/scripts/insert-stub.mjs +1 -1
  92. package/skills/{adia-ui-release → adia-release}/scripts/package-paths.mjs +6 -0
  93. package/skills/{adia-ui-release → adia-release}/scripts/promote-unreleased.mjs +1 -1
  94. package/skills/{adia-ui-release → adia-release}/scripts/release-pack.mjs +13 -21
  95. package/skills/{adia-ui-release → adia-release}/scripts/tag-lockstep.mjs +5 -1
  96. package/skills/adia-site-docs/SKILL.md +68 -0
  97. package/skills/adia-site-docs/evals/audit-report.md +30 -0
  98. package/skills/adia-site-docs/evals/routing-corpus.json +176 -0
  99. package/skills/adia-site-docs/intent.md +72 -0
  100. package/agents/README.md +0 -209
  101. package/agents/author.md +0 -56
  102. package/agents/repo-steward.md +0 -56
  103. package/agents/spec-architect.md +0 -53
  104. package/agents/tech-lead.md +0 -57
  105. package/agents/verifier.md +0 -55
  106. package/bin/lib/audit-axes.mjs +0 -555
  107. package/bin/lib/dry-run-irreversible.mjs +0 -236
  108. package/bin/lib/run-skill-evals.mjs +0 -487
  109. package/bin/lib/teach-router.mjs +0 -250
  110. package/commands/adia-forge-a2ui.md +0 -10
  111. package/commands/adia-forge-author.md +0 -10
  112. package/commands/adia-forge-dogfood.md +0 -8
  113. package/commands/adia-forge-llm.md +0 -8
  114. package/commands/adia-forge-orient.md +0 -10
  115. package/commands/adia-forge-release.md +0 -8
  116. package/commands/adia-forge-review.md +0 -10
  117. package/references/shared/pev-rationale.md +0 -64
  118. package/references/shared/skill-conventions.md +0 -133
  119. package/skills/adia-ui-a2ui/CHANGELOG.md +0 -32
  120. package/skills/adia-ui-a2ui/SKILL.md +0 -243
  121. package/skills/adia-ui-a2ui/evals/adversarial-corpus.json +0 -75
  122. package/skills/adia-ui-a2ui/evals/teach-routing-cases.json +0 -100
  123. package/skills/adia-ui-a2ui/references/anti-patterns.md +0 -24
  124. package/skills/adia-ui-a2ui/references/chunk-authoring.md +0 -88
  125. package/skills/adia-ui-a2ui/references/corpus-discipline.md +0 -56
  126. package/skills/adia-ui-a2ui/references/eval-diagnostics.md +0 -127
  127. package/skills/adia-ui-a2ui/references/fragment-graph.md +0 -91
  128. package/skills/adia-ui-a2ui/references/mcp-pipeline-ops.md +0 -106
  129. package/skills/adia-ui-a2ui/references/mcp-tool-reference.md +0 -398
  130. package/skills/adia-ui-a2ui/references/pipeline-overview.md +0 -175
  131. package/skills/adia-ui-a2ui/references/semantic-fail-lifting.md +0 -120
  132. package/skills/adia-ui-a2ui/references/strategy-engines.md +0 -111
  133. package/skills/adia-ui-a2ui/references/teach-protocol.md +0 -220
  134. package/skills/adia-ui-a2ui/references/zettel-calibration.md +0 -93
  135. package/skills/adia-ui-a2ui/scripts/audit-a2ui-roster.mjs +0 -96
  136. package/skills/adia-ui-a2ui/scripts/teach-route.mjs +0 -157
  137. package/skills/adia-ui-a2ui/skill.json +0 -38
  138. package/skills/adia-ui-authoring/CHANGELOG.md +0 -32
  139. package/skills/adia-ui-authoring/SKILL.md +0 -256
  140. package/skills/adia-ui-authoring/assets/case-studies/admin-shell-decomposition.md +0 -101
  141. package/skills/adia-ui-authoring/assets/case-studies/maxtokens-32768-discovery.md +0 -109
  142. package/skills/adia-ui-authoring/assets/case-studies/theme-panel-promotion.md +0 -113
  143. package/skills/adia-ui-authoring/evals/adversarial-design-plan-gates.json +0 -138
  144. package/skills/adia-ui-authoring/evals/routing-corpus.json +0 -245
  145. package/skills/adia-ui-authoring/references/canonical-pattern-index.md +0 -179
  146. package/skills/adia-ui-authoring/references/common-gotchas.md +0 -93
  147. package/skills/adia-ui-authoring/references/composite-demo-protocol.md +0 -1084
  148. package/skills/adia-ui-authoring/references/teach-protocol.md +0 -428
  149. package/skills/adia-ui-authoring/scripts/audit-authoring-roster.mjs +0 -148
  150. package/skills/adia-ui-authoring/skill.json +0 -45
  151. package/skills/adia-ui-dogfood/CHANGELOG.md +0 -17
  152. package/skills/adia-ui-dogfood/README.md +0 -62
  153. package/skills/adia-ui-dogfood/SKILL.md +0 -866
  154. package/skills/adia-ui-dogfood/skill.json +0 -40
  155. package/skills/adia-ui-forge/SKILL.md +0 -88
  156. package/skills/adia-ui-forge/evals/routing-corpus.json +0 -30
  157. package/skills/adia-ui-gen-review/CHANGELOG.md +0 -108
  158. package/skills/adia-ui-gen-review/SKILL.md +0 -266
  159. package/skills/adia-ui-gen-review/references/loop-protocol.md +0 -712
  160. package/skills/adia-ui-gen-review/references/rubric-cosmetic.md +0 -144
  161. package/skills/adia-ui-gen-review/references/rubric-decompose.md +0 -117
  162. package/skills/adia-ui-gen-review/references/rubric-score.md +0 -249
  163. package/skills/adia-ui-gen-review/references/teach-protocol.md +0 -214
  164. package/skills/adia-ui-gen-review/skill.json +0 -23
  165. package/skills/adia-ui-llm/CHANGELOG.md +0 -25
  166. package/skills/adia-ui-llm/SKILL.md +0 -165
  167. package/skills/adia-ui-llm/evals/adversarial-corpus.json +0 -75
  168. package/skills/adia-ui-llm/evals/routing-corpus.json +0 -30
  169. package/skills/adia-ui-llm/evals/teach-routing-cases.json +0 -73
  170. package/skills/adia-ui-llm/references/teach-protocol.md +0 -78
  171. package/skills/adia-ui-llm/scripts/audit-llm-roster.mjs +0 -93
  172. package/skills/adia-ui-llm/scripts/teach-route.mjs +0 -119
  173. package/skills/adia-ui-llm/skill.json +0 -33
  174. package/skills/adia-ui-ops/CHANGELOG.md +0 -291
  175. package/skills/adia-ui-ops/SKILL.md +0 -401
  176. package/skills/adia-ui-ops/references/INDEX.md +0 -158
  177. package/skills/adia-ui-ops/references/audit-cadence.md +0 -263
  178. package/skills/adia-ui-ops/references/audit-patterns/archive-link-sweep.md +0 -96
  179. package/skills/adia-ui-ops/references/audit-patterns/audit-history-ledger.md +0 -162
  180. package/skills/adia-ui-ops/references/audit-patterns/browser-bundle-node-imports.md +0 -154
  181. package/skills/adia-ui-ops/references/audit-patterns/changelog-unreleased-bloat.md +0 -75
  182. package/skills/adia-ui-ops/references/audit-patterns/coverage-gaps.md +0 -187
  183. package/skills/adia-ui-ops/references/audit-patterns/entry-file-coverage.md +0 -122
  184. package/skills/adia-ui-ops/references/audit-patterns/format-hygiene.md +0 -217
  185. package/skills/adia-ui-ops/references/audit-patterns/lockstep-versioning.md +0 -113
  186. package/skills/adia-ui-ops/references/audit-patterns/memory-fragmentation.md +0 -180
  187. package/skills/adia-ui-ops/references/audit-patterns/orphan-detection.md +0 -202
  188. package/skills/adia-ui-ops/references/audit-patterns/pointer-validation.md +0 -180
  189. package/skills/adia-ui-ops/references/audit-patterns/redundancy-detection.md +0 -210
  190. package/skills/adia-ui-ops/references/audit-patterns/spec-dating-sweep.md +0 -91
  191. package/skills/adia-ui-ops/references/audit-patterns/stale-content.md +0 -182
  192. package/skills/adia-ui-ops/references/audit-patterns/staleness-tooling.md +0 -156
  193. package/skills/adia-ui-ops/references/audit-patterns/token-waste-detection.md +0 -196
  194. package/skills/adia-ui-ops/references/doc-types/adr-pattern.md +0 -210
  195. package/skills/adia-ui-ops/references/doc-types/architecture-md.md +0 -190
  196. package/skills/adia-ui-ops/references/doc-types/changelog.md +0 -183
  197. package/skills/adia-ui-ops/references/doc-types/decisions-log.md +0 -146
  198. package/skills/adia-ui-ops/references/doc-types/plan-roadmap.md +0 -182
  199. package/skills/adia-ui-ops/references/doc-types/postmortem-pattern.md +0 -206
  200. package/skills/adia-ui-ops/references/genres/prose-and-writing.md +0 -149
  201. package/skills/adia-ui-ops/references/guidance/context-budget.md +0 -137
  202. package/skills/adia-ui-ops/references/guidance/llm-doc-writing.md +0 -116
  203. package/skills/adia-ui-ops/references/guidance/reliability-dial.md +0 -186
  204. package/skills/adia-ui-ops/references/recipes/adr-introduction.md +0 -211
  205. package/skills/adia-ui-ops/references/recipes/audit-existing-repo.md +0 -234
  206. package/skills/adia-ui-ops/references/recipes/cold-start-harvest.md +0 -263
  207. package/skills/adia-ui-ops/references/recipes/concurrent-learnings-merge.md +0 -158
  208. package/skills/adia-ui-ops/references/recipes/continuous-learning-loop.md +0 -169
  209. package/skills/adia-ui-ops/references/recipes/external-reference-verification.md +0 -158
  210. package/skills/adia-ui-ops/references/recipes/findings-index-readout.md +0 -126
  211. package/skills/adia-ui-ops/references/recipes/greenfield-setup.md +0 -252
  212. package/skills/adia-ui-ops/references/recipes/harvest-repo-brain.md +0 -169
  213. package/skills/adia-ui-ops/references/recipes/import-repo-brain-harvest.md +0 -153
  214. package/skills/adia-ui-ops/references/recipes/memory-organization.md +0 -182
  215. package/skills/adia-ui-ops/references/recipes/recommend-then-validate.md +0 -199
  216. package/skills/adia-ui-ops/references/recipes/self-healing-hooks.md +0 -366
  217. package/skills/adia-ui-ops/references/recipes/skill-stewardship-loop.md +0 -113
  218. package/skills/adia-ui-ops/references/standards/agents-md-spec.md +0 -138
  219. package/skills/adia-ui-ops/references/standards/claude-md-convention.md +0 -123
  220. package/skills/adia-ui-ops/references/standards/cross-tool-matrix.md +0 -85
  221. package/skills/adia-ui-ops/references/standards/readme-conventions.md +0 -232
  222. package/skills/adia-ui-ops/references/teach-protocol.md +0 -215
  223. package/skills/adia-ui-ops/scripts/audit-ops-roster.mjs +0 -104
  224. package/skills/adia-ui-ops/skill.json +0 -65
  225. package/skills/adia-ui-release/CHANGELOG.md +0 -66
  226. package/skills/adia-ui-release/SKILL.md +0 -323
  227. package/skills/adia-ui-release/assets/case-studies/2026-05-20-batch-push-v0.6.14-v0.6.15.md +0 -144
  228. package/skills/adia-ui-release/assets/case-studies/2026-05-20-corpus-drift-remediation-v0.6.15.md +0 -155
  229. package/skills/adia-ui-release/assets/case-studies/2026-05-20-version-skip-correction-v0.6.12.md +0 -114
  230. package/skills/adia-ui-release/assets/case-studies/2026-05-21-author-from-scratch-v0.6.18.md +0 -139
  231. package/skills/adia-ui-release/assets/case-studies/2026-05-21-feedback37-retraction-v0.6.21.md +0 -124
  232. package/skills/adia-ui-release/assets/case-studies/2026-05-21-fn1-enrichment-pass-v0.6.19.md +0 -125
  233. package/skills/adia-ui-release/assets/case-studies/2026-05-21-stale-test-detection-v0.6.20.md +0 -142
  234. package/skills/adia-ui-release/assets/case-studies/2026-05-23-freshness-gate-recovery-v0.6.32.md +0 -97
  235. package/skills/adia-ui-release/assets/case-studies/2026-05-26-catalog-drift-recurring-v0.6.40.md +0 -147
  236. package/skills/adia-ui-release/assets/templates/stub-changelog.template.md +0 -22
  237. package/skills/adia-ui-release/evals/evals.json +0 -164
  238. package/skills/adia-ui-release/references/changelog-discipline.md +0 -250
  239. package/skills/adia-ui-release/references/cycle-happy-path.md +0 -520
  240. package/skills/adia-ui-release/references/exe-deploy.md +0 -149
  241. package/skills/adia-ui-release/references/gates-catalog.md +0 -778
  242. package/skills/adia-ui-release/references/independent-package-release.md +0 -129
  243. package/skills/adia-ui-release/references/ledger-discipline.md +0 -232
  244. package/skills/adia-ui-release/references/migration-guide-authoring.md +0 -174
  245. package/skills/adia-ui-release/references/multi-agent-baseline.md +0 -207
  246. package/skills/adia-ui-release/references/notes-authoring.md +0 -212
  247. package/skills/adia-ui-release/references/recovery-paths.md +0 -262
  248. package/skills/adia-ui-release/references/rollup-notes.md +0 -208
  249. package/skills/adia-ui-release/references/teach-protocol.md +0 -468
  250. package/skills/adia-ui-release/scripts/audit-gate-roster.mjs +0 -196
  251. package/skills/adia-ui-release/scripts/make-ledger.mjs +0 -200
  252. package/skills/adia-ui-release/skill.json +0 -77
  253. package/skills/dogfood-sweep/CHANGELOG.md +0 -37
  254. package/skills/dogfood-sweep/README.md +0 -105
  255. package/skills/dogfood-sweep/SKILL.md +0 -1000
  256. package/skills/dogfood-sweep/analyze.mjs +0 -600
  257. package/skills/dogfood-sweep/skill.json +0 -31
  258. /package/skills/{adia-ui-authoring → adia-author}/references/api-contract.md +0 -0
  259. /package/skills/{adia-ui-release → adia-release}/scripts/assert-monorepo-root.mjs +0 -0
@@ -1,97 +0,0 @@
1
- # Case study — v0.6.32 (2026-05-23)
2
-
3
- ## Freshness-gate recovery: deploy-handoff variant catching pre-flight gap
4
-
5
- **Variant:** Mode 3 (Deploy peer handoff) + freshness-gate recovery preamble.
6
-
7
- **Status:** Resolved cleanly. 9/9 npm publishes succeeded on first dispatch. Tags re-pointed without force-push.
8
-
9
- ---
10
-
11
- ## What happened
12
-
13
- Peer (Kim) pre-authored v0.6.32 release commit `5285defa8` after a substantive substrate sweep:
14
-
15
- - `60a247efa` — tag/badge/segment phantom-gap fix
16
- - `6db1d8a58` — FB-51 P0: `everything.min.js` now registers all 95+ primitives (was incomplete)
17
- - `e394a8099` — remove duplicate `data-chunk-kind` attrs
18
- - `d8f4ff2c0` — admin-shell `[data-col]/[data-row]` CSS scoped to ancestor
19
- - **`5d8c62a80`** — feat(0.6.32): everything.js bundle fix + icons-manifest + llms.txt + **status:stable sweep on all 141 component YAMLs + anatomy sweep across examples pages**
20
- - `5285defa8` — release commit + 10 tags created locally
21
-
22
- The status:stable yaml sweep + anatomy sweep touched 284 yaml/json files. The chunk corpus is yaml-derived — peer's sweep regenerated the yaml sources but **did not run `harvest:chunks` + `build:embeddings:chunks`** as a follow-on step.
23
-
24
- Peer's commit message claimed verification was green with 7 gates enumerated:
25
-
26
- > check:lockstep OK / verify:components clean / verify:traits 56/56 / check:css-bundles-fresh 5/5 / check:js-bundles-fresh 6/6 / smoke:engines ok / test:a2ui 22/22
27
-
28
- **The remaining 9 of 16 gates were skipped** — including `verify:corpus`, `check:chunks-fresh`, `check:embeddings-fresh`, and `check:links`. The post-yaml drift was invisible to peer's automation.
29
-
30
- ## What I caught
31
-
32
- User instruction: _"re-harvest the chunks then cut 0.6.32"_
33
-
34
- Operator probe acting as forensic gate. I picked up the cycle at deploy-handoff state (release commit + tags pre-created locally, tags not yet pushed), ran `npm run harvest:chunks`:
35
-
36
- - 387 chunk instances parsed → 238 unique → 190 leaf + 48 nested-expanded
37
- - **230+ chunk JSON files updated** + `chunks/_index.json` regenerated
38
-
39
- Then `check:embeddings-fresh` reported:
40
-
41
- ```text
42
- [embeddings] FAILED — drift detected:
43
- ✗ chunk-embeddings.json is 1.0d older than chunks/_index.json
44
- — run `npm run build:embeddings:chunks`
45
- ```
46
-
47
- ## Recovery (clean — no force-push)
48
-
49
- Because peer's tags were local-only (never pushed to origin), recovery was a tag-move, not a tag-rewrite:
50
-
51
- 1. `npm run build:embeddings:chunks` — regenerated chunk-embeddings.json (OpenAI text-embedding-3-small, 8 batches, 238 × 1536d, ~6.8 MB)
52
- 2. Updated `@adia-ai/a2ui-corpus [0.6.32]` CHANGELOG entry to document the regen (replaced peer's `_No pending changes._` placeholder).
53
- 3. Committed `chunks/` + `chunk-embeddings.json` + CHANGELOG as `e864fc396 chore(a2ui-corpus): v0.6.32 re-harvest — 238 chunks + embeddings regen`.
54
- 4. Re-ran the FULL 16-gate Step 3 roster. All green (`verify:corpus` exit code 0; 65 pre-existing warnings carried forward — 61 field-wraps-widget + 4 enum-out-of-range, all technical debt unrelated to v0.6.32).
55
- 5. Deleted local tags at `5285defa8`, recreated all 10 at `e864fc396`:
56
-
57
- ```bash
58
- for tag in v0.6.32 web-{components,modules}-v0.6.32 llm-v0.6.32 \
59
- a2ui-{compose,corpus,mcp,retrieval,runtime,validator}-v0.6.32; do
60
- git tag -d $tag && git tag $tag HEAD
61
- done
62
- ```
63
-
64
- 6. F-N1 (`check:release --all-pending`): 9/9 per-package clean.
65
- 7. Pushed branch + 10 tags, dispatched 9 publish workflows → 9/9 success on first dispatch.
66
-
67
- ## Key lessons graduated into the skill
68
-
69
- ### 1. Step 3 grew §Step 3.0 (harvest preamble)
70
-
71
- When source content changes (yaml / examples / contents.html with data-chunk-\* annotations / status:stable sweeps / anatomy sweeps), proactively run `harvest:chunks` + `build:embeddings:chunks` BEFORE the gates — not reactively after they fail. Cheap to run, catches drift before it lands in a tag.
72
-
73
- Documented in `cycle-happy-path.md` §Step 3.0 with source-content signal list + recipe.
74
-
75
- ### 2. Step 3 grew an explicit "all 16 must run" rule
76
-
77
- The previous Step 3 listed the gates but didn't forbid selective subsets. Peer's automation enumerated 7. The rule is now:
78
-
79
- > **All 16 gates MUST run. Selective subset = pre-flight failure.**
80
-
81
- Documented in `cycle-happy-path.md` §Step 3.1 with the canonical roster numbered 1-16.
82
-
83
- ### 3. The recovery recipe is preserved as this case study
84
-
85
- Future cycles facing the same situation can follow this playbook:
86
-
87
- - Tags local-only → safe to delete + recreate at new HEAD
88
- - Tags pushed → either force-push tags (rare, document why) or roll forward to next version
89
- - Always: re-run F-N1 after tag-move; full 16-gate roster after harvest preamble.
90
-
91
- ## Cross-references
92
-
93
- - Audit-history ledger: `.brain/audit-history/2026-05-23-release-cut-v0.6.32.json`
94
- - Release notes draft: `/tmp/release-v0.6.32/notes.md`
95
- - Sibling case studies:
96
- - [corpus-drift-remediation-v0.6.15](./2026-05-20-corpus-drift-remediation-v0.6.15.md) — earlier embeddings drift (6.6 days stale, batch-push context).
97
- - [version-skip-correction-v0.6.12](./2026-05-20-version-skip-correction-v0.6.12.md) — adjacent recovery pattern (tag-rewrite, force-push variant).
@@ -1,147 +0,0 @@
1
- # Case study — v0.6.37 + v0.6.40 (2026-05-25 / 2026-05-26)
2
-
3
- ## Catalog-drift recurring — §Step 3.0 graduation was incomplete; v1.9.0 closes the output-staging gap
4
-
5
- **Variant:** Mode 1 (Cut & ship) — both occurrences. Same class of CI failure (catalog drift on `verify:components`), same recovery shape (regen + commit follow-up + force-move 10 tags + re-dispatch).
6
-
7
- **Status:** Both cycles published 9/9 net of recovery. v0.6.37 took ~5 min of recovery; v0.6.40 took ~5 min of recovery on the **same** class. v1.9.0 graduates the gap that v1.8.0 missed.
8
-
9
- ---
10
-
11
- ## What happened — twice
12
-
13
- ### First occurrence — v0.6.37 (2026-05-25)
14
-
15
- 7/9 publish workflows failed at the `verify:components` step. The diagnostic was:
16
-
17
- ```text
18
- [verify] DRIFT catalog: packages/a2ui/corpus/catalog-a2ui_0_9.json
19
- [verify] DRIFT rules: packages/a2ui/corpus/catalog-a2ui_0_9_rules.txt
20
- [verify] 2 file(s) would change. Run build-components.mjs to update.
21
- ##[error]Process completed with exit code 1.
22
- ```
23
-
24
- Root cause: catalog files were modified in WT by peer (uncommitted local audit-token-pair or yaml-sweep work). The release agent correctly excluded the WT pre-state from the release-commit allowlist per multi-agent baseline discipline. **§Step 3.0 didn't run a catalog regen** — the v1.7.0 graduation covered `harvest:chunks` + `build:embeddings:chunks` but not `node scripts/build/components.mjs` (catalog regen).
25
-
26
- Recovery: regen + commit follow-up + force-move 10 tags + re-dispatch.
27
-
28
- ### v1.8.0 graduation — incomplete
29
-
30
- The v0.6.37 case study lesson graduated into **adia-ui-release v1.8.0**, which added `node scripts/build/components.mjs` (catalog regen) to §Step 3.0 alongside `harvest:chunks` + `build:embeddings:chunks` + `build:bundles`.
31
-
32
- **The graduation covered REGEN but not OUTPUT-STAGING.** Step 3.0 told the agent to regenerate the catalog. It didn't tell the agent that the regen output had to LAND in the release commit even when the same file paths were also peer-in-flight in the working tree.
33
-
34
- ### Second occurrence — v0.6.40 (2026-05-26)
35
-
36
- 8/9 publish workflows failed at `verify:components` — only `llm` succeeded (pure ride-along, no catalog dependency). Same diagnostic; same root cause shape.
37
-
38
- The release agent followed v1.8.0 §Step 3.0 to the letter — ran `node scripts/build/components.mjs`, got fresh catalog output, ran the gates locally (`verify:components` clean). Then inspected WT:
39
-
40
- ```text
41
- M packages/a2ui/corpus/catalog-a2ui_0_9.json ← peer-in-flight + my regen overlay
42
- M packages/a2ui/corpus/catalog-a2ui_0_9_rules.txt ← same
43
- M packages/web-components/components/badge/badge.d.ts ← peer-in-flight (NOT mine)
44
- M packages/web-components/components/card/card.css ← peer-in-flight (NOT mine)
45
- M packages/web-components/components/progress-row/progress-row.css ← peer-in-flight
46
- ```
47
-
48
- Multi-agent baseline discipline says "stage explicit allowlist; never `git add -A`." Catalog files were on the WT pre-state list as peer-in-flight, so the agent excluded them. **The regen output (correct for this release) also got excluded — same file paths.**
49
-
50
- Tags pushed. CI hit DRIFT. 8/9 failed.
51
-
52
- Recovery: identical to v0.6.37 — regen + commit follow-up + force-move 10 tags + re-dispatch. ~5 min.
53
-
54
- **Twice in the same class is a missing trip-wire.**
55
-
56
- ---
57
-
58
- ## What I caught (post-mortem clarity)
59
-
60
- The v1.8.0 wording said _regenerate the catalog_. It didn't say:
61
-
62
- - "The regen output supersedes any peer-in-flight WT pre-state on the same paths."
63
- - "Catalog files are non-negotiable in the release-commit allowlist when source content changed in the window."
64
- - "Re-verify with `verify:components` after staging — if DRIFT, you excluded the regen output."
65
-
66
- All three would have caught the v0.6.40 occurrence. The conflict between "exclude peer WT pre-state" (baseline discipline) and "stage regen output" (§Step 3.0) had no documented winner. The agent resolved the conflict toward exclusion both times.
67
-
68
- ---
69
-
70
- ## v1.9.0 graduation — three layers, defense in depth
71
-
72
- ### Layer 1 — Stronger §Step 3.0 wording (supersedes-WT contract)
73
-
74
- The regen step has FOUR deliverables (was implicit; now enumerated):
75
-
76
- ```bash
77
- node scripts/build/components.mjs # → catalog + sidecar
78
- npm run harvest:chunks # → chunks/_index + per-chunk JSON
79
- npm run build:embeddings:chunks # → chunk-embeddings.json
80
- npm run build:bundles # → dist/*.min.{css,js}
81
- ```
82
-
83
- **The regen output supersedes any peer-in-flight WT pre-state on the same file paths.** Peer's uncommitted catalog modifications are superseded by the fresh regen — stage the regenerated catalog into the release-commit allowlist UNCONDITIONALLY. Peer can rebase any divergent work on top of the release commit after the cycle.
84
-
85
- ### Layer 2 — NEW §Step 5.5 — pre-commit verification trip-wire
86
-
87
- After `git add` (Step 5) but BEFORE `git commit`, re-run the verify gates one final time:
88
-
89
- ```bash
90
- node scripts/build/components.mjs --verify # catalog drift?
91
- npm run check:chunks-fresh
92
- npm run check:embeddings-fresh
93
- ```
94
-
95
- **Any DRIFT here means a regen output was excluded from staging.** Recovery is in-cycle (no force-push): `git add <drift-paths>` → re-run `verify` until clean → Step 6 (commit).
96
-
97
- The trip-wire runs in <2 seconds locally vs ~5 minutes to recover from a CI failure. Pure win.
98
-
99
- ### Layer 3 — §Step 5 allowlist convention update
100
-
101
- When source content changed in this window (yaml / examples.html / contents.html with `data-chunk-*` / status:stable sweeps / Wave commits / OD-5 sweeps), the release-commit allowlist MUST include these regen-deterministic outputs UNCONDITIONALLY:
102
-
103
- - `packages/a2ui/corpus/catalog-a2ui_0_9.json`
104
- - `packages/a2ui/corpus/catalog-a2ui_0_9_rules.txt`
105
- - `packages/a2ui/corpus/chunk-embeddings.json`
106
- - `packages/a2ui/corpus/chunks/` (if chunk content drifted)
107
- - `packages/web-components/dist/web-components.min.{css,js}`
108
- - `packages/web-components/dist/icons-manifest.js`
109
- - `packages/web-modules/dist/everything.min.js`
110
- - `packages/web-modules/dist/shell/admin-shell.min.js`
111
- - `packages/web-modules/dist/icons-manifest.js`
112
-
113
- These are regen-deterministic outputs; their WT pre-state (if any) is always superseded by the release-cycle regen.
114
-
115
- This is **not** "stage WT changes" (still violates multi-agent baseline). This is "stage the regen outputs you produced in §Step 3.0 — they supersede any peer WT pre-state on the same paths."
116
-
117
- ---
118
-
119
- ## How v1.9.0 closes the gap (verification target for the next cycle)
120
-
121
- For the next v0.6.41+ cycle:
122
-
123
- 1. Verify peer-in-flight catalog modifications exist in WT (simulate by `touch packages/a2ui/corpus/catalog-a2ui_0_9.json` if needed).
124
- 2. Run §Step 3.0 (catalog regen).
125
- 3. Stage allowlist per the new convention — catalog UNCONDITIONALLY included.
126
- 4. Run §Step 5.5 trip-wire (`node scripts/build/components.mjs --verify` + `check:chunks-fresh` + `check:embeddings-fresh`).
127
- 5. Expected: clean. Commit lands; CI passes 9/9 on first dispatch.
128
-
129
- If the trip-wire fails: the v1.9.0 graduation is still incomplete; back to the bench.
130
-
131
- ---
132
-
133
- ## Cross-references
134
-
135
- - Sibling case studies:
136
- - [freshness-gate-recovery-v0.6.32](./2026-05-23-freshness-gate-recovery-v0.6.32.md) — same pattern shape: CI failure detected at publish time → graduation into §Step 3.0 (this case is the v1.8.0 → v1.9.0 iteration). v0.6.32 → v1.7.0 graduated cleanly; v0.6.37 → v1.8.0 graduated incompletely.
137
- - [corpus-drift-remediation-v0.6.15](./2026-05-20-corpus-drift-remediation-v0.6.15.md) — earlier embeddings drift (6.6 days stale, batch-push context).
138
- - Audit-history ledgers:
139
- - `.brain/audit-history/2026-05-25-release-cut-v0.6.37.json`
140
- - `.brain/audit-history/2026-05-26-release-cut-v0.6.40.json`
141
- - FEEDBACK ticket that motivated this graduation: `FEEDBACK-75` (the internal release-cycle self-feedback ticket)
142
-
143
- ## Lesson aphorism
144
-
145
- > "Once is happenstance, twice is coincidence, twice in the same class is a missing trip-wire."
146
-
147
- The release skill survives because every CI failure that recurs gets graduated into mechanical defense, not into a longer recovery runbook.
@@ -1,22 +0,0 @@
1
- <!--
2
- Lockstep stub block — for a ride-along package with no source changes
3
- in this release. The substantive description points at the relevant
4
- @adia-ai/* package whose CHANGELOG carries the headline.
5
-
6
- Variables (replace before use):
7
- $VERSION — the version being cut (e.g. 0.6.21)
8
- $DATE — release date in YYYY-MM-DD
9
- $SUBSTANTIVE — one-sentence summary of the substantive work and
10
- where it shipped, with the cross-reference path.
11
-
12
- Example invocation:
13
- node scripts/insert-stub.mjs --version 0.6.21 --date 2026-05-21 \
14
- --substantive "table-ui truncate-default (§403) and FEEDBACK-37 retraction in @adia-ai/web-modules" \
15
- --xref "packages/web-modules/CHANGELOG.md#0621--2026-05-21"
16
- -->
17
-
18
- ## [$VERSION] — $DATE
19
-
20
- ### Maintenance
21
-
22
- - **Lockstep version bump only.** No source changes in this package; bumped to maintain the 9-package version coherence enforced by `scripts/release/check-lockstep.mjs`. Substantive v$VERSION work shipped in $SUBSTANTIVE. See `$XREF` for details.
@@ -1,164 +0,0 @@
1
- {
2
- "$schema": "https://anthropic.com/schemas/skill-evals.v1.json",
3
- "skill": "adia-ui-release",
4
- "version": "0.1.0",
5
- "description": "Mode-trigger evals + diagnostic-routing evals for the autonomous release engineer (release cycle + migration-guide authoring).",
6
- "evals": [
7
- {
8
- "id": "mode-1-bare-cut",
9
- "category": "mode-trigger",
10
- "input": "prepare and initiate 0.6.22 release",
11
- "expected_mode": 1,
12
- "expected_loads": ["cycle-happy-path.md", "multi-agent-baseline.md"],
13
- "must_NOT_load": ["rollup-notes.md", "recovery-paths.md"]
14
- },
15
- {
16
- "id": "mode-2-from-scratch",
17
- "category": "mode-trigger",
18
- "input": "the peer landed feedback fixes under [Unreleased] — cut v0.6.22 from scratch",
19
- "expected_mode": 2,
20
- "expected_loads": ["cycle-happy-path.md", "changelog-discipline.md"],
21
- "must_NOT_load": ["rollup-notes.md"]
22
- },
23
- {
24
- "id": "mode-3-deploy-handoff",
25
- "category": "mode-trigger",
26
- "input": "peer pre-cut the v0.6.22 release commit; deploy + publish it",
27
- "expected_mode": 3,
28
- "expected_loads": ["cycle-happy-path.md"]
29
- },
30
- {
31
- "id": "mode-4-batch-push",
32
- "category": "mode-trigger",
33
- "input": "there are 2 unpushed release commits — ship them together",
34
- "expected_mode": 4,
35
- "expected_loads": ["recovery-paths.md"]
36
- },
37
- {
38
- "id": "mode-5-rollup",
39
- "category": "mode-trigger",
40
- "input": "write a consolidated rollup release note for v0.6.16 → v0.6.21",
41
- "expected_mode": 5,
42
- "expected_loads": ["rollup-notes.md"],
43
- "must_NOT_load": ["cycle-happy-path.md", "multi-agent-baseline.md"]
44
- },
45
- {
46
- "id": "mode-6-just-verify",
47
- "category": "mode-trigger",
48
- "input": "run the pre-flight gates — I just want to smoke-check",
49
- "expected_mode": 6,
50
- "expected_loads": ["gates-catalog.md"],
51
- "must_NOT_load": ["cycle-happy-path.md", "notes-authoring.md"]
52
- },
53
- {
54
- "id": "mode-7-recovery",
55
- "category": "mode-trigger",
56
- "input": "we just shipped v0.6.22 and a consumer reports the demo-shell is broken",
57
- "expected_mode": 7,
58
- "expected_loads": ["recovery-paths.md"],
59
- "may_route_to": ["ops-postmortem"]
60
- },
61
- {
62
- "id": "mode-8-investigation",
63
- "category": "mode-trigger",
64
- "input": "what shipped in v0.6.18? what did we miss?",
65
- "expected_mode": 8,
66
- "expected_loads": ["ledger-discipline.md"]
67
- },
68
- {
69
- "id": "mode-9-notes-only",
70
- "category": "mode-trigger",
71
- "input": "I just need the GH release body for v0.6.22 — don't cut anything",
72
- "expected_mode": 9,
73
- "expected_loads": ["notes-authoring.md"],
74
- "must_NOT_load": ["cycle-happy-path.md", "multi-agent-baseline.md"]
75
- },
76
- {
77
- "id": "mode-11-migration-guide-authoring",
78
- "category": "mode-trigger",
79
- "input": "we're cutting a breaking MINOR that renames variant=danger to color=danger — author the MIGRATION GUIDE section",
80
- "expected_mode": 11,
81
- "expected_loads": ["migration-guide-authoring.md"],
82
- "must_NOT_load": ["rollup-notes.md"]
83
- },
84
- {
85
- "id": "diagnostic-migration-consumer-side-rejected",
86
- "category": "diagnostic-routing",
87
- "input": "migrate our downstream consumer app to @adia-ai/web-components 0.0.20",
88
- "expected_route": "NOT this skill — consumer-side migration lives in the separate consumer/app-author plugin; this skill owns only the PRODUCER side (authoring the guide + sweeping in-repo surfaces when cutting the breaking release)",
89
- "expected_action": "decline + redirect to the consumer/app-author plugin"
90
- },
91
- {
92
- "id": "bare-activation",
93
- "category": "cold-start",
94
- "input": "use adia-ui-release",
95
- "expected_behavior": "render the mode triage menu verbatim + ask for mode+version; do NOT load any references/*.md bundle",
96
- "expected_loads": []
97
- },
98
- {
99
- "id": "diagnostic-fn1-warn",
100
- "category": "diagnostic-routing",
101
- "input": "F-N1 says: '[warn] diff packages/web-components/components/ touched but CHANGELOG [0.6.22] doesn't mention components'",
102
- "expected_route": "changelog-discipline.md § F-N1 diff-coverage enrichment",
103
- "expected_action": "enrich an existing CHANGELOG entry to include the 'components/' path keyword; amend release commit; delete + re-tag; re-run F-N1",
104
- "expected_severity": "cosmetic"
105
- },
106
- {
107
- "id": "diagnostic-demo-shells-fail",
108
- "category": "diagnostic-routing",
109
- "input": "check:demo-shells fails: 'demo packages/web-components/components/table/table.html missing skeleton-ui'",
110
- "expected_route": "gates-catalog.md § Category 3 § check:demo-shells",
111
- "expected_action": "add <script type='module' src='../skeleton/skeleton.js'> to the demo .html",
112
- "expected_severity": "HIGH (release-blocking)"
113
- },
114
- {
115
- "id": "diagnostic-embeddings-stale",
116
- "category": "diagnostic-routing",
117
- "input": "check:embeddings-fresh FAILED — chunk-embeddings.json is 6.6d older than chunks/_index.json",
118
- "expected_route": "gates-catalog.md § Category 7 § check:embeddings-fresh",
119
- "expected_action": "npm run build:embeddings:chunks; stage chunk-embeddings.json; add a CHANGELOG note to a2ui-corpus [vX.Y.Z]"
120
- },
121
- {
122
- "id": "diagnostic-version-skip",
123
- "category": "diagnostic-routing",
124
- "input": "peer's release commit bumped 0.6.11 → 0.6.13 but I want to cut 0.6.12",
125
- "expected_route": "recovery-paths.md § Scenario 1 (version-skip correction)",
126
- "expected_action": "correction commit on top of peer's commit; rewrite v0.6.13 → v0.6.12 across pkg.json + CHANGELOGs + CSS comments + ADRs + tickets + lockfile; tag v0.6.12 at correction commit",
127
- "case_study": "assets/case-studies/2026-05-20-version-skip-correction-v0.6.12.md"
128
- },
129
- {
130
- "id": "diagnostic-stale-test",
131
- "category": "diagnostic-routing",
132
- "input": "vitest fails: admin-shell.test.js expects '[slot=heading] { display: none }' but the source has ':is(...)[slot=heading], [slot=heading]:not(:has(> [slot])) { display: none }'",
133
- "expected_route": "recovery-paths.md § Scenario 5 (stale test detection)",
134
- "expected_action": "read the CHANGELOG [vX.Y.Z] entry — does it describe the new behavior? If yes → update the test assertion to match the new shape, add a comment naming the cycle, add a guard assertion for the new contract. If no → real regression, fix the source."
135
- },
136
- {
137
- "id": "diagnostic-peer-in-flight-stray",
138
- "category": "diagnostic-routing",
139
- "input": "working tree has admin-shell.tokens.css modified (uncommitted, undocumented, contradicts the [VERSION] CHANGELOG entry)",
140
- "expected_route": "multi-agent-baseline.md § Discipline 4 (stash workflow)",
141
- "expected_action": "git stash push the file with a clear message; ship without; restore after; flag to operator; note in ledger"
142
- },
143
- {
144
- "id": "stash-pop-conflict-after-release",
145
- "category": "diagnostic-routing",
146
- "input": "after the cycle, git stash pop reports 'kept the stash' — concurrent peer activity",
147
- "expected_route": "recovery-paths.md § Scenario 6 (concurrent peer mid-cycle)",
148
- "expected_action": "compare stash content vs current HEAD; if peer committed equivalent content, drop stash (redundant); if not, leave stashed; document in ledger"
149
- },
150
- {
151
- "id": "behavior-shipped-needs-retract",
152
- "category": "diagnostic-routing",
153
- "input": "FEEDBACK-N shipped in vN.M.X but is now diagnosed as misdiagnosis — how to retract?",
154
- "expected_route": "case-studies/2026-05-21-feedback37-retraction-v0.6.21.md",
155
- "expected_action": "frame retraction as a 'Fixed — no longer emits spurious X' entry in the next cycle's CHANGELOG; add a heads-up paragraph in the release notes; consider ADR if the retraction reveals a framing issue worth ratifying"
156
- }
157
- ],
158
- "non_eval_invariants": [
159
- "Bare activation MUST NOT exceed 500 lines loaded (SKILL.md + skill.json + CHANGELOG.md only).",
160
- "Modes 5, 6, 9, 11 (single-purpose modes) each MUST NOT load cycle-happy-path.md or multi-agent-baseline.md.",
161
- "Every case-study referenced from an eval MUST exist at the named path.",
162
- "Every CLI helper named in cycle-happy-path.md MUST exist at the named path."
163
- ]
164
- }