stepwell-core 0.0.0-stage → 0.2.4

package/dist/aliases.d.ts

@@ -0,0 +1,12 @@
+import type { Priority, Status } from "./types.ts";
+/**
+ * ASCII-Aliase je Emoji-Wert (T3): Die CLI akzeptiert zusätzlich zu den Icons
+ * diese Aliase (case-insensitiv). Das MCP-Schema bleibt bei den Emojis —
+ * Agenten emittieren sie zuverlässig; Menschen tippen die Aliase.
+ */
+export declare const PRIORITY_ALIASES: Readonly<Record<Exclude<Priority, "unknown">, readonly string[]>>;
+export declare const STATUS_ALIASES: Readonly<Record<Exclude<Status, "unknown">, readonly string[]>>;
+export declare function resolvePriority(token: string): Priority | undefined;
+export declare function resolveStatus(token: string): Status | undefined;
+export declare function priorityAliasHelp(): string;
+export declare function statusAliasHelp(): string;

package/dist/aliases.js

@@ -0,0 +1,51 @@
+/**
+ * ASCII-Aliase je Emoji-Wert (T3): Die CLI akzeptiert zusätzlich zu den Icons
+ * diese Aliase (case-insensitiv). Das MCP-Schema bleibt bei den Emojis —
+ * Agenten emittieren sie zuverlässig; Menschen tippen die Aliase.
+ */
+export const PRIORITY_ALIASES = {
+    "🔴": ["red", "kritisch", "p1"],
+    "🟠": ["orange", "hoch", "p2"],
+    "🟡": ["yellow", "mittel", "p3"],
+    "🟢": ["green", "niedrig", "p4"],
+    "🔵": ["blue", "test", "p5"],
+};
+export const STATUS_ALIASES = {
+    "⬜": ["open"],
+    "🔄": ["running", "wip"],
+    "✅": ["done"],
+    "⛔": ["blocked"],
+};
+const PRIORITY_KEYS = Object.keys(PRIORITY_ALIASES);
+const STATUS_KEYS = Object.keys(STATUS_ALIASES);
+export function resolvePriority(token) {
+    if (PRIORITY_KEYS.includes(token))
+        return token;
+    if (token === "unknown")
+        return "unknown";
+    const t = token.toLowerCase();
+    for (const key of PRIORITY_KEYS) {
+        if (PRIORITY_ALIASES[key].includes(t))
+            return key;
+    }
+    return undefined;
+}
+export function resolveStatus(token) {
+    if (STATUS_KEYS.includes(token))
+        return token;
+    if (token === "unknown")
+        return "unknown";
+    const t = token.toLowerCase();
+    for (const key of STATUS_KEYS) {
+        if (STATUS_ALIASES[key].includes(t))
+            return key;
+    }
+    return undefined;
+}
+export function priorityAliasHelp() {
+    return (PRIORITY_KEYS.map((key) => `${key}=${PRIORITY_ALIASES[key].join("/")}`).join(", ") +
+        ", unknown");
+}
+export function statusAliasHelp() {
+    return (STATUS_KEYS.map((key) => `${key}=${STATUS_ALIASES[key].join("/")}`).join(", ") + ", unknown");
+}

package/dist/archive.d.ts

@@ -0,0 +1,5 @@
+import type { ArchiveItem, BacklogItem, ParseResult, PhaseBlock } from "./types.ts";
+export declare function parseBacklogArchive(content: string, file?: string): ParseResult<ArchiveItem[]>;
+/** Archive view of a parsed item: picks the done line out of the block body. */
+export declare function toArchiveItem(item: BacklogItem): ArchiveItem;
+export declare function parseProgressArchive(content: string, file?: string): ParseResult<PhaseBlock[]>;

package/dist/archive.js

@@ -0,0 +1,24 @@
+import { parseBacklog } from "./backlog.js";
+import { parseProgress } from "./progress.js";
+import { allSynonyms, escapeRegExp } from "./profile.js";
+const ERLEDIGT_LINE = new RegExp(`^-\\s+\\*\\*(?:${allSynonyms("doneLabel").map(escapeRegExp).join("|")}):\\*\\*\\s*(.+?)\\s*$`, "u");
+export function parseBacklogArchive(content, file = "docs/archive/BACKLOG_ARCHIVE.md") {
+    const result = parseBacklog(content, file);
+    return { value: result.value.items.map(toArchiveItem), warnings: result.warnings };
+}
+/** Archive view of a parsed item: picks the done line out of the block body. */
+export function toArchiveItem(item) {
+    const archive = { ...item, doneLine: "" };
+    for (const line of item.text.split("\n")) {
+        const m = ERLEDIGT_LINE.exec(line);
+        if (m) {
+            archive.doneLine = m[1];
+            break;
+        }
+    }
+    return archive;
+}
+export function parseProgressArchive(content, file = "docs/archive/PROGRESS_ARCHIVE.md") {
+    const result = parseProgress(content, file);
+    return { value: result.value.phases, warnings: result.warnings };
+}

