@magic-spells/constellation 0.3.0 → 0.4.0

package/constellation/decision/DECISION-FEATURE-RELEASE-TYPES.md

@@ -0,0 +1,50 @@
+---
+name: FEATURE and RELEASE are native card types
+status: built
+connections:
+  - DOC-CARD-TYPES
+  - FILE-TYPES
+  - DECISION-NATIVE-DECISION-TYPE
+---
+
+# FEATURE and RELEASE are native card types
+
+## Context
+
+Constellation modeled the *initial* build well — PLAN cards and phases, work
+marked `status: planned` — but had no primitive for how projects actually grow
+afterwards: feature branches that ship in release versions. `planned` marks
+individual cards, yet nothing groups a coherent slice of work; and a version's
+intent (theme, upgrade notes) had no home that isn't a changelog.
+
+## Decision
+
+Add two types (the 19th and 20th). **FEATURE** — a coherent unit of future
+work, connected to every card it adds or touches; fields `release` (handle of
+the RELEASE it targets — structured ref, auto-connects) and `branch`
+(informational). **RELEASE** — a version milestone; field `version`. Status
+carries each card's arc: a FEATURE goes `planned → building → built` as its
+branch merges; a RELEASE goes `planned → built` as it ships.
+
+Two guardrails hold the philosophy:
+
+- **FEATURE is not a ticket tracker.** Work that is one card's status flip
+  needs no FEATURE card; the backlog stays a `status` query.
+- **RELEASE is not a changelog.** What shipped is git's job ([[DOC-CHANGE-TRACKING]]);
+  the card holds only what git can't say — theme, intent, migration notes.
+
+## Alternatives
+
+- **Scoped PLAN cards per feature** — rejected: plans are living summaries, not
+  units of work with an arc; and retrieval by type ("show open features") needs
+  a prefix.
+- **External trackers only (issues/boards)** — rejected: the plan is the
+  agent-facing memory; work the graph can't see can't be traversed, assembled,
+  or drift-checked.
+
+## Consequences
+
+- The iteration loop is now first-class: feature branch ↔ FEATURE card,
+  release version ↔ RELEASE card, wired by `release:`.
+- A shipped FEATURE card stays, like a DECISION card
+  ([[DECISION-NATIVE-DECISION-TYPE]]) — provenance of why the system grew.

package/constellation/decision/DECISION-NATIVE-DECISION-TYPE.md

@@ -0,0 +1,58 @@
+---
+name: DECISION is a native card type
+status: built
+connections:
+  - DOC-CARD-TYPES
+  - DOC-MCP-UPGRADES
+  - FILE-TYPES
+---
+
+# DECISION is a native card type
+
+Reverses the earlier call in [[DOC-MCP-UPGRADES]] ("decided AGAINST a dedicated
+`DECISION` card type"). This card is itself the first native decision card — the
+new type records the *why*; [[DOC-CARD-TYPES]] records the *what*.
+
+## Context
+
+The original reasoning was that co-location beats a separate filing system:
+decisions live as `append_note(kind: decision)` on the cards they concern, or as
+a DOC card (`kind: decision`) when bigger. Field use broke that model two ways:
+
+- **Volume.** Real projects accumulated 30+ `DOC-…` decision cards, burying the
+  actual documentation (guides, rules) in `doc/` and making "every decision" a
+  kind-filter query instead of a folder and a type.
+- **Fan-out.** A decision routinely shapes *several* cards, so there is no single
+  card to co-locate a note on. The graph already had the right primitive —
+  connections — but no node type for the decision itself.
+
+The skill also already mandated one-file-per-decision ("Decisions (ADRs) get one
+DOC card each"), so the "separate filing system" existed either way; it was just
+typed as documentation.
+
+## Decision
+
+Add `DECISION-` / `decision/` as the 18th type. A DECISION card is an ADR — the
+choice, the why, the alternatives rejected — **connected to every card it
+shaped**. One structured field, `supersedes` (an earlier DECISION handle; must
+resolve, and connects the two). Superseded decisions are kept, never deleted.
+
+`append_note(kind: decision)` stays: it remains the right home for a choice local
+to a single card. Promote a note to a DECISION card when the choice touches more
+than one card or the rejected alternatives are worth recording.
+
+## Alternatives
+
+- **Status quo (DOC `kind: decision`)** — rejected: pollutes `doc/`, invisible in
+  the type system, and retrieval (viewer nav, `list_cards`, `describe_type`)
+  can't treat decisions as first-class.
+- **Notes only, no decision cards** — rejected: cross-cutting decisions have no
+  co-location target; splitting one rationale across N notes drifts.
+
+## Consequences
+
+- `doc/` is documentation again: suggested DOC kinds shrink to guide / rule / meta.
+- Adding the type touched the usual four places ([[DOC-CARD-TYPES]]) plus the
+  three agent-guidance copies and the viewer palette.
+- Existing plans with `DOC-…` decision cards can migrate one card at a time with
+  `rename_card` (e.g. `DOC-DECISION-X` → `DECISION-X`); nothing forces it.

package/constellation/doc/DOC-CARD-TYPES.md

@@ -1,12 +1,12 @@
 ---
-name: The 17 card types
+name: The 20 card types
 kind: reference
 status: built
 ---
 
-# The 17 card types
+# The 20 card types
 
-The prefix before the first dash determines a card's type and must be one of these 17. Folder
+The prefix before the first dash determines a card's type and must be one of these 20. Folder
 placement matches the type (a misfiled card warns W001, not errors — the prefix is
 authoritative). Defined in [[FILE-TYPES]] (`TYPE_NAMES`) and [[FILE-HANDLES]] (`TYPE_FOLDERS`).
 
@@ -17,6 +17,7 @@ authoritative). Defined in [[FILE-TYPES]] (`TYPE_NAMES`) and [[FILE-HANDLES]] (`
 | DATATYPE | `DATATYPE-` | `datatype/` | Data type schemas (interfaces, Zod, etc.) |
 | ROLE | `ROLE-` | `role/` | User roles / permission groups |
 | DOC | `DOC-` | `doc/` | Documentation cards |
+| DECISION | `DECISION-` | `decision/` | Architecture decision records — the why + rejected alternatives |
 | FILE | `FILE-` | `file/` | Source file references (require `path`) |
 | TEST | `TEST-` | `test/` | Test specs |
 | EXTERNAL | `EXTERNAL-` | `external/` | External services / integrations |
@@ -29,6 +30,8 @@ authoritative). Defined in [[FILE-TYPES]] (`TYPE_NAMES`) and [[FILE-HANDLES]] (`
 | DIAGRAM | `DIAGRAM-` | `diagram/` | Architecture diagrams |
 | AGENT | `AGENT-` | `agent/` | AI agent instructions / policies |
 | PLAN | `PLAN-` | `plan/` | Plan documents (`plan.md` = PLAN-PROJECT) |
+| FEATURE | `FEATURE-` | `feature/` | Future work units — the iteration primitive |
+| RELEASE | `RELEASE-` | `release/` | Version milestones — theme + upgrade notes, never a changelog |
 
 **Adding or renaming a type touches four places that must agree:** `TYPE_NAMES`
 ([[FILE-TYPES]]) + `TYPE_FOLDERS` ([[FILE-HANDLES]]); `schemas/<folder>.json`;

package/constellation/doc/DOC-FILE-FORMAT.md

@@ -17,7 +17,7 @@ normative format; the JSON Schemas in `schemas/` define per-type frontmatter and
 The filename IS the handle: `api/API-TICKETS.md` defines the card `API-TICKETS`. There is no
 `handle:` or `type:` field — the path already says it. Handle grammar:
 `^[A-Z][A-Z0-9]*-[A-Z0-9][A-Z0-9-]*$` (3–135 chars; uppercase, digits, dashes). The prefix
-before the first dash is the type and must be one of the 17 canonical prefixes (see
+before the first dash is the type and must be one of the 20 canonical prefixes (see
 [[DOC-CARD-TYPES]]). `plan.md` at the root is the one special file — the card `PLAN-PROJECT`.
 
 ## Frontmatter

package/constellation/doc/DOC-LINT-CODES.md

@@ -15,7 +15,7 @@ Structural codes come from [[FILE-INDEXER]]; schema codes (W002/W003) from [[FIL
 | Code | Rule |
 |---|---|
 | E001 | Filename is not a valid handle |
-| E002 | Handle prefix is not one of the 17 canonical prefixes |
+| E002 | Handle prefix is not one of the 20 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 |

package/constellation/doc/DOC-MCP-UPGRADES.md

@@ -46,9 +46,10 @@ call. `assemble` fuses both into a fan-out-ready work package.
   change flag; the drift verdict stays live and unstored ([[DOC-CHANGE-TRACKING]], [[FILE-SYNC]]).
 - **Code attach is same-repo** — cards never bind across repos; reach a sibling's code via the
   `repo` selector ([[DOC-CONNECTED-REPOS]]).
-- **Decided AGAINST a dedicated `DECISION` card type** — decisions live as data on the cards
-  they concern: an `append_note(kind: decision)`, a DOC card (`kind: decision`, like this one),
-  or a DIAGRAM. Co-location beats a separate filing system you have to remember to open.
+- **Decided AGAINST a dedicated `DECISION` card type** — *superseded by
+  [[DECISION-NATIVE-DECISION-TYPE]]*: real projects accumulated dozens of DOC decision cards,
+  and cross-cutting decisions have no single card to co-locate a note on. Card-local choices
+  still live as `append_note(kind: decision)` on the card they concern.
 - **Memory must be retrievable to be memory** — `search` indexes note text alongside bodies,
   and `list_notes` gives the cross-card view (every gotcha / every decision in one call). A
   note that full-text search can't find would silently defeat the point of appending it.

package/constellation/file/FILE-HANDLES.md

@@ -3,7 +3,7 @@ name: handles.ts
 status: built
 path: src/core/handles.ts
 language: typescript
-summary: Handle grammar, the 17 canonical prefixes, and the type↔folder map
+summary: Handle grammar, the 20 canonical prefixes, and the type↔folder map
 ---
 
 Defines the handle regex (`^[A-Z][A-Z0-9]*-[A-Z0-9][A-Z0-9-]*$`), `isHandleShaped` / `isKnownHandle` / `typeForHandle`, and `TYPE_FOLDERS` — the authority for which prefix is which type and where its cards live.

package/constellation/file/FILE-TYPES.md

@@ -3,7 +3,7 @@ name: types.ts
 status: built
 path: src/core/types.ts
 language: typescript
-summary: Core domain types + TYPE_NAMES (the 17 types)
+summary: Core domain types + TYPE_NAMES (the 20 types)
 ---
 
 `Card`, `Connection`, `PlanIndex`, `Issue`, `CardRefs`, `ConnectedRepo`, and `TYPE_NAMES`. One of the four places a type addition must touch.

package/constellation/file/FILE-VALIDATE.md

@@ -8,4 +8,4 @@ connections:
   - FILE-TYPES
 ---
 
-Validates each card's frontmatter against `schemas/`. Derives the W003 base allow-list from `card.json`'s properties (not a hardcoded list), so cross-type metadata fields are blessed on all 17 types. Ajv ships CJS — loaded via createRequire.
+Validates each card's frontmatter against `schemas/`. Derives the W003 base allow-list from `card.json`'s properties (not a hardcoded list), so cross-type metadata fields are blessed on all 20 types. Ajv ships CJS — loaded via createRequire.

package/dist/core/handles.d.ts

@@ -7,7 +7,7 @@ export declare const HANDLE_MAX_LENGTH = 135;
 export declare const TYPE_FOLDERS: Record<TypeName, string>;
 /** True when the string matches the handle grammar (prefix may be unknown). */
 export declare function isHandleShaped(value: string): boolean;
-/** Type for a handle's prefix, or null when the prefix is not one of the 17. */
+/** Type for a handle's prefix, or null when the prefix is not one of the 20. */
 export declare function typeForHandle(handle: string): TypeName | null;
 /** Shaped AND carries a known prefix — the test used for reference extraction. */
 export declare function isKnownHandle(value: string): boolean;

package/dist/core/handles.js

@@ -10,6 +10,7 @@ export const TYPE_FOLDERS = {
     DATATYPE: 'datatype',
     ROLE: 'role',
     DOC: 'doc',
+    DECISION: 'decision',
     FILE: 'file',
     TEST: 'test',
     EXTERNAL: 'external',
@@ -22,6 +23,8 @@ export const TYPE_FOLDERS = {
     DIAGRAM: 'diagram',
     AGENT: 'agent',
     PLAN: 'plan',
+    FEATURE: 'feature',
+    RELEASE: 'release',
 };
 const TYPE_SET = new Set(TYPE_NAMES);
 /** True when the string matches the handle grammar (prefix may be unknown). */
@@ -30,7 +33,7 @@ export function isHandleShaped(value) {
         value.length <= HANDLE_MAX_LENGTH &&
         HANDLE_PATTERN.test(value));
 }
-/** Type for a handle's prefix, or null when the prefix is not one of the 17. */
+/** Type for a handle's prefix, or null when the prefix is not one of the 20. */
 export function typeForHandle(handle) {
     const dash = handle.indexOf('-');
     if (dash <= 0)

package/dist/core/handles.js.map

@@ -1 +1 @@
-{"version":3,"file":"handles.js","sourceRoot":"","sources":["../../src/core/handles.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAiB,MAAM,YAAY,CAAC;AAEvD,oEAAoE;AACpE,MAAM,CAAC,MAAM,cAAc,GAAG,qCAAqC,CAAC;AAEpE,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC;AACnC,MAAM,CAAC,MAAM,iBAAiB,GAAG,GAAG,CAAC;AAErC,mEAAmE;AACnE,MAAM,CAAC,MAAM,YAAY,GAA6B;IACpD,GAAG,EAAE,KAAK;IACV,EAAE,EAAE,IAAI;IACR,QAAQ,EAAE,UAAU;IACpB,IAAI,EAAE,MAAM;IACZ,GAAG,EAAE,KAAK;IACV,IAAI,EAAE,MAAM;IACZ,IAAI,EAAE,MAAM;IACZ,QAAQ,EAAE,UAAU;IACpB,KAAK,EAAE,OAAO;IACd,SAAS,EAAE,WAAW;IACtB,IAAI,EAAE,MAAM;IACZ,GAAG,EAAE,KAAK;IACV,IAAI,EAAE,MAAM;IACZ,KAAK,EAAE,OAAO;IACd,OAAO,EAAE,SAAS;IAClB,KAAK,EAAE,OAAO;IACd,IAAI,EAAE,MAAM;CACb,CAAC;AAEF,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAS,UAAU,CAAC,CAAC;AAE7C,+EAA+E;AAC/E,MAAM,UAAU,cAAc,CAAC,KAAa;IAC1C,OAAO,CACL,KAAK,CAAC,MAAM,IAAI,iBAAiB;QACjC,KAAK,CAAC,MAAM,IAAI,iBAAiB;QACjC,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC,CAC3B,CAAC;AACJ,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,aAAa,CAAC,MAAc;IAC1C,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACjC,IAAI,IAAI,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAC3B,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;IACrC,OAAO,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAE,MAAmB,CAAC,CAAC,CAAC,IAAI,CAAC;AAC5D,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,aAAa,CAAC,KAAa;IACzC,OAAO,cAAc,CAAC,KAAK,CAAC,IAAI,aAAa,CAAC,KAAK,CAAC,KAAK,IAAI,CAAC;AAChE,CAAC"}
+{"version":3,"file":"handles.js","sourceRoot":"","sources":["../../src/core/handles.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAiB,MAAM,YAAY,CAAC;AAEvD,oEAAoE;AACpE,MAAM,CAAC,MAAM,cAAc,GAAG,qCAAqC,CAAC;AAEpE,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC;AACnC,MAAM,CAAC,MAAM,iBAAiB,GAAG,GAAG,CAAC;AAErC,mEAAmE;AACnE,MAAM,CAAC,MAAM,YAAY,GAA6B;IACpD,GAAG,EAAE,KAAK;IACV,EAAE,EAAE,IAAI;IACR,QAAQ,EAAE,UAAU;IACpB,IAAI,EAAE,MAAM;IACZ,GAAG,EAAE,KAAK;IACV,QAAQ,EAAE,UAAU;IACpB,IAAI,EAAE,MAAM;IACZ,IAAI,EAAE,MAAM;IACZ,QAAQ,EAAE,UAAU;IACpB,KAAK,EAAE,OAAO;IACd,SAAS,EAAE,WAAW;IACtB,IAAI,EAAE,MAAM;IACZ,GAAG,EAAE,KAAK;IACV,IAAI,EAAE,MAAM;IACZ,KAAK,EAAE,OAAO;IACd,OAAO,EAAE,SAAS;IAClB,KAAK,EAAE,OAAO;IACd,IAAI,EAAE,MAAM;IACZ,OAAO,EAAE,SAAS;IAClB,OAAO,EAAE,SAAS;CACnB,CAAC;AAEF,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAS,UAAU,CAAC,CAAC;AAE7C,+EAA+E;AAC/E,MAAM,UAAU,cAAc,CAAC,KAAa;IAC1C,OAAO,CACL,KAAK,CAAC,MAAM,IAAI,iBAAiB;QACjC,KAAK,CAAC,MAAM,IAAI,iBAAiB;QACjC,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC,CAC3B,CAAC;AACJ,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,aAAa,CAAC,MAAc;IAC1C,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACjC,IAAI,IAAI,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAC3B,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;IACrC,OAAO,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAE,MAAmB,CAAC,CAAC,CAAC,IAAI,CAAC;AAC5D,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,aAAa,CAAC,KAAa;IACzC,OAAO,cAAc,CAAC,KAAK,CAAC,IAAI,aAAa,CAAC,KAAK,CAAC,KAAK,IAAI,CAAC;AAChE,CAAC"}

package/dist/core/indexer.js

@@ -57,7 +57,7 @@ function readCard(relPath, filePath, raw, issues) {
         issues.push({
             severity: 'error',
             code: 'E002',
-            message: `Unknown handle prefix: ${handle.split('-')[0]}- (expected one of the 17 canonical prefixes)`,
+            message: `Unknown handle prefix: ${handle.split('-')[0]}- (expected one of the 20 canonical prefixes)`,
             file: relPath,
         });
         return null;

package/dist/core/types.d.ts

@@ -1,4 +1,4 @@
-export declare const TYPE_NAMES: readonly ["API", "DB", "DATATYPE", "ROLE", "DOC", "FILE", "TEST", "EXTERNAL", "EVENT", "COMPONENT", "PAGE", "JOB", "FLOW", "STATE", "DIAGRAM", "AGENT", "PLAN"];
+export declare const TYPE_NAMES: readonly ["API", "DB", "DATATYPE", "ROLE", "DOC", "DECISION", "FILE", "TEST", "EXTERNAL", "EVENT", "COMPONENT", "PAGE", "JOB", "FLOW", "STATE", "DIAGRAM", "AGENT", "PLAN", "FEATURE", "RELEASE"];
 export type TypeName = (typeof TYPE_NAMES)[number];
 export interface CardRefs {
     /** Handles listed in the frontmatter `connections` key. */

package/dist/core/types.js

@@ -1,5 +1,6 @@
 export const TYPE_NAMES = [
-    'API', 'DB', 'DATATYPE', 'ROLE', 'DOC', 'FILE', 'TEST', 'EXTERNAL', 'EVENT',
-    'COMPONENT', 'PAGE', 'JOB', 'FLOW', 'STATE', 'DIAGRAM', 'AGENT', 'PLAN',
+    'API', 'DB', 'DATATYPE', 'ROLE', 'DOC', 'DECISION', 'FILE', 'TEST', 'EXTERNAL',
+    'EVENT', 'COMPONENT', 'PAGE', 'JOB', 'FLOW', 'STATE', 'DIAGRAM', 'AGENT', 'PLAN',
+    'FEATURE', 'RELEASE',
 ];
 //# sourceMappingURL=types.js.map

package/dist/core/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO;IAC3E,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM;CAC/D,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU;IAC9E,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM;IAChF,SAAS,EAAE,SAAS;CACZ,CAAC"}

package/dist/mcp/server.js

@@ -55,12 +55,15 @@ whole card — make the honest update the easy one: append_note adds an append-o
 replaces a single ## section in place. Reach for these to record a correction the moment you
 learn it, so cards stay true instead of drifting. Notes are retrievable memory: search
 matches note text, and list_notes lists them across cards by kind — every gotcha or decision
-in one call. To rename a handle, use rename_card: it moves the file and rewrites every
+in one call. A decision note is for a choice local to that one card; a decision that shaped
+SEVERAL cards gets its own DECISION card, connected to every card it shaped (the successor
+of a replaced decision points at it via supersedes — never delete decision history). To
+rename a handle, use rename_card: it moves the file and rewrites every
 reference plan-wide (connections, frontmatter values, [[links]], mermaid node IDs) as whole
 tokens — never delete-and-recreate to rename.
 
 describe_type is the type reference, served by this server: call it with no args for the
-catalog of all 17 card types, or with a type (e.g. describe_type PAGE) for that type's
+catalog of all 20 card types, or with a type (e.g. describe_type PAGE) for that type's
 frontmatter schema + a golden example. Consult it before authoring a type you haven't used
 this session — you don't need the authoring skill loaded to get the fields right.
 
@@ -96,6 +99,12 @@ the affected neighborhood (get_card / traverse / search, connected: "full"), the
 update the cards so they describe the desired END STATE (work that isn't built yet is
 status: planned), wiring every connection between the affected cards. Show that set of card
 changes as the proposal; on approval, bring the CODE up to match via the sync loop above.
+Past the initial build, model iteration explicitly: a coherent slice of future work is a
+FEATURE card connected to every card it adds or touches (intent/scope/acceptance in the
+body, branch: while in flight, status planned → building → built as it merges), optionally
+targeting a RELEASE card (a version milestone; features point at it via release:). A RELEASE
+body is theme + upgrade notes, NEVER a changelog — what shipped is git's job. Neither is a
+ticket tracker: work that is one card's status flip needs no FEATURE card.
 FINISH by reconciling — re-read the touched cards against the code, run check_integrity so
 no affected card is left an orphan and every connection is set, bump status (planned →
 building → built → verified), commit, and set_sync_point. In plan mode the write tools are
@@ -807,7 +816,7 @@ export function buildServer(options = {}) {
     }));
     server.registerTool('describe_type', {
         annotations: { readOnlyHint: true },
-        description: 'The card-type reference, served straight from this package. Call with no args for the catalog — all 17 types with their prefix, folder, and one-line purpose. Call with a type for everything needed to author one: the frontmatter JSON Schema (fields, which are required, descriptions) plus the golden example and authoring guidance. Use it before writing a card of a type you have not authored this session — it is the contract create_card/create_cards/update_card validate against (W002/W003), so you do not need the authoring skill loaded to get the fields right.',
+        description: 'The card-type reference, served straight from this package. Call with no args for the catalog — all 20 types with their prefix, folder, and one-line purpose. Call with a type for everything needed to author one: the frontmatter JSON Schema (fields, which are required, descriptions) plus the golden example and authoring guidance. Use it before writing a card of a type you have not authored this session — it is the contract create_card/create_cards/update_card validate against (W002/W003), so you do not need the authoring skill loaded to get the fields right.',
         inputSchema: {
             type: typeSchema.optional().describe('omit for the full catalog'),
         },