@magic-spells/constellation 0.2.2 → 0.4.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 (183) hide show
  1. package/README.md +13 -6
  2. package/constellation/agent/AGENT-GUIDANCE.md +22 -0
  3. package/constellation/component/COMPONENT-EDITABLE.md +9 -0
  4. package/constellation/component/COMPONENT-STATUS-PILL.md +9 -0
  5. package/constellation/component/COMPONENT-SYNC-PILL.md +9 -0
  6. package/constellation/decision/DECISION-FEATURE-RELEASE-TYPES.md +50 -0
  7. package/constellation/decision/DECISION-NATIVE-DECISION-TYPE.md +58 -0
  8. package/constellation/diagram/DIAGRAM-ARCHITECTURE.md +28 -0
  9. package/constellation/doc/DOC-CARD-TYPES.md +39 -0
  10. package/constellation/doc/DOC-CHANGE-TRACKING.md +26 -0
  11. package/constellation/doc/DOC-CONNECTED-REPOS.md +25 -0
  12. package/constellation/doc/DOC-DIAGRAMS.md +22 -0
  13. package/constellation/doc/DOC-FILE-FORMAT.md +54 -0
  14. package/constellation/doc/DOC-LINT-CODES.md +35 -0
  15. package/constellation/doc/DOC-MCP-SERVER.md +59 -0
  16. package/constellation/doc/DOC-MCP-UPGRADES.md +57 -0
  17. package/constellation/external/EXTERNAL-AJV.md +7 -0
  18. package/constellation/external/EXTERNAL-GIT.md +7 -0
  19. package/constellation/external/EXTERNAL-GRAY-MATTER.md +7 -0
  20. package/constellation/external/EXTERNAL-MCP-SDK.md +7 -0
  21. package/constellation/external/EXTERNAL-ZOD.md +7 -0
  22. package/constellation/file/FILE-CLI.md +9 -0
  23. package/constellation/file/FILE-CODE.md +9 -0
  24. package/constellation/file/FILE-EXTRACT.md +9 -0
  25. package/constellation/file/FILE-GIT.md +9 -0
  26. package/constellation/file/FILE-HANDLES.md +9 -0
  27. package/constellation/file/FILE-INDEXER.md +11 -0
  28. package/constellation/file/FILE-LINT.md +9 -0
  29. package/constellation/file/FILE-MCP-SEARCH.md +12 -0
  30. package/constellation/file/FILE-MCP-SERVER.md +9 -0
  31. package/constellation/file/FILE-PARSE.md +9 -0
  32. package/constellation/file/FILE-RENAME.md +18 -0
  33. package/constellation/file/FILE-REPOS.md +9 -0
  34. package/constellation/file/FILE-RESOLVE.md +9 -0
  35. package/constellation/file/FILE-SCAFFOLD.md +12 -0
  36. package/constellation/file/FILE-SERVE.md +9 -0
  37. package/constellation/file/FILE-SYNC.md +9 -0
  38. package/constellation/file/FILE-TYPES.md +9 -0
  39. package/constellation/file/FILE-VALIDATE.md +11 -0
  40. package/constellation/file/FILE-WRITER.md +11 -0
  41. package/constellation/flow/FLOW-DRIFT-DETECT.md +11 -0
  42. package/constellation/flow/FLOW-LINT-PIPELINE.md +14 -0
  43. package/constellation/flow/FLOW-SYNC-PLAN.md +13 -0
  44. package/constellation/page/PAGE-VIEWER-CARD.md +9 -0
  45. package/constellation/page/PAGE-VIEWER-HOME.md +9 -0
  46. package/constellation/plan.md +59 -0
  47. package/constellation/test/TEST-SUITE.md +9 -0
  48. package/dist/cli/index.js +37 -0
  49. package/dist/cli/index.js.map +1 -1
  50. package/dist/core/code.d.ts +4 -2
  51. package/dist/core/code.js +22 -7
  52. package/dist/core/code.js.map +1 -1
  53. package/dist/core/git.d.ts +2 -0
  54. package/dist/core/git.js +6 -0
  55. package/dist/core/git.js.map +1 -1
  56. package/dist/core/handles.d.ts +1 -1
  57. package/dist/core/handles.js +4 -1
  58. package/dist/core/handles.js.map +1 -1
  59. package/dist/core/indexer.js +1 -1
  60. package/dist/core/rename.d.ts +24 -0
  61. package/dist/core/rename.js +72 -0
  62. package/dist/core/rename.js.map +1 -0
  63. package/dist/core/repos.d.ts +2 -0
  64. package/dist/core/repos.js +5 -1
  65. package/dist/core/repos.js.map +1 -1
  66. package/dist/core/sync.d.ts +2 -0
  67. package/dist/core/sync.js +3 -1
  68. package/dist/core/sync.js.map +1 -1
  69. package/dist/core/types.d.ts +1 -1
  70. package/dist/core/types.js +3 -2
  71. package/dist/core/types.js.map +1 -1
  72. package/dist/core/validate.js +14 -1
  73. package/dist/core/validate.js.map +1 -1
  74. package/dist/core/writer.d.ts +29 -0
  75. package/dist/core/writer.js +98 -3
  76. package/dist/core/writer.js.map +1 -1
  77. package/dist/mcp/search.d.ts +2 -2
  78. package/dist/mcp/search.js +27 -5
  79. package/dist/mcp/search.js.map +1 -1
  80. package/dist/mcp/server.js +311 -101
  81. package/dist/mcp/server.js.map +1 -1
  82. package/dist/serve/server.js +6 -7
  83. package/dist/serve/server.js.map +1 -1
  84. package/examples/constellation/decision/DECISION-NO-HARD-DELETE.md +31 -0
  85. package/examples/constellation/feature/FEATURE-AUTO-ASSIGNMENT.md +24 -0
  86. package/examples/constellation/release/RELEASE-V1-1-0.md +14 -0
  87. package/package.json +2 -2
  88. package/schemas/decision.json +14 -0
  89. package/schemas/doc.json +1 -1
  90. package/schemas/feature.json +19 -0
  91. package/schemas/plan.json +1 -1
  92. package/schemas/release.json +14 -0
  93. package/skill/SKILL.md +39 -7
  94. package/skill/methodology.md +10 -3
  95. package/skill/types/decision.md +59 -0
  96. package/skill/types/doc.md +2 -2
  97. package/skill/types/feature.md +53 -0
  98. package/skill/types/plan.md +1 -1
  99. package/skill/types/release.md +37 -0
  100. package/viewer/dist/assets/{arc-YuzGWkw8.js → arc-DcXsmPgw.js} +1 -1
  101. package/viewer/dist/assets/architecture-7EHR7CIX-CXZxmtF5.js +1 -0
  102. package/viewer/dist/assets/{architectureDiagram-3BPJPVTR-BgksqMlF.js → architectureDiagram-3BPJPVTR-Cfq3OC2M.js} +1 -1
  103. package/viewer/dist/assets/{blockDiagram-GPEHLZMM-Bc6JILFK.js → blockDiagram-GPEHLZMM-CPuRJqEW.js} +1 -1
  104. package/viewer/dist/assets/{c4Diagram-AAUBKEIU-CRVt42df.js → c4Diagram-AAUBKEIU-CcVcItWo.js} +1 -1
  105. package/viewer/dist/assets/channel-DjvAjJNc.js +1 -0
  106. package/viewer/dist/assets/{chunk-2J33WTMH-CpuwKeX6.js → chunk-2J33WTMH-C_N821rH.js} +1 -1
  107. package/viewer/dist/assets/{chunk-3OPIFGDE-BG_ijJhE.js → chunk-3OPIFGDE-C5c2MY1i.js} +1 -1
  108. package/viewer/dist/assets/{chunk-4BX2VUAB-Bgz1tnDP.js → chunk-4BX2VUAB-BjYatXZ-.js} +1 -1
  109. package/viewer/dist/assets/{chunk-55IACEB6-NdWURd2K.js → chunk-55IACEB6-A3JXj2W_.js} +1 -1
  110. package/viewer/dist/assets/{chunk-5ZQYHXKU-wzW5x_7z.js → chunk-5ZQYHXKU-zDiW1Z3e.js} +1 -1
  111. package/viewer/dist/assets/{chunk-727SXJPM-BxKeJXYf.js → chunk-727SXJPM-CI3VBaXr.js} +1 -1
  112. package/viewer/dist/assets/{chunk-AQP2D5EJ-gPm6xhPX.js → chunk-AQP2D5EJ-DHpkJ1wF.js} +1 -1
  113. package/viewer/dist/assets/{chunk-BSJP7CBP-C30ZXEUD.js → chunk-BSJP7CBP-DXx1-_Zs.js} +1 -1
  114. package/viewer/dist/assets/{chunk-CSCIHK7Q-C9h7yfl1.js → chunk-CSCIHK7Q-DQOe6SQo.js} +6 -6
  115. package/viewer/dist/assets/{chunk-FMBD7UC4-BcSnkYc3.js → chunk-FMBD7UC4-DSvwBCfP.js} +1 -1
  116. package/viewer/dist/assets/{chunk-KSCS5N6A-rxSD5-MD.js → chunk-KSCS5N6A-C3haQOao.js} +1 -1
  117. package/viewer/dist/assets/{chunk-L5ZTLDWV-DGwFsVWy.js → chunk-L5ZTLDWV-DyHfVaRK.js} +1 -1
  118. package/viewer/dist/assets/{chunk-LZXEDZCA-BY3sTuvt.js → chunk-LZXEDZCA-CtMQqok_.js} +2 -2
  119. package/viewer/dist/assets/{chunk-ND2GUHAM-PqmKwdzq.js → chunk-ND2GUHAM-Cfp2zN_i.js} +1 -1
  120. package/viewer/dist/assets/{chunk-NZK2D7GU-BAZbzxhl.js → chunk-NZK2D7GU-Cn753oIP.js} +1 -1
  121. package/viewer/dist/assets/{chunk-O5CBEL6O-SvZfZ-0j.js → chunk-O5CBEL6O-BO32_B2k.js} +1 -1
  122. package/viewer/dist/assets/chunk-QZHKN3VN-uc4X3bta.js +1 -0
  123. package/viewer/dist/assets/chunk-WU5MYG2G-D-wARmLR.js +1 -0
  124. package/viewer/dist/assets/{chunk-XPW4576I-1OXPbRQX.js → chunk-XPW4576I-DQFQAfwD.js} +1 -1
  125. package/viewer/dist/assets/classDiagram-4FO5ZUOK-CosoTts2.js +1 -0
  126. package/viewer/dist/assets/classDiagram-v2-Q7XG4LA2-CosoTts2.js +1 -0
  127. package/viewer/dist/assets/{cose-bilkent-S5V4N54A-DtCvLpah.js → cose-bilkent-S5V4N54A-Ibe8V5Cm.js} +1 -1
  128. package/viewer/dist/assets/{dagre-BM42HDAG-B55Ilz10.js → dagre-BM42HDAG-BlOzR9WP.js} +1 -1
  129. package/viewer/dist/assets/{diagram-2AECGRRQ-ClqSMarp.js → diagram-2AECGRRQ-l8omQVTU.js} +1 -1
  130. package/viewer/dist/assets/{diagram-5GNKFQAL-Dx74UdxY.js → diagram-5GNKFQAL-_rHQzAtO.js} +1 -1
  131. package/viewer/dist/assets/{diagram-KO2AKTUF-Vj0buH8e.js → diagram-KO2AKTUF-DCLRVRMY.js} +1 -1
  132. package/viewer/dist/assets/{diagram-LMA3HP47-DpEm8RZd.js → diagram-LMA3HP47-14HnEIqk.js} +1 -1
  133. package/viewer/dist/assets/{diagram-OG6HWLK6-Crl3BdwC.js → diagram-OG6HWLK6-CVKNCbkR.js} +1 -1
  134. package/viewer/dist/assets/{dist-C2uHOEFB.js → dist-BcVVfWxM.js} +1 -1
  135. package/viewer/dist/assets/{erDiagram-TEJ5UH35-B-Mf-EHP.js → erDiagram-TEJ5UH35-CNjpEfJD.js} +1 -1
  136. package/viewer/dist/assets/eventmodeling-FCH6USID-Dv27utnc.js +1 -0
  137. package/viewer/dist/assets/{flowDiagram-I6XJVG4X-B9stChWN.js → flowDiagram-I6XJVG4X-Bvekb5gu.js} +1 -1
  138. package/viewer/dist/assets/{ganttDiagram-6RSMTGT7-DzWlclwM.js → ganttDiagram-6RSMTGT7-2TpeWF0N.js} +1 -1
  139. package/viewer/dist/assets/{gitGraph-WXDBUCRP-CdVI3GTp.js → gitGraph-WXDBUCRP-CPfybYvf.js} +1 -1
  140. package/viewer/dist/assets/{gitGraphDiagram-PVQCEYII-Dn9yRc1N.js → gitGraphDiagram-PVQCEYII-BWZNJ9lY.js} +1 -1
  141. package/viewer/dist/assets/index-BEJYsfzU.css +2 -0
  142. package/viewer/dist/assets/{index-BsGRgBOD.js → index-Cqx2pndu.js} +3 -3
  143. package/viewer/dist/assets/{info-J43DQDTF-CXV3Mm9T.js → info-J43DQDTF-CxgngY4X.js} +1 -1
  144. package/viewer/dist/assets/{infoDiagram-5YYISTIA-zIUka_J2.js → infoDiagram-5YYISTIA-CARF_viY.js} +1 -1
  145. package/viewer/dist/assets/{ishikawaDiagram-YF4QCWOH-DsZwNuE3.js → ishikawaDiagram-YF4QCWOH-DcxZvtur.js} +1 -1
  146. package/viewer/dist/assets/{journeyDiagram-JHISSGLW-BhSTSB2s.js → journeyDiagram-JHISSGLW-Wu7zolY5.js} +1 -1
  147. package/viewer/dist/assets/{kanban-definition-UN3LZRKU-sCAldj86.js → kanban-definition-UN3LZRKU--LMKLf5s.js} +1 -1
  148. package/viewer/dist/assets/{line-D7b3fopb.js → line-DH7DV7uw.js} +1 -1
  149. package/viewer/dist/assets/{linear-BWlvVc_d.js → linear-C6xJ2LrZ.js} +1 -1
  150. package/viewer/dist/assets/{mermaid-parser.core-BdEYBvaj.js → mermaid-parser.core-DkqLwTDu.js} +2 -2
  151. package/viewer/dist/assets/{mermaid.core-C9bGWeJU.js → mermaid.core-H-eI9axh.js} +3 -3
  152. package/viewer/dist/assets/{mindmap-definition-RKZ34NQL-DbTvvku-.js → mindmap-definition-RKZ34NQL-xjt8VE8m.js} +1 -1
  153. package/viewer/dist/assets/{packet-YPE3B663-DRfLruyq.js → packet-YPE3B663-BX0W_wIa.js} +1 -1
  154. package/viewer/dist/assets/{pie-LRSECV5Y-47xXMkK-.js → pie-LRSECV5Y-B8cD_uBh.js} +1 -1
  155. package/viewer/dist/assets/{pieDiagram-4H26LBE5-Ckno9E1M.js → pieDiagram-4H26LBE5-DpM-20zS.js} +1 -1
  156. package/viewer/dist/assets/{quadrantDiagram-W4KKPZXB-XB5kJ_2c.js → quadrantDiagram-W4KKPZXB-CLS4_FQ4.js} +1 -1
  157. package/viewer/dist/assets/{radar-GUYGQ44K-CLwIH5Zr.js → radar-GUYGQ44K-CQKcm4b5.js} +1 -1
  158. package/viewer/dist/assets/{requirementDiagram-4Y6WPE33-D3fApL0X.js → requirementDiagram-4Y6WPE33-ESLvOyQ5.js} +1 -1
  159. package/viewer/dist/assets/{sankeyDiagram-5OEKKPKP-6UdaRhuZ.js → sankeyDiagram-5OEKKPKP-BT6w9JdP.js} +1 -1
  160. package/viewer/dist/assets/{sequenceDiagram-3UESZ5HK-ClIrrs0w.js → sequenceDiagram-3UESZ5HK-DJNAaEbv.js} +1 -1
  161. package/viewer/dist/assets/{src-BPb55SrS.js → src-ituc2uBy.js} +1 -1
  162. package/viewer/dist/assets/{stateDiagram-AJRCARHV-CCsrcv5R.js → stateDiagram-AJRCARHV-Bw7VoMlA.js} +1 -1
  163. package/viewer/dist/assets/stateDiagram-v2-BHNVJYJU-DZdCGd2U.js +1 -0
  164. package/viewer/dist/assets/{timeline-definition-PNZ67QCA-BkiWQlVI.js → timeline-definition-PNZ67QCA-Ddr17PAT.js} +1 -1
  165. package/viewer/dist/assets/{treeView-BLDUP644-m1mGpAE8.js → treeView-BLDUP644-mqjp8QBZ.js} +1 -1
  166. package/viewer/dist/assets/{treemap-LRROVOQU-Bapvwi0Q.js → treemap-LRROVOQU-BeaxV5lr.js} +1 -1
  167. package/viewer/dist/assets/{vennDiagram-CIIHVFJN-BlH71Nmx.js → vennDiagram-CIIHVFJN-ySQYfWol.js} +1 -1
  168. package/viewer/dist/assets/{wardley-L42UT6IY-CPRSoKgV.js → wardley-L42UT6IY-BvtBpxdo.js} +1 -1
  169. package/viewer/dist/assets/{wardleyDiagram-YWT4CUSO-C-ptFJ9t.js → wardleyDiagram-YWT4CUSO-DRZFQiXX.js} +1 -1
  170. package/viewer/dist/assets/{xychartDiagram-2RQKCTM6-C4rfeH4W.js → xychartDiagram-2RQKCTM6-kXPrRy2n.js} +1 -1
  171. package/viewer/dist/index.html +2 -2
  172. package/docs/001-file-format.md +0 -265
  173. package/docs/002-mcp.md +0 -186
  174. package/docs/003-mcp-upgrade-plan.md +0 -138
  175. package/viewer/dist/assets/architecture-7EHR7CIX-BAboPvK1.js +0 -1
  176. package/viewer/dist/assets/channel-D8YnBgqu.js +0 -1
  177. package/viewer/dist/assets/chunk-QZHKN3VN-ClYnv9g5.js +0 -1
  178. package/viewer/dist/assets/chunk-WU5MYG2G-CvL2Yleq.js +0 -1
  179. package/viewer/dist/assets/classDiagram-4FO5ZUOK-B8YUd1jx.js +0 -1
  180. package/viewer/dist/assets/classDiagram-v2-Q7XG4LA2-B8YUd1jx.js +0 -1
  181. package/viewer/dist/assets/eventmodeling-FCH6USID-CZ5gxAxG.js +0 -1
  182. package/viewer/dist/assets/index-Bqs39Itl.css +0 -2
  183. package/viewer/dist/assets/stateDiagram-v2-BHNVJYJU-C1phrPNi.js +0 -1
