@schnick371/devsteps-shared 1.1.0-next.3 → 2.0.0-next.1

package/dist/core/doctor-schema-tokens.js

@@ -0,0 +1,88 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Locate root JSON string tokens so repair preserves every unrelated source byte.
+ * JSON syntax is validated by the raw reader before this scanner is used.
+ */
+function endOfString(text, start) {
+    for (let index = start + 1; index < text.length; index++) {
+        if (text[index] === '\\')
+            index++;
+        else if (text[index] === '"')
+            return index + 1;
+    }
+    throw new Error('Metadata string token is incomplete');
+}
+function skipWhitespace(text, start) {
+    let index = start;
+    while (/\s/.test(text[index] ?? '') && index < text.length)
+        index++;
+    return index;
+}
+export function rootMetadataTokens(text) {
+    const strings = new Map();
+    const seen = new Set();
+    const duplicates = new Set();
+    let depth = 0;
+    for (let index = 0; index < text.length; index++) {
+        const char = text[index];
+        if (char === '{' || char === '[')
+            depth++;
+        else if (char === '}' || char === ']')
+            depth--;
+        else if (char === '"') {
+            const end = endOfString(text, index);
+            const colon = skipWhitespace(text, end);
+            if (depth === 1 && text[colon] === ':') {
+                const key = JSON.parse(text.slice(index, end));
+                if (seen.has(key))
+                    duplicates.add(key);
+                seen.add(key);
+                const start = skipWhitespace(text, colon + 1);
+                if (text[start] === '"')
+                    strings.set(key, { start, end: endOfString(text, start) });
+            }
+            index = end - 1;
+        }
+    }
+    return { strings, duplicateKeys: [...duplicates] };
+}
+/** Replace selected strings and insert explicit absent fields, retaining all other bytes. */
+export function patchMetadataStringTokens(text, changes) {
+    const { strings } = rootMetadataTokens(text);
+    const patches = changes
+        .filter((change) => change.operation !== 'insert')
+        .map((change) => {
+        const token = strings.get(change.field);
+        if (!token || JSON.parse(text.slice(token.start, token.end)) !== change.before) {
+            throw new Error(`Cannot locate the stored ${change.field} string for schema repair`);
+        }
+        return { ...token, value: JSON.stringify(change.after) };
+    });
+    let patched = text;
+    for (const patch of patches.sort((a, b) => b.start - a.start)) {
+        patched = patched.slice(0, patch.start) + patch.value + patched.slice(patch.end);
+    }
+    const insertions = changes.filter((change) => change.operation === 'insert');
+    if (insertions.length > 0) {
+        const raw = JSON.parse(patched);
+        for (const change of insertions) {
+            if (Object.hasOwn(raw, change.field)) {
+                throw new Error(`Cannot insert existing ${change.field} for schema repair`);
+            }
+        }
+        // Validated JSON has one root closing brace. Insert before its original whitespace;
+        // neither nested values nor the preexisting source need reserialization.
+        let insertion = patched.trimEnd().length - 1;
+        while (/\s/.test(patched[insertion - 1] ?? '') && insertion > 0)
+            insertion--;
+        const members = insertions
+            .map((change) => `${JSON.stringify(change.field)}:${JSON.stringify(change.after)}`)
+            .join(',');
+        const prefix = Object.keys(raw).length > 0 ? ',' : '';
+        patched = patched.slice(0, insertion) + prefix + members + patched.slice(insertion);
+    }
+    return patched;
+}
+//# sourceMappingURL=doctor-schema-tokens.js.map

