stepwell 0.0.0-stage → 0.2.4

package/dist/tools.js

@@ -0,0 +1,551 @@
+import { z } from "zod";
+import { applyArchivePlan, applyBacklogAddPlan, applyBacklogRemovePlan, applyBacklogUpdatePlan, applyPhasePlan, applyProgressPlan, backlogShow, docsRepair, docsStatus, docsValidate, loadProject, planArchiveItem, planBacklogAdd, planBacklogRemove, planBacklogUpdate, planPhase, planProgressUpdate, ProjectNotInitializedError, readBacklog, readProgress, } from "stepwell-core";
+import { commitDocs, docCommitMessage, foreignDocState, pullTrunk, pushTrunk, syncPreview, workstreamReport } from "stepwell-git";
+function textResult(value) {
+    return { content: [{ type: "text", text: JSON.stringify(value) }] };
+}
+/** Text-Payload, bei Opt-in (`structured: true`) zusätzlich als structuredContent (M3/9.7, E1/12.1). */
+function structuredResult(value) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(value) }],
+        structuredContent: value,
+    };
+}
+function errorResult(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return { content: [{ type: "text", text: message }], isError: true };
+}
+function errorOrThrow(err) {
+    if (err instanceof ProjectNotInitializedError) {
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({ code: err.code, message: err.message, missing: err.missing }),
+                }],
+            isError: true,
+        };
+    }
+    return errorResult(err);
+}
+async function asResult(fn) {
+    try {
+        return textResult(fn());
+    }
+    catch (err) {
+        return errorOrThrow(err);
+    }
+}
+async function asStructuredResult(fn, structured) {
+    try {
+        const value = fn();
+        return structured ? structuredResult(value) : textResult(value);
+    }
+    catch (err) {
+        return errorOrThrow(err);
+    }
+}
+const PRIORITY_VALUES = ["🔴", "🟠", "🟡", "🟢", "🔵", "unknown"];
+const PRIORITY_WRITE_VALUES = ["🔴", "🟠", "🟡", "🟢", "🔵"];
+const TEXT_FIELD = z.string().optional()
+    .describe("Item body as bullets (e.g. \"- **Location:** …\\n- **Problem:** …\") — taken over verbatim.");
+const DRYRUN_FIELD = z.boolean().default(true)
+    .describe("true (default): plan/diff preview only; false: write the changes.");
+const STRUCTURED_FIELD = z.boolean().default(false)
+    .describe("true: payload additionally as structuredContent (M3); false (default): text content only.");
+const DETAIL_FIELD = z.enum(["summary", "diff"]).default("diff")
+    .describe("Plan detail level for dry-runs: \"diff\" (default) = full preview; \"summary\" = " +
+    "headline + line counts (routine status maintenance). Apply responses are unchanged.");
+const COMMIT_FIELD = z.boolean().default(false)
+    .describe("false (default): no git action. true: after a successful apply, commit ONLY the four doc " +
+    "files (deterministic staging — never code or other files; refused with COMMIT_BLOCKED when " +
+    "the index has pre-staged changes; a failed commit keeps the edits applied, code COMMIT_FAILED). " +
+    "Ignored for dry-runs. Result lands as a `commit` section in the response.");
+const COMMIT_MESSAGE_FIELD = z.string().optional()
+    .describe("Optional commit subject with commit: true; default: generated from the operation.");
+/** Attaches the commit section after a successful apply (never on a failed one). */
+function attachCommit(result, root, message) {
+    if (result.verification?.ok === false)
+        return;
+    result.commit = commitDocs(root, { message });
+}
+/** Projiziert Dry-run-Pläne auf Headline + Zeilenzahlen (E1/12.2) — Apply bleibt unberührt. */
+function summarizePlan(plan) {
+    if (plan.dryRun !== true)
+        return plan;
+    const changes = plan.changes;
+    if (changes === undefined)
+        return plan;
+    return {
+        ...plan,
+        detail: "summary",
+        changes: changes.map((c) => ({
+            file: c.file,
+            description: c.description,
+            beforeLines: c.before.split("\n").length,
+            afterLines: c.after.split("\n").length,
+        })),
+    };
+}
+const ROOT_FIELD = z.string().describe("Absolute path to the project root (containing BACKLOG.md/PROGRESS.md).");
+// MCP-Annotations je Tool-Klasse (Step 9.2/M2): explizit gesetzt, auch wo der
+// Spec-Default passen würde — Clients sollen nicht auf Defaults raten müssen.
+export const READ_ONLY_ANNOTATIONS = {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+};
+export const DESTRUCTIVE_ANNOTATIONS = {
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: false,
+};
+export const MUTATING_ANNOTATIONS = {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+};
+const LOCALE_FIELD = z.enum(["de", "en"]).optional()
+    .describe("Language for generated texts (index line, done/verification markers). " +
+    "Default: auto-detection from the file context.");
+function withoutRaw(item) {
+    const { raw: _raw, ...rest } = item;
+    return rest;
+}
+const PROJECTABLE_FIELDS = [
+    "id",
+    "title",
+    "priority",
+    "section",
+    "open",
+    "location",
+    "files",
+    "dependsOn",
+    "blockedBy",
+    "ready",
+    "text",
+    "span",
+];
+function projectItem(item, fields) {
+    const full = withoutRaw(item);
+    return Object.fromEntries(fields.map((f) => [f, full[f]]));
+}
+export function registerDocsTools(server) {
+    server.registerTool("backlog_list", {
+        annotations: { ...READ_ONLY_ANNOTATIONS },
+        title: "Backlog list",
+        description: "Lists items of a STEPWELL project's BACKLOG.md (without raw, lean payload) " +
+            "including parse warnings; filter: priority, open, section, ready (M21/30.6: " +
+            "startable = open with no open Depends-on ancestors); projection: fields " +
+            "(e.g. [\"id\",\"title\",\"priority\",\"open\",\"section\"] for overview calls).",
+        inputSchema: {
+            root: ROOT_FIELD,
+            priority: z.array(z.enum(PRIORITY_VALUES)).optional()
+                .describe("Filter on priorities."),
+            open: z.boolean().optional().describe("Filter on open/completed checkbox."),
+            section: z.string().optional().describe("Exact section title (without emoji)."),
+            ready: z.boolean().optional()
+                .describe("M21/30.6: filter on startability (open AND no open Depends-on ancestors); items without a Depends-on bullet are ready when open."),
+            fields: z.array(z.enum(PROJECTABLE_FIELDS)).optional()
+                .describe("Project each item to the listed fields (token economy, E1); " +
+                "if the parameter is missing, all fields except raw are returned."),
+        },
+    }, ({ root, priority, open, section, ready, fields }) => asResult(() => {
+        const parsed = readBacklog(root);
+        let items = parsed.value.items;
+        if (priority !== undefined) {
+            const wanted = new Set(priority);
+            items = items.filter((i) => wanted.has(i.priority));
+        }
+        if (open !== undefined) {
+            items = items.filter((i) => i.open === open);
+        }
+        if (section !== undefined) {
+            items = items.filter((i) => i.section === section);
+        }
+        if (ready !== undefined) {
+            items = items.filter((i) => i.ready === ready);
+        }
+        return {
+            count: items.length,
+            items: items.map((i) => (fields ? projectItem(i, fields) : withoutRaw(i))),
+            warnings: parsed.warnings,
+        };
+    }));
+    server.registerTool("backlog_show", {
+        annotations: { ...READ_ONLY_ANNOTATIONS },
+        title: "Backlog item view",
+        description: "Merge view for an item id across the open BACKLOG, Done Index and BACKLOG_ARCHIVE " +
+            "— including raw + span; if the item is not identified, isError is returned.",
+        inputSchema: {
+            root: ROOT_FIELD,
+            id: z.string().describe("Item id, exact and case-sensitive (e.g. \"H1\")."),
+        },
+    }, ({ root, id }) => asResult(() => {
+        const entry = backlogShow(root, id);
+        if (entry === undefined) {
+            throw new Error(`unknown item id: ${id} (not in the open BACKLOG, Done Index or archive)`);
+        }
+        return entry;
+    }));
+    const STATUS_VALUES = ["⬜", "🔄", "✅", "⛔", "unknown"];
+    server.registerTool("progress_list", {
+        annotations: { ...READ_ONLY_ANNOTATIONS },
+        title: "Progress list",
+        description: "Lists the rows of the progress table in PROGRESS.md including parse warnings; " +
+            "filter: status (icon or \"unknown\").",
+        inputSchema: {
+            root: ROOT_FIELD,
+            status: z.enum(STATUS_VALUES).optional().describe("Filter on status icon."),
+        },
+    }, ({ root, status }) => asResult(() => {
+        const parsed = readProgress(root);
+        let rows = parsed.value.rows;
+        if (status !== undefined) {
+            rows = rows.filter((r) => r.status === status);
+        }
+        return { count: rows.length, rows, warnings: parsed.warnings };
+    }));
+    const matchesPhase = (block, phase) => block.name === phase ||
+        block.title === phase ||
+        `${block.name} — ${block.title}` === phase;
+    server.registerTool("progress_show", {
+        annotations: { ...READ_ONLY_ANNOTATIONS },
+        title: "Phase detail",
+        description: "Detail block of a phase (including raw) — search across active phases and archive; " +
+            "matched by name (\"Phase 2\"), title, or both (\"Phase 2 — UI Polish\").",
+        inputSchema: {
+            root: ROOT_FIELD,
+            phase: z.string().describe("Phase name or title, e.g. \"Phase 2\"."),
+        },
+    }, ({ root, phase }) => asResult(() => {
+        const docs = loadProject(root);
+        const block = docs.progress().value.phases.find((p) => matchesPhase(p, phase)) ??
+            docs.progressArchive().value.find((p) => matchesPhase(p, phase));
+        if (block === undefined) {
+            throw new Error(`unknown phase: ${phase} (neither a running phase nor in the archive)`);
+        }
+        return block;
+    }));
+    server.registerTool("docs_status", {
+        annotations: { ...READ_ONLY_ANNOTATIONS },
+        title: "Docs status",
+        description: "Aggregate of a STEPWELL project: open items per priority, running steps/phases, " +
+            "✅-ratio and all validation/parse warnings.",
+        inputSchema: {
+            root: ROOT_FIELD,
+            include: z.array(z.enum(["nextStepScope"])).optional()
+                .describe('Additional context: "nextStepScope" returns the goal/acceptance/scope bullet + ' +
+                "merged backlog item of the next step (1 call instead of 3, E2/12.3)."),
+        },
+    }, ({ root, include }) => asResult(() => docsStatus(root, include ? { include } : undefined)));
+    server.registerTool("docs_validate", {
+        annotations: { ...READ_ONLY_ANNOTATIONS },
+        title: "Docs validation",
+        description: "Checks cross-consistency of the four doc files (Done Index ↔ archive, checkbox ↔ " +
+            "archival, 🔄 ↔ detail block, id/date convention) and collects parse warnings.",
+        inputSchema: { root: ROOT_FIELD, structured: STRUCTURED_FIELD },
+    }, ({ root, structured }) => asStructuredResult(() => docsValidate(root), structured));
+    server.registerTool("docs_repair", {
+        annotations: { ...DESTRUCTIVE_ANNOTATIONS },
+        title: "Docs repair (dry-run)",
+        description: "Mechanical repair path for validate findings, over the responsible planners — never " +
+            "text manipulation: EMPTY_MARKER_STALE (placeholder removal), DATE_LEGACY YYMMDD/HHMM " +
+            "(→ ISO 8601; MM/YYYY stays a finding — the day is not reconstructible), NOT_ARCHIVED " +
+            "(delegates to archive_item), ARCHIVE_WITHOUT_INDEX (Done-Index line from the archive " +
+            "block title), WIP_WITHOUT_PLAN (skeleton, only when the phase has no other table rows). " +
+            "Everything else stays a finding (human judgment). Applies sequentially with " +
+            "re-validation between repairs; refusals are reported, never retried. Deliberately a " +
+            "SEPARATE tool from docs_validate: a tool cannot be read-only AND mutating — the " +
+            "static readOnly annotation of docs_validate protects consumer auto-approval flows (M4).",
+        inputSchema: {
+            root: ROOT_FIELD,
+            structured: STRUCTURED_FIELD,
+            dryRun: z.boolean().default(true)
+                .describe("true (default): report planned/skipped without writing; false: apply the mechanical repairs."),
+        },
+    }, ({ root, structured, dryRun }) => asStructuredResult(() => docsRepair(root, { dryRun }), structured));
+    server.registerTool("archive_item", {
+        annotations: { ...DESTRUCTIVE_ANNOTATIONS },
+        title: "Archive item (dry-run)",
+        description: "Plans the verbatim move of a completed backlog item into BACKLOG_ARCHIVE " +
+            "(checkbox → [x], optional note as **Done:** line) plus a one-liner in the " +
+            "Done Index. Returns the plan with a diff preview; nothing is written unless " +
+            "dryRun is false.",
+        inputSchema: {
+            root: ROOT_FIELD,
+            id: z.string().describe("Item id of the open backlog item, exact (e.g. \"H1\")."),
+            note: z.string().optional()
+                .describe("Optional done note (e.g. commit hash) — ends up in the archive block and index tail."),
+            locale: LOCALE_FIELD,
+            structured: STRUCTURED_FIELD,
+            detail: DETAIL_FIELD,
+            dryRun: z.boolean().default(true)
+                .describe("true (default): plan/diff preview only; false: write the changes."),
+            commit: COMMIT_FIELD,
+            commitMessage: COMMIT_MESSAGE_FIELD,
+        },
+    }, ({ root, id, note, locale, structured, detail, dryRun, commit, commitMessage }) => asStructuredResult(() => {
+        const plan = planArchiveItem(root, id, {
+            dryRun,
+            ...(note !== undefined ? { note } : {}),
+            ...(locale !== undefined ? { locale: locale } : {}),
+        });
+        const result = plan.dryRun ? plan : applyArchivePlan(plan);
+        if (!plan.dryRun && commit) {
+            attachCommit(result, root, commitMessage ?? docCommitMessage({ kind: "archive", id }));
+        }
+        return detail === "summary" ? summarizePlan(result) : result;
+    }, structured));
+    server.registerTool("progress_update", {
+        annotations: { ...MUTATING_ANNOTATIONS },
+        title: "Update step status (dry-run)",
+        description: "Sets the status of a step in the progress table (missing rows are added), " +
+            "creates a detail block skeleton under 'Active Phases' on 🔄 and moves complete " +
+            "phases verbatim into PROGRESS_ARCHIVE (note → **Verification:** line). Returns the " +
+            "plan with a diff preview; nothing is written unless dryRun is false.",
+        inputSchema: {
+            root: ROOT_FIELD,
+            phase: z.string().describe("Phase name, title, both, or a bare phase number (e.g. \"Phase 2\" / \"Phase 2 — UI Polish\" / \"2\")."),
+            step: z.union([z.string(), z.array(z.string())])
+                .describe("Step number per table/scope (e.g. \"2.2\") or an array of step numbers for multi-step updates in one call (e.g. phase completion; only with dryRun: false)."),
+            status: z.enum(["⬜", "🔄", "✅", "⛔"]).describe("New status icon."),
+            title: z.string().optional()
+                .describe("New phase title — renames the detail block heading consistently (table stays unchanged); a full heading text is accepted as-is, no prefix doubling (L16/29.3); on phase completion in the same call the block moves into the archive under the new title."),
+            note: z.string().optional()
+                .describe("Optional note — on phase completion it becomes the **Verification:** line on the archive block."),
+            checkpoint: z.string().optional()
+                .describe("Optional commit SHA of the phase (7–40 hex) — on phase completion it appears in the verification line of the archive block."),
+            locale: LOCALE_FIELD,
+            structured: STRUCTURED_FIELD,
+            detail: DETAIL_FIELD,
+            dryRun: z.boolean().default(true)
+                .describe("true (default): plan/diff preview only; false: write the changes."),
+            commit: COMMIT_FIELD,
+            commitMessage: COMMIT_MESSAGE_FIELD,
+        },
+    }, ({ root, phase, step, status, title, note, checkpoint, locale, structured, detail, dryRun, commit, commitMessage }) => asStructuredResult(() => {
+        const steps = Array.isArray(step) ? step : [step];
+        if (steps.length > 1 && dryRun) {
+            throw new Error(`multi-step (${steps.join(", ")}) requires dryRun: false — dry-run previews are only defined for a single step`);
+        }
+        if (steps.length > 1 && detail === "summary") {
+            throw new Error(`multi-step (${steps.join(", ")}) returns the aggregate result — detail: "summary" is only defined for a single step`);
+        }
+        const planOptions = {
+            dryRun,
+            ...(title !== undefined ? { title } : {}),
+            ...(note !== undefined ? { note } : {}),
+            ...(checkpoint !== undefined ? { checkpoint } : {}),
+            ...(locale !== undefined ? { locale: locale } : {}),
+        };
+        const archivedThisBatch = new Set();
+        const runSingle = (oneStep) => {
+            const plan = planProgressUpdate(root, phase, oneStep, status, {
+                ...planOptions,
+                ...(archivedThisBatch.has(phase) ? { phaseAlreadyArchived: true } : {}),
+            });
+            if (plan.completedPhase)
+                archivedThisBatch.add(phase);
+            const result = plan.dryRun ? plan : applyProgressPlan(plan);
+            return detail === "summary" ? summarizePlan(result) : result;
+        };
+        if (steps.length === 1) {
+            const result = runSingle(steps[0]);
+            if (!dryRun && commit) {
+                attachCommit(result, root, commitMessage ?? docCommitMessage({ kind: "progress", steps, status: status }));
+            }
+            return result;
+        }
+        // M9/18.1: validate every step up-front (planning is read-only) so a bad
+        // step fails before the first write; residual apply-time failures report
+        // what was already persisted.
+        steps.map((oneStep) => planProgressUpdate(root, phase, oneStep, status, planOptions));
+        const writtenSoFar = [];
+        try {
+            const results = steps.map((oneStep) => {
+                const result = runSingle(oneStep);
+                writtenSoFar.push(...result.written);
+                return result;
+            });
+            const written = [...new Set(results.flatMap((r) => r.written))];
+            const messages = results.flatMap((r) => r.verification.messages);
+            const allOk = results.every((r) => r.verification.ok);
+            const aggregate = { written, steps, verification: { ok: allOk, messages } };
+            // one doc commit for the whole batch (H5/26.3), only after a fully successful apply
+            if (commit) {
+                attachCommit(aggregate, root, commitMessage ?? docCommitMessage({ kind: "progress", steps, status: status }));
+            }
+            return aggregate;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(`multi-step (${steps.join(", ")}) failed after partially applying — ` +
+                `already written: ${writtenSoFar.length > 0 ? writtenSoFar.join(", ") : "(none)"} — ` +
+                `cause: ${message}`);
+        }
+    }, structured));
+    server.registerTool("backlog_add", {
+        annotations: { ...MUTATING_ANNOTATIONS },
+        title: "Create backlog item (dry-run)",
+        description: "Creates an open backlog item at the end of the target section: conforming id " +
+            "(series convention, auto-assigned K/H/M/L per priority or explicit), correct " +
+            "block format, As of: timestamp updated. Returns the plan with a diff preview; " +
+            "nothing is written unless dryRun is false.",
+        inputSchema: {
+            root: ROOT_FIELD,
+            section: z.string().describe("Target section (title without emoji, e.g. \"HIGH\")."),
+            title: z.string().describe("Item title after the id."),
+            priority: z.enum(PRIORITY_WRITE_VALUES).describe("Priority emoji (part of the title)."),
+            id: z.string().optional()
+                .describe("Explicit item id (convention ^[A-Z][0-9]+$); if missing, the next free number of the priority series (K/H/M/L) is assigned. 🔵 requires an explicit id."),
+            text: TEXT_FIELD,
+            detail: DETAIL_FIELD,
+            dryRun: DRYRUN_FIELD,
+            considerWorktrees: z.boolean().default(false)
+                .describe("M20/30.5: when true, the next free id also skips the ids occupied in ALL foreign worktree doc states (git satellite read); without git it falls back to the own tree with a worktreeWarnings entry. Explicit ids are never filtered."),
+        },
+    }, ({ root, section, title, priority, id, text, detail, dryRun, considerWorktrees }) => asResult(() => {
+        const worktreeWarnings = [];
+        let excludeIds;
+        if (considerWorktrees) {
+            const foreign = foreignDocState(root);
+            excludeIds = foreign.ids;
+            worktreeWarnings.push(...foreign.warnings);
+        }
+        const plan = planBacklogAdd(root, {
+            dryRun,
+            section,
+            title,
+            priority: priority,
+            ...(id !== undefined ? { id } : {}),
+            ...(text !== undefined ? { text } : {}),
+            ...(excludeIds !== undefined ? { excludeIds } : {}),
+        });
+        const result = plan.dryRun ? plan : applyBacklogAddPlan(plan);
+        const withWarnings = worktreeWarnings.length > 0 ? { ...result, worktreeWarnings } : result;
+        return detail === "summary" ? summarizePlan(withWarnings) : withWarnings;
+    }));
+    server.registerTool("backlog_update", {
+        annotations: { ...MUTATING_ANNOTATIONS },
+        title: "Update backlog item (dry-run)",
+        description: "Changes title, priority, text or section of an open item in the block format " +
+            "(span re-computation, As of: timestamp). A priority change moves the block to the " +
+            "matching priority section; `position` (L17/30.7) places the block within its " +
+            "(target) section — top/bottom/1-based slot, byte-identical content, structured " +
+            "out-of-range refusal. Returns the plan with a diff preview; nothing is " +
+            "written unless dryRun is false.",
+        inputSchema: {
+            root: ROOT_FIELD,
+            id: z.string().describe("Item id of the open backlog item, exact (e.g. \"H1\")."),
+            title: z.string().optional().describe("New title."),
+            priority: z.enum(PRIORITY_WRITE_VALUES).optional().describe("New priority."),
+            section: z.string().optional()
+                .describe("New target section (title without emoji); default: matching priority section on priority change, otherwise the item stays in place."),
+            position: z.union([z.literal("top"), z.literal("bottom"), z.number().int().min(1)]).optional()
+                .describe("L17/30.7: block position within the (target) section — \"top\", \"bottom\" or a 1-based slot among the section's item blocks; with `section` the order is first switch, then place; out of range is a structured error."),
+            text: TEXT_FIELD,
+            detail: DETAIL_FIELD,
+            dryRun: DRYRUN_FIELD,
+        },
+    }, ({ root, id, title, priority, section, position, text, detail, dryRun }) => asResult(() => {
+        const plan = planBacklogUpdate(root, id, {
+            dryRun,
+            ...(title !== undefined ? { title } : {}),
+            ...(priority !== undefined ? { priority: priority } : {}),
+            ...(section !== undefined ? { section } : {}),
+            ...(position !== undefined ? { position } : {}),
+            ...(text !== undefined ? { text } : {}),
+        });
+        const result = plan.dryRun ? plan : applyBacklogUpdatePlan(plan);
+        return detail === "summary" ? summarizePlan(result) : result;
+    }));
+    server.registerTool("backlog_remove", {
+        annotations: { ...DESTRUCTIVE_ANNOTATIONS },
+        title: "Remove backlog item (dry-run)",
+        description: "Removes an open item WITHOUT hard delete: the block moves verbatim into BACKLOG_ARCHIVE " +
+            "(checkbox stays [ ], optional note as **Removed:** line), the Done Index gets a tail " +
+            "without a Done marker. Returns the plan with a diff preview; nothing is written " +
+            "unless dryRun is false.",
+        inputSchema: {
+            root: ROOT_FIELD,
+            id: z.string().describe("Item id of the open backlog item, exact (e.g. \"H1\")."),
+            note: z.string().optional()
+                .describe("Optional removal note — ends up in the archive block and index tail."),
+            locale: LOCALE_FIELD,
+            detail: DETAIL_FIELD,
+            dryRun: DRYRUN_FIELD,
+        },
+    }, ({ root, id, note, locale, detail, dryRun }) => asResult(() => {
+        const plan = planBacklogRemove(root, id, {
+            dryRun,
+            ...(note !== undefined ? { note } : {}),
+            ...(locale !== undefined ? { locale: locale } : {}),
+        });
+        const result = plan.dryRun ? plan : applyBacklogRemovePlan(plan);
+        return detail === "summary" ? summarizePlan(result) : result;
+    }));
+    server.registerTool("progress_plan_phase", {
+        annotations: { ...MUTATING_ANNOTATIONS },
+        title: "Plan phase ahead (dry-run)",
+        description: "Plans a new phase: creates table rows for all steps (⬜, with names) and a " +
+            "detail block skeleton with the full scope under 'Active Phases'. If the phase " +
+            "already exists as an active phase, it is extended with the new steps (missing " +
+            "table rows + scope bullets, without touching neighbouring rows). Validates that " +
+            "the step numbers match the phase name (Phase <N> → <N>.<x>) and that phase/steps " +
+            "are still free. Returns the plan with a diff preview; nothing is written unless " +
+            "dryRun is false.",
+        inputSchema: {
+            root: ROOT_FIELD,
+            phase: z.string().describe('New phase in the pattern "Phase <N>[ — Title]", e.g. "Phase 7 — Polish".'),
+            steps: z
+                .array(z.object({ step: z.string(), name: z.string() }))
+                .describe("Steps of the phase in order (e.g. [{ step: \"7.1\", name: \"Setup\" }])."),
+            detail: DETAIL_FIELD,
+            dryRun: DRYRUN_FIELD,
+            considerWorktrees: z.boolean().default(false)
+                .describe("M20/30.5: when true, the phase number and steps must also be free in ALL foreign worktree doc states (structured refusal otherwise); without git it falls back to the own tree with a worktreeWarnings entry."),
+        },
+    }, ({ root, phase, steps, detail, dryRun, considerWorktrees }) => asResult(() => {
+        const worktreeWarnings = [];
+        let excludePhases;
+        let excludeSteps;
+        if (considerWorktrees) {
+            const foreign = foreignDocState(root);
+            excludePhases = foreign.phases;
+            excludeSteps = foreign.steps;
+            worktreeWarnings.push(...foreign.warnings);
+        }
+        const plan = planPhase(root, phase, steps, {
+            dryRun,
+            ...(excludePhases !== undefined ? { excludePhases } : {}),
+            ...(excludeSteps !== undefined ? { excludeSteps } : {}),
+        });
+        const result = plan.dryRun ? plan : applyPhasePlan(plan);
+        const withWarnings = worktreeWarnings.length > 0 ? { ...result, worktreeWarnings } : result;
+        return detail === "summary" ? summarizePlan(withWarnings) : withWarnings;
+    }));
+    server.registerTool("workstream_sync", {
+        annotations: { ...MUTATING_ANNOTATIONS },
+        title: "Workstream sync (dry-run)",
+        description: "Git workstream sync (Decision 14/H5): pull merges the trunk into this worktree branch " +
+            "(the risky side — conflicts surface here as a clean abort with a structured report), push " +
+            "fast-forwards the trunk to this branch (precondition: trunk head already pulled — never a " +
+            "real merge on the trunk side), status returns the read-only workstream report (per-worktree " +
+            "liveness + conflict-candidate overlap, derived from git itself). Dry-run (default) runs the " +
+            "exact guard chain of the real operation and previews the effect without touching anything.",
+        inputSchema: {
+            root: ROOT_FIELD,
+            direction: z.enum(["pull", "push", "status"]).describe("pull: merge trunk → branch. push: fast-forward trunk → branch head. status: read-only report."),
+            structured: STRUCTURED_FIELD,
+            dryRun: z.boolean().default(true)
+                .describe("true (default): pre-flight — guard chain + preview, no git mutation. false: execute pull/push. Ignored for status."),
+        },
+    }, ({ root, direction, structured, dryRun }) => asStructuredResult(() => {
+        if (direction === "status")
+            return workstreamReport(root);
+        const preview = syncPreview(root, direction);
+        if (dryRun || !preview.ok)
+            return preview;
+        return direction === "pull" ? pullTrunk(root) : pushTrunk(root);
+    }, structured));
+}

package/package.json

@@ -1,6 +1,30 @@
 {
   "name": "stepwell",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.4",
+  "type": "module",
+  "license": "MIT",
+  "files": [
+    "dist",
+    "skills"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "stepwell": "./dist/cli.js"
+  },
+  "dependencies": {
+    "stepwell-core": "*",
+    "stepwell-git": "*",
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "zod": "^3.25.0"
+  },
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json",
+    "build": "tsc -p tsconfig.build.json",
+    "prepublishOnly": "npm run build"
+  }
+}