package/skill/SKILL.md CHANGED
@@ -41,7 +41,8 @@ dashes only. No underscores, no lowercase.
41
41
  | `DB-` | `db/` | Tables / collections | `types/db.md` |
42
42
  | `DATATYPE-` | `datatype/` | Type schemas | `types/datatype.md` |
43
43
  | `ROLE-` | `role/` | Roles / permissions | `types/role.md` |
44
- | `DOC-` | `doc/` | Documentation, rules, decisions | `types/doc.md` |
44
+ | `DOC-` | `doc/` | Documentation, guides, rules | `types/doc.md` |
45
+ | `DECISION-` | `decision/` | Architecture decisions (ADRs) | `types/decision.md` |
45
46
  | `FILE-` | `file/` | Source file references | `types/file.md` |
46
47
  | `TEST-` | `test/` | Test specs | `types/test.md` |
47
48
  | `EXTERNAL-` | `external/` | External services | `types/external.md` |
@@ -54,6 +55,8 @@ dashes only. No underscores, no lowercase.
54
55
  | `DIAGRAM-` | `diagram/` | Architecture diagrams | `types/diagram.md` |
55
56
  | `AGENT-` | `agent/` | AI agent instructions | `types/agent.md` |
56
57
  | `PLAN-` | `plan/` | Plan docs (`plan.md` at root = `PLAN-PROJECT`) | `types/plan.md` |