package/dist/core/doctor-schema-tokens.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor-schema-tokens.js","sourceRoot":"","sources":["../../src/core/doctor-schema-tokens.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAcH,SAAS,WAAW,CAAC,IAAY,EAAE,KAAa;IAC9C,KAAK,IAAI,KAAK,GAAG,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,CAAC;QACzD,IAAI,IAAI,CAAC,KAAK,CAAC,KAAK,IAAI;YAAE,KAAK,EAAE,CAAC;aAC7B,IAAI,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG;YAAE,OAAO,KAAK,GAAG,CAAC,CAAC;IACjD,CAAC;IACD,MAAM,IAAI,KAAK,CAAC,qCAAqC,CAAC,CAAC;AACzD,CAAC;AAED,SAAS,cAAc,CAAC,IAAY,EAAE,KAAa;IACjD,IAAI,KAAK,GAAG,KAAK,CAAC;IAClB,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,IAAI,KAAK,GAAG,IAAI,CAAC,MAAM;QAAE,KAAK,EAAE,CAAC;IACpE,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,IAAY;IAC7C,MAAM,OAAO,GAAG,IAAI,GAAG,EAAuB,CAAC;IAC/C,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,MAAM,UAAU,GAAG,IAAI,GAAG,EAAU,CAAC;IACrC,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,CAAC;QACjD,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC;QACzB,IAAI,IAAI,KAAK,GAAG,IAAI,IAAI,KAAK,GAAG;YAAE,KAAK,EAAE,CAAC;aACrC,IAAI,IAAI,KAAK,GAAG,IAAI,IAAI,KAAK,GAAG;YAAE,KAAK,EAAE,CAAC;aAC1C,IAAI,IAAI,KAAK,GAAG,EAAE,CAAC;YACtB,MAAM,GAAG,GAAG,WAAW,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;YACrC,MAAM,KAAK,GAAG,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;YACxC,IAAI,KAAK,KAAK,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,EAAE,CAAC;gBACvC,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,CAAC,CAAW,CAAC;gBACzD,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;oBAAE,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;gBACvC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;gBACd,MAAM,KAAK,GAAG,cAAc,CAAC,IAAI,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;gBAC9C,IAAI,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG;oBAAE,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,WAAW,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE,CAAC,CAAC;YACtF,CAAC;YACD,KAAK,GAAG,GAAG,GAAG,CAAC,CAAC;QAClB,CAAC;IACH,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,CAAC,GAAG,UAAU,CAAC,EAAE,CAAC;AACrD,CAAC;AAED,6FAA6F;AAC7F,MAAM,UAAU,yBAAyB,CACvC,IAAY,EACZ,OAAsC;IAEtC,MAAM,EAAE,OAAO,EAAE,GAAG,kBAAkB,CAAC,IAAI,CAAC,CAAC;IAC7C,MAAM,OAAO,GAAG,OAAO;SACpB,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,SAAS,KAAK,QAAQ,CAAC;SACjD,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE;QACd,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACxC,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,KAAK,MAAM,CAAC,MAAM,EAAE,CAAC;YAC/E,MAAM,IAAI,KAAK,CAAC,4BAA4B,MAAM,CAAC,KAAK,2BAA2B,CAAC,CAAC;QACvF,CAAC;QACD,OAAO,EAAE,GAAG,KAAK,EAAE,KAAK,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;IAC3D,CAAC,CAAC,CAAC;IACL,IAAI,OAAO,GAAG,IAAI,CAAC;IACnB,KAAK,MAAM,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC;QAC9D,OAAO,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,KAAK,CAAC,GAAG,KAAK,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACnF,CAAC;IACD,MAAM,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,SAAS,KAAK,QAAQ,CAAC,CAAC;IAC7E,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC1B,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAA4B,CAAC;QAC3D,KAAK,MAAM,MAAM,IAAI,UAAU,EAAE,CAAC;YAChC,IAAI,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;gBACrC,MAAM,IAAI,KAAK,CAAC,0BAA0B,MAAM,CAAC,KAAK,oBAAoB,CAAC,CAAC;YAC9E,CAAC;QACH,CAAC;QACD,oFAAoF;QACpF,yEAAyE;QACzE,IAAI,SAAS,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC;QAC7C,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,SAAS,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,IAAI,SAAS,GAAG,CAAC;YAAE,SAAS,EAAE,CAAC;QAC7E,MAAM,OAAO,GAAG,UAAU;aACvB,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;aAClF,IAAI,CAAC,GAAG,CAAC,CAAC;QACb,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;QACtD,OAAO,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;IACtF,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/core/doctor-schema.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Doctor check for item files that violate the item schema (STORY-391).
+ * Every other read path treats such a file as absent: `listItems()` maps it to
+ * null, `status` counts one item less, and the integrity loader skips it.
+ * This check is the one that names it.
+ */
+import type { CheckResult } from './doctor-types.js';
+/**
+ * Scan every item directory, including `items/docs`, which the relationship
+ * checks do not cover.
+ */
+export declare function detectSchemaInvalidItems(devstepsDir: string): CheckResult;
+//# sourceMappingURL=doctor-schema.d.ts.map

package/dist/core/doctor-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor-schema.d.ts","sourceRoot":"","sources":["../../src/core/doctor-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AA+BrD;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,WAAW,EAAE,MAAM,GAAG,WAAW,CAsBzE"}

package/dist/core/doctor-schema.js

