@magic-spells/constellation 0.2.0 → 0.2.2

package/skill/SKILL.md

@@ -10,6 +10,20 @@ typed piece of the plan, linked to other cards by **connections**. Filenames are
 identities, frontmatter is structure, the body is prose, and git is the
 change-tracking system.
 
+## Why it exists: durable cross-session memory
+
+Constellation is the project's **durable, cross-session memory** for AI agents — memory you
+share with every past and future agent, not docs you skim. Before changing code an area's
+cards cover, read those cards: you're recovering prior agents' understanding, not starting
+fresh. After changing that code, bring the cards back into line — that's part of "done,"
+like updating tests. Understanding then **compounds** across sessions instead of being
+re-derived each time — but only if the cards stay true, so **a card you can't trust is worse
+than no card.** Put in cards what code can't say (intent, decisions, current state, gotchas,
+cross-cutting rules); never duplicate DDL / signatures / code that lives in the repo — link
+to it, because copies drift. `built`/`verified` is a claim, not a fact: mark it with
+`set_verified` so a later agent can re-check whether the bound code moved (`stale_report` /
+`check_sync`). Durability, not distrust.
+
 ## The one rule that matters most
 
 **The filename is the handle.** `constellation/api/API-TICKETS.md` defines the card
@@ -58,6 +72,12 @@ connections:                       # plain list of handles — no kinds, no dire
   - DB-TICKETS
 ```
 
+Beyond the four reserved keys, a few **cross-type metadata fields** are valid on any card
+(defined in `schemas/card.json`) but are tool-managed, not hand-authored: `code_refs` (extra
+code this card is bound to — `path` or `path:symbol`), `verified_sha` / `verified_at` (set by
+`set_verified` — the drift baseline), and `notes` (append-only typed memory, via
+`append_note`). Reach for the tools rather than writing these by hand.
+
 ## Connections — how the graph gets wired
 
 Connections are undirected and come from four places; all count equally:
@@ -143,8 +163,9 @@ Constellation:
    `set_sync_point`.
 
 **In plan mode, read as much of the plan as you can.** The write tools are unavailable there
-by design (the read tools — `get_card`, `list_cards`, `search`, `traverse`, `describe_type`,
-`check_integrity`, `diff_plan`, `plan_log` — are marked read-only and stay available). Spend
+by design (the read tools — `get_card`, `list_cards`, `search`, `traverse`, `assemble`,
+`describe_type`, `check_integrity`, `diff_plan`, `plan_log`, `stale_report`, `check_sync`,
+`list_connected_repos` — are marked read-only and stay available). Spend
 plan mode pulling the relevant plan into context — `traverse` from the entry points with
 `connected: "full"` — to build a strong model of the project fast, and fold the card edits
 you intend into the plan you present. Execute those Constellation writes first, before any
@@ -222,14 +243,20 @@ Cards never connect across repos; the relationship between repos lives in the
 1. Before creating a card, check it doesn't exist: the filename is deterministic,
    so look up `constellation/<folder>/<HANDLE>.md`; grep for the handle to find
    prose references.
-2. Write or edit the card.
+2. Write or edit the card — prefer small, byte-cheap writes over rewriting a whole card:
+   `append_note` for a typed note (decision / gotcha / state / deviation / verified),
+   `edit_section` to replace a single `##` section in place.
 3. Verify: `npx constellation lint` (errors break the graph and must be fixed;
    warnings are quality signals).
-4. Update `status` when reality changes: `planned → building → built`, and
-   `verified` only after checking the card against the actual code.
+4. Update `status` when reality changes: `planned → building → built`, and mark
+   `verified` only after checking the card against the actual code — use `set_verified`,
+   which records the git sha you checked against so later drift is detectable
+   (`stale_report` / `check_sync`).
 5. Never bulk-rewrite `constellation/plan.md` — edit the relevant section.
    Decisions go in DOC cards (`kind: decision`), one file each, not in the plan.
 
 "What changed in the plan" is never tracked in cards — that's
-`git diff -- constellation/`. Don't add dirty flags, changelogs, or timestamps to
-frontmatter.
+`git diff -- constellation/`. Don't add dirty flags or changelogs to frontmatter. The one
+recorded baseline that's allowed is verification provenance — `verified_sha` / `verified_at`
+(set by `set_verified`), the basis of a "verified" claim, not a change flag; the staleness
+verdict itself is always recomputed live, never stored.

package/skill/methodology.md

@@ -211,8 +211,11 @@ the smallest set of changes that most improves the plan — not the most cards.
 - When reverse-engineering shipped code, default new cards to `built`, then verify in a
   second pass — don't claim `verified` you haven't earned.
 - After reconciling the plan with code, commit the plan, then `set_sync_point` to mark the
-  reconciliation. Change history is git (`diff_plan`, `plan_log`) — never stamp dirty
-  flags, changelogs, or timestamps into cards.
+  reconciliation. Change history is git (`diff_plan`, `plan_log`) — never stamp dirty flags
+  or changelogs into cards. The one allowed baseline is verification provenance: mark a card
+  `verified` with `set_verified` (it records `verified_sha`, the sha you checked against), so
+  `stale_report` / `check_sync` can later flag the card if its bound code moved. The
+  staleness verdict stays live — recomputed from git, never stored.
 - The opposite direction — bringing **code** up to a changed **plan** ("sync the plan to
   the code") — is its own loop, documented in *Syncing the plan to code* in `SKILL.md`:
   `diff_plan` → `traverse` the blast radius → update code → verify → `set_sync_point`. For a

package/viewer/dist/assets/{arc-CMMRgIq9.js → arc-YuzGWkw8.js}

@@ -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-DzXuQd4N.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};
+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};

package/viewer/dist/assets/architecture-7EHR7CIX-BAboPvK1.js

@@ -0,0 +1 @@
+import"./chunk-NNHCCRGN-DlpIbxXb.js";import{x as e}from"./mermaid-parser.core-BdEYBvaj.js";export{e as createArchitectureServices};