@magic-spells/constellation 0.2.1 → 0.3.0

package/dist/mcp/server.js

@@ -1,4 +1,4 @@
-import { readFile, rm } from 'node:fs/promises';
+import { readFile, rm, stat } from 'node:fs/promises';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
@@ -9,12 +9,29 @@ import { loadPlan } from '../core/indexer.js';
 import { lintPlan } from '../core/lint.js';
 import { resolvePlanDir } from '../core/resolve.js';
 import { TYPE_NAMES } from '../core/types.js';
-import { diffPlan, planDirty, planLog, writeSyncPoint } from '../core/git.js';
+import { changedFilesSince, diffPlan, headSha, planDirty, planLog, readSyncPoint, resolveCommit, writeSyncPoint, } from '../core/git.js';
+import { computeSyncStatus } from '../core/sync.js';
+import { boundPathsForCard, resolveCodeForCard } from '../core/code.js';
 import { searchCards } from './search.js';
-import { applyCardPatch, createCardFile, deepMerge, relPathForHandle, reservedFieldKeys, updateCardFile, } from '../core/writer.js';
-import { connectedRepoToFm, listConnectedRepos, readConnectedRepos, removeConnectedRepoEntry, resolveConnectedRepo, upsertConnectedRepo, } from '../core/repos.js';
+import { applyCardPatch, bodyHeadingTexts, createCardFile, deepMerge, mutateCardFile, relPathForHandle, replaceBodySection, reservedFieldKeys, withAppendedNote, } from '../core/writer.js';
+import { renameCard, RenameCardError } from '../core/rename.js';
+import { connectedRepoToFm, connectedReposFromFrontmatter, listConnectedRepos, readConnectedRepos, removeConnectedRepoEntry, resolveConnectedRepo, upsertConnectedRepo, } from '../core/repos.js';
 const INSTRUCTIONS = `# Constellation MCP
 
+Constellation is this project's durable, cross-session memory for AI agents — treat it as
+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. The payoff is that understanding COMPOUNDS across sessions
+instead of being re-derived from scratch each time; that only holds if you keep the cards
+true. A card you can't trust is worse than no card.
+
+Put in cards what the code can't say — intent, decisions (and the alternatives you rejected),
+current built/live state, gotchas, cross-cutting rules. Do NOT duplicate what the repo already
+holds — DDL, signatures, code: link to it instead; copies drift. "built"/"verified" is a
+claim, not a fact — stamp it with set_verified so a later agent can re-check whether the bound
+code moved (stale_report / check_sync). Durability, not distrust.
+
 The project's architecture plan lives as markdown files in a constellation/ folder.
 Each file is a **card** (the filename is the handle: api/API-TICKETS.md = API-TICKETS);
 cards are linked by undirected **connections** derived from the connections: frontmatter
@@ -22,11 +39,25 @@ list, handle-shaped frontmatter values, [[HANDLE]] body links, and mermaid node
 
 Retrieval is hydrated: get_card / search / traverse can return connected cards with
 their FULL frontmatter and body in one call (connected: "full"). Use that when you are
-about to work on an area; use "summary" for orientation.
+about to work on an area; use "summary" for orientation. get_card can also hand back the
+CODE a card is bound to — code: "paths" returns the resolved file paths of its connected
+FILE cards (path:) plus its own code_refs; code: "direct" attaches their contents (over-cap
+files truncated, binaries/lockfiles/generated skipped) so a background coder starts from
+intent + current code in one call. assemble turns a delta (or a handle set) into a work package: the changed
+cards + their neighborhood (full) + bound code + a heuristic build order + FILE-DISJOINT
+units you can fan out one sub-agent per, with no two touching the same file.
 
 Writes are validated: every write tool lints and returns issues for the file it touched.
 update_card patch.fields deep-merges (arrays replace, null deletes); body replaces.
-Body-only updates never reformat frontmatter.
+Body-only updates never reformat frontmatter. Prefer SMALL, cheap writes over rewriting a
+whole card — make the honest update the easy one: append_note adds an append-only typed note
+(decision / gotcha / state / deviation / verified) with no full-body rewrite; edit_section
+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
+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
@@ -34,7 +65,13 @@ frontmatter schema + a golden example. Consult it before authoring a type you ha
 this session — you don't need the authoring skill loaded to get the fields right.
 
 Change tracking is git: diff_plan reports per-card changes since the sync marker (or HEAD).
-Never stamp dirty flags into cards.
+Never stamp dirty flags or changelogs into cards — "what changed" is git's job. The one
+recorded baseline that IS allowed is verification provenance: set_verified stamps verified_sha
+(the git sha you checked a card against) + verified_at. That is the basis of a claim, not a
+change flag — and the staleness VERDICT is always recomputed live (stale_report / check_sync),
+never stored. stale_report lists built/verified cards whose bound code changed since their
+verified_sha (reverse drift); check_sync rolls that per-card drift plus the plan-global state
+into one definition-of-done verdict (advisory — the server reports, it can't block).
 
 "Sync the plan" / "sync the plan to the code" = bring the CODE up to match the plan (the
 plan is the source of truth — behavior changes in the plan FIRST, then in code, never the
@@ -62,9 +99,10 @@ changes as the proposal; on approval, bring the CODE up to match via the sync lo
 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
-unavailable 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), so spend plan mode READING: pull in as much of the relevant plan as you can
+unavailable by design (the read tools — get_card, list_cards, list_notes, 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), so spend plan mode READING:
+pull in as much of the relevant plan as you can
 (traverse from the entry points, connected: "full") to build a strong model of the project
 fast, fold the intended card edits into the plan you present, and write them to
 Constellation first, before any code, once the user approves.
@@ -73,7 +111,11 @@ For migrations or large scaffolds, use create_cards and add_connections (batched
 lint pass) instead of many single calls — connections between cards in the same batch
 resolve without transient "does not resolve" errors. A card is created even when issues
 are returned (issues are lint state, not failure). check_integrity reports orphans
-(zero-connection cards), and list_cards connected:false lists them.
+(zero-connection cards), and list_cards connected:false lists them. The BACKLOG view —
+everything not yet built — is list_cards status: ["planned", "building", "none"] ("none" =
+cards with no status set, which usually means unbuilt). traverse takes the same status
+filter as a post-filter: the walk still passes through built cards, so a built hub never
+hides the planned work behind it.
 
 The plan folder is found by walking up from the working directory, BOUNDED by the repo
 root (it never adopts another repo's plan). If no plan exists in this repo (tools return
@@ -231,15 +273,165 @@ function connectedCards(index, handle, detail) {
 function issuesForFile(issues, relPath) {
     return issues.filter((i) => i.file === relPath);
 }
+/**
+ * Code-side drift: for every card that makes a claim about code it is bound to
+ * (status built/verified, or carrying a verified_sha) compare its bound files
+ * against its baseline (its own verified_sha, else the passed base, else the
+ * sync marker). A card whose bound code changed — or whose bound file vanished —
+ * since it was verified is stale. The verdict is computed live and never stored.
+ * Shared by stale_report and check_sync.
+ */
+async function computeStaleCards(root, index, base) {
+    let marker = null;
+    try {
+        marker = (await readSyncPoint(root))?.synced_sha ?? null;
+    }
+    catch {
+        marker = null;
+    }
+    const fallback = base ?? marker ?? null;
+    const claims = [];
+    for (const card of index.cards.values()) {
+        const verifiedSha = typeof card.frontmatter.verified_sha === 'string'
+            ? card.frontmatter.verified_sha
+            : undefined;
+        const isClaim = card.status === 'built' || card.status === 'verified' || Boolean(verifiedSha);
+        if (!isClaim)
+            continue;
+        if (boundPathsForCard(index, card).length === 0)
+            continue;
+        const resolved = await resolveCodeForCard(root, index, card, 'paths');
+        claims.push({
+            card,
+            baseline: verifiedSha ?? fallback,
+            baseline_source: verifiedSha ? 'verified_sha' : base ? 'argument' : 'sync-marker',
+            paths: resolved.files.map((f) => f.path),
+            missing: resolved.files.filter((f) => !f.exists).map((f) => f.path),
+        });
+    }
+    // Pass 2: one git call per DISTINCT baseline (usually just the sync marker),
+    // not one per card — a plan with 100 verified cards must not spawn 100 diffs.
+    const changedBy = new Map();
+    const baselines = new Set(claims.map((c) => c.baseline).filter((b) => Boolean(b)));
+    for (const baseline of baselines) {
+        const union = [
+            ...new Set(claims.filter((c) => c.baseline === baseline).flatMap((c) => c.paths)),
+        ];
+        try {
+            changedBy.set(baseline, await changedFilesSince(root, baseline, union));
+        }
+        catch {
+            changedBy.set(baseline, 'unreachable');
+        }
+    }
+    const stale = [];
+    const noBaseline = [];
+    for (const { card, baseline, baseline_source, paths, missing } of claims) {
+        if (!baseline) {
+            noBaseline.push({ handle: card.handle, status: card.status ?? null, files: paths });
+            continue;
+        }
+        const changed = changedBy.get(baseline);
+        if (changed === 'unreachable') {
+            noBaseline.push({
+                handle: card.handle,
+                status: card.status ?? null,
+                files: paths,
+                reason: `baseline ${baseline.slice(0, 8)} unreachable in git history`,
+            });
+            continue;
+        }
+        const changedFiles = paths.filter((p) => changed.has(p));
+        if (changedFiles.length > 0 || missing.length > 0) {
+            stale.push({
+                handle: card.handle,
+                name: card.name ?? null,
+                status: card.status ?? null,
+                baseline: baseline.slice(0, 12),
+                baseline_source,
+                changed_files: changedFiles,
+                missing_files: missing,
+            });
+        }
+    }
+    return { checked: claims.length, stale, no_baseline: noBaseline };
+}
+// Rough dependency tiers for assemble's suggested build order: data first, then
+// contracts, then surfaces. Connections are undirected, so this is a heuristic
+// by type, not a true topological sort.
+const TYPE_TIER = {
+    DB: 0, DATATYPE: 1, ROLE: 2, EXTERNAL: 2, EVENT: 2,
+    API: 3, JOB: 3, STATE: 4, FLOW: 4, COMPONENT: 5, PAGE: 6,
+    FILE: 7, TEST: 8, DOC: 9, DIAGRAM: 9, AGENT: 9, PLAN: 9,
+};
+const tierOf = (type) => TYPE_TIER[type] ?? 5;
+/**
+ * Partition seed handles into groups whose bound file sets are disjoint, so each
+ * group can be handed to its own sub-agent with no risk of two agents editing
+ * the same file. Seeds that share any bound file land in the same group.
+ */
+function partitionByFiles(seeds, filesBy) {
+    const parent = new Map();
+    seeds.forEach((s) => parent.set(s, s));
+    const find = (x) => {
+        let root = x;
+        while (parent.get(root) !== root)
+            root = parent.get(root);
+        while (parent.get(x) !== root) {
+            const next = parent.get(x);
+            parent.set(x, root);
+            x = next;
+        }
+        return root;
+    };
+    const union = (a, b) => parent.set(find(a), find(b));
+    const fileOwner = new Map();
+    for (const s of seeds) {
+        for (const f of filesBy.get(s) ?? []) {
+            const owner = fileOwner.get(f);
+            if (owner)
+                union(owner, s);
+            else
+                fileOwner.set(f, s);
+        }
+    }
+    const groups = new Map();
+    for (const s of seeds) {
+        const r = find(s);
+        if (!groups.has(r))
+            groups.set(r, { handles: [], files: new Set() });
+        const g = groups.get(r);
+        g.handles.push(s);
+        for (const f of filesBy.get(s) ?? [])
+            g.files.add(f);
+    }
+    return [...groups.values()].map((g) => ({
+        handles: g.handles.sort(),
+        files: [...g.files].sort(),
+    }));
+}
 const detailSchema = z.enum(['none', 'summary', 'full']);
 const typeSchema = z.enum(TYPE_NAMES);
 const statusSchema = z.enum(['planned', 'building', 'built', 'verified']);
+// Filter variant: "none" selects cards with no status at all — unset usually
+// means nobody has claimed the card is built, so backlog queries want it.
+const statusFilterSchema = z.enum(['planned', 'building', 'built', 'verified', 'none']);
+const statusesSchema = z
+    .union([statusFilterSchema, z.array(statusFilterSchema).min(1)])
+    .optional();
+function statusSetOf(status) {
+    if (status === undefined)
+        return null;
+    return new Set(Array.isArray(status) ? status : [status]);
+}
+const noteKindSchema = z.enum(['decision', 'gotcha', 'state', 'deviation', 'verified']);
+const codeModeSchema = z.enum(['none', 'paths', 'direct']);
 const repoSchema = z
     .string()
     .optional()
     .describe('Target a connected repo by its connected_repos name (or a path). Omit to use the current repo.');
 export function buildServer(options = {}) {
-    const server = new McpServer({ name: 'constellation', version: '0.2.1' }, { instructions: INSTRUCTIONS });
+    const server = new McpServer({ name: 'constellation', version: '0.2.2' }, { instructions: INSTRUCTIONS });
     server.registerPrompt('bootstrap_plan', {
         title: 'Bootstrap a plan from the codebase',
         description: 'Analyze this repository macro→micro and build (or extend) the Constellation plan: follow the data and the user/auth journeys, capture flows, diagrams, and state machines, ask the user what the code cannot answer, and flag gaps.',
@@ -349,29 +541,55 @@ export function buildServer(options = {}) {
     });
     server.registerTool('get_card', {
         annotations: { readOnlyHint: true },
-        description: 'Fetch one card by handle, optionally with all connected cards hydrated. connected: "full" returns the complete frontmatter and body of every connected card — use it when about to work on an area.',
+        description: 'Fetch one card by handle, optionally with all connected cards hydrated. connected: "full" returns the complete frontmatter and body of every connected card — use it when about to work on an area. code: "paths" returns the resolved file paths the card is bound to (connected FILE cards plus code_refs); code: "direct" attaches their contents (over-cap files truncated with truncated:true; binaries/lockfiles/generated skipped) so a background coder starts from intent + current code in one call.',
         inputSchema: {
             handle: z.string(),
             connected: detailSchema.optional().describe('default: summary'),
+            code: codeModeSchema
+                .optional()
+                .describe('attach bound code: none (default) | paths | direct'),
+            notes_kind: noteKindSchema
+                .optional()
+                .describe('filter the returned card.notes to one kind'),
+            notes_limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(100)
+                .optional()
+                .describe('return only the most recent N notes'),
             repo: repoSchema,
         },
-    }, withPlan(async (root, { handle, connected }) => {
+    }, withPlan(async (root, { handle, connected, code, notes_kind, notes_limit }) => {
         const index = await loadPlan(root);
         const card = index.cards.get(handle.toUpperCase());
         if (!card)
             return fail('NOT_FOUND', `No card with handle ${handle}`);
-        return ok({
-            card: full(card),
+        let cardView = full(card);
+        if ((notes_kind || notes_limit) && Array.isArray(card.frontmatter.notes)) {
+            let notes = card.frontmatter.notes.filter((n) => Boolean(n) && typeof n === 'object');
+            if (notes_kind)
+                notes = notes.filter((n) => n.kind === notes_kind);
+            if (notes_limit)
+                notes = notes.slice(-notes_limit);
+            cardView = { ...cardView, frontmatter: { ...card.frontmatter, notes } };
+        }
+        const result = {
+            card: cardView,
             connected_cards: connectedCards(index, card.handle, connected ?? 'summary'),
-        });
+        };
+        if (code && code !== 'none') {
+            result.code = await resolveCodeForCard(root, index, card, code);
+        }
+        return ok(result);
     }));
     server.registerTool('list_cards', {
         annotations: { readOnlyHint: true },
-        description: 'Catalog of cards filtered by type, kind, status, and/or connectedness. connected:false returns orphans (cards with zero connections). Returns summaries (handle, type, kind, name, status).',
+        description: 'Catalog of cards filtered by type, kind, status, and/or connectedness. status takes one value or a list; "none" selects cards with no status at all — status: ["planned", "building", "none"] is the backlog view (everything not yet built). connected:false returns orphans (cards with zero connections). Returns summaries (handle, type, kind, name, status).',
         inputSchema: {
             types: z.array(typeSchema).optional(),
             kind: z.string().optional(),
-            status: statusSchema.optional(),
+            status: statusesSchema.describe('one status or a list; "none" = cards with no status set'),
             connected: z
                 .boolean()
                 .optional()
@@ -382,11 +600,12 @@ export function buildServer(options = {}) {
     }, withPlan(async (root, { types, kind, status, connected, limit }) => {
         const index = await loadPlan(root);
         const typeFilter = types && types.length > 0 ? new Set(types) : null;
+        const statusFilter = statusSetOf(status);
         const isConnected = (h) => (index.connectedHandles.get(h)?.size ?? 0) > 0;
         const matched = [...index.cards.values()]
             .filter((c) => !typeFilter || typeFilter.has(c.type))
             .filter((c) => !kind || c.kind === kind)
-            .filter((c) => !status || c.status === status)
+            .filter((c) => !statusFilter || statusFilter.has(c.status ?? 'none'))
             .filter((c) => connected === undefined || isConnected(c.handle) === connected)
             .sort((a, b) => a.handle.localeCompare(b.handle));
         return ok({
@@ -418,15 +637,16 @@ export function buildServer(options = {}) {
     }));
     server.registerTool('traverse', {
         annotations: { readOnlyHint: true },
-        description: 'Breadth-first walk of the connection graph from one or more starting handles. Seed it with diff_plan output for impact analysis. detail: "full" includes frontmatter and body of every reached card.',
+        description: 'Breadth-first walk of the connection graph from one or more starting handles. Seed it with diff_plan output for impact analysis. detail: "full" includes frontmatter and body of every reached card. status filters the RESULT only — the walk still passes through non-matching cards, so a built hub never hides the planned work behind it (status: ["planned", "building", "none"] = open work in this neighborhood). types, by contrast, prunes the walk itself.',
         inputSchema: {
             start: z.union([z.string(), z.array(z.string()).min(1)]),
             depth: z.number().int().min(0).max(5).optional().describe('default: 2'),
             types: z.array(typeSchema).optional(),
+            status: statusesSchema.describe('post-filter on returned cards; "none" = no status set. The walk passes through non-matching cards.'),
             detail: z.enum(['summary', 'full']).optional().describe('default: summary'),
             repo: repoSchema,
         },
-    }, withPlan(async (root, { start, depth, types, detail }) => {
+    }, withPlan(async (root, { start, depth, types, status, detail }) => {
         const index = await loadPlan(root);
         const starts = (Array.isArray(start) ? start : [start]).map((s) => s.toUpperCase());
         const missing = starts.filter((s) => !index.cards.has(s));
@@ -456,7 +676,12 @@ export function buildServer(options = {}) {
             }
             frontier = next;
         }
+        // Status is a post-filter: the walk above passed THROUGH every card, so
+        // a built hub in the middle never hides open work behind it.
+        const statusFilter = statusSetOf(status);
         const cards = [...distance.entries()]
+            .filter(([handle]) => !statusFilter ||
+            statusFilter.has(index.cards.get(handle).status ?? 'none'))
             .map(([handle, dist]) => {
             const card = index.cards.get(handle);
             return {
@@ -465,9 +690,121 @@ export function buildServer(options = {}) {
             };
         })
             .sort((a, b) => a.distance - b.distance || a.handle.localeCompare(b.handle));
-        const connections = index.connections.filter((c) => distance.has(c.a) && distance.has(c.b));
+        const surviving = new Set(cards.map((c) => c.handle));
+        const connections = index.connections.filter((c) => surviving.has(c.a) && surviving.has(c.b));
         return ok({ cards, connections, not_found: missing });
     }));
+    server.registerTool('assemble', {
+        annotations: { readOnlyHint: true },
+        description: 'Turn a set of cards (or the plan delta since a base) into a ready-to-work package: the seed cards plus their connected neighborhood (full), the code each is bound to (code: paths|direct), a heuristic build order (data → contracts → surfaces), and — the key bit — the seeds split into FILE-DISJOINT units so you can hand one sub-agent per unit with no risk of two agents editing the same file. Omit handles to assemble everything changed since base (default: the sync marker). This is the orchestration bridge: diff_plan + traverse + code attach in one call.',
+        inputSchema: {
+            handles: z
+                .array(z.string())
+                .optional()
+                .describe('seed handles; omit to use the plan delta since base'),
+            base: z
+                .string()
+                .optional()
+                .describe('base for the delta when handles is omitted (default: sync marker)'),
+            depth: z
+                .number()
+                .int()
+                .min(0)
+                .max(3)
+                .optional()
+                .describe('neighborhood depth around each seed (default: 1)'),
+            code: codeModeSchema.optional().describe('attach bound code per card (default: paths)'),
+            repo: repoSchema,
+        },
+    }, withPlan(async (root, { handles, base, depth, code }) => {
+        const index = await loadPlan(root);
+        let seeds;
+        let notFound = [];
+        let delta = null;
+        if (handles && handles.length > 0) {
+            const requested = [...new Set(handles.map((h) => h.toUpperCase()))];
+            seeds = requested.filter((h) => index.cards.has(h));
+            notFound = requested.filter((h) => !index.cards.has(h));
+        }
+        else {
+            let diff;
+            try {
+                diff = await diffPlan(root, base);
+            }
+            catch (err) {
+                return fail('BAD_BASE', `Could not diff against base ${base ?? '(marker/HEAD)'}: ${err instanceof Error ? err.message : String(err)}. Pass a reachable base sha, or omit it to use the sync marker.`);
+            }
+            delta = { base: diff.base, base_source: diff.base_source };
+            seeds = [...new Set(diff.changes.map((c) => c.handle))].filter((h) => index.cards.has(h));
+        }
+        if (seeds.length === 0) {
+            return ok({
+                base: delta,
+                seeds: [],
+                not_found: notFound,
+                units: [],
+                note: handles
+                    ? 'None of the given handles exist in the plan.'
+                    : 'No plan changes since base — nothing to assemble.',
+            });
+        }
+        const maxDepth = depth ?? 1;
+        const distance = new Map();
+        let frontier = seeds;
+        for (const s of seeds)
+            distance.set(s, 0);
+        for (let d = 1; d <= maxDepth && frontier.length > 0; d++) {
+            const next = [];
+            for (const h of frontier) {
+                for (const n of index.connectedHandles.get(h) ?? []) {
+                    if (distance.has(n) || !index.cards.has(n))
+                        continue;
+                    distance.set(n, d);
+                    next.push(n);
+                }
+            }
+            frontier = next;
+        }
+        const reached = [...distance.keys()];
+        const codeMode = code ?? 'paths';
+        const filesBy = new Map();
+        for (const s of seeds) {
+            filesBy.set(s, boundPathsForCard(index, index.cards.get(s)).map((b) => b.path));
+        }
+        const partitions = partitionByFiles(seeds, filesBy);
+        const suggestedOrder = [...reached].sort((a, b) => tierOf(index.cards.get(a).type) - tierOf(index.cards.get(b).type) ||
+            a.localeCompare(b));
+        const units = [];
+        for (const part of partitions) {
+            const cards = [];
+            for (const h of part.handles) {
+                const card = index.cards.get(h);
+                const entry = {
+                    ...full(card),
+                    connected_cards: connectedCards(index, h, 'full'),
+                };
+                if (codeMode !== 'none') {
+                    entry.code = await resolveCodeForCard(root, index, card, codeMode);
+                }
+                cards.push(entry);
+            }
+            units.push({ handles: part.handles, files: part.files, cards });
+        }
+        return ok({
+            base: delta,
+            seeds,
+            not_found: notFound,
+            reached_handles: reached,
+            suggested_order: suggestedOrder,
+            units,
+            fanout: {
+                unit_count: units.length,
+                note: units.length > 1
+                    ? `${units.length} file-disjoint units — assign one sub-agent each; no two share a bound file. Still assign each card to exactly one agent.`
+                    : 'One unit — the seeds share bound files (or have none); do not split across agents.',
+            },
+        });
+    }));
     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.',
@@ -673,12 +1010,17 @@ export function buildServer(options = {}) {
         const touched = new Set();
         for (const [src, targets] of additions) {
             const card = index.cards.get(src);
-            const existingList = Array.isArray(card.frontmatter.connections)
-                ? card.frontmatter.connections.filter((c) => typeof c === 'string')
-                : [];
-            const merged = [...new Set([...existingList, ...targets])];
-            const frontmatter = applyCardPatch(card.frontmatter, { connections: merged });
-            await updateCardFile(card.filePath, { frontmatter });
+            // Merge against the file's CURRENT list inside the lock, not the index
+            // snapshot — a concurrent write must not be clobbered.
+            await mutateCardFile(card.filePath, (current) => {
+                const existingList = Array.isArray(current.frontmatter.connections)
+                    ? current.frontmatter.connections.filter((c) => typeof c === 'string')
+                    : [];
+                const merged = [...new Set([...existingList, ...targets])];
+                return {
+                    frontmatter: applyCardPatch(current.frontmatter, { connections: merged }),
+                };
+            });
             touched.add(card.relPath);
             added += targets.size;
         }
@@ -699,9 +1041,13 @@ export function buildServer(options = {}) {
             })
                 .optional(),
             body: z.string().optional(),
+            if_mtime: z
+                .number()
+                .optional()
+                .describe('optional stale-write guard: current rounded file mtime from a client-side stat or viewer payload'),
             repo: repoSchema,
         },
-    }, withPlan(async (root, { handle, patch, body }) => {
+    }, withPlan(async (root, { handle, patch, body, if_mtime }) => {
         const index = await loadPlan(root);
         const card = index.cards.get(handle.toUpperCase());
         if (!card)
@@ -713,14 +1059,229 @@ export function buildServer(options = {}) {
         if (reserved.length > 0) {
             return fail('INVALID_FIELDS', `fields cannot contain reserved keys: ${reserved.join(', ')}`);
         }
-        const frontmatter = patch
-            ? applyCardPatch(card.frontmatter, patch)
-            : undefined;
-        await updateCardFile(card.filePath, { frontmatter, body });
+        if (typeof if_mtime === 'number' && if_mtime !== 0) {
+            const current = Math.round((await stat(card.filePath)).mtimeMs);
+            if (current !== if_mtime) {
+                return fail('STALE', `${card.handle} changed on disk`);
+            }
+        }
+        // Apply the patch to the file's CURRENT frontmatter inside the lock —
+        // patch semantics compose with a concurrent write instead of undoing it.
+        await mutateCardFile(card.filePath, (current) => ({
+            frontmatter: patch ? applyCardPatch(current.frontmatter, patch) : undefined,
+            body,
+        }));
+        const lint = await lintPlan(root);
+        const updated = lint.index.cards.get(card.handle);
+        return ok({
+            card: updated ? full(updated) : null,
+            issues: issuesForFile(lint.issues, card.relPath),
+        });
+    }));
+    server.registerTool('append_note', {
+        description: 'Append one typed note to a card\'s memory — append-only, NO full-body rewrite (cheap, so the honest path stays the cheap path). kind: decision (a choice + why) | gotcha (a non-obvious trap) | state (current built/live reality) | deviation (where code intentionally differs from the card) | verified (a verification note). Capture what the code can\'t say; do NOT paste code/DDL/signatures that live in the repo — link to them. Notes are queryable by kind (get_card notes_kind) and ordered newest-last.',
+        inputSchema: {
+            handle: z.string(),
+            kind: noteKindSchema,
+            text: z.string().min(1).max(4000),
+            sha: z
+                .string()
+                .optional()
+                .describe('optional git sha this note was recorded against'),
+            repo: repoSchema,
+        },
+    }, withPlan(async (root, { handle, kind, text, sha }) => {
+        const index = await loadPlan(root);
+        const card = index.cards.get(handle.toUpperCase());
+        if (!card)
+            return fail('NOT_FOUND', `No card with handle ${handle}`);
+        const note = { kind, text };
+        if (sha)
+            note.sha = sha;
+        // Append to the CURRENT notes list inside the lock so two concurrent
+        // appends both land — the memory tool must never lose a note.
+        await mutateCardFile(card.filePath, (current) => ({
+            frontmatter: withAppendedNote(current.frontmatter, note),
+        }));
+        const lint = await lintPlan(root);
+        const updated = lint.index.cards.get(card.handle);
+        return ok({
+            card: updated ? full(updated) : null,
+            note_count: Array.isArray(updated?.frontmatter.notes)
+                ? updated.frontmatter.notes.length
+                : 0,
+            issues: issuesForFile(lint.issues, card.relPath),
+        });
+    }));
+    server.registerTool('list_notes', {
+        annotations: { readOnlyHint: true },
+        description: 'All typed notes across the plan (the memory recorded via append_note), in handle order and newest-last within each card. Filter by kind — "show me every gotcha" / "every decision" in one call — and/or by handles. The cross-card view of the plan\'s memory; for one card\'s notes use get_card notes_kind/notes_limit.',
+        inputSchema: {
+            kind: noteKindSchema.optional().describe('return only notes of this kind'),
+            handles: z
+                .array(z.string())
+                .optional()
+                .describe('restrict to these cards; omit for the whole plan'),
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(500)
+                .optional()
+                .describe('default 200'),
+            repo: repoSchema,
+        },
+    }, withPlan(async (root, { kind, handles, limit }) => {
+        const index = await loadPlan(root);
+        const wanted = handles && handles.length > 0
+            ? new Set(handles.map((h) => h.toUpperCase()))
+            : null;
+        const notes = [];
+        const sorted = [...index.cards.values()].sort((a, b) => a.handle.localeCompare(b.handle));
+        for (const card of sorted) {
+            if (wanted && !wanted.has(card.handle))
+                continue;
+            const list = Array.isArray(card.frontmatter.notes)
+                ? card.frontmatter.notes
+                : [];
+            for (const n of list) {
+                if (!n || typeof n !== 'object')
+                    continue;
+                const note = n;
+                if (typeof note.text !== 'string')
+                    continue;
+                const noteKind = typeof note.kind === 'string' ? note.kind : 'note';
+                if (kind && noteKind !== kind)
+                    continue;
+                notes.push({
+                    handle: card.handle,
+                    kind: noteKind,
+                    text: note.text,
+                    ...(typeof note.sha === 'string' ? { sha: note.sha } : {}),
+                });
+            }
+        }
+        return ok({ total: notes.length, notes: notes.slice(0, limit ?? 200) });
+    }));
+    server.registerTool('edit_section', {
+        description: 'Replace the content under one markdown heading in a card\'s body, keeping every other section byte-for-byte — a cheap, surgical alternative to rewriting the whole body. Match the heading by its text (case-insensitive, no #). Errors if no such heading exists (use update_card to set the whole body or add a section).',
+        inputSchema: {
+            handle: z.string(),
+            section: z
+                .string()
+                .describe('heading text to replace under, e.g. "Notes" or "Current state"'),
+            text: z.string().describe('new markdown content for that section (heading kept)'),
+            repo: repoSchema,
+        },
+    }, withPlan(async (root, { handle, section, text }) => {
+        const index = await loadPlan(root);
+        const card = index.cards.get(handle.toUpperCase());
+        if (!card)
+            return fail('NOT_FOUND', `No card with handle ${handle}`);
+        // Replace against the CURRENT body inside the lock — concurrent edits to
+        // different sections compose instead of the later one clobbering.
+        let failure = null;
+        await mutateCardFile(card.filePath, (current) => {
+            const body = replaceBodySection(current.body, section, text);
+            if (body === null) {
+                const headings = bodyHeadingTexts(current.body);
+                const target = section.trim().replace(/^#+\s*/, '').toLowerCase();
+                const matchCount = headings.filter((h) => h.toLowerCase() === target).length;
+                failure =
+                    matchCount > 1
+                        ? fail('AMBIGUOUS_SECTION', `${card.handle} has ${matchCount} headings called "${section}"; edit_section can't tell them apart. Use update_card to set the whole body.`)
+                        : fail('SECTION_NOT_FOUND', `No heading "${section}" in ${card.handle}. Headings present: ${headings.length ? headings.join(', ') : '(none)'}. Use update_card to set the whole body or add the section.`);
+                return null;
+            }
+            return { body };
+        });
+        if (failure)
+            return failure;
+        const lint = await lintPlan(root);
+        const updated = lint.index.cards.get(card.handle);
+        return ok({
+            card: updated ? full(updated) : null,
+            issues: issuesForFile(lint.issues, card.relPath),
+        });
+    }));
+    server.registerTool('set_verified', {
+        description: 'Mark a card verified against the real code: stamp verified_sha (the git sha you checked it at, default HEAD) + verified_at, set status to verified, and optionally append a verified note. The verified_sha is the BASELINE for code-side drift (stale_report / check_sync): later, if the card\'s bound code changed since this sha, the claim is flagged for re-verification. This is durability, not distrust — verify only against code you actually checked.',
+        inputSchema: {
+            handle: z.string(),
+            sha: z
+                .string()
+                .optional()
+                .describe('git sha verified against (default: current HEAD)'),
+            note: z
+                .string()
+                .optional()
+                .describe('optional verification note appended to the card'),
+            repo: repoSchema,
+        },
+    }, withPlan(async (root, { handle, sha, note }) => {
+        const index = await loadPlan(root);
+        const card = index.cards.get(handle.toUpperCase());
+        if (!card)
+            return fail('NOT_FOUND', `No card with handle ${handle}`);
+        const warnings = [];
+        let resolvedSha = sha;
+        if (resolvedSha) {
+            // Normalize to the full commit sha; a typo'd baseline would otherwise
+            // surface only later, as an unreachable baseline in stale_report.
+            try {
+                resolvedSha = await resolveCommit(root, resolvedSha);
+            }
+            catch {
+                warnings.push(`sha ${resolvedSha} does not resolve to a commit in this repo; stamped as given — stale_report will report this card's baseline as unreachable until it does.`);
+            }
+        }
+        else {
+            try {
+                resolvedSha = await headSha(root);
+            }
+            catch {
+                warnings.push('Not a git repo (or no commits): stamped verified_at + status only. Drift detection needs a verified_sha baseline — pass sha or commit first.');
+            }
+        }
+        // A verified_sha is a claim about COMMITTED code. Uncommitted edits to the
+        // bound files are not covered by it — mirror set_sync_point's dirty warning.
+        if (resolvedSha) {
+            try {
+                const bound = boundPathsForCard(index, card).map((b) => b.path);
+                const dirty = await changedFilesSince(root, 'HEAD', bound);
+                const dirtyBound = bound.filter((p) => dirty.has(p));
+                if (dirtyBound.length > 0) {
+                    warnings.push(`Bound file(s) have uncommitted changes the baseline does not include: ${dirtyBound.join(', ')}. Commit first, then set_verified.`);
+                }
+            }
+            catch {
+                // Best-effort: no git repo or nothing bound — nothing to warn about.
+            }
+        }
+        const verifiedAt = new Date().toISOString();
+        const fields = { verified_at: verifiedAt };
+        if (resolvedSha)
+            fields.verified_sha = resolvedSha;
+        await mutateCardFile(card.filePath, (current) => {
+            let frontmatter = applyCardPatch(current.frontmatter, {
+                status: 'verified',
+                fields,
+            });
+            if (note) {
+                const n = { kind: 'verified', text: note };
+                if (resolvedSha)
+                    n.sha = resolvedSha;
+                frontmatter = withAppendedNote(frontmatter, n);
+            }
+            return { frontmatter };
+        });
         const lint = await lintPlan(root);
         const updated = lint.index.cards.get(card.handle);
         return ok({
             card: updated ? full(updated) : null,
+            verified_sha: resolvedSha ?? null,
+            verified_at: verifiedAt,
+            warning: warnings.length > 0 ? warnings.join(' ') : undefined,
             issues: issuesForFile(lint.issues, card.relPath),
         });
     }));
