@magic-spells/constellation 0.2.2 → 0.4.0

package/docs/001-file-format.md

@@ -1,265 +0,0 @@
-# Constellation File Format (v2)
-
-Constellation stores a project's architecture plan as markdown files in the repo, under a
-`constellation/` folder. Each file is one **card** — one typed piece of the plan,
-linked to other cards by **connections**. ("Node" is reserved for diagram elements
-inside DIAGRAM cards; everything else is a card.)
-Git provides branching, diffing, merging, and history for the plan; the Constellation
-tooling (lint, MCP, viewer) provides validation, graph queries, and rendering on top.
-
-This document is the normative format spec. The JSON Schemas in `schemas/` define the
-per-type frontmatter fields; the skill in `skill/` teaches AI agents to author cards.
-
-## Design principles
-
-1. **The files are the source of truth.** Everything else — reverse indexes, catalogs,
-   rollups, subgraph diagrams, diffs — is derived in memory and never stored.
-2. **A card with no frontmatter is valid.** The file path gives identity; the body gives
-   content. All structure is opt-in.
-3. **Git is the change-tracking system.** `git diff -- constellation/` *is* the plan diff.
-   Lifecycle state (`status`) is a property of a card; "what changed" is a property of
-   history — the format never conflates them.
-4. **Cheap to connect.** Connections are a plain list of handles. Friction on
-   connecting cards produces sparse graphs, and a sparse graph is useless.
-
-## Folder layout
-
-```
-constellation/
-  plan.md              ← the project plan (handle PLAN-PROJECT)
-  api/
-    API-TICKETS.md
-  datatype/
-    DATATYPE-TICKET.md
-  db/
-    DB-TICKETS.md
-  doc/  file/  test/  external/  event/  component/
-  page/  job/  flow/  state/  diagram/  agent/  role/  plan/
-```
-
-- The plan root is a folder named `constellation/`, normally at the repo root. Tooling
-  finds it by walking up from the working directory (like `.git`).
-- Each card lives in the folder matching its type (see table below). Folder placement is
-  a **convention**: the handle prefix is authoritative for type; a card in the wrong
-  folder lints as a warning, not an error.
-- `plan.md` at the plan root is the one special file: it is the card `PLAN-PROJECT`
-  (type PLAN). Additional PLAN cards (e.g. `PLAN-FRONTEND`) live in `plan/`.
-
-## Files and handles
-
-**The filename is the handle.** `api/API-TICKETS.md` defines the card `API-TICKETS`.
-There is no `handle:` or `type:` field in frontmatter — the path already says it, and one
-source of truth means they can never disagree.
-
-Handle grammar:
-
-```
-^[A-Z][A-Z0-9]*-[A-Z0-9][A-Z0-9-]*$     (3–135 characters)
-```
-
-Uppercase letters, digits, and dashes. The prefix (everything before the first dash)
-determines the type and MUST be one of the 17 canonical prefixes. v1 alias prefixes
-(`TYPE-`, `COMP-`, `RULE-`) are not valid in v2.
-
-| Type      | Prefix       | Folder       | What it is                                  |
-|-----------|--------------|--------------|---------------------------------------------|
-| API       | `API-`       | `api/`       | HTTP/RPC endpoints                          |
-| DB        | `DB-`        | `db/`        | Database tables / collections               |
-| DATATYPE  | `DATATYPE-`  | `datatype/`  | Data type schemas (interfaces, Zod, etc.)   |
-| ROLE      | `ROLE-`      | `role/`      | User roles / permission groups              |
-| DOC       | `DOC-`       | `doc/`       | Documentation cards                         |
-| FILE      | `FILE-`      | `file/`      | Source file references                      |
-| TEST      | `TEST-`      | `test/`      | Test specs                                  |
-| EXTERNAL  | `EXTERNAL-`  | `external/`  | External services / integrations            |
-| EVENT     | `EVENT-`     | `event/`     | Domain events / signals                     |
-| COMPONENT | `COMPONENT-` | `component/` | Reusable UI components                      |
-| PAGE      | `PAGE-`      | `page/`      | Frontend routes / screens                   |
-| JOB       | `JOB-`       | `job/`       | Background / scheduled / queued work        |
-| FLOW      | `FLOW-`      | `flow/`      | Multi-step sequenced processes              |
-| STATE     | `STATE-`     | `state/`     | State machines                              |
-| DIAGRAM   | `DIAGRAM-`   | `diagram/`   | Architecture diagrams                       |
-| AGENT     | `AGENT-`     | `agent/`     | AI agent instructions / policies            |
-| PLAN      | `PLAN-`      | `plan/`      | Plan documents (`plan.md` = `PLAN-PROJECT`) |
-
-## Card anatomy
-
-```markdown
----
-name: List & create tickets
-status: built
-path: /api/v1/tickets
-methods:
-  GET:
-    query_params:
-      - { name: status, type: string }
-    response_schema: DATATYPE-TICKET
-  POST:
-    request_schema: DATATYPE-CREATE-TICKET-INPUT
-    response_schema: DATATYPE-TICKET
-connections:
-  - DB-TICKETS
----
-
-# Tickets API
-
-Returns tickets for the active inbox. POST validates the requester exists
-before inserting — see [[FLOW-CREATE-TICKET]] for the full sequence.
-```
-
-### Frontmatter
-
-YAML frontmatter is optional. Four keys are **reserved** (defined in
-`schemas/card.json`); every other key is a type-specific field (defined in
-`schemas/<type>.json`):
-
-| Key           | Type     | Meaning                                                      |
-|---------------|----------|--------------------------------------------------------------|
-| `name`        | string   | Display name (the handle is the identity; this is the label) |
-| `kind`        | string   | Subtype discriminator, lowercase slug (`sql-table`, `e2e`, `decision`) |
-| `status`      | enum     | Lifecycle: `planned` \| `building` \| `built` \| `verified`  |
-| `connections` | string[] | Plain list of handles this card is connected to              |
-
-Beyond the reserved keys, `schemas/card.json` also defines a few **cross-type metadata
-fields** — valid on *any* card and managed by tooling rather than hand-authored:
-
-| Key            | Type     | Meaning                                                                 |
-|----------------|----------|------------------------------------------------------------------------|
-| `code_refs`    | string[] | Code the card is bound to (`path` or `path:symbol`), for drift detection and code attach. The *primary* binding stays a connected `FILE` card's `path:`; `code_refs` adds precision where it earns its keep. |
-| `verified_sha` | string   | Git sha the card was last verified against — the drift baseline (see *Change tracking* below). |
-| `verified_at`  | string   | ISO-8601 time the card was last verified. |
-| `notes`        | object[] | Append-only typed memory: `{ kind, text, sha? }`, `kind ∈ decision \| gotcha \| state \| deviation \| verified`. Ordered newest-last (position is recency); no timestamps. |
-
-Type-specific fields sit at the top level of frontmatter (not nested under a `data` key).
-Schemas are permissive: almost nothing is required, known fields are typed, unknown
-fields are allowed (lint warns so typos get caught).
-
-### Body
-
-The body is markdown — the card's narrative. Two constructs are graph-aware:
-
-- **Wiki-links**: `[[API-TICKETS]]` connects this card to `API-TICKETS`. Use them freely
-  in prose; they are the cheapest way to wire the graph.
-- **Mermaid blocks**: inside ` ```mermaid ` fences, any node identifier shaped like a
-  handle counts as a connection (see Diagrams below).
-
-## Graph rules
-
-The indexer derives the connection set from four sources, in all cards:
-
-1. The `connections:` list in frontmatter.
-2. Handle-shaped string values anywhere else in frontmatter (so
-   `response_schema: DATATYPE-TICKET` connects automatically — no need to repeat it in
-   `connections`).
-3. `[[HANDLE]]` wiki-links in the body.
-4. Handle-shaped identifiers inside ` ```mermaid ` blocks in the body.
-
-Connections are **undirected** and deduped by pair: declare a connection on whichever
-card you are editing; both cards see it when queried. Self-references are ignored. The reverse
-view ("what points at X?") is the indexer's job — it is never written into files.
-
-## Diagrams and flows
-
-Three tiers, cheapest first:
-
-1. **Derived subgraphs** (default for "what does this area look like"): the viewer/MCP
-   render any card's neighborhood from the real connection graph on demand. Never stored,
-   never stale.
-2. **Authored Mermaid** (default for conceptual diagrams): a DIAGRAM card whose body is a
-   ` ```mermaid ` block. Use handles as Mermaid node IDs so the diagram joins the graph.
-   Sequence diagrams (`sequenceDiagram`) and state diagrams (`stateDiagram-v2`) work the
-   same way in FLOW and STATE cards.
-3. **Pinned layouts** (escape hatch for curated diagrams): structured `nodes` / `edges` /
-   `phases` in DIAGRAM frontmatter with explicit positions — see `schemas/diagram.json`. Use
-   only when layout carries meaning; positions make noisy diffs.
-
-**FLOW cards are linear.** Steps are a numbered markdown list in the body, with nested
-list items for error/edge cases. If a flow needs real branching, it is either a Mermaid
-flowchart or actually a STATE card.
-
-```markdown
-1. [[PAGE-INBOX]] submits the new ticket form
-2. [[API-CREATE-TICKET]] validates the requester
-   - if the requester is unknown → 422, form shows inline error
-3. Ticket row inserted into [[DB-TICKETS]]
-4. [[EVENT-TICKET-CREATED]] fires → [[JOB-AUTO-ASSIGN]]
-```
-
-## Lint policy
-
-**Errors** (break the graph; non-zero exit, CI should block):
-
-| Code | Rule |
-|------|------|
-| E001 | Filename is not a valid handle |
-| E002 | Handle prefix is not one of the 17 canonical prefixes |
-| E003 | Duplicate handle (two files resolve to the same handle) |
-| E004 | `connections` entry is not a handle-shaped string |
-| E005 | `connections` or frontmatter-field target resolves to no card |
-| E006 | Frontmatter is not valid YAML |
-
-**Warnings** (style/quality; reported, exit 0):
-
-| Code | Rule |
-|------|------|
-| W001 | Card is not in the folder matching its type |
-| W002 | Frontmatter violates the type's JSON Schema |
-| W003 | Unknown frontmatter field (not a reserved/cross-type key from `card.json`, not in the type schema) |
-| W004 | Body `[[link]]` or Mermaid reference resolves to no card |
-
-The split between E005 and W004 is deliberate: structured references (frontmatter) are
-contracts and must resolve; prose references may legitimately point at cards that are
-planned but not yet written.
-
-## Change tracking and sync
-
-- **What changed**: `git diff <ref> -- constellation/` . Plan changes ride branches and
-  PRs like any other change; reviewing a plan PR is the human approval gate before an
-  AI syncs code to it.
-- **Sync marker**: a reconciling agent records the last plan commit it synced code against in
-  `constellation/.sync.json` (plan-global, written by `set_sync_point`). "Drifted" = anything
-  in `git diff <synced>..HEAD -- constellation/` (the plan moved) or code commits since the
-  marker (the code moved).
-- **Lifecycle**: `status` tracks where a card is in its life (`planned` → `building` →
-  `built` → `verified`), orthogonal to git history. An agent that verifies a card
-  against the actual code sets `status: verified`.
-- **Verification provenance vs. change tracking.** "What changed" is never stamped into a card
-  — that's git's job: no dirty flags, no changelogs, no per-card *change* marks. The one
-  recorded per-card baseline that *is* kept is `verified_sha`/`verified_at`: when a card is
-  verified against code, `set_verified` stamps the sha it was checked at. That is the basis of
-  a *claim*, not a change flag — and the drift *verdict* ("has the bound code moved since?") is
-  always recomputed live by `stale_report`/`check_sync`, never stored. This is what lets a
-  `built`/`verified` claim be re-verified later instead of taken on faith.
-
-## Connected repos (multi-repo)
-
-A project that spans several repos can declare its siblings on `PLAN-PROJECT`. This is the
-one cross-repo concept in the format, and it is deliberately minimal: each repo's
-`constellation/` is identical to a standalone one, references only its own cards, and lints
-clean on its own — connections never cross repos.
-
-`plan.md` frontmatter may carry a `connected_repos` list (validated by `schemas/plan.json`):
-
-```yaml
-connected_repos:
-  - name: pyramid-server          # lowercase id; the `repo` selector in MCP tools
-    path: ../pyramid-server       # relative to this repo's root (or absolute)
-    description: Back-end API for Pyramid, written in Go.
-```
-
-These are **repo-level links only** — never card-to-card connections, never a merged graph.
-The path is local topology (it may differ per machine), so it is **never validated by lint**;
-tooling reports reachability only when something actually uses it. The MCP server's `repo`
-selector resolves a name (or path) to that sibling's plan, so one agent can read or write
-across repos; the per-repo plan remains the unit, and **plan resolution still never crosses a
-repo boundary** on its own — a sibling is reached only when explicitly named.
-
-## What is deliberately not in the format
-
-- No IDs other than handles. No UUIDs/ULIDs.
-- No cross-repo card references. Cards connect only within their own plan; sibling repos are
-  linked at the project level via `connected_repos` (above), not by handle.
-- No connection kinds, directions, or metadata. If a relationship needs explanation,
-  explain it in prose in the body — structure is for navigation, prose is for meaning.
-- No revision/branch/diff machinery. Git does that.
-- No required fields beyond the filename (single exception: `FILE` cards require `path`,
-  because a file reference without a path refers to nothing).

package/docs/002-mcp.md

@@ -1,186 +0,0 @@
-# Constellation MCP (v2)
-
-The MCP server gives AI agents graph queries, hydrated retrieval, validated writes,
-and git-powered change tracking over a plan folder. It is a thin layer over
-`src/core/`: every tool call reloads the index from disk (tens of milliseconds at
-realistic plan sizes), so it is always correct while files are being edited in
-parallel — no watcher, no cache invalidation.
-
-Entry point: `constellation mcp` (stdio). Bootstrap is folder discovery: the server
-walks up from the working directory to find `constellation/`, **bounded by the repo
-root** (the first ancestor with `.git`) — it never crosses into another repo's plan,
-so a repo with no plan returns `NO_PLAN_FOUND` rather than silently adopting a
-sibling's. No accounts, no tokens, no settings handshake. When no plan exists yet,
-`init_plan` scaffolds `constellation/` + starter `plan.md` (same shared scaffold the
-CLI `constellation init` uses); every other tool works immediately after — no restart.
-
-Every tool also accepts an optional **`repo`** selector to act on a *sibling* repo declared
-in `connected_repos` (see [Connected repos](#connected-repos-multi-repo) below). Without it,
-everything operates on the repo found by walk-up, exactly as before — the boundary above is
-never crossed implicitly, only when a sibling is named.
-
-## Vocabulary
-
-**Card** (a file in the plan), **connection** (an undirected link between two cards).
-Tool responses use `connected_cards`, never `connected_nodes`.
-
-## Hydrated retrieval (core requirement)
-
-Any read tool can return connected cards **with their full data** in one call. Three
-levels, chosen by the caller because the cost is context tokens, not compute:
-
-- `none` — the card(s) only
-- `summary` — connected cards as `{ handle, type, kind, name, status }`
-- `full` — connected cards with complete `frontmatter` and `body`
-
-The acceptance test: one `get_card` call returns an API card plus the complete
-content of every card connected to it (its datatypes, table, tests, docs).
-
-## Tools
-
-### Read
-
-| Tool | Input | Returns |
-|---|---|---|
-| `get_card` | `handle`, `connected?` (default `summary`), `code?` (`none`/`paths`/`direct`), `notes_kind?`, `notes_limit?` | `{ card, connected_cards, code? }` |
-| `list_cards` | `types?`, `kind?`, `status?`, `connected?`, `limit?` | `{ cards: summary[], total }` (`connected:false` → orphans only) |
-| `search` | `q`, `types?`, `limit?` (20), `connected?` (default `none`) | `{ matches: [{ card, score, excerpt, connected_cards? }] }` |
-| `traverse` | `start` (handle or array), `depth?` (2, max 5), `types?`, `detail?` (`summary`/`full`) | `{ cards: [{ …, distance }], connections }` |
-| `assemble` | `handles?` (else the delta since `base?`), `depth?` (1), `code?` (`none`/`paths`/`direct`) | `{ base, seeds, reached_handles, suggested_order, units: [{ handles, files, cards }], fanout }` |
-| `describe_type` | `type?` | No arg → catalog of all 17 types (`{ type, prefix, folder, purpose }`); a type → `{ schema, reference, reserved, prefix, folder }` (frontmatter JSON Schema + golden example). Plan-independent — works with no plan loaded. |
-
-`search` scoring: handle match ≫ name match > kind/type match > body occurrences;
-excerpt is the first matching body line. Seeding `traverse` with multiple handles
-(e.g. the output of `diff_plan`) is the impact-analysis pattern.
-
-### Write
-
-| Tool | Input | Notes |
-|---|---|---|
-| `create_card` | `handle`, `name?`, `kind?`, `status?`, `connections?`, `fields?`, `body?`, `validate?` | Writes `<folder>/<HANDLE>.md`; `fields` = type-specific frontmatter. `validate:false` skips lint (bulk import) |
-| `create_cards` | `cards: [...]` (1–500) | Bulk create: validates all up front, writes all, lints ONCE → intra-batch references resolve. `{ created, failed, cards, issues }` |
-| `update_card` | `handle`, `patch?`, `body?` | See merge semantics below |
-| `append_note` | `handle`, `kind` (`decision`/`gotcha`/`state`/`deviation`/`verified`), `text`, `sha?` | Appends one typed note to `notes` — append-only, no full-body rewrite |
-| `edit_section` | `handle`, `section`, `text` | Replaces one `##` section in the body, the rest byte-for-byte; errors if no such heading |
-| `set_verified` | `handle`, `sha?` (default HEAD), `note?` | Stamps `verified_sha`+`verified_at`, sets `status: verified`, optional verified note |
-| `delete_card` | `handle` | Returns `referenced_by` so the caller can clean up |
-| `add_connection` | `from`, `to` | Appends to `from`'s connections (no-op if already connected from any source) |
-| `add_connections` | `connections: [{from,to}]` (1–1000) | Bulk connect, idempotent/undirected, one lint pass. `{ added, failed, issues }` |
-| `remove_connection` | `a`, `b` | Removes from either card's list; reports if the connection survives via other sources (frontmatter field, body link, mermaid) |
-
-Every write reloads the index, lints, and returns the issues touching the written
-file — an agent finds out immediately if it created a dangling reference. **A card
-is created even when issues are returned** — `issues` are the current lint state,
-not a failure. For migrations, prefer `create_cards` + `add_connections` (batched,
-one lint pass, no transient dangling-reference noise) or `create_card validate:false`
-followed by a single `check_integrity`.
-
-**Merge semantics for `update_card`:** `patch.name/kind/status` set (or delete with
-`null`); `patch.connections` replaces the list wholesale (use add/remove_connection
-for incremental edits); `patch.fields` deep-merges into type-specific frontmatter —
-objects merge recursively, arrays replace, `null` deletes a key. `body` replaces the
-whole body.
-
-**Formatting preservation:** a body-only update never touches frontmatter bytes.
-A frontmatter update re-serializes **only the top-level keys whose values
-changed** — unchanged keys keep their original text byte-for-byte (flow-style
-maps, comments, and all), so a status flip is a one-line diff. Key order is
-preserved; new keys append. Only a changed key's value normalizes to canonical
-YAML style.
-
-### Git
-
-| Tool | Input | Returns |
-|---|---|---|
-| `diff_plan` | `base?`, `head?` | `{ base, base_source, head, changes: [{ handle, file, change, changed_keys?, body_changed? }] }` |
-| `plan_log` | `handle`, `limit?` (20) | commits touching that card |
-| `set_sync_point` | `sha?` (default `HEAD`) | writes `constellation/.sync.json`; `warning` if the plan is uncommitted |
-| `stale_report` | `base?` | Cards whose bound code changed since their `verified_sha` (else `base`, else marker): `{ checked, stale_count, stale: [{ handle, name, status, baseline, baseline_source, changed_files, missing_files }], no_baseline }` |
-| `check_sync` | `base?` | Definition-of-done verdict: plan-global `state` + drift counts + integrity + `status_rollup` + per-card `stale_cards`. Advisory (cannot block) |
-| `check_integrity` | — | lint result + `orphans` (zero-connection cards) |
-
-`diff_plan` base resolution: explicit argument → sync marker (`.sync.json`) →
-`HEAD` (i.e. uncommitted plan changes). `head` defaults to the working tree.
-`change` is `added` / `modified` / `removed` / `renamed`; for modified cards the
-old and new versions are parsed and compared, yielding `changed_keys` (frontmatter)
-and `body_changed`.
-
-The sync workflow ("sync the plan to the code"): the plan is the source of truth, so
-a code-sync agent brings code up to a changed plan — it calls `diff_plan` (base =
-marker), traverses the changed handles for blast radius, updates code, then
-`set_sync_point` to move the marker. For a large diff it acts as an **orchestrator**:
-it partitions the blast radius into non-overlapping neighborhoods and fans out a
-sub-agent per neighborhood (split on file boundaries so no two agents touch the same
-file), which keeps the orchestrator's context clean and on the macro view. It always
-verifies the sub-agents' work — against the cards, and via build/tests — after they
-finish, and only then sets the sync point (once). `.sync.json` is versioned, rides
-branches, and the indexer ignores dotfiles so it is never treated as a card.
-
-### Code binding, drift & assembly (the durability loop)
-
-A card binds to code two ways: a connected `FILE` card's `path:` (the primary binding) or the
-card's own `code_refs` (`path` or `path:symbol` — optional precision). That binding powers three
-things, all sharing one resolver (`src/core/code.ts`):
-
-- **Attach** — `get_card(handle, code: "paths" | "direct")`. `paths` returns the resolved bound
-  file paths (cheap; the agent Reads what it wants); `direct` attaches their contents under
-  per-file (64 KB) and total (256 KB) caps, skipping binaries, lockfiles, and generated output,
-  truncation noted. Same-repo only — cards never bind across repos, so use the `repo` selector to
-  attach a sibling's code from the sibling's card.
-- **Detect** — `stale_report` / `check_sync` flag every `built`/`verified` card whose bound code
-  changed since its `verified_sha` baseline (reverse drift), plus bound files that have vanished.
-  The verdict is computed live from git; nothing is stored.
-- **Assemble** — `assemble` turns a delta (or handle set) into a work package: the seed cards +
-  their neighborhood (full) + bound code + a heuristic build order + **file-disjoint units**, so a
-  large change can be fanned out one sub-agent per unit with no two touching the same file.
-
-Cheap writes keep the memory honest: `append_note` (append-only typed notes) and `edit_section`
-(replace one `##` section) are byte-preserving, so recording a correction the moment you learn it
-costs far less than rewriting a card — removing the friction that otherwise causes drift.
-
-### Viewer
-
-| Tool | Input | Returns |
-|---|---|---|
-| `start_viewer` | `port?` (default 4747; `0` = any free port), `readonly?`, `open?` | `{ url, port, plan_root, editable }`; idempotent — if already running, `{ already_running, url, plan_root }` |
-| `stop_viewer` | — | `{ stopped, was }`, or `{ running: false }` if it wasn't running |
-
-`start_viewer` renders the plan as a browsable, editable site and scans forward from the
-requested port for a free one, so always read the actual `port` from the response and post
-the `url` back to the user. The viewer runs until `stop_viewer` or until the MCP process exits.
-
-### Connected repos (multi-repo)
-
-A project can declare sibling repos on `PLAN-PROJECT` `connected_repos` (name + path +
-description; see `docs/001-file-format.md`). These are repo-level links, not card
-connections — each repo's plan stays self-contained.
-
-Every read and write tool takes an optional **`repo`** selector: omit it for the current plan
-(default, unchanged), or pass a `connected_repos` name (or a path) to read or write **that**
-sibling's plan instead. An unknown `repo` is refused (`UNKNOWN_REPO`, listing the declared
-names) rather than landing in the wrong place. Three tools manage the links:
-
-| Tool | Input | Returns |
-|---|---|---|
-| `list_connected_repos` | `repo?` | `{ connected_repos: [{ name, path, description, reachable }] }` |
-| `add_connected_repo` | `name`, `path`, `description?`, `reciprocate?`, `reverse_description?`, `repo?` | Upserts the link on the selected repo's `PLAN-PROJECT`; `reciprocate` also writes the reverse link into the target repo |
-| `remove_connected_repo` | `name`, `repo?` | Removes the link from the selected repo's `PLAN-PROJECT` |
-
-Paths are local topology and are **never** linted; `reachable` is computed at call time.
-Cross-repo investigation has two modes: read a sibling's *plan* in-process with `repo:`, or —
-for the sibling's real code, or when its plan can't answer — spawn a sub-agent scoped to that
-repo's path. For one change spanning repos, the orchestrator writes the per-repo card updates
-with `repo:` set on every write, then fans out a per-repo implementer sub-agent (each in plain
-single-repo mode) and sets each repo's sync point.
-
-## What v1 tools deliberately died
-
-- `expand_handles` — handles ARE the identifiers; nothing to resolve.
-- `init_project` / `link_project` / `check_health` — bootstrap is finding a folder.
-  (`init_plan` exists for MCP-only environments, but it just creates the folder —
-  no server, no settings file, no linking.)
-- `read_plan` / `update_plan` — `get_card("PLAN-PROJECT")` / `update_card`.
-
-(Bulk variants were *not* dropped — v1 punted on them, but `create_cards` /
-`add_connections` now exist: batching lints once, so intra-batch references resolve
-without transient dangling-reference noise. See the Write table above.)