@@ -0,0 +1,59 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Doctor check for item files that violate the item schema (STORY-391).
+ * Every other read path treats such a file as absent: `listItems()` maps it to
+ * null, `status` counts one item less, and the integrity loader skips it.
+ * This check is the one that names it.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { ItemMetadata } from '../schemas/index.js';
+import { itemPaths } from './item-paths.js';
+import { listItemIds } from './item-store.js';
+import { describeZodIssues } from './item-validation.js';
+const MAX_REPORTED = 10;
+function inspectItem(devstepsDir, id) {
+    const metadataPath = itemPaths(devstepsDir, id).metadata;
+    if (!existsSync(metadataPath)) {
+        return { id, reason: `item folder without ${id}.json` };
+    }
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(metadataPath, 'utf-8'));
+    }
+    catch (error) {
+        return { id, reason: `not valid JSON — ${error instanceof Error ? error.message : 'unknown'}` };
+    }
+    const parsed = ItemMetadata.safeParse(raw);
+    if (parsed.success)
+        return undefined;
+    return { id, reason: describeZodIssues(parsed.error.issues, raw).join('; ') };
+}
+/**
+ * Scan every item directory, including `items/docs`, which the relationship
+ * checks do not cover.
+ */
+export function detectSchemaInvalidItems(devstepsDir) {
+    const invalid = [];
+    for (const id of listItemIds(devstepsDir)) {
+        const finding = inspectItem(devstepsDir, id);
+        if (finding)
+            invalid.push(finding);
+    }
+    if (invalid.length === 0) {
+        return {
+            name: 'Item Schema Validity',
+            status: 'pass',
+            message: 'All item files satisfy the item schema',
+        };
+    }
+    return {
+        name: 'Item Schema Validity',
+        status: 'fail',
+        message: `${invalid.length} item file(s) violate the schema and are invisible to list, status and board`,
+        details: invalid.slice(0, MAX_REPORTED).map(({ id, reason }) => `${id}: ${reason}`),
+        fix: 'Inspect: devsteps get <ID> --raw. Preview: devsteps doctor --fix schema --item <ID>; add --apply to write only a fully valid deterministic repair. Other issues require explicit correction or retirement.',
+    };
+}
+//# sourceMappingURL=doctor-schema.js.map

package/dist/core/doctor-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor-schema.js","sourceRoot":"","sources":["../../src/core/doctor-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAEnD,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC9C,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAEzD,MAAM,YAAY,GAAG,EAAE,CAAC;AAOxB,SAAS,WAAW,CAAC,WAAmB,EAAE,EAAU;IAClD,MAAM,YAAY,GAAG,SAAS,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC,QAAQ,CAAC;IACzD,IAAI,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;QAC9B,OAAO,EAAE,EAAE,EAAE,MAAM,EAAE,uBAAuB,EAAE,OAAO,EAAE,CAAC;IAC1D,CAAC;IAED,IAAI,GAAY,CAAC;IACjB,IAAI,CAAC;QACH,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC,CAAC;IACxD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,EAAE,EAAE,EAAE,MAAM,EAAE,oBAAoB,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC;IAClG,CAAC;IAED,MAAM,MAAM,GAAG,YAAY,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;IAC3C,IAAI,MAAM,CAAC,OAAO;QAAE,OAAO,SAAS,CAAC;IAErC,OAAO,EAAE,EAAE,EAAE,MAAM,EAAE,iBAAiB,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;AAChF,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,wBAAwB,CAAC,WAAmB;IAC1D,MAAM,OAAO,GAAkB,EAAE,CAAC;IAClC,KAAK,MAAM,EAAE,IAAI,WAAW,CAAC,WAAW,CAAC,EAAE,CAAC;QAC1C,MAAM,OAAO,GAAG,WAAW,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;QAC7C,IAAI,OAAO;YAAE,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACrC,CAAC;IAED,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO;YACL,IAAI,EAAE,sBAAsB;YAC5B,MAAM,EAAE,MAAM;YACd,OAAO,EAAE,wCAAwC;SAClD,CAAC;IACJ,CAAC;IAED,OAAO;QACL,IAAI,EAAE,sBAAsB;QAC5B,MAAM,EAAE,MAAM;QACd,OAAO,EAAE,GAAG,OAAO,CAAC,MAAM,8EAA8E;QACxG,OAAO,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,YAAY,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,GAAG,EAAE,KAAK,MAAM,EAAE,CAAC;QACnF,GAAG,EAAE,4MAA4M;KAClN,CAAC;AACJ,CAAC"}

package/dist/core/doctor-types.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Result shape shared by every doctor check, in the CLI and over MCP.
+ */
+export type CheckStatus = 'pass' | 'warn' | 'fail';
+export interface CheckResult {
+    name: string;
+    status: CheckStatus;
+    message: string;
+    details?: string[];
+    fix?: string;
+}
+export interface CheckSummary {
+    /** Worst status across all checks. */
+    verdict: CheckStatus;
+    pass: number;
+    warn: number;
+    fail: number;
+}
+export declare function summarizeChecks(checks: readonly CheckResult[]): CheckSummary;
+//# sourceMappingURL=doctor-types.d.ts.map

package/dist/core/doctor-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor-types.d.ts","sourceRoot":"","sources":["../../src/core/doctor-types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;AAEnD,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,WAAW,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,YAAY;IAC3B,sCAAsC;IACtC,OAAO,EAAE,WAAW,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,SAAS,WAAW,EAAE,GAAG,YAAY,CAK5E"}

package/dist/core/doctor-types.js