58
+ | `FEATURE-` | `feature/` | Future work units (iteration) | `types/feature.md` |
59
+ | `RELEASE-` | `release/` | Version milestones | `types/release.md` |
57
60
 
58
61
  Read the matching `types/<type>.md` before writing a card of a type you haven't
59
62
  authored in this session — it has the field table and a golden example.
@@ -76,7 +79,11 @@ Beyond the four reserved keys, a few **cross-type metadata fields** are valid on
76
79
  (defined in `schemas/card.json`) but are tool-managed, not hand-authored: `code_refs` (extra
77
80
  code this card is bound to — `path` or `path:symbol`), `verified_sha` / `verified_at` (set by
78
81
  `set_verified` — the drift baseline), and `notes` (append-only typed memory, via
79
- `append_note`). Reach for the tools rather than writing these by hand.
82
+ `append_note`). Reach for the tools rather than writing these by hand. Notes are
83
+ retrievable: `search` matches note text, `list_notes` lists them across cards by kind
84
+ (every gotcha / every decision in one call), and `get_card` filters them per card.
85
+ A `decision` note is for a choice local to that one card; a decision that shaped
86
+ *several* cards gets its own `DECISION` card, connected to each of them.
80
87
 
81
88
  ## Connections — how the graph gets wired
82
89
 