package/dist/backlog.d.ts

@@ -0,0 +1,11 @@
+import type { Backlog, ParseResult } from "./types.ts";
+/**
+ * H10/30.4: path-like tokens extracted from the location bullet — the cheap
+ * prediction surface for workstream overlaps. Tolerant for backticks, `file.ts:12`
+ * line refs, parenthetical comments and comma/semicolon lists. Only path-shaped
+ * tokens pass (a separator or a file extension, at least one letter): prose,
+ * dates (11/2026) and globs are skipped — no invention, no glob expansion.
+ */
+export declare function extractFiles(location: string | undefined): string[];
+export declare function parseBacklog(rawContent: string, file?: string): ParseResult<Backlog>;
+export declare function readBacklog(root: string): ParseResult<Backlog>;

package/dist/backlog.js

@@ -0,0 +1,380 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { allSynonyms, escapeRegExp, stripBom, synonymPattern } from "./profile.js";
+import { BACKLOG_PATH, REQUIRED_FILES, missingProjectFiles, ProjectNotInitializedError, } from "./project-files.js";
+const PRIORITY_EMOJIS = ["🔴", "🟠", "🟡", "🟢", "🔵"];
+const PICTOGRAPHIC = /^[\p{Extended_Pictographic}\uFE0F\u200D]+$/u;
+const SEPARATOR = /^(.*?)\s+—\s+([\s\S]*)$/;
+const TITLE_SUFFIX = /^(.*\S)\s+—\s+(\S+)$/u;
+const OPTIONAL_SUFFIX = /\s*\*\([^()]*\)\*$/u;
+const BULLET = /^-\s+\*\*.+?:\*\*/u;
+const union = (words) => words.map(escapeRegExp).join("|");
+const LOCATION_BULLET = new RegExp(`^-\\s+\\*\\*(?:${union(allSynonyms("locationLabel"))}):\\*\\*\\s+(.+?)\\s*$`, "u");
+// M21/30.6: optional dependency bullet — DE variant read silently (union matching)
+const DEPENDS_BULLET = new RegExp(`^-\\s+\\*\\*(?:${union(allSynonyms("dependsOnLabel"))}):\\*\\*\\s+(.+?)\\s*$`, "u");
+const DEP_ID = /^[A-Z][0-9]+$/u;
+/**
+ * H10/30.4: path-like tokens extracted from the location bullet — the cheap
+ * prediction surface for workstream overlaps. Tolerant for backticks, `file.ts:12`
+ * line refs, parenthetical comments and comma/semicolon lists. Only path-shaped
+ * tokens pass (a separator or a file extension, at least one letter): prose,
+ * dates (11/2026) and globs are skipped — no invention, no glob expansion.
+ */
+export function extractFiles(location) {
+    if (location === undefined || location.trim() === "")
+        return [];
+    const HAS_SEPARATOR = /[\\/]/u;
+    const HAS_EXT = /\.[A-Za-z0-9]{1,6}$/u;
+    const allNumericSegments = (token) => token.split(/[\\/]/u).every((segment) => /^\d+$/u.test(segment));
+    const files = [];
+    const seen = new Set();
+    const push = (token) => {
+        const cleaned = token.trim().replace(/^[`'"]+|[`'",.;:]+$/gu, "").trim();
+        if (cleaned === "" || cleaned.includes("*"))
+            return;
+        const path = /^(.*?\.[A-Za-z0-9]+)(?::\d+)?$/u.exec(cleaned)?.[1] ?? cleaned;
+        if (!HAS_SEPARATOR.test(path) && !HAS_EXT.test(path))
+            return;
+        if (!/[A-Za-z]/u.test(path) || allNumericSegments(path))
+            return;
+        if (!seen.has(path)) {
+            seen.add(path);
+            files.push(path);
+        }
+    };
+    for (const m of location.matchAll(/`([^`]+)`/gu))
+        push(m[1]);
+    const rest = location.replace(/`[^`]*`/gu, " ");
+    for (const token of rest.split(/[,;()[\]]|\s+/u))
+        push(token);
+    return files;
+}
+const DONE_LINE = new RegExp(`^-\\s+(.+?)\\s+—\\s+(.+?)\\s+—\\s+(?:${union(allSynonyms("doneWord"))})(?:\\s+in\\s+\`([^\`]+)\`)?`, "u");
+const DONE_INDEX_HEADING = synonymPattern("doneIndexHeading");
+const SEPARATOR_RULE = /^-{3,}\s*$/u;
+const TABLE_ROW = /^\s*\|.*\|\s*$/u;
+const TABLE_SEPARATOR = /^\s*\|(\s*:?-+:?\s*\|)+\s*$/u;
+const BACKTICKED = /`([^`]+)`/u;
+const FIRST_TOKEN = /\S+/u;
+const isKnownPriority = (token) => PRIORITY_EMOJIS.includes(token);
+const stripQuote = (line) => line.replace(/^>\s?/, "");
+function splitEmoji(heading) {
+    const m = /^(\S+)\s+([\s\S]*)$/.exec(heading);
+    if (m && PICTOGRAPHIC.test(m[1])) {
+        return { emoji: m[1], title: m[2].trim() };
+    }
+    return { emoji: "", title: heading.trim() };
+}
+/**
+ * Erledigt-Index als GFM-Tabelle (tolerierte Variante, Realformat internal-pwa):
+ * Spalten [Serie, Item, Commit/Phase] — `id` = erstes Token der Item-Spalte,
+ * `summary` = Rest; `sha` = erstes Backtick-Token der Commit/Phase-Spalte.
+ * Zwei Spalten ([Item, Commit/Phase]) lesen die ID aus der ersten Spalte.
+ */
+function parseDoneTableRow(line, lineNo) {
+    const cells = line
+        .trim()
+        .replace(/^\|/, "")
+        .replace(/\|$/, "")
+        .split("|")
+        .map((cell) => cell.trim());
+    if (cells.length < 2)
+        return undefined;
+    const itemCell = cells.length >= 3 ? cells[1] : cells[0];
+    const commitCell = cells.length >= 3 ? cells[2] : cells[1];
+    const token = FIRST_TOKEN.exec(itemCell)?.[0];
+    if (!token)
+        return undefined;
+    const entry = { id: token, summary: itemCell.slice(token.length).trim(), line: lineNo };
+    const sha = BACKTICKED.exec(commitCell);
+    if (sha) {
+        entry.sha = sha[1];
+    }
+    return entry;
+}
+function extractTitleParts(rest) {
+    const sep = SEPARATOR.exec(rest);
+    let id;
+    let title;
+    if (sep) {
+        id = sep[1].trim();
+        title = sep[2].trim();
+    }
+    else {
+        id = rest.trim();
+        title = "";
+    }
+    let knownCount = 0;
+    let known;
+    let unknownEmoji = false;
+    for (;;) {
+        const stripped = title.replace(OPTIONAL_SUFFIX, "").trim();
+        let changed = stripped !== title;
+        title = stripped;
+        const m = TITLE_SUFFIX.exec(title);
+        if (m) {
+            const token = m[2];
+            if (isKnownPriority(token)) {
+                knownCount += 1;
+                known = token;
+                title = m[1].trim();
+                changed = true;
+            }
+            else if (!unknownEmoji && PICTOGRAPHIC.test(token)) {
+                unknownEmoji = true;
+                title = m[1].trim();
+                changed = true;
+            }
+        }
+        if (!changed)
+            break;
+    }
+    return { id, title, known, duplicate: knownCount > 1, unknownEmoji };
+}
+function buildItem(raw, section, file) {
+    const warnings = [];
+    const { id, title, known, duplicate, unknownEmoji } = extractTitleParts(raw.rest);
+    if (duplicate) {
+        warnings.push({
+            code: "PRIO_DUPLICATE",
+            file,
+            line: raw.headingLine,
+            message: `Item "${id}" carries multiple priority markers in its title — only one is captured.`,
+        });
+    }
+    let priority;
+    if (known !== undefined) {
+        priority = known;
+    }
+    else if (unknownEmoji) {
+        priority = "unknown";
+        warnings.push({
+            code: "PRIO_UNKNOWN",
+            file,
+            line: raw.headingLine,
+            message: `Item "${id}" carries an unknown priority emoji — priority is "unknown".`,
+        });
+    }
+    else if (section !== null && isKnownPriority(section.emoji)) {
+        priority = section.emoji;
+        warnings.push({
+            code: "PRIO_MISSING",
+            file,
+            line: raw.headingLine,
+            message: `Item "${id}" has no priority suffix in its title — priority taken from the section emoji.`,
+        });
+    }
+    else {
+        priority = "unknown";
+        warnings.push({
+            code: "PRIO_MISSING",
+            file,
+            line: raw.headingLine,
+            message: `Item "${id}" has neither a title suffix nor a known section emoji — priority is "unknown".`,
+        });
+    }
+    if (id !== "" && title === "") {
+        warnings.push({
+            code: "TITLE_EMPTY",
+            file,
+            line: raw.headingLine,
+            message: `Item "${id}" has no title after the separator.`,
+        });
+    }
+    let bodyEnd = raw.headingLine + raw.body.length;
+    while (bodyEnd > raw.headingLine && (raw.body[bodyEnd - raw.headingLine - 1] ?? "").trim() === "") {
+        bodyEnd -= 1;
+    }
+    const bodyLines = raw.body.slice(0, bodyEnd - raw.headingLine);
+    const contentLines = bodyLines.filter((l) => l.trim() !== "");
+    if (contentLines.length > 0 && !contentLines.some((l) => BULLET.test(l))) {
+        warnings.push({
+            code: "BLOCK_UNSTRUCTURED",
+            file,
+            line: raw.headingLine,
+            message: `Item "${id}" has no structured block (no **Label:** bullets) — text captured as free prose.`,
+        });
+    }
+    const item = {
+        id,
+        title,
+        priority,
+        section: section?.title ?? "",
+        open: raw.open,
+        files: [],
+        dependsOn: [],
+        blockedBy: [],
+        ready: raw.open,
+        text: bodyLines.join("\n"),
+        span: { start: raw.headingLine, end: bodyEnd },
+        raw: [raw.heading, ...bodyLines].join("\n"),
+    };
+    for (const line of bodyLines) {
+        const location = LOCATION_BULLET.exec(line);
+        if (location) {
+            item.location = location[1];
+            item.files = extractFiles(location[1]);
+            break;
+        }
+    }
+    for (const line of bodyLines) {
+        const depends = DEPENDS_BULLET.exec(line);
+        if (depends === null)
+            continue;
+        for (const token of depends[1].split(/[,;]/u)) {
+            const id = token.trim();
+            if (DEP_ID.test(id) && !item.dependsOn.includes(id))
+                item.dependsOn.push(id);
+        }
+    }
+    return { item, warnings };
+}
+export function parseBacklog(rawContent, file = "BACKLOG.md") {
+    const content = stripBom(rawContent);
+    const lines = content.split(/\r?\n/);
+    const warnings = [];
+    const sections = [];
+    const headerRules = [];
+    const items = [];
+    const doneIndex = [];
+    let currentSection = null;
+    let inDoneIndex = false;
+    let doneTableData = false;
+    let headerRuleOpen = false;
+    let currentItem = null;
+    const flushItem = () => {
+        if (currentItem === null)
+            return;
+        const built = buildItem(currentItem, currentSection, file);
+        items.push(built.item);
+        warnings.push(...built.warnings);
+        currentItem = null;
+    };
+    const endSection = () => {
+        flushItem();
+        currentSection = null;
+        headerRuleOpen = false;
+    };
+    for (const [idx, line] of lines.entries()) {
+        const lineNo = idx + 1;
+        const sectionMatch = /^##\s+(.*)$/.exec(line);
+        if (sectionMatch) {
+            endSection();
+            const heading = sectionMatch[1].trim();
+            if (DONE_INDEX_HEADING.test(heading)) {
+                inDoneIndex = true;
+                doneTableData = false;
+                continue;
+            }
+            inDoneIndex = false;
+            doneTableData = false;
+            const { emoji, title } = splitEmoji(heading);
+            currentSection = { title, emoji, headerRule: "" };
+            headerRules.push([]);
+            sections.push(currentSection);
+            headerRuleOpen = true;
+            continue;
+        }
+        const itemMatch = /^###\s+\[(.)\]\s*([\s\S]*)$/u.exec(line);
+        if (itemMatch) {
+            if (inDoneIndex)
+                continue;
+            flushItem();
+            headerRuleOpen = false;
+            currentItem = {
+                heading: line,
+                headingLine: lineNo,
+                open: itemMatch[1] === " ",
+                rest: itemMatch[2] ?? "",
+                body: [],
+            };
+            continue;
+        }
+        if (SEPARATOR_RULE.test(line)) {
+            endSection();
+            inDoneIndex = false;
+            doneTableData = false;
+            continue;
+        }
+        if (currentItem !== null) {
+            currentItem.body.push(line);
+            continue;
+        }
+        if (inDoneIndex) {
+            const done = DONE_LINE.exec(line);
+            if (done) {
+                const entry = { id: done[1].trim(), summary: done[2].trim(), line: lineNo };
+                if (done[3] !== undefined) {
+                    entry.sha = done[3];
+                }
+                doneIndex.push(entry);
+                continue;
+            }
+            if (TABLE_ROW.test(line)) {
+                if (TABLE_SEPARATOR.test(line)) {
+                    doneTableData = true;
+                }
+                else if (doneTableData) {
+                    const entry = parseDoneTableRow(line, lineNo);
+                    if (entry) {
+                        doneIndex.push(entry);
+                    }
+                }
+            }
+            continue;
+        }
+        if (currentSection !== null && headerRuleOpen) {
+            const ruleParts = headerRules[sections.indexOf(currentSection)];
+            if (line.startsWith(">")) {
+                ruleParts?.push(stripQuote(line));
+            }
+            else if (line.trim() !== "") {
+                headerRuleOpen = false;
+            }
+        }
+    }
+    endSection();
+    for (const [i, section] of sections.entries()) {
+        section.headerRule = (headerRules[i] ?? []).join("\n");
+    }
+    // M21/30.6: derive blockedBy (transitive OPEN ancestors) + ready per item —
+    // a cross-item pass, so it runs after every item is built. Unknown refs are
+    // skipped here (DEP_UNKNOWN surfaces at validate); the visited set guards
+    // against cycles without an infinite loop (cycle members block themselves).
+    const byId = new Map(items.map((i) => [i.id, i]));
+    for (const item of items) {
+        const visited = new Set();
+        const stack = [...item.dependsOn];
+        const blocked = new Set();
+        while (stack.length > 0) {
+            const id = stack.pop();
+            if (visited.has(id))
+                continue;
+            visited.add(id);
+            const ref = byId.get(id);
+            if (ref === undefined)
+                continue;
+            if (ref.open)
+                blocked.add(id);
+            stack.push(...ref.dependsOn);
+        }
+        item.blockedBy = [...blocked].sort();
+        item.ready = item.open && item.blockedBy.length === 0;
+    }
+    return { value: { sections, items, doneIndex }, warnings };
+}
+export function readBacklog(root) {
+    const path = join(root, BACKLOG_PATH);
+    let content;
+    try {
+        content = readFileSync(path, "utf8");
+    }
+    catch {
+        const missing = missingProjectFiles(root);
+        if (missing.length === REQUIRED_FILES.length) {
+            throw new ProjectNotInitializedError(root, missing);
+        }
+        throw new Error(`missing required file: ${path}`);
+    }
+    return parseBacklog(content, path);
+}

package/dist/context.d.ts

@@ -0,0 +1,15 @@
+import type { BacklogItem, PhaseBlock, ProgressRow } from "./types.ts";
+/**
+ * Phase-Kontext zur Lesezeit (G5/12.6): Phase verbatim, Tabellen-Zeilen der Phase und
+ * die per ID-Ref gemergten Backlog-Item-Bodies in Step-Reihenfolge — kein Duplikat in
+ * den Dateien, kein Schreibpfad, kein Cache (Zero-Cache bleibt).
+ */
+export interface PhaseContext {
+    phase: PhaseBlock;
+    rows: ProgressRow[];
+    items: BacklogItem[];
+    /** Explizite Refs `(X/n)`, die weder offen noch im Archiv auflösbar sind — toleriert, kein Crash (Decision 6). */
+    unresolved: string[];
+    markdown: string;
+}
+export declare function phaseContext(root: string, phase: string): PhaseContext;

package/dist/context.js

@@ -0,0 +1,76 @@
+import { canonical, detectLocale } from "./profile.js";
+import { loadProject } from "./project.js";
+import { phaseMatches, scopeSteps } from "./progress.js";
+const EXPLICIT_REF = /\(([A-Z]+[0-9]+)\/[0-9]+\)/gu;
+const ID_TOKEN = /\b([A-Z]{1,3}[0-9]{1,4})\b/gu;
+function findBlock(docs, phase) {
+    return (docs.progress().value.phases.find((b) => phaseMatches(b, phase)) ??
+        docs.progressArchive().value.find((b) => phaseMatches(b, phase)));
+}
+function collectRefs(block) {
+    const ids = [];
+    const seen = new Set();
+    const explicitRefs = new Map();
+    const push = (id, rawRef) => {
+        if (!seen.has(id)) {
+            seen.add(id);
+            ids.push(id);
+        }
+        if (rawRef !== undefined)
+            explicitRefs.set(id, rawRef);
+    };
+    for (const entry of block.scope) {
+        for (const m of entry.matchAll(EXPLICIT_REF))
+            push(m[1], m[0].slice(1, -1));
+        for (const m of entry.matchAll(ID_TOKEN))
+            push(m[1], undefined);
+    }
+    return { ids, explicitRefs };
+}
+function resolveItem(docs, id) {
+    return (docs.backlog().value.items.find((i) => i.id === id) ??
+        docs.backlogArchive().value.find((i) => i.id === id));
+}
+function renderMarkdown(block, rows, items, unresolved) {
+    const locale = detectLocale(block.raw);
+    const progressLabel = canonical("progressHeading", locale);
+    const lines = [block.raw, "", `**${progressLabel}:**`, "", "| # | Step | Status |", "|---|------|--------|"];
+    for (const row of rows) {
+        lines.push(`| ${row.step} | ${row.name} | ${row.status} |`);
+    }
+    for (const item of items) {
+        lines.push("", `### ${item.id} — ${item.title} — ${item.priority}`, "", item.text);
+    }
+    if (unresolved.length > 0) {
+        lines.push("", `> unresolved refs: ${unresolved.join(", ")}`);
+    }
+    return lines.join("\n");
+}
+export function phaseContext(root, phase) {
+    const docs = loadProject(root);
+    const block = findBlock(docs, phase);
+    if (block === undefined) {
+        throw new Error(`unknown phase: ${phase} (neither a running phase nor in the archive)`);
+    }
+    const steps = new Set(scopeSteps(block));
+    const rows = docs.progress().value.rows.filter((r) => steps.has(r.step));
+    const { ids, explicitRefs } = collectRefs(block);
+    const items = [];
+    const unresolved = [];
+    for (const id of ids) {
+        const item = resolveItem(docs, id);
+        if (item !== undefined) {
+            items.push(item);
+        }
+        else if (explicitRefs.has(id)) {
+            unresolved.push(explicitRefs.get(id));
+        }
+    }
+    return {
+        phase: block,
+        rows,
+        items,
+        unresolved,
+        markdown: renderMarkdown(block, rows, items, unresolved),
+    };
+}