@@ -0,0 +1,14 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Result shape shared by every doctor check, in the CLI and over MCP.
+ */
+export function summarizeChecks(checks) {
+    const summary = { verdict: 'pass', pass: 0, warn: 0, fail: 0 };
+    for (const check of checks)
+        summary[check.status] += 1;
+    summary.verdict = summary.fail > 0 ? 'fail' : summary.warn > 0 ? 'warn' : 'pass';
+    return summary;
+}
+//# sourceMappingURL=doctor-types.js.map

package/dist/core/doctor-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor-types.js","sourceRoot":"","sources":["../../src/core/doctor-types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAoBH,MAAM,UAAU,eAAe,CAAC,MAA8B;IAC5D,MAAM,OAAO,GAAiB,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;IAC7E,KAAK,MAAM,KAAK,IAAI,MAAM;QAAE,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACvD,OAAO,CAAC,OAAO,GAAG,OAAO,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC;IACjF,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/core/doctor.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Project integrity doctor.
+ * STORY-116: one set of checks for `devsteps doctor` and the MCP `doctor` tool, so an
+ * agent can verify the data it works on without leaving the session.
+ */
+import type { CheckResult } from './doctor-types.js';
+export type { CheckResult, CheckStatus, CheckSummary } from './doctor-types.js';
+export { summarizeChecks } from './doctor-types.js';
+/**
+ * Run every integrity check and return one result per check category.
+ * Nothing is written; the results name the repair command where one exists.
+ */
+export declare function runIntegrityChecks(devstepsDir: string): Promise<CheckResult[]>;
+//# sourceMappingURL=doctor.d.ts.map

package/dist/core/doctor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/core/doctor.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AA0BH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAIrD,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAChF,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AA6DpD;;;GAGG;AACH,wBAAsB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAsDpF"}

package/dist/core/doctor.js

@@ -0,0 +1,132 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Project integrity doctor.
+ * STORY-116: one set of checks for `devsteps doctor` and the MCP `doctor` tool, so an
+ * agent can verify the data it works on without leaving the session.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { ItemMetadata } from '../schemas/index.js';
+import { listArchivedItemIds } from './archive.js';
+import { loadClassificationRegistry, } from './classification-registry.js';
+import { getConfig } from './config.js';
+import { detectAttachmentProblems } from './doctor-attachments.js';
+import { detectClassificationDrift } from './doctor-classification.js';
+import { detectCommitEvidence } from './doctor-commit-evidence.js';
+import { detectCoordinationTextInItems } from './doctor-coordination.js';
+import { detectCountersBehindDisk } from './doctor-counters.js';
+import { detectPlaceholderCandidates } from './doctor-placeholders.js';
+import { detectAsymmetricLinks, detectBrokenReferences, detectInvalidRelationships, detectLegacyRelationshipStructure, detectMissingHierarchyParents, detectOrphanedItems, } from './doctor-relations.js';
+import { detectSchemaInvalidItems } from './doctor-schema.js';
+import { itemPaths } from './item-paths.js';
+import { listItemIds } from './item-store.js';
+export { summarizeChecks } from './doctor-types.js';
+const RELATION_KEYS = [
+    'implements',
+    'implemented-by',
+    'tested-by',
+    'tests',
+    'blocks',
+    'blocked-by',
+    'relates-to',
+    'depends-on',
+    'required-by',
+    'supersedes',
+    'superseded-by',
+    'canonical-for',
+    'derived-from',
+    'documented-by',
+    'documents',
+];
+/** Load every schema-valid item; malformed files are reported by the schema check. */
+function loadAllItems(devstepsDir) {
+    const items = new Map();
+    const legacyRelationshipIds = [];
+    // Every type, docs included, so a `documents` edge to a DOC item is not reported as broken.
+    for (const id of listItemIds(devstepsDir)) {
+        try {
+            const raw = JSON.parse(readFileSync(itemPaths(devstepsDir, id).metadata, 'utf-8'));
+            const meta = ItemMetadata.parse(raw);
+            items.set(meta.id, meta);
+            const linkedItems = raw.linked_items;
+            if (linkedItems === undefined ||
+                RELATION_KEYS.some((relationKey) => !(relationKey in linkedItems))) {
+                legacyRelationshipIds.push(meta.id);
+            }
+        }
+        catch {
+            // Malformed or schema-invalid: reported by detectSchemaInvalidItems.
+        }
+    }
+    return { items, legacyRelationshipIds };
+}
+async function readMethodology(devstepsDir) {
+    try {
+        const config = await getConfig(devstepsDir);
+        return config.settings?.methodology || 'hybrid';
+    }
+    catch {
+        return 'hybrid';
+    }
+}
+/**
+ * Run every integrity check and return one result per check category.
+ * Nothing is written; the results name the repair command where one exists.
+ */
+export async function runIntegrityChecks(devstepsDir) {
+    if (!existsSync(join(devstepsDir, 'items'))) {
+        return [
+            {
+                name: 'Relationship Integrity',
+                status: 'warn',
+                message: 'No items directory found — skipping integrity checks',
+            },
+        ];
+    }
+    const loaded = loadAllItems(devstepsDir);
+    // Runs before the empty-project shortcut: a project whose items all fail the
+    // schema looks empty here and used to be reported as "No items found".
+    const schemaCheck = detectSchemaInvalidItems(devstepsDir);
+    const placeholderCheck = detectPlaceholderCandidates(devstepsDir);
+    const commitEvidenceCheck = await detectCommitEvidence(devstepsDir, loaded.items);
+    if (loaded.items.size === 0) {
+        return [
+            schemaCheck,
+            placeholderCheck,
+            commitEvidenceCheck,
+            { name: 'Relationship Integrity', status: 'pass', message: 'No items found to check' },
+        ];
+    }
+    const methodology = await readMethodology(devstepsDir);
+    let registry = null;
+    try {
+        registry = loadClassificationRegistry(devstepsDir);
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        return [
+            schemaCheck,
+            placeholderCheck,
+            commitEvidenceCheck,
+            { name: 'Classification', status: 'fail', message: `Registry unreadable: ${reason}` },
+        ];
+    }
+    return [
+        schemaCheck,
+        placeholderCheck,
+        commitEvidenceCheck,
+        detectBrokenReferences(loaded.items, new Set(listArchivedItemIds(devstepsDir))),
+        detectAsymmetricLinks(loaded.items),
+        detectInvalidRelationships(loaded.items, methodology),
+        detectMissingHierarchyParents(loaded.items, methodology),
+        detectLegacyRelationshipStructure(loaded.legacyRelationshipIds),
+        detectOrphanedItems(loaded.items),
+        detectClassificationDrift(loaded.items, registry),
+        detectCountersBehindDisk(devstepsDir),
+        detectAttachmentProblems(devstepsDir, loaded.items.keys()),
+        detectCoordinationTextInItems(devstepsDir, loaded.items),
+    ];
+}
+//# sourceMappingURL=doctor.js.map