package/docs/003-mcp-upgrade-plan.md

@@ -1,138 +0,0 @@
-# 003 — Constellation MCP Upgrade Plan
-
-_Status: **implemented** (branch `feat/mcp-upgrades-003`). Authored 2026-06-19 from two agents using Constellation as cross-session memory during a real build (a Claude building `pyramid-server`'s GitHub integration + a Claude building `pyramid-web`). Companion to [002-mcp.md](./002-mcp.md)._
-
-> **Implementation status (2026-06-19).** Phases 0–6 all landed, with tests:
-> - **0** framing → MCP `instructions` + `skill/SKILL.md` + `skill/methodology.md` (all three copies).
-> - **1** cheap writes → `append_note`, `edit_section` (byte-preserving).
-> - **2** binding + baseline → `set_verified`; cross-type `code_refs` / `verified_sha` / `verified_at` / `notes` live in `schemas/card.json`, blessed on all 17 types via `validate.ts`.
-> - **3** detect → `stale_report` (per-card reverse drift vs `verified_sha`).
-> - **4** attach → `get_card(code: "paths" | "direct")` with size caps + skips (`src/core/code.ts`).
-> - **5** assemble → `assemble` (work package + file-disjoint fan-out units).
-> - **6** enforcement → `check_sync` (exposes the existing `computeSyncStatus` over MCP + per-card drift; advisory, can't block).
->
-> **Deferred / decided:** the optional *memory-structure* extras — a dedicated `DECISION` card type and a structured partial-status model — are **not** built; typed `notes` (`kind: decision | state | …`) cover most of that need for now. Code *attach* is intentionally **same-repo** (cards never bind across repos — the invariant holds; reach a sibling's code via the `repo` selector). The "no per-card stamping" format rule was reconciled, not broken: `verified_sha` is verification *provenance* (a recorded claim baseline), while the drift *verdict* is still computed live and never stored.
-
-## Why this plan exists
-
-Constellation is used as **durable, cross-session, cross-agent memory** for AI coding agents. Every session an agent pays a "discovery tax" — building a mental model of the code before it can act. Without a place to bank that understanding it evaporates at session end and the next agent re-pays it in full. Constellation's value is that the understanding **compounds** instead.
-
-Two failure modes erode that value; this plan attacks both:
-
-1. **Drift** — a card's claim (`status: built`, a DDL block, a "not built yet" note) silently diverges from the code. *A card you can't trust is worse than no card.*
-2. **Friction** — updating a card is expensive (today it's a full-body replace), so agents skip it — which *causes* drift.
-
-### Design principles (apply to every change below)
-
-- **`built` is a claim that outlives its author.** The agent reading a card next isn't the one who verified it and can't see the basis; code drifts after marking; even a careful agent can miss a path. So claims must be **re-verifiable**, not taken on faith forever. This is *durability, not distrust* — the same reason you keep tests even though you trust the author.
-- **Card what code can't say** — intent, decisions, current state, gotchas, cross-cutting rules. **Don't duplicate** DDL / signatures / code that lives in the repo; link to it. Copies drift; the repo is the source of truth.
-- **Make the honest path the cheap path.** Most drift is just skipped updates. Lower the cost of a small correction and cards stay true.
-- **Purpose belongs in the intro.** The MCP `instructions` are loaded every session; stating what Constellation is *for* and how to treat it changes agent defaults more than any tool.
-
----
-
-## The two headline capabilities
-
-Everything else ladders up to two things agents actually want the MCP to *do*.
-
-### A. "Hand me the delta" — what changed since I last looked
-
-Given a sync marker (or explicit handles), report what changed and hand back a ready-to-work bundle. Two directions:
-
-- **Plan-side** — which cards changed. ✅ **Already exists** — `diff_plan` reports per-card changes since the sync marker / HEAD.
-- **Code-side** — which cards are bound to code that changed *without the card moving* (reverse drift). ❌ **Missing — the core new capability.**
-- **Assemble** — turn that delta into a work package: changed cards + their connected cards (full) + the bound code + a suggested dependency order, optionally split into file-disjoint units for fan-out.
-
-### B. "Hand me the code behind a card"
-
-When a card connects to FILE cards (which carry a `path:`), optionally attach the live file — so an agent starts from *intent + current reality* in one call instead of a card describing code it then has to hunt down.
-
-```
-get_card(handle, connected: "full", code: "none" | "paths" | "direct")
-```
-- **`paths`** — return resolved file paths of *directly*-connected FILE cards. Cheap; the agent Reads what it wants. Default for interactive agents.
-- **`direct`** — attach the *contents* of directly-connected FILE cards (capped). For background / fan-out coders that shouldn't need a second round-trip.
-- Resolves **cross-repo** via `connected_repos` — a `pyramid-web` card can pull the real `pyramid-server` file it's bound to.
-
-These two share machinery: **Assemble (A) reuses B's path-resolution** to attach each coder's files to its work package.
-
----
-
-## Supporting infrastructure (what A and B need underneath)
-
-### Binding — how a card points at code _(foundational; A and B both need it)_
-Today the only binding is a FILE card's `path:`. Keep that as the primary binding; add an optional `code_refs` (`path` or `path:symbol`) on any card for precision. **Recommendation:** FILE-`path:` is the default; `code_refs` only where drift precision earns its keep, so you don't tax every card.
-
-### `verified_sha` / `verified_at` _(foundational; A's code-side drift needs a baseline)_
-When a card is marked `built`/`verified`, stamp the git sha + timestamp it was verified against. Code-side drift then = "bound files changed since `verified_sha`." Without a baseline there's nothing to diff against.
-
-### Cheap writes _(kills the #1 drift cause)_
-- `append_note(handle, kind, text)` — append-only, **no full-body rewrite**. `kind ∈ {decision, gotcha, state, deviation, verified}`. _(Audit `plan_log` first — it may already cover part of this; if so, surface it in the intro so agents reach for it.)_
-- Section-level edit — replace a single `##` section.
-- **Compaction / filtering** so append-only notes don't bloat a card — retrieval returns latest-N or filters by kind.
-
-### Memory structure _(so the gold is queryable, not buried in prose)_
-- First-class typed notes (state / gotcha / decision / deviation) instead of free-text provenance, so a tool can answer *"show every known limitation in area X."*
-- **Partial status** for half-built cards: `{ built: [...], pending: [...] }` or per-section — instead of jamming "inbound done, outbound not" into one enum + prose.
-- Optional `DECISION` card type (or decision log): rationale + rejected alternatives — the highest-value "don't re-litigate" memory.
-
----
-
-## Phased rollout (by leverage-per-effort)
-
-| Phase | What | Why here | Effort |
-|---|---|---|---|
-| **0** | **Reframe the MCP `instructions`** — purpose (memory/compounding), discipline (update cards as part of *done*), content rule (intent yes / code-copies no), durability framing, "a card you can't trust is worse than none." | Loaded every session; changes defaults; **zero code**. | XS |
-| **1** | **Cheap writes** — `append_note`, section edit, note compaction. | Removes the friction that causes drift. | S |
-| **2** | **Binding + `verified_sha`** — FILE `path:` (+ optional `code_refs`); stamp sha/time on verify. | Foundational for 3–5. | S–M |
-| **3** | **Detect** — code-side drift report (`stale_report`) atop the existing `diff_plan`. | Makes `built` re-verifiable. | M |
-| **4** | **Attach** — `get_card(..., code: "paths"\|"direct")` with guardrails. | Capability B; high value every session. | M |
-| **5** | **Assemble** — `assemble(delta\|handles)` → work package + file-disjoint fan-out units. | Capability A; bridges to multi-agent orchestration. | M–L |
-| **6** | **Enforcement** — `check_sync` / definition-of-done hook: code changed without bound cards re-verified → surface/block. | Takes "remember to sync" off the human. | M |
-
-**If you only do three:** Phase 0 (framing), Phase 1 (cheap writes), Phase 4 `paths` mode. They change every future session for modest code.
-
-**Sequencing:** 0 → 1 → 2 → (3 ‖ 4) → 5 → 6, with the memory-structure track folded into 1 and 3.
-
----
-
-## Guardrails for Attach (B) — the craft is here
-
-Without these, attaching files backfires (token blow-up buries the one file you wanted):
-
-- **Opt-in + scoped** — `code: "direct"` attaches only *directly*-connected FILE cards, never the whole neighborhood.
-- **Size caps** — per-file cap with truncation noted; total budget reported.
-- **Missing / moved file → drift warning, not an error** — a stale `path:` is a useful signal (feeds Detect).
-- **Skip** binaries, lockfiles, generated output.
-- **`paths` is the cheap 80%** — return resolved paths, let the agent Read selectively. Default for interactive use; `direct` for background coders.
-
----
-
-## Proposed tool surface (sketch)
-
-```
-# existing
-diff_plan(base?)                       # plan-side delta (per-card changes)            ✅ have
-
-# new
-append_note(handle, kind, text)        # append-only; no full-body rewrite              P1
-set_verified(handle, sha?, note?)      # stamp verified_sha + verified_at               P2
-stale_report(base?)                    # cards whose bound code changed since verify     P3
-get_card(handle, connected, code)      # code: "none" | "paths" | "direct" (+ caps)     P4
-assemble(delta | handles, code?)       # work package: cards + connected + code + order  P5
-check_sync()                           # code touched without bound cards re-verified    P6
-```
-
----
-
-## The one decision everything hinges on
-
-**Code-binding granularity.** FILE-`path:` only is simplest but coarse (file-level drift). `path:symbol` gives precise drift detection at higher authoring cost. **Recommendation:** FILE-`path:` as the default binding for most cards; `code_refs` with symbols only where precision earns its keep. Detect's precision, Attach's accuracy, and Assemble's bundles all ride on this choice.
-
----
-
-## Provenance
-
-Synthesized 2026-06-19 from two Claude agents using Constellation as working memory across the `pyramid-server` + `pyramid-web` build:
-- **Intro-purpose framing, write-friction, memory-structure, phasing** — pyramid-server Claude.
-- **Durability-not-suspicion framing for verification, the Detect/Assemble split, attach guardrails + `paths`-vs-`direct` modes** — pyramid-web Claude.

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

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

package/viewer/dist/assets/channel-D8YnBgqu.js

@@ -1 +0,0 @@
-import{at as e,ot as t}from"./chunk-CSCIHK7Q-C9h7yfl1.js";var n=(n,r)=>t.lang.round(e.parse(n)[r]);export{n as t};

package/viewer/dist/assets/chunk-QZHKN3VN-ClYnv9g5.js

@@ -1 +0,0 @@
-import{h as e}from"./src-BPb55SrS.js";var t=class{constructor(e){this.init=e,this.records=this.init()}static{e(this,`ImperativeState`)}reset(){this.records=this.init()}};export{t};

package/viewer/dist/assets/chunk-WU5MYG2G-CvL2Yleq.js

@@ -1 +0,0 @@
-import{h as e,p as t}from"./src-BPb55SrS.js";import{x as n}from"./chunk-CSCIHK7Q-C9h7yfl1.js";var r=e(e=>{let{securityLevel:r}=n(),i=t(`body`);return r===`sandbox`&&(i=t((t(`#i${e}`).node()?.contentDocument??document).body)),i.select(`#${e}`)},`selectSvgElement`);export{r as t};

package/viewer/dist/assets/classDiagram-4FO5ZUOK-B8YUd1jx.js

@@ -1 +0,0 @@
-import{h as e}from"./src-BPb55SrS.js";import"./chunk-CSCIHK7Q-C9h7yfl1.js";import"./chunk-5ZQYHXKU-wzW5x_7z.js";import"./chunk-O5CBEL6O-SvZfZ-0j.js";import"./chunk-FMBD7UC4-BcSnkYc3.js";import"./chunk-BSJP7CBP-C30ZXEUD.js";import"./chunk-L5ZTLDWV-DGwFsVWy.js";import"./chunk-ND2GUHAM-PqmKwdzq.js";import"./chunk-55IACEB6-NdWURd2K.js";import"./chunk-2J33WTMH-CpuwKeX6.js";import"./chunk-NZK2D7GU-BAZbzxhl.js";import"./chunk-3OPIFGDE-BG_ijJhE.js";import"./chunk-KSCS5N6A-rxSD5-MD.js";import"./chunk-LZXEDZCA-BY3sTuvt.js";import{i as t,n,r,t as i}from"./chunk-727SXJPM-BxKeJXYf.js";var a={parser:n,get db(){return new i},renderer:r,styles:t,init:e(e=>{e.class||={},e.class.arrowMarkerAbsolute=e.arrowMarkerAbsolute},`init`)};export{a as diagram};

package/viewer/dist/assets/classDiagram-v2-Q7XG4LA2-B8YUd1jx.js

@@ -1 +0,0 @@
-import{h as e}from"./src-BPb55SrS.js";import"./chunk-CSCIHK7Q-C9h7yfl1.js";import"./chunk-5ZQYHXKU-wzW5x_7z.js";import"./chunk-O5CBEL6O-SvZfZ-0j.js";import"./chunk-FMBD7UC4-BcSnkYc3.js";import"./chunk-BSJP7CBP-C30ZXEUD.js";import"./chunk-L5ZTLDWV-DGwFsVWy.js";import"./chunk-ND2GUHAM-PqmKwdzq.js";import"./chunk-55IACEB6-NdWURd2K.js";import"./chunk-2J33WTMH-CpuwKeX6.js";import"./chunk-NZK2D7GU-BAZbzxhl.js";import"./chunk-3OPIFGDE-BG_ijJhE.js";import"./chunk-KSCS5N6A-rxSD5-MD.js";import"./chunk-LZXEDZCA-BY3sTuvt.js";import{i as t,n,r,t as i}from"./chunk-727SXJPM-BxKeJXYf.js";var a={parser:n,get db(){return new i},renderer:r,styles:t,init:e(e=>{e.class||={},e.class.arrowMarkerAbsolute=e.arrowMarkerAbsolute},`init`)};export{a as diagram};

package/viewer/dist/assets/eventmodeling-FCH6USID-CZ5gxAxG.js

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