package/dist/diff.d.ts

@@ -0,0 +1 @@
+export declare function lineDiff(before: string, after: string, context?: number): string;

package/dist/diff.js

@@ -0,0 +1,34 @@
+export function lineDiff(before, after, context = 2) {
+    const splitLines = (content) => content === "" ? [] : content.replace(/\r?\n$/u, "").split("\n");
+    const a = splitLines(before);
+    const b = splitLines(after);
+    let prefix = 0;
+    while (prefix < a.length && prefix < b.length && a[prefix] === b[prefix]) {
+        prefix += 1;
+    }
+    let suffix = 0;
+    while (suffix < a.length - prefix &&
+        suffix < b.length - prefix &&
+        a[a.length - 1 - suffix] === b[b.length - 1 - suffix]) {
+        suffix += 1;
+    }
+    const removed = a.slice(prefix, a.length - suffix);
+    const added = b.slice(prefix, b.length - suffix);
+    if (removed.length === 0 && added.length === 0) {
+        return "";
+    }
+    const lines = [];
+    for (const line of a.slice(Math.max(0, prefix - context), prefix)) {
+        lines.push(` ${line}`);
+    }
+    for (const line of removed) {
+        lines.push(`-${line}`);
+    }
+    for (const line of added) {
+        lines.push(`+${line}`);
+    }
+    for (const line of a.slice(a.length - suffix, a.length - suffix + context)) {
+        lines.push(` ${line}`);
+    }
+    return lines.join("\n");
+}

package/dist/hashes.d.ts

@@ -0,0 +1,10 @@
+import { DOC_FILES } from "./project-files.ts";
+export { DOC_FILES };
+/**
+ * SHA256 je gelesener Doku-Datei (E2/12.5) — Clients vergleichen gegen den letzten
+ * bekannten Stand und überspringen Voll-Lese. Tolerant: fehlende Dateien bekommen
+ * keinen Schlüssel (Decision 6), kein Crash. M25/32.4: derived doc file set —
+ * existing archive shards are part of the manifest (the fast path would never
+ * see shard changes otherwise → stale hashes → consumers read stale states).
+ */
+export declare function fileHashes(root: string): Record<string, string>;

package/dist/hashes.js

@@ -0,0 +1,22 @@
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { docFileSet, DOC_FILES } from "./project-files.js";
+export { DOC_FILES };
+/**
+ * SHA256 je gelesener Doku-Datei (E2/12.5) — Clients vergleichen gegen den letzten
+ * bekannten Stand und überspringen Voll-Lese. Tolerant: fehlende Dateien bekommen
+ * keinen Schlüssel (Decision 6), kein Crash. M25/32.4: derived doc file set —
+ * existing archive shards are part of the manifest (the fast path would never
+ * see shard changes otherwise → stale hashes → consumers read stale states).
+ */
+export function fileHashes(root) {
+    const hashes = {};
+    for (const rel of docFileSet(root)) {
+        const abs = join(root, ...rel.split("/"));
+        if (!existsSync(abs))
+            continue;
+        hashes[rel] = createHash("sha256").update(readFileSync(abs, "utf8")).digest("hex");
+    }
+    return hashes;
+}

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+export { parseBacklog, readBacklog } from "./backlog.ts";
+export { parseProgress, readProgress, scopeSteps, appendChunkOrder, latestStampKey, } from "./progress.ts";
+export { parseBacklogArchive, parseProgressArchive } from "./archive.ts";
+export { backlogShow, loadProject } from "./project.ts";
+export type { ProjectDocs } from "./project.ts";
+export { ProjectNotInitializedError, REQUIRED_FILES, archiveShardPaths, docFileSet, missingProjectFiles, type ArchiveKind, } from "./project-files.ts";
+export { lineDiff } from "./diff.ts";
+export { applyArchivePlan, applyProgressPlan, applyBacklogAddPlan, applyBacklogRemovePlan, EMPTY_MARKER_CANONICAL, applyBacklogUpdatePlan, applyPhasePlan, planArchiveItem, planBacklogAdd, planBacklogRemove, planBacklogUpdate, planPhase, planProgressUpdate, stampNow, type ArchiveItemOptions, type BacklogAddOptions, type BacklogRemoveOptions, type BacklogUpdateOptions, type PhaseOptions, type PhaseStep, type ProgressUpdateOptions, } from "./mutations.ts";
+export { docsRepair } from "./repair.ts";
+export type { DocsRepairAction, DocsRepairOptions, DocsRepairPlan } from "./types.ts";
+export { allSynonyms, canonical, detectLocale, getFieldByRole, stripBom, synonymPattern, LOCALES, SYNONYMS, type Locale, type SynonymRole, } from "./profile.ts";
+export { fileHashes, DOC_FILES } from "./hashes.ts";
+export { phaseContext, type PhaseContext } from "./context.ts";
+export { docsStatus } from "./status.ts";
+export { docsValidate } from "./validate.ts";
+export { TEMPLATE_KINDS, projectTemplates, type TemplateKind } from "./templates.ts";
+export { PRIORITY_ALIASES, STATUS_ALIASES, priorityAliasHelp, resolvePriority, resolveStatus, statusAliasHelp, } from "./aliases.ts";
+export type { ArchiveItem, ArchiveItemPlan, ApplyResult, Backlog, BacklogAddPlan, BacklogEntry, BacklogItem, BacklogRemovePlan, BacklogSection, BacklogUpdatePlan, DoneEntry, DocsStatus, ParseResult, PhaseBlock, PhasePlan, PlanChange, Priority, Progress, ProgressRow, ProgressUpdatePlan, Status, ValidateResult, Warning, } from "./types.ts";
+export declare const TOOL_NAME = "stepwell";
+export declare const TOOL_VERSION: string;