package/dist/core/doctor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.js","sourceRoot":"","sources":["../../src/core/doctor.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,YAAY,EAAoB,MAAM,qBAAqB,CAAC;AACrE,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,EAEL,0BAA0B,GAC3B,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,wBAAwB,EAAE,MAAM,yBAAyB,CAAC;AACnE,OAAO,EAAE,yBAAyB,EAAE,MAAM,4BAA4B,CAAC;AACvE,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,EAAE,6BAA6B,EAAE,MAAM,0BAA0B,CAAC;AACzE,OAAO,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAChE,OAAO,EAAE,2BAA2B,EAAE,MAAM,0BAA0B,CAAC;AACvE,OAAO,EACL,qBAAqB,EACrB,sBAAsB,EACtB,0BAA0B,EAC1B,iCAAiC,EACjC,6BAA6B,EAC7B,mBAAmB,GACpB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AAE9D,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAG9C,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEpD,MAAM,aAAa,GAAG;IACpB,YAAY;IACZ,gBAAgB;IAChB,WAAW;IACX,OAAO;IACP,QAAQ;IACR,YAAY;IACZ,YAAY;IACZ,YAAY;IACZ,aAAa;IACb,YAAY;IACZ,eAAe;IACf,eAAe;IACf,cAAc;IACd,eAAe;IACf,WAAW;CACH,CAAC;AAOX,sFAAsF;AACtF,SAAS,YAAY,CAAC,WAAmB;IACvC,MAAM,KAAK,GAAG,IAAI,GAAG,EAAwB,CAAC;IAC9C,MAAM,qBAAqB,GAAa,EAAE,CAAC;IAE3C,4FAA4F;IAC5F,KAAK,MAAM,EAAE,IAAI,WAAW,CAAC,WAAW,CAAC,EAAE,CAAC;QAC1C,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,SAAS,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC,QAAQ,EAAE,OAAO,CAAC,CAEhF,CAAC;YACF,MAAM,IAAI,GAAG,YAAY,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;YACrC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;YACzB,MAAM,WAAW,GAAG,GAAG,CAAC,YAAY,CAAC;YACrC,IACE,WAAW,KAAK,SAAS;gBACzB,aAAa,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,IAAI,WAAW,CAAC,CAAC,EAClE,CAAC;gBACD,qBAAqB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACtC,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,qEAAqE;QACvE,CAAC;IACH,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,qBAAqB,EAAE,CAAC;AAC1C,CAAC;AAED,KAAK,UAAU,eAAe,CAAC,WAAmB;IAChD,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,WAAW,CAAC,CAAC;QAC5C,OAAQ,MAAM,CAAC,QAAQ,EAAE,WAA2B,IAAI,QAAQ,CAAC;IACnE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,QAAQ,CAAC;IAClB,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,WAAmB;IAC1D,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC,EAAE,CAAC;QAC5C,OAAO;YACL;gBACE,IAAI,EAAE,wBAAwB;gBAC9B,MAAM,EAAE,MAAM;gBACd,OAAO,EAAE,sDAAsD;aAChE;SACF,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAG,YAAY,CAAC,WAAW,CAAC,CAAC;IACzC,6EAA6E;IAC7E,uEAAuE;IACvE,MAAM,WAAW,GAAG,wBAAwB,CAAC,WAAW,CAAC,CAAC;IAC1D,MAAM,gBAAgB,GAAG,2BAA2B,CAAC,WAAW,CAAC,CAAC;IAClE,MAAM,mBAAmB,GAAG,MAAM,oBAAoB,CAAC,WAAW,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC;IAClF,IAAI,MAAM,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;QAC5B,OAAO;YACL,WAAW;YACX,gBAAgB;YAChB,mBAAmB;YACnB,EAAE,IAAI,EAAE,wBAAwB,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,yBAAyB,EAAE;SACvF,CAAC;IACJ,CAAC;IAED,MAAM,WAAW,GAAG,MAAM,eAAe,CAAC,WAAW,CAAC,CAAC;IACvD,IAAI,QAAQ,GAAkC,IAAI,CAAC;IACnD,IAAI,CAAC;QACH,QAAQ,GAAG,0BAA0B,CAAC,WAAW,CAAC,CAAC;IACrD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,MAAM,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACtE,OAAO;YACL,WAAW;YACX,gBAAgB;YAChB,mBAAmB;YACnB,EAAE,IAAI,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,wBAAwB,MAAM,EAAE,EAAE;SACtF,CAAC;IACJ,CAAC;IACD,OAAO;QACL,WAAW;QACX,gBAAgB;QAChB,mBAAmB;QACnB,sBAAsB,CAAC,MAAM,CAAC,KAAK,EAAE,IAAI,GAAG,CAAC,mBAAmB,CAAC,WAAW,CAAC,CAAC,CAAC;QAC/E,qBAAqB,CAAC,MAAM,CAAC,KAAK,CAAC;QACnC,0BAA0B,CAAC,MAAM,CAAC,KAAK,EAAE,WAAW,CAAC;QACrD,6BAA6B,CAAC,MAAM,CAAC,KAAK,EAAE,WAAW,CAAC;QACxD,iCAAiC,CAAC,MAAM,CAAC,qBAAqB,CAAC;QAC/D,mBAAmB,CAAC,MAAM,CAAC,KAAK,CAAC;QACjC,yBAAyB,CAAC,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC;QACjD,wBAAwB,CAAC,WAAW,CAAC;QACrC,wBAAwB,CAAC,WAAW,EAAE,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;QAC1D,6BAA6B,CAAC,WAAW,EAAE,MAAM,CAAC,KAAK,CAAC;KACzD,CAAC;AACJ,CAAC"}