@@ -104,6 +111,8 @@ that's how you mark future work.
104
111
  - STATE: a ```mermaid stateDiagram-v2 block.
105
112
  - DIAGRAM: a ```mermaid flowchart with **handles as node IDs** so the diagram joins
106
113
  the graph.
114
+ - DECISION: `## Context` / `## Decision` / `## Alternatives` / `## Consequences`
115
+ sections (suggested, not enforced).
107
116
  - Everything else: prose with `[[links]]`. Put relationship nuance in prose, not
108
117
  in structure.
109
118
 
@@ -171,6 +180,24 @@ plan mode pulling the relevant plan into context — `traverse` from the entry p
171
180
  you intend into the plan you present. Execute those Constellation writes first, before any
172
181
  code, once the user approves.
173
182
 
183
+ ## Iterating: features & releases
184
+
185
+ PLAN cards and phases carry the *initial* build. Once a project is live, work
186
+ arrives as feature branches and ships as versions — model that with FEATURE and
187
+ RELEASE cards:
188
+
189
+ - A coherent slice of future work is a **FEATURE** card: connect it to every card
190
+ it adds or touches (new work as `status: planned`), record intent / scope /
191
+ acceptance in the body, and set `branch:` while it's in flight. Its status is
192
+ the arc: `planned` → `building` (on its branch) → `built` (merged) →
193
+ `verified`. A shipped FEATURE stays — it's the record of why the system grew.
194
+ - A version milestone is a **RELEASE** card; features target it via their
195
+ `release:` field. The body is theme + upgrade/migration notes — **never a
196
+ changelog** (what shipped is git's job).
197
+ - Not a ticket tracker: work that's one card's status flip needs no FEATURE
198
+ card. The backlog stays `list_cards status: ["planned", "building", "none"]`;
199
+ a FEATURE's neighborhood (`traverse` from its handle) is the feature's spec.
200
+
174
201
  ## Syncing the plan to code
175
202
 
176
203
  The plan is the source of truth: you change behavior by editing the **plan first**, then
@@ -246,14 +273,19 @@ Cards never connect across repos; the relationship between repos lives in the
246
273
  2. Write or edit the card — prefer small, byte-cheap writes over rewriting a whole card:
247
274
  `append_note` for a typed note (decision / gotcha / state / deviation / verified),
248
275
  `edit_section` to replace a single `##` section in place.
249
- 3. Verify: `npx constellation lint` (errors break the graph and must be fixed;
276
+ 3. Renaming a handle is a plan-wide operation: use the MCP `rename_card`, which moves the
277
+ file and rewrites every reference (connections, frontmatter values, `[[links]]`, mermaid
278
+ node IDs) as whole tokens. Never hand-rename the file and chase references yourself.
279
+ 4. Verify: `npx constellation lint` (errors break the graph and must be fixed;
250
280
  warnings are quality signals).
251
- 4. Update `status` when reality changes: `planned → building → built`, and mark
281
+ 5. Update `status` when reality changes: `planned → building → built`, and mark
252
282
  `verified` only after checking the card against the actual code — use `set_verified`,
253
283
  which records the git sha you checked against so later drift is detectable
254
- (`stale_report` / `check_sync`).
255
- 5. Never bulk-rewrite `constellation/plan.md` edit the relevant section.
256
- Decisions go in DOC cards (`kind: decision`), one file each, not in the plan.
284
+ (`stale_report` / `check_sync`). The backlog view — everything not yet built — is
285
+ `list_cards status: ["planned", "building", "none"]` (`"none"` = no status set).
286
+ 6. Never bulk-rewrite `constellation/plan.md` edit the relevant section.
287
+ Decisions go in DECISION cards, one file each, not in the plan — connected to
288
+ the cards they shaped (card-local choices: `append_note(kind: decision)`).
257
289
 
258
290
  "What changed in the plan" is never tracked in cards — that's
259
291
  `git diff -- constellation/`. Don't add dirty flags or changelogs to frontmatter. The one
@@ -155,9 +155,13 @@ the plan the way a seasoned engineer reviews a design doc: assume something impo
155
155
  missing, and go find it. This matters more than any single card you write.
156
156
 
157
157
  **First, a quick hygiene sweep** (mechanical, cheap, not the point): `check_integrity` for
158
- orphans, `list_cards connected:false` for islands, lint for dangling `[[links]]`/refs (W004)
158
+ orphans, `list_cards connected:false` for islands, `list_cards status: ["planned",
159
+ "building", "none"]` for the open backlog, lint for dangling `[[links]]`/refs (W004)
159
160
  and unresolved structured refs (E005), plus code with no card and `built` cards with no
160
- code. Fix or note these and move on they're table stakes.
161
+ code. Skim the recorded memory too `list_notes kind:gotcha` / `kind:deviation` surfaces
162
+ earlier agents' traps and intentional divergences as review input. If a handle no longer
163
+ says what its card is, `rename_card` moves the file and rewrites every reference plan-wide.
164
+ Fix or note these and move on — they're table stakes.
161
165
 
162
166
  **Then the real review.** Run these lenses across each area *and* the whole — but calibrate
163
167
  to the project's stage and scope; a weekend prototype and a production system have very
@@ -200,7 +204,10 @@ the two kinds of finding:
200
204
 
201
205
  Keep it to the few highest-value items, each with a one-line *why* and the card(s) it
202
206
  implies. Capture confirmed gaps as `status: planned` cards — visible as intent, honest
203
- about not existing yet. Suggest structural cleanups (split an overloaded card, add a
207
+ about not existing yet. When several planned cards form one coherent slice of work,
208
+ group them under a `FEATURE` card (connected to each, intent/scope/acceptance in the
209
+ body), optionally targeting a `RELEASE` milestone via its `release:` field — that is
210
+ how iteration stays modeled once the initial build ships. Suggest structural cleanups (split an overloaded card, add a
204
211
  missing `STATE`, connect two islands) but leave the call to the user. Taste means proposing
205
212
  the smallest set of changes that most improves the plan — not the most cards.
206
213
 
@@ -0,0 +1,59 @@
1
+ # DECISION cards (`DECISION-`, `decision/`)
2
+
3
+ One card per architecture decision (ADR): the choice, the *why*, and the
4
+ alternatives rejected. Docs explain how the system is set up; a DECISION explains
5
+ why it came to be that way. Connect the card to **every card the decision
6
+ shaped** — that's the point of making decisions graph nodes: reading any affected
7
+ card surfaces the reasoning behind it.
8
+
9
+ Scope rule: a choice local to a single card is an `append_note(kind: decision)`
10
+ on that card, not a DECISION card. Promote it to a DECISION card when it touches
11
+ more than one card or was genuinely debated (alternatives worth recording).
12
+
13
+ | Field | Type | Notes |
14
+ |---|---|---|
15
+ | `supersedes` | handle | earlier `DECISION-` card this one replaces; must resolve, and connects the two |
16
+
17
+ `status` reads naturally: `planned` = proposed, `built` = adopted/in effect,
18
+ `verified` = re-checked against the code. Never delete a superseded decision —
19
+ the successor points at it via `supersedes`; history is the point.
20
+
21
+ Body sections (suggested, not enforced): **Context** (the forces), **Decision**
22
+ (what was chosen), **Alternatives** (what was rejected and why), **Consequences**
23
+ (what follows).
24
+
25
+ Example — `constellation/decision/DECISION-NO-HARD-DELETE.md`:
26
+
27
+ ```markdown
28
+ ---
29
+ name: Tickets are never hard-deleted
30
+ status: built
31
+ connections:
32
+ - DB-TICKETS
33
+ - STATE-TICKET
34
+ ---
35
+
36
+ # Tickets are never hard-deleted
37
+
38
+ ## Context
39
+
40
+ Support history is evidence: agents cite past tickets in disputes, and
41
+ [[JOB-AUTO-ASSIGN]] scores assignees on historical volume.
42
+
43
+ ## Decision
44
+
45
+ Rows in [[DB-TICKETS]] are never deleted. "Deleting" a ticket moves it to
46
+ `closed` in [[STATE-TICKET]]; the API exposes no DELETE.
47
+
48
+ ## Alternatives
49
+
50
+ - **Hard delete with an audit table** — rejected: two sources of truth, and the
51
+ audit copy drifts from the live schema.
52
+ - **Soft-delete flag (`deleted_at`)** — rejected: every query must remember to
53
+ filter it; `closed` already expresses "out of the working set."
54
+
55
+ ## Consequences
56
+
57
+ - Table growth is unbounded; revisit archiving if it becomes a problem.
58
+ - Requester PII lives in closed tickets — retention policy must handle it.
59
+ ```
@@ -1,8 +1,8 @@
1
1
  # DOC cards (`DOC-`, `doc/`)
2
2
 
3
3
  No structured fields — DOC cards are prose. Suggested `kind`: `guide`, `rule`,
4
- `decision`, `meta`. Decisions (ADRs) get one DOC card each (`kind: decision`),
5
- never a section in `plan.md`.
4
+ `meta`. DOCs explain *how* the system is set up; the *why* behind a choice is a
5
+ [DECISION card](./decision.md), not a DOC.
6
6
 
7
7
  Example — `constellation/doc/DOC-TICKET-LIFECYCLE.md`:
8
8
 
@@ -0,0 +1,53 @@
1
+ # FEATURE cards (`FEATURE-`, `feature/`)
2
+
3
+ One card per coherent unit of *future* work — the iteration primitive once a
4
+ project is past its initial build. PLAN cards and phases carry the first build;
5
+ after that, work arrives as features on branches. A FEATURE card groups that
6
+ slice: connect it to **every card the feature adds or touches**, so the graph
7
+ answers "what does shipping this involve" in one hop.
8
+
9
+ Scope rule: this is not a ticket tracker. Work small enough to be one card's
10
+ status flip needs no FEATURE card — just flip the status. Reach for a FEATURE
11
+ when the work spans several cards or needs intent/acceptance recorded.
12
+
13
+ | Field | Type | Notes |
14
+ |---|---|---|
15
+ | `release` | handle | `RELEASE-` card this feature targets or shipped in; must resolve, and connects the two |
16
+ | `branch` | string | git branch it's developed on (informational — the card outlives the branch) |
17
+
18
+ `status` is the feature's arc: `planned` = specced, not started; `building` = in
19
+ progress on its branch; `built` = merged; `verified` = confirmed in a release.
20
+ A shipped FEATURE card stays — it's the record of why the system grew, alongside
21
+ any [DECISION cards](./decision.md) it produced.
22
+
23
+ Body: intent (the problem), scope (in/out), acceptance (how you know it's done),
24
+ with `[[links]]` to the cards involved.
25
+
26
+ Example — `constellation/feature/FEATURE-AUTO-ASSIGNMENT.md`:
27
+
28
+ ```markdown
29
+ ---
30
+ name: Auto-assignment of new tickets
31
+ status: planned
32
+ release: RELEASE-V1-1-0
33
+ branch: feature/auto-assign
34
+ connections:
35
+ - JOB-AUTO-ASSIGN
36
+ ---
37
+
38
+ # Auto-assignment of new tickets
39
+
40
+ New tickets sit unassigned until a human triages them; median first-response
41
+ time suffers. Ship [[JOB-AUTO-ASSIGN]] so every ticket created via
42
+ [[API-TICKETS]] gets an assignee within a minute.
43
+
44
+ ## Scope
45
+
46
+ - In: assignment job, round-robin scoring over open ticket counts in [[DB-TICKETS]].
47
+ - Out: skill-based routing; reassignment of already-open tickets.
48
+
49
+ ## Acceptance
50
+
51
+ - A ticket created while at least one agent is active is assigned in < 60s.
52
+ - Assignment respects [[STATE-TICKET]] — only `open` tickets are eligible.
53
+ ```
@@ -5,7 +5,7 @@ where the project stands. Scoped plans (`PLAN-FRONTEND`) live in `plan/`.
5
5
 
6
6
  Keep it **short**. Three rules:
7
7
 
8
- - Decisions go in DOC cards (`kind: decision`), one file each — not in the plan.
8
+ - Decisions go in DECISION cards, one file each — not in the plan.
9
9
  - Per-card status lives on the cards (`status:`), not in plan checklists.
10
10
  - Edit the relevant section; never bulk-rewrite the file (it's shared state).
11
11
 
@@ -0,0 +1,37 @@
1
+ # RELEASE cards (`RELEASE-`, `release/`)
2
+
3
+ One card per version milestone: the **theme and intent** of a release, what's
4
+ targeted at it, and the migration/upgrade notes users need. FEATURE cards point
5
+ here via their `release:` field — the release is the milestone, features are the
6
+ work.
7
+
8
+ **A RELEASE card is not a changelog.** What actually shipped is git's job (tags,
9
+ `diff_plan`, `plan_log`) — never enumerate commits or card-by-card changes in
10
+ the body. Card what git *can't* say: why this release exists, what it's named
11
+ for, what a consumer must do to upgrade.
12
+
13
+ | Field | Type | Notes |
14
+ |---|---|---|
15
+ | `version` | string | exact version string, e.g. `1.1.0` (the handle is the identity: `RELEASE-V1-1-0`) |
16
+
17
+ `status` is the milestone's arc: `planned` = targeted/next; `building` = in
18
+ flight; `built` = shipped/tagged; `verified` = validated in production.
19
+
20
+ Example — `constellation/release/RELEASE-V1-1-0.md`:
21
+
22
+ ```markdown
23
+ ---
24
+ name: v1.1.0 — assignment automation
25
+ status: planned
26
+ version: 1.1.0
27
+ ---
28
+
29
+ # v1.1.0 — assignment automation
30
+
31
+ Theme: stop tickets from sitting unassigned. Everything in this release serves
32
+ median first-response time.
33
+
34
+ ## Upgrade notes
35
+
36
+ - New env var `ASSIGN_INTERVAL_SECONDS` (default 30); no schema migration.
37
+ ```
@@ -1 +1 @@
1
- import{n as e,t}from"./path-BWPyau1x.js";import{a as n,c as r,d as i,f as a,i as o,l as s,m as c,n as l,o as u,p as d,r as f,u as p}from"./dist-C2uHOEFB.js";function m(e){return e.innerRadius}function h(e){return e.outerRadius}function g(e){return e.startAngle}function _(e){return e.endAngle}function v(e){return e&&e.padAngle}function y(e,t,n,r,i,a,o,s){var c=n-e,l=r-t,u=o-i,d=s-a,f=d*c-u*l;if(!(f*f<1e-12))return f=(u*(t-a)-d*(e-i))/f,[e+f*c,t+f*l]}function b(e,t,n,r,i,a,o){var c=e-n,l=t-r,u=(o?a:-a)/d(c*c+l*l),f=u*l,p=-u*c,m=e+f,h=t+p,g=n+f,_=r+p,v=(m+g)/2,y=(h+_)/2,b=g-m,x=_-h,S=b*b+x*x,C=i-a,w=m*_-g*h,T=(x<0?-1:1)*d(s(0,C*C*S-w*w)),E=(w*x-b*T)/S,D=(-w*b-x*T)/S,O=(w*x+b*T)/S,k=(-w*b+x*T)/S,A=E-v,j=D-y,M=O-v,N=k-y;return A*A+j*j>M*M+N*N&&(E=O,D=k),{cx:E,cy:D,x01:-f,y01:-p,x11:E*(i/C-1),y11:D*(i/C-1)}}function x(){var s=m,x=h,S=e(0),C=null,w=g,T=_,E=v,D=null,O=t(k);function k(){var e,t,m=+s.apply(this,arguments),h=+x.apply(this,arguments),g=w.apply(this,arguments)-r,_=T.apply(this,arguments)-r,v=l(_-g),k=_>g;if(D||=e=O(),h<m&&(t=h,h=m,m=t),!(h>1e-12))D.moveTo(0,0);else if(v>c-1e-12)D.moveTo(h*u(g),h*a(g)),D.arc(0,0,h,g,_,!k),m>1e-12&&(D.moveTo(m*u(_),m*a(_)),D.arc(0,0,m,_,g,k));else{var A=g,j=_,M=g,N=_,P=v,F=v,I=E.apply(this,arguments)/2,L=I>1e-12&&(C?+C.apply(this,arguments):d(m*m+h*h)),R=p(l(h-m)/2,+S.apply(this,arguments)),z=R,B=R,V,H;if(L>1e-12){var U=o(L/m*a(I)),W=o(L/h*a(I));(P-=U*2)>1e-12?(U*=k?1:-1,M+=U,N-=U):(P=0,M=N=(g+_)/2),(F-=W*2)>1e-12?(W*=k?1:-1,A+=W,j-=W):(F=0,A=j=(g+_)/2)}var G=h*u(A),K=h*a(A),q=m*u(N),J=m*a(N);if(R>1e-12){var Y=h*u(j),X=h*a(j),Z=m*u(M),Q=m*a(M),$;if(v<i)if($=y(G,K,Z,Q,Y,X,q,J)){var ee=G-$[0],te=K-$[1],ne=Y-$[0],re=X-$[1],ie=1/a(f((ee*ne+te*re)/(d(ee*ee+te*te)*d(ne*ne+re*re)))/2),ae=d($[0]*$[0]+$[1]*$[1]);z=p(R,(m-ae)/(ie-1)),B=p(R,(h-ae)/(ie+1))}else z=B=0}F>1e-12?B>1e-12?(V=b(Z,Q,G,K,h,B,k),H=b(Y,X,q,J,h,B,k),D.moveTo(V.cx+V.x01,V.cy+V.y01),B<R?D.arc(V.cx,V.cy,B,n(V.y01,V.x01),n(H.y01,H.x01),!k):(D.arc(V.cx,V.cy,B,n(V.y01,V.x01),n(V.y11,V.x11),!k),D.arc(0,0,h,n(V.cy+V.y11,V.cx+V.x11),n(H.cy+H.y11,H.cx+H.x11),!k),D.arc(H.cx,H.cy,B,n(H.y11,H.x11),n(H.y01,H.x01),!k))):(D.moveTo(G,K),D.arc(0,0,h,A,j,!k)):D.moveTo(G,K),!(m>1e-12)||!(P>1e-12)?D.lineTo(q,J):z>1e-12?(V=b(q,J,Y,X,m,-z,k),H=b(G,K,Z,Q,m,-z,k),D.lineTo(V.cx+V.x01,V.cy+V.y01),z<R?D.arc(V.cx,V.cy,z,n(V.y01,V.x01),n(H.y01,H.x01),!k):(D.arc(V.cx,V.cy,z,n(V.y01,V.x01),n(V.y11,V.x11),!k),D.arc(0,0,m,n(V.cy+V.y11,V.cx+V.x11),n(H.cy+H.y11,H.cx+H.x11),k),D.arc(H.cx,H.cy,z,n(H.y11,H.x11),n(H.y01,H.x01),!k))):D.arc(0,0,m,N,M,k)}if(D.closePath(),e)return D=null,e+``||null}return k.centroid=function(){var e=(+s.apply(this,arguments)+ +x.apply(this,arguments))/2,t=(+w.apply(this,arguments)+ +T.apply(this,arguments))/2-i/2;return[u(t)*e,a(t)*e]},k.innerRadius=function(t){return arguments.length?(s=typeof t==`function`?t:e(+t),k):s},k.outerRadius=function(t){return arguments.length?(x=typeof t==`function`?t:e(+t),k):x},k.cornerRadius=function(t){return arguments.length?(S=typeof t==`function`?t:e(+t),k):S},k.padRadius=function(t){return arguments.length?(C=t==null?null:typeof t==`function`?t:e(+t),k):C},k.startAngle=function(t){return arguments.length?(w=typeof t==`function`?t:e(+t),k):w},k.endAngle=function(t){return arguments.length?(T=typeof t==`function`?t:e(+t),k):T},k.padAngle=function(t){return arguments.length?(E=typeof t==`function`?t:e(+t),k):E},k.context=function(e){return arguments.length?(D=e??null,k):D},k}export{x as t};
1
+ import{n as e,t}from"./path-BWPyau1x.js";import{a as n,c as r,d as i,f as a,i as o,l as s,m as c,n as l,o as u,p as d,r as f,u as p}from"./dist-BcVVfWxM.js";function m(e){return e.innerRadius}function h(e){return e.outerRadius}function g(e){return e.startAngle}function _(e){return e.endAngle}function v(e){return e&&e.padAngle}function y(e,t,n,r,i,a,o,s){var c=n-e,l=r-t,u=o-i,d=s-a,f=d*c-u*l;if(!(f*f<1e-12))return f=(u*(t-a)-d*(e-i))/f,[e+f*c,t+f*l]}function b(e,t,n,r,i,a,o){var c=e-n,l=t-r,u=(o?a:-a)/d(c*c+l*l),f=u*l,p=-u*c,m=e+f,h=t+p,g=n+f,_=r+p,v=(m+g)/2,y=(h+_)/2,b=g-m,x=_-h,S=b*b+x*x,C=i-a,w=m*_-g*h,T=(x<0?-1:1)*d(s(0,C*C*S-w*w)),E=(w*x-b*T)/S,D=(-w*b-x*T)/S,O=(w*x+b*T)/S,k=(-w*b+x*T)/S,A=E-v,j=D-y,M=O-v,N=k-y;return A*A+j*j>M*M+N*N&&(E=O,D=k),{cx:E,cy:D,x01:-f,y01:-p,x11:E*(i/C-1),y11:D*(i/C-1)}}function x(){var s=m,x=h,S=e(0),C=null,w=g,T=_,E=v,D=null,O=t(k);function k(){var e,t,m=+s.apply(this,arguments),h=+x.apply(this,arguments),g=w.apply(this,arguments)-r,_=T.apply(this,arguments)-r,v=l(_-g),k=_>g;if(D||=e=O(),h<m&&(t=h,h=m,m=t),!(h>1e-12))D.moveTo(0,0);else if(v>c-1e-12)D.moveTo(h*u(g),h*a(g)),D.arc(0,0,h,g,_,!k),m>1e-12&&(D.moveTo(m*u(_),m*a(_)),D.arc(0,0,m,_,g,k));else{var A=g,j=_,M=g,N=_,P=v,F=v,I=E.apply(this,arguments)/2,L=I>1e-12&&(C?+C.apply(this,arguments):d(m*m+h*h)),R=p(l(h-m)/2,+S.apply(this,arguments)),z=R,B=R,V,H;if(L>1e-12){var U=o(L/m*a(I)),W=o(L/h*a(I));(P-=U*2)>1e-12?(U*=k?1:-1,M+=U,N-=U):(P=0,M=N=(g+_)/2),(F-=W*2)>1e-12?(W*=k?1:-1,A+=W,j-=W):(F=0,A=j=(g+_)/2)}var G=h*u(A),K=h*a(A),q=m*u(N),J=m*a(N);if(R>1e-12){var Y=h*u(j),X=h*a(j),Z=m*u(M),Q=m*a(M),$;if(v<i)if($=y(G,K,Z,Q,Y,X,q,J)){var ee=G-$[0],te=K-$[1],ne=Y-$[0],re=X-$[1],ie=1/a(f((ee*ne+te*re)/(d(ee*ee+te*te)*d(ne*ne+re*re)))/2),ae=d($[0]*$[0]+$[1]*$[1]);z=p(R,(m-ae)/(ie-1)),B=p(R,(h-ae)/(ie+1))}else z=B=0}F>1e-12?B>1e-12?(V=b(Z,Q,G,K,h,B,k),H=b(Y,X,q,J,h,B,k),D.moveTo(V.cx+V.x01,V.cy+V.y01),B<R?D.arc(V.cx,V.cy,B,n(V.y01,V.x01),n(H.y01,H.x01),!k):(D.arc(V.cx,V.cy,B,n(V.y01,V.x01),n(V.y11,V.x11),!k),D.arc(0,0,h,n(V.cy+V.y11,V.cx+V.x11),n(H.cy+H.y11,H.cx+H.x11),!k),D.arc(H.cx,H.cy,B,n(H.y11,H.x11),n(H.y01,H.x01),!k))):(D.moveTo(G,K),D.arc(0,0,h,A,j,!k)):D.moveTo(G,K),!(m>1e-12)||!(P>1e-12)?D.lineTo(q,J):z>1e-12?(V=b(q,J,Y,X,m,-z,k),H=b(G,K,Z,Q,m,-z,k),D.lineTo(V.cx+V.x01,V.cy+V.y01),z<R?D.arc(V.cx,V.cy,z,n(V.y01,V.x01),n(H.y01,H.x01),!k):(D.arc(V.cx,V.cy,z,n(V.y01,V.x01),n(V.y11,V.x11),!k),D.arc(0,0,m,n(V.cy+V.y11,V.cx+V.x11),n(H.cy+H.y11,H.cx+H.x11),k),D.arc(H.cx,H.cy,z,n(H.y11,H.x11),n(H.y01,H.x01),!k))):D.arc(0,0,m,N,M,k)}if(D.closePath(),e)return D=null,e+``||null}return k.centroid=function(){var e=(+s.apply(this,arguments)+ +x.apply(this,arguments))/2,t=(+w.apply(this,arguments)+ +T.apply(this,arguments))/2-i/2;return[u(t)*e,a(t)*e]},k.innerRadius=function(t){return arguments.length?(s=typeof t==`function`?t:e(+t),k):s},k.outerRadius=function(t){return arguments.length?(x=typeof t==`function`?t:e(+t),k):x},k.cornerRadius=function(t){return arguments.length?(S=typeof t==`function`?t:e(+t),k):S},k.padRadius=function(t){return arguments.length?(C=t==null?null:typeof t==`function`?t:e(+t),k):C},k.startAngle=function(t){return arguments.length?(w=typeof t==`function`?t:e(+t),k):w},k.endAngle=function(t){return arguments.length?(T=typeof t==`function`?t:e(+t),k):T},k.padAngle=function(t){return arguments.length?(E=typeof t==`function`?t:e(+t),k):E},k.context=function(e){return arguments.length?(D=e??null,k):D},k}export{x as t};
@@ -0,0 +1 @@
1
+ import"./chunk-NNHCCRGN-DlpIbxXb.js";import{x as e}from"./mermaid-parser.core-DkqLwTDu.js";export{e as createArchitectureServices};