@@ -744,6 +1305,38 @@ export function buildServer(options = {}) {
             issues: lint.issues.filter((i) => handleToken.test(i.message)),
         });
     }));
+    server.registerTool('rename_card', {
+        description: 'Rename a card\'s handle and rewrite every reference to it across the plan — connections lists, handle-shaped frontmatter values, [[links]], mermaid nodes, and prose mentions (whole-token matches only; API-USER never touches API-USERS). The file moves to the new handle\'s path, so a cross-type rename (new prefix) also moves folders and the card\'s fields are then validated against the new type\'s schema. Returns the handles whose references were rewritten plus lint issues for every touched file.',
+        inputSchema: { from: z.string(), to: z.string(), repo: repoSchema },
+    }, withPlan(async (root, args) => {
+        let result;
+        try {
+            result = await renameCard(root, args.from, args.to);
+        }
+        catch (err) {
+            if (err instanceof RenameCardError)
+                return fail(err.code, err.message);
+            throw err;
+        }
+        if (result.noop) {
+            return ok({ renamed: null, note: 'from and to are the same handle — nothing to do.' });
+        }
+        const lint = await lintPlan(root);
+        const touched = new Set([result.file]);
+        for (const h of result.references_updated) {
+            const rel = lint.index.cards.get(h)?.relPath;
+            if (rel)
+                touched.add(rel);
+        }
+        const renamed = lint.index.cards.get(result.to);
+        return ok({
+            renamed: { from: result.from, to: result.to },
+            file: result.file,
+            references_updated: result.references_updated,
+            card: renamed ? full(renamed) : null,
+            issues: lint.issues.filter((i) => touched.has(i.file)),
+        });
+    }));
     server.registerTool('add_connection', {
         description: 'Connect two cards by appending `to` to `from`’s connections list. No-op if they are already connected through any source.',
         inputSchema: { from: z.string(), to: z.string(), repo: repoSchema },
@@ -757,13 +1350,18 @@ export function buildServer(options = {}) {
         if (index.connectedHandles.get(from.handle)?.has(to.handle)) {
             return ok({ already_connected: true, between: [from.handle, to.handle] });
         }
-        const existing = Array.isArray(from.frontmatter.connections)
-            ? from.frontmatter.connections
-            : [];
-        const frontmatter = deepMerge(from.frontmatter, {
-            connections: [...existing, to.handle],
+        await mutateCardFile(from.filePath, (current) => {
+            const existing = Array.isArray(current.frontmatter.connections)
+                ? current.frontmatter.connections.filter((c) => typeof c === 'string')
+                : [];
+            if (existing.includes(to.handle))
+                return null; // raced: already added
+            return {
+                frontmatter: deepMerge(current.frontmatter, {
+                    connections: [...existing, to.handle],
+                }),
+            };
         });
-        await updateCardFile(from.filePath, { frontmatter });
         const lint = await lintPlan(root);
         return ok({
             connected: [from.handle, to.handle],
@@ -786,17 +1384,24 @@ export function buildServer(options = {}) {
             [cardA, cardB.handle],
             [cardB, cardA.handle],
         ]) {
-            const list = Array.isArray(card.frontmatter.connections)
-                ? card.frontmatter.connections
-                : [];
-            if (list.includes(other)) {
+            let removed = false;
+            await mutateCardFile(card.filePath, (current) => {
+                // Keep malformed (non-string) entries as-is — lint owns reporting them.
+                const list = Array.isArray(current.frontmatter.connections)
+                    ? current.frontmatter.connections
+                    : [];
+                if (!list.includes(other))
+                    return null;
+                removed = true;
                 const next = list.filter((h) => h !== other);
-                const frontmatter = deepMerge(card.frontmatter, {
-                    connections: next.length > 0 ? next : null,
-                });
-                await updateCardFile(card.filePath, { frontmatter });
+                return {
+                    frontmatter: deepMerge(current.frontmatter, {
+                        connections: next.length > 0 ? next : null,
+                    }),
+                };
+            });
+            if (removed)
                 removedFrom.push(card.handle);
-            }
         }
         const lint = await lintPlan(root);
         const after = lint.index;
@@ -871,11 +1476,15 @@ export function buildServer(options = {}) {
             return fail('NO_PLAN_PROJECT', 'No plan.md (PLAN-PROJECT) at the plan root to record connected_repos on.');
         }
         const entry = { name, path: repoPath, description };
-        const next = upsertConnectedRepo(await readConnectedRepos(root), entry);
-        const frontmatter = applyCardPatch(planCard.frontmatter, {
-            fields: { connected_repos: next.map(connectedRepoToFm) },
+        let next = [];
+        await mutateCardFile(planCard.filePath, (current) => {
+            next = upsertConnectedRepo(connectedReposFromFrontmatter(current.frontmatter), entry);
+            return {
+                frontmatter: applyCardPatch(current.frontmatter, {
+                    fields: { connected_repos: next.map(connectedRepoToFm) },
+                }),
+            };
         });
-        await updateCardFile(planCard.filePath, { frontmatter });
         let reciprocated;
         if (reciprocate) {
             const target = await resolveConnectedRepo(root, repoPath);
@@ -899,12 +1508,13 @@ export function buildServer(options = {}) {
                         path: path.relative(target.repoRoot, homeRepoRoot) || '.',
                         description: reverse_description,
                     };
-                    const targetNext = upsertConnectedRepo(await readConnectedRepos(target.root), reverseEntry);
-                    await updateCardFile(targetPlan.filePath, {
-                        frontmatter: applyCardPatch(targetPlan.frontmatter, {
-                            fields: { connected_repos: targetNext.map(connectedRepoToFm) },
+                    await mutateCardFile(targetPlan.filePath, (current) => ({
+                        frontmatter: applyCardPatch(current.frontmatter, {
+                            fields: {
+                                connected_repos: upsertConnectedRepo(connectedReposFromFrontmatter(current.frontmatter), reverseEntry).map(connectedRepoToFm),
+                            },
                         }),
-                    });
+                    }));
                     reciprocated = {
                         ok: true,
                         repo_root: target.repoRoot,
@@ -932,11 +1542,16 @@ export function buildServer(options = {}) {
         if (!existing.some((r) => r.name === name)) {
             return ok({ removed: false, connected_repos: existing.map(connectedRepoToFm) });
         }
-        const next = removeConnectedRepoEntry(existing, name);
-        await updateCardFile(planCard.filePath, {
-            frontmatter: applyCardPatch(planCard.frontmatter, {
-                fields: { connected_repos: next.length > 0 ? next.map(connectedRepoToFm) : null },
-            }),
+        let next = [];
+        await mutateCardFile(planCard.filePath, (current) => {
+            next = removeConnectedRepoEntry(connectedReposFromFrontmatter(current.frontmatter), name);
+            return {
+                frontmatter: applyCardPatch(current.frontmatter, {
+                    fields: {
+                        connected_repos: next.length > 0 ? next.map(connectedRepoToFm) : null,
+                    },
+                }),
+            };
         });
         const lint = await lintPlan(root);
         return ok({
@@ -1003,6 +1618,54 @@ export function buildServer(options = {}) {
                 : undefined,
         });
     }));
+    server.registerTool('stale_report', {
+        annotations: { readOnlyHint: true },
+        description: 'Code-side drift: cards that claim something about code (status built/verified, or carrying a verified_sha) whose BOUND code changed since they were verified. Binding = directly-connected FILE cards (path:) + the card\'s own code_refs. Each card\'s baseline is its verified_sha, else base, else the sync marker. Reports changed_files and vanished missing_files per stale card, plus cards with no baseline to check against. This makes a "built/verified" claim re-verifiable instead of taken on faith. Feed the handles to traverse or assemble.',
+        inputSchema: {
+            base: z
+                .string()
+                .optional()
+                .describe('fallback baseline sha for cards without verified_sha'),
+            repo: repoSchema,
+        },
+    }, withPlan(async (root, { base }) => {
+        const index = await loadPlan(root);
+        const r = await computeStaleCards(root, index, base);
+        return ok({
+            checked: r.checked,
+            stale_count: r.stale.length,
+            stale: r.stale,
+            no_baseline: r.no_baseline,
+        });
+    }));
+    server.registerTool('check_sync', {
+        annotations: { readOnlyHint: true },
+        description: 'Definition-of-done check: one glanceable verdict on whether the plan and code are in sync. Combines the plan-global state (in-sync / drifted / dirty / never-synced) — plan changes and code commits since the marker, lint integrity, status rollup — with the per-card code-side drift from stale_report. Advisory only: the server reports, it cannot block; treat code changed without its bound cards re-verified as "not done yet".',
+        inputSchema: {
+            base: z
+                .string()
+                .optional()
+                .describe('fallback baseline sha for per-card drift (default: sync marker)'),
+            repo: repoSchema,
+        },
+    }, withPlan(async (root, { base }) => {
+        const lint = await lintPlan(root);
+        const status = await computeSyncStatus(root, { lint });
+        const r = await computeStaleCards(root, lint.index, base);
+        return ok({
+            advisory: 'Advisory only — the MCP server reports sync state, it cannot block. Use as a definition-of-done gate before calling work complete.',
+            state: status.state,
+            marker: status.marker,
+            plan_dirty: status.plan_dirty,
+            plan_changes_since_marker: status.plan_changes_since_marker,
+            code_commits_since_marker: status.code_commits_since_marker,
+            integrity: status.integrity,
+            status_rollup: status.status_rollup,
+            total_cards: status.total_cards,
+            stale_cards: r.stale,
+            cards_without_baseline: r.no_baseline,
+        });
+    }));
     server.registerTool('start_viewer', {
         description: 'Start a local web server that renders this plan as a browsable, editable site, and return its URL (e.g. http://localhost:4747/). Idempotent: if the viewer is already running, returns the existing URL. The server runs until stop_viewer or until this MCP process exits. ALWAYS reply to the user with the returned url as a clickable link and state the port it bound to.',
         inputSchema: {