package/dist/core/epic-sections.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Tolerant reader of an epic's master document (EPIC-059, design v6.1 §2 and §3): finds the
+ * template sections under any accepted heading and level, and splits a section into lines.
+ * The epic warnings and the compass block both read epics through this module.
+ */
+import { type EpicSectionKey, type EpicSectionSpec } from '../templates/epic.js';
+export interface MarkdownSection {
+    heading: string;
+    level: number;
+    /** 1-based line of the heading. */
+    line: number;
+    /** The text up to the next heading of the same or a higher level. */
+    body: string;
+}
+/** One line of a section: a bullet, a paragraph or a sub-heading title, with its check. */
+export interface SectionLine {
+    text: string;
+    check?: string;
+}
+export declare function stripComments(text: string): string;
+/** Every ATX heading outside code fences, with the body it owns. */
+export declare function markdownSections(markdown: string): MarkdownSection[];
+export declare function normalizeHeading(text: string): string;
+export declare function headingMatches(heading: string, spec: EpicSectionSpec): boolean;
+/** The first section whose heading is one of the accepted names for `key`. */
+export declare function findEpicSection(markdown: string, key: EpicSectionKey): MarkdownSection | undefined;
+export declare function hasContent(section: MarkdownSection | undefined): boolean;
+/** The required sections of `specs` that are absent or hold only placeholders. */
+export declare function missingSections(markdown: string, specs: readonly EpicSectionSpec[]): EpicSectionSpec[];
+/** The required epic template sections that are absent or hold only placeholders. */
+export declare function missingEpicSections(markdown: string): EpicSectionSpec[];
+/** The text before the first heading, without comments: a story's opening user story. */
+export declare function openingText(markdown: string): string;
+/** Split a section body into lines: bullets, paragraphs, or the titles of its sub-entries. */
+export declare function sectionLines(body: string): SectionLine[];
+//# sourceMappingURL=epic-sections.d.ts.map

package/dist/core/epic-sections.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"epic-sections.d.ts","sourceRoot":"","sources":["../../src/core/epic-sections.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,eAAe,EAErB,MAAM,sBAAsB,CAAC;AAE9B,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,mCAAmC;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAC;CACd;AAED,2FAA2F;AAC3F,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAQD,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAElD;AAMD,oEAAoE;AACpE,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,eAAe,EAAE,CAmBpE;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CASrD;AAED,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,GAAG,OAAO,CAU9E;AAED,8EAA8E;AAC9E,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,cAAc,GAClB,eAAe,GAAG,SAAS,CAG7B;AAED,wBAAgB,UAAU,CAAC,OAAO,EAAE,eAAe,GAAG,SAAS,GAAG,OAAO,CAExE;AAED,kFAAkF;AAClF,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,SAAS,eAAe,EAAE,GAChC,eAAe,EAAE,CAOnB;AAED,qFAAqF;AACrF,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,eAAe,EAAE,CAEvE;AAED,yFAAyF;AACzF,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAKpD;AAgDD,8FAA8F;AAC9F,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,EAAE,CAMxD"}

package/dist/core/epic-sections.js

@@ -0,0 +1,147 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Tolerant reader of an epic's master document (EPIC-059, design v6.1 §2 and §3): finds the
+ * template sections under any accepted heading and level, and splits a section into lines.
+ * The epic warnings and the compass block both read epics through this module.
+ */
+import { EPIC_SECTIONS, epicSectionSpec, } from '../templates/epic.js';
+const FENCE = /^\s*(```|~~~)/;
+const HEADING = /^(#{1,6})\s+(.*?)\s*#*\s*$/;
+const BULLET = /^(\s*)(?:[-*+]|\d+[.)])\s+(.*)$/;
+const ENTRY_TITLE = /^[A-Z]+-\d+\s*[·|]\s*[^·|]+[·|]\s*(.+)$/;
+const CHECK = /\s*\(?\bcheck:\s*/i;
+export function stripComments(text) {
+    return text.replace(/<!--[\s\S]*?-->/g, '');
+}
+function splitLines(markdown) {
+    return markdown.replace(/\r\n?/g, '\n').split('\n');
+}
+/** Every ATX heading outside code fences, with the body it owns. */
+export function markdownSections(markdown) {
+    const lines = splitLines(markdown);
+    const headings = [];
+    let inFence = false;
+    lines.forEach((line, index) => {
+        if (FENCE.test(line))
+            inFence = !inFence;
+        const match = inFence ? null : HEADING.exec(line);
+        if (match)
+            headings.push({ level: match[1].length, text: match[2].trim(), index });
+    });
+    return headings.map((heading, position) => {
+        const next = headings.slice(position + 1).find((later) => later.level <= heading.level);
+        const end = next?.index ?? lines.length;
+        return {
+            heading: heading.text,
+            level: heading.level,
+            line: heading.index + 1,
+            body: lines.slice(heading.index + 1, end).join('\n'),
+        };
+    });
+}
+export function normalizeHeading(text) {
+    return text
+        .toLowerCase()
+        .replace(/[*_`]/g, '')
+        .replace(/^\s*(\d+[.)]\s*)+/, '')
+        .replace(/[‐-―]/g, '-')
+        .replace(/[:.]+\s*$/, '')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+export function headingMatches(heading, spec) {
+    const normalized = normalizeHeading(heading);
+    return spec.aliases.some((alias) => {
+        const expected = normalizeHeading(alias);
+        return (normalized === expected ||
+            normalized.startsWith(`${expected} `) ||
+            normalized.startsWith(`${expected}(`));
+    });
+}
+/** The first section whose heading is one of the accepted names for `key`. */
+export function findEpicSection(markdown, key) {
+    const spec = epicSectionSpec(key);
+    return markdownSections(markdown).find((section) => headingMatches(section.heading, spec));
+}
+export function hasContent(section) {
+    return Boolean(section && stripComments(section.body).trim() !== '');
+}
+/** The required sections of `specs` that are absent or hold only placeholders. */
+export function missingSections(markdown, specs) {
+    const sections = markdownSections(markdown);
+    return specs.filter((spec) => !spec.optional &&
+        !hasContent(sections.find((section) => headingMatches(section.heading, spec))));
+}
+/** The required epic template sections that are absent or hold only placeholders. */
+export function missingEpicSections(markdown) {
+    return missingSections(markdown, EPIC_SECTIONS);
+}
+/** The text before the first heading, without comments: a story's opening user story. */
+export function openingText(markdown) {
+    const first = markdownSections(markdown)[0];
+    const lines = splitLines(markdown);
+    const opening = first ? lines.slice(0, first.line - 1) : lines;
+    return stripComments(opening.join('\n')).trim();
+}
+function splitCheck(raw) {
+    const text = raw.replace(/\s+/g, ' ').trim();
+    const match = CHECK.exec(text);
+    if (!match || match.index === 0)
+        return { text };
+    const check = text
+        .slice(match.index + match[0].length)
+        .replace(/[).\s]+$/, '')
+        .trim();
+    const before = text.slice(0, match.index).replace(/[.;,\s]+$/, '');
+    return check ? { text: before, check } : { text: before };
+}
+/** Sub-headings such as `### N-1 · MUST · Title` become one line each, with their Check. */
+function entryLines(body) {
+    return markdownSections(body).map((entry) => {
+        const title = ENTRY_TITLE.exec(entry.heading)?.[1] ?? entry.heading;
+        const check = /^\s*[-*+]\s*check:\s*(.+)$/im.exec(stripComments(entry.body))?.[1];
+        return check ? { text: title.trim(), check: check.trim() } : { text: title.trim() };
+    });
+}
+function proseLines(body) {
+    const items = [];
+    let open = false;
+    let inFence = false;
+    for (const line of splitLines(body)) {
+        if (FENCE.test(line))
+            inFence = !inFence;
+        if (inFence || FENCE.test(line))
+            continue;
+        const bullet = BULLET.exec(line);
+        if (bullet && (bullet[1].length < 2 || !open)) {
+            items.push(bullet[2]);
+            open = true;
+        }
+        else if (bullet) {
+            items[items.length - 1] += `; ${bullet[2]}`;
+        }
+        else if (line.trim() === '') {
+            open = false;
+        }
+        else if (open) {
+            items[items.length - 1] += ` ${line.trim()}`;
+        }
+        else {
+            items.push(line.trim());
+            open = true;
+        }
+    }
+    return items;
+}
+/** Split a section body into lines: bullets, paragraphs, or the titles of its sub-entries. */
+export function sectionLines(body) {
+    const text = stripComments(body);
+    if (markdownSections(text).length > 0)
+        return entryLines(text);
+    return proseLines(text)
+        .map(splitCheck)
+        .filter((line) => line.text !== '');
+}
+//# sourceMappingURL=epic-sections.js.map

package/dist/core/epic-sections.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"epic-sections.js","sourceRoot":"","sources":["../../src/core/epic-sections.ts"],"names":[],"mappings":"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"}

package/dist/core/expedition-metadata.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Read and patch an epic's `metadata.expedition` record (EPIC-059). Writers go through
+ * `patchExpeditionMetadata`, which carries the read stamp (STORY-428).
+ */
+import { ExpeditionMetadata } from '../schemas/expedition.js';
+import type { ItemMetadata } from '../schemas/index.js';
+/** The tag that makes an epic an expedition. */
+export declare const EXPEDITION_TAG = "expedition";
+export declare function isExpeditionEpic(item: Pick<ItemMetadata, 'type' | 'tags'>): boolean;
+/** The epic's expedition record, or undefined when it has none; a malformed record throws. */
+export declare function readExpeditionMetadata(item: Pick<ItemMetadata, 'id' | 'metadata'>): {
+    [x: string]: unknown;
+    baseline_commit?: string | undefined;
+    project_core_hash?: string | undefined;
+    epic_core_hash?: string | undefined;
+    baseline_date?: string | undefined;
+    based_on?: string | undefined;
+    permissions?: {
+        settings_file: string;
+        added: {
+            allow: string[];
+            deny: string[];
+        };
+        applied_at: string;
+    } | undefined;
+    harvest?: {
+        tip_commit: string;
+        harvested_at: string;
+        report: string;
+    } | undefined;
+} | undefined;
+/** True once the human baseline pinned the epic. */
+export declare function isBaselined(record: ExpeditionMetadata | undefined): boolean;
+/**
+ * Merge `patch` into the epic's expedition record and write it. A key set to undefined in
+ * the patch is removed. Refuses an item that is not an expedition epic.
+ */
+export declare function patchExpeditionMetadata(devstepsDir: string, epicId: string, patch: Partial<ExpeditionMetadata>): Promise<ExpeditionMetadata>;
+//# sourceMappingURL=expedition-metadata.d.ts.map

package/dist/core/expedition-metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"expedition-metadata.d.ts","sourceRoot":"","sources":["../../src/core/expedition-metadata.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAKxD,gDAAgD;AAChD,eAAO,MAAM,cAAc,eAAe,CAAC;AAE3C,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,IAAI,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAAC,GAAG,OAAO,CAEnF;AAED,8FAA8F;AAC9F,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,IAAI,CAAC,YAAY,EAAE,IAAI,GAAG,UAAU,CAAC;;;;;;;;;;;;;;;;;;;;cAQjF;AAED,oDAAoD;AACpD,wBAAgB,WAAW,CAAC,MAAM,EAAE,kBAAkB,GAAG,SAAS,GAAG,OAAO,CAE3E;AAED;;;GAGG;AACH,wBAAsB,uBAAuB,CAC3C,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,OAAO,CAAC,kBAAkB,CAAC,GACjC,OAAO,CAAC,kBAAkB,CAAC,CAe7B"}