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

package/dist/core/item-validation.js

@@ -0,0 +1,99 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Write-path guard for item metadata (BUG-115 / STORY-382)
+ * `getItem()` parses every item against `ItemMetadata` and throws on any violation.
+ * Until this guard existed, no write path checked the same contract, so a single
+ * `add` could persist an item that could never be read, updated, linked, archived
+ * or purged again. Every writer runs this before it touches the filesystem.
+ */
+import { ItemMetadata } from '../schemas/index.js';
+/**
+ * Raised when metadata would be persisted in a shape the read path rejects.
+ * Carries the readable per-field lines so adapters can present them as they like.
+ */
+export class ItemValidationError extends Error {
+    issues;
+    constructor(message, issues) {
+        super(message);
+        this.name = 'ItemValidationError';
+        this.issues = issues;
+    }
+}
+const MAX_SHOWN_VALUE = 60;
+function valueAtPath(input, path) {
+    let current = input;
+    for (const segment of path) {
+        if (current === null || typeof current !== 'object')
+            return undefined;
+        current = current[segment];
+    }
+    return current;
+}
+function quote(value) {
+    const shown = value.length > MAX_SHOWN_VALUE ? `${value.slice(0, MAX_SHOWN_VALUE)}…` : value || '(empty)';
+    return `"${shown}"`;
+}
+/**
+ * Zod compares string length in Unicode code points, not in UTF-16 code units:
+ * `'A'.repeat(199) + '🚀'` has `.length === 201` and still passes `.max(200)`,
+ * while a decomposed umlaut (a + combining diaeresis) counts as two. Reporting
+ * `String.length` here would name a number the limit was never compared against,
+ * so the message has to state the counted one.
+ */
+function countUnits(value) {
+    return [...value].length;
+}
+function describeStringLength(field, value, issue) {
+    if (issue.code === 'too_big') {
+        const limit = typeof issue.maximum === 'number' ? issue.maximum : undefined;
+        return `${field} is too long: ${countUnits(value)} characters${limit === undefined ? '' : ` (max ${limit})`} — counted in Unicode code points, so a decomposed umlaut counts as two`;
+    }
+    if (issue.code === 'too_small') {
+        const limit = typeof issue.minimum === 'number' ? issue.minimum : undefined;
+        return limit === 1
+            ? `${field} must not be empty`
+            : `${field} is too short: ${countUnits(value)} characters${limit === undefined ? '' : ` (min ${limit})`}`;
+    }
+    return undefined;
+}
+/** One readable line per Zod issue, resolving each offending value from `input`. */
+export function describeZodIssues(issues, input, origins = {}) {
+    return issues.map((issue) => describeIssue(issue, input, origins));
+}
+function describeIssue(issue, input, origins) {
+    const field = issue.path.length > 0 ? issue.path.join('.') : 'metadata';
+    const value = valueAtPath(input, issue.path);
+    const origin = origins[field];
+    const suffix = origin === undefined ? '' : ` (value came from ${origin})`;
+    if (typeof value === 'string') {
+        const lengthMessage = describeStringLength(field, value, issue);
+        if (lengthMessage !== undefined)
+            return `${lengthMessage}${suffix}`;
+        if (issue.code === 'invalid_format') {
+            return `${field} has an invalid format: ${quote(value)} — ${issue.message}${suffix}`;
+        }
+    }
+    if (value === undefined && issue.code === 'invalid_type') {
+        return `${field} is missing${suffix}`;
+    }
+    return `${field}: ${issue.message}${suffix}`;
+}
+/**
+ * Validate metadata about to be written and return the parsed value.
+ * Throws `ItemValidationError` with one readable line per violation instead of
+ * the raw Zod JSON, which is what reached the caller before this guard existed.
+ */
+export function assertValidItemMetadata(metadata, options = {}) {
+    const parsed = ItemMetadata.safeParse(metadata);
+    if (parsed.success)
+        return parsed.data;
+    const issues = describeZodIssues(parsed.error.issues, metadata, options.origins ?? {});
+    const id = metadata !== null && typeof metadata === 'object'
+        ? metadata.id
+        : undefined;
+    const subject = typeof id === 'string' && id.length > 0 ? id : 'item';
+    throw new ItemValidationError(`Cannot write ${subject}: ${issues.join('; ')}`, issues);
+}
+//# sourceMappingURL=item-validation.js.map

package/dist/core/item-validation.js.map

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

package/dist/core/item-write-pair.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * The second half of an update that wrote the `<ID>.md` before its metadata (BUG-182). When the
+ * metadata write fails — a rename that a virus scanner or an indexer keeps failing on Windows, or
+ * a concurrent writer (`StaleItemError`) — the description this update wrote is put back, so the
+ * item stays as it was. Only when that fails too is the item half written, and the error names
+ * both files and the repair.
+ * @see STORY-428
+ */
+import type { ItemMetadata } from '../schemas/index.js';
+import { type FileStamp } from './item-store.js';
+/** The description an update wrote, and what the file held before; undefined: no file. */
+export type WrittenDescription = Readonly<{
+    text: string;
+    before: string | undefined;
+}>;
+/**
+ * Write the metadata under `stamp` after the update wrote `written` to the `<ID>.md`. On failure
+ * the description goes back and the error says the item is unchanged; a `StaleItemError` is
+ * rethrown as it is, so the caller re-reads and retries. Every error names both files.
+ */
+export declare function writeMetadataAfterDescription(devstepsDir: string, metadata: ItemMetadata, stamp: FileStamp, written: WrittenDescription | undefined): void;
+//# sourceMappingURL=item-write-pair.d.ts.map

package/dist/core/item-write-pair.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"item-write-pair.d.ts","sourceRoot":"","sources":["../../src/core/item-write-pair.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAGxD,OAAO,EAAE,KAAK,SAAS,EAAqD,MAAM,iBAAiB,CAAC;AAEpG,0FAA0F;AAC1F,MAAM,MAAM,kBAAkB,GAAG,QAAQ,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAC,CAAC;AAwBxF;;;;GAIG;AACH,wBAAgB,6BAA6B,CAC3C,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,YAAY,EACtB,KAAK,EAAE,SAAS,EAChB,OAAO,EAAE,kBAAkB,GAAG,SAAS,GACtC,IAAI,CA4BN"}

package/dist/core/item-write-pair.js

@@ -0,0 +1,71 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * The second half of an update that wrote the `<ID>.md` before its metadata (BUG-182). When the
+ * metadata write fails — a rename that a virus scanner or an indexer keeps failing on Windows, or
+ * a concurrent writer (`StaleItemError`) — the description this update wrote is put back, so the
+ * item stays as it was. Only when that fails too is the item half written, and the error names
+ * both files and the repair.
+ * @see STORY-428
+ */
+import { existsSync, readFileSync, rmSync } from 'node:fs';
+import { writeFileAtomic } from '../utils/atomic-write.js';
+import { itemPaths } from './item-paths.js';
+import { invalidateItem, StaleItemError, writeItemMetadata } from './item-store.js';
+const reason = (error) => (error instanceof Error ? error.message : String(error));
+/**
+ * Put the description back unless another writer replaced it since; the file holds `text`.
+ * False when it was replaced, so it stays as the other writer left it. A writer between this
+ * read and the rename can still be lost; without a lock that window remains, much narrower
+ * than the half-written item it replaces.
+ */
+function restore(file, written) {
+    const now = existsSync(file) ? readFileSync(file, 'utf-8') : undefined;
+    if (now !== written.text)
+        return false;
+    if (written.before === undefined)
+        rmSync(file, { force: true });
+    else
+        writeFileAtomic(file, written.before);
+    return true;
+}
+/** An error that keeps the failed write's `code` (`STALE_ITEM` among them) for the caller. */
+function failure(message, error) {
+    const code = error?.code;
+    return Object.assign(new Error(message, { cause: error }), code === undefined ? {} : { code });
+}
+/**
+ * Write the metadata under `stamp` after the update wrote `written` to the `<ID>.md`. On failure
+ * the description goes back and the error says the item is unchanged; a `StaleItemError` is
+ * rethrown as it is, so the caller re-reads and retries. Every error names both files.
+ */
+export function writeMetadataAfterDescription(devstepsDir, metadata, stamp, written) {
+    try {
+        writeItemMetadata(devstepsDir, metadata, stamp);
+        return;
+    }
+    catch (error) {
+        if (!written)
+            throw error;
+        const paths = itemPaths(devstepsDir, metadata.id);
+        const lead = `Update of ${metadata.id}: ${paths.metadata} could not be written (${reason(error)})`;
+        let restored;
+        try {
+            restored = restore(paths.description, written);
+        }
+        catch (restoreError) {
+            throw failure(`${lead}, and ${paths.description} keeps the new description because it could not be restored (${reason(restoreError)}); re-read the item and check ${paths.description} before you retry`, error);
+        }
+        finally {
+            invalidateItem(devstepsDir, metadata.id);
+        }
+        if (error instanceof StaleItemError)
+            throw error;
+        if (!restored) {
+            throw failure(`${lead}; another writer changed ${paths.description} since, so it is left as that writer wrote it; re-read the item before you retry`, error);
+        }
+        throw failure(`${lead}; ${paths.description} was restored, so the item is unchanged`, error);
+    }
+}
+//# sourceMappingURL=item-write-pair.js.map

package/dist/core/item-write-pair.js.map

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

package/dist/core/link-conflicts.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Explicit association promotion and conflict recovery instructions (BUG-248).
+ */
+import type { ItemMetadata } from '../schemas/index.js';
+import type { LinkItemArgs, LinkItemResult } from './link.js';
+/** Mutates planned snapshots only; both endpoints must pass before either is persisted. */
+export declare function prepareLinkEndpoints(args: LinkItemArgs, source: ItemMetadata, target: ItemMetadata): LinkItemResult | undefined;
+//# sourceMappingURL=link-conflicts.d.ts.map

package/dist/core/link-conflicts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"link-conflicts.d.ts","sourceRoot":"","sources":["../../src/core/link-conflicts.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAgB,MAAM,qBAAqB,CAAC;AAEtE,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAI9D,2FAA2F;AAC3F,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,YAAY,EAClB,MAAM,EAAE,YAAY,EACpB,MAAM,EAAE,YAAY,GACnB,cAAc,GAAG,SAAS,CAqC5B"}

package/dist/core/link-conflicts.js

@@ -0,0 +1,45 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Explicit association promotion and conflict recovery instructions (BUG-248).
+ */
+import { isHierarchyRelation } from '../schemas/relationships.js';
+import { INVERSE_RELATIONS } from './relationship-map.js';
+import { validateRelationConflict } from './validation.js';
+/** Mutates planned snapshots only; both endpoints must pass before either is persisted. */
+export function prepareLinkEndpoints(args, source, target) {
+    if (args.replace && isHierarchyRelation(args.relationType)) {
+        source.linked_items['relates-to'] = source.linked_items['relates-to'].filter((id) => id !== target.id);
+        target.linked_items['relates-to'] = target.linked_items['relates-to'].filter((id) => id !== source.id);
+    }
+    const endpoints = [
+        [source, args.relationType, target.id],
+        [target, INVERSE_RELATIONS[args.relationType], source.id],
+    ];
+    for (const [item, relation, otherId] of endpoints) {
+        const conflict = validateRelationConflict(otherId, relation, item.linked_items);
+        if (conflict.valid)
+            continue;
+        const unlink = `devsteps unlink ${item.id} ${conflict.conflicting_relation} ${otherId}`;
+        const eligible = isHierarchyRelation(args.relationType) && conflict.conflicting_relation === 'relates-to';
+        const retry = `devsteps link ${args.sourceId} ${args.relationType} ${args.targetId}${eligible ? ' --replace' : ''}`;
+        return {
+            success: false,
+            validation_failed: true,
+            validation_kind: 'conflict',
+            error: conflict.error,
+            suggestion: eligible
+                ? `Run ${unlink}, then retry; or run ${retry}.`
+                : `Run ${unlink}, then retry.`,
+            next: { unlink, retry },
+        };
+    }
+    source.linked_items[args.relationType] = [
+        ...new Set([...source.linked_items[args.relationType], target.id]),
+    ];
+    const inverse = INVERSE_RELATIONS[args.relationType];
+    target.linked_items[inverse] = [...new Set([...target.linked_items[inverse], source.id])];
+    return undefined;
+}
+//# sourceMappingURL=link-conflicts.js.map

package/dist/core/link-conflicts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"link-conflicts.js","sourceRoot":"","sources":["../../src/core/link-conflicts.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAElE,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,EAAE,wBAAwB,EAAE,MAAM,iBAAiB,CAAC;AAE3D,2FAA2F;AAC3F,MAAM,UAAU,oBAAoB,CAClC,IAAkB,EAClB,MAAoB,EACpB,MAAoB;IAEpB,IAAI,IAAI,CAAC,OAAO,IAAI,mBAAmB,CAAC,IAAI,CAAC,YAAY,CAAC,EAAE,CAAC;QAC3D,MAAM,CAAC,YAAY,CAAC,YAAY,CAAC,GAAG,MAAM,CAAC,YAAY,CAAC,YAAY,CAAC,CAAC,MAAM,CAC1E,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,KAAK,MAAM,CAAC,EAAE,CACzB,CAAC;QACF,MAAM,CAAC,YAAY,CAAC,YAAY,CAAC,GAAG,MAAM,CAAC,YAAY,CAAC,YAAY,CAAC,CAAC,MAAM,CAC1E,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,KAAK,MAAM,CAAC,EAAE,CACzB,CAAC;IACJ,CAAC;IACD,MAAM,SAAS,GAAgD;QAC7D,CAAC,MAAM,EAAE,IAAI,CAAC,YAAY,EAAE,MAAM,CAAC,EAAE,CAAC;QACtC,CAAC,MAAM,EAAE,iBAAiB,CAAC,IAAI,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC,EAAE,CAAC;KAC1D,CAAC;IACF,KAAK,MAAM,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,CAAC,IAAI,SAAS,EAAE,CAAC;QAClD,MAAM,QAAQ,GAAG,wBAAwB,CAAC,OAAO,EAAE,QAAQ,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC;QAChF,IAAI,QAAQ,CAAC,KAAK;YAAE,SAAS;QAC7B,MAAM,MAAM,GAAG,mBAAmB,IAAI,CAAC,EAAE,IAAI,QAAQ,CAAC,oBAAoB,IAAI,OAAO,EAAE,CAAC;QACxF,MAAM,QAAQ,GACZ,mBAAmB,CAAC,IAAI,CAAC,YAAY,CAAC,IAAI,QAAQ,CAAC,oBAAoB,KAAK,YAAY,CAAC;QAC3F,MAAM,KAAK,GAAG,iBAAiB,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,YAAY,IAAI,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;QACpH,OAAO;YACL,OAAO,EAAE,KAAK;YACd,iBAAiB,EAAE,IAAI;YACvB,eAAe,EAAE,UAAU;YAC3B,KAAK,EAAE,QAAQ,CAAC,KAAK;YACrB,UAAU,EAAE,QAAQ;gBAClB,CAAC,CAAC,OAAO,MAAM,wBAAwB,KAAK,GAAG;gBAC/C,CAAC,CAAC,OAAO,MAAM,eAAe;YAChC,IAAI,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE;SACxB,CAAC;IACJ,CAAC;IACD,MAAM,CAAC,YAAY,CAAC,IAAI,CAAC,YAAY,CAAC,GAAG;QACvC,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC,YAAY,CAAC,IAAI,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC;KACnE,CAAC;IACF,MAAM,OAAO,GAAG,iBAAiB,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;IACrD,MAAM,CAAC,YAAY,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC,YAAY,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IAC1F,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/core/link-write.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Guarded relationship writes with recovery of the first endpoint (BUG-248).
+ * The relationship lock is in-process; this is not a cross-process transaction.
+ */
+import type { ItemMetadata } from '../schemas/index.js';
+import { type StoredItemMetadata } from './item-store.js';
+/** Both stamps are checked before writing. Rollback checks our exact bytes and write stamp. */
+export declare function writeLinkEndpoints(devstepsDir: string, endpoints: Array<{
+    original: StoredItemMetadata;
+    planned: ItemMetadata;
+}>): void;
+//# sourceMappingURL=link-write.d.ts.map

package/dist/core/link-write.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"link-write.d.ts","sourceRoot":"","sources":["../../src/core/link-write.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAIxD,OAAO,EAKL,KAAK,kBAAkB,EAExB,MAAM,iBAAiB,CAAC;AAyBzB,+FAA+F;AAC/F,wBAAgB,kBAAkB,CAChC,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,KAAK,CAAC;IAAE,QAAQ,EAAE,kBAAkB,CAAC;IAAC,OAAO,EAAE,YAAY,CAAA;CAAE,CAAC,GACxE,IAAI,CAiCN"}

package/dist/core/link-write.js

@@ -0,0 +1,63 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Guarded relationship writes with recovery of the first endpoint (BUG-248).
+ * The relationship lock is in-process; this is not a cross-process transaction.
+ */
+import { readFileSync, statSync } from 'node:fs';
+import { writeFileAtomic } from '../utils/atomic-write.js';
+import { getCurrentTimestamp } from '../utils/index.js';
+import { itemPaths } from './item-paths.js';
+import { assertItemUnchanged, invalidateItem, StaleItemError, writeItemMetadata, } from './item-store.js';
+const reason = (error) => (error instanceof Error ? error.message : String(error));
+function restoreEndpoint(devstepsDir, metadata, stamp, before) {
+    const file = itemPaths(devstepsDir, metadata.id).metadata;
+    const assertOurs = () => {
+        assertItemUnchanged(devstepsDir, metadata.id, stamp);
+        if (readFileSync(file, 'utf8') !== JSON.stringify(metadata, null, 2)) {
+            throw new StaleItemError(metadata.id);
+        }
+    };
+    try {
+        assertOurs();
+        writeFileAtomic(file, before, { beforeRename: assertOurs });
+    }
+    finally {
+        invalidateItem(devstepsDir, metadata.id);
+    }
+}
+/** Both stamps are checked before writing. Rollback checks our exact bytes and write stamp. */
+export function writeLinkEndpoints(devstepsDir, endpoints) {
+    const changed = endpoints.filter(({ original, planned }) => JSON.stringify(original.metadata.linked_items) !== JSON.stringify(planned.linked_items));
+    for (const { original } of endpoints) {
+        assertItemUnchanged(devstepsDir, original.metadata.id, original.stamp);
+    }
+    const first = changed[0];
+    if (!first)
+        return;
+    const file = itemPaths(devstepsDir, first.planned.id).metadata;
+    const before = readFileSync(file, 'utf8');
+    const timestamp = getCurrentTimestamp();
+    for (const { planned } of changed)
+        planned.updated = timestamp;
+    writeItemMetadata(devstepsDir, first.planned, first.original.stamp);
+    const { mtimeMs, size } = statSync(file);
+    try {
+        for (const endpoint of changed.slice(1)) {
+            writeItemMetadata(devstepsDir, endpoint.planned, endpoint.original.stamp);
+        }
+    }
+    catch (error) {
+        let recovery = `${first.planned.id} was restored`;
+        try {
+            restoreEndpoint(devstepsDir, first.planned, { mtimeMs, size }, before);
+        }
+        catch (restoreError) {
+            recovery = `rollback of ${first.planned.id} was refused or failed (${reason(restoreError)}); re-read both items and run devsteps doctor before retrying`;
+        }
+        const code = error?.code;
+        throw Object.assign(new Error(`Link write failed (${reason(error)}); ${recovery}`, { cause: error }), code === undefined ? {} : { code });
+    }
+}
+//# sourceMappingURL=link-write.js.map

package/dist/core/link-write.js.map

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

package/dist/core/link.d.ts

@@ -10,6 +10,9 @@ export interface LinkItemArgs {
     sourceId: string;
     relationType: RelationType;
     targetId: string;
+    skipValidation?: boolean;
+    /** Replace only relates-to on this pair when adding implements/implemented-by. */
+    replace?: boolean;
 }
 export interface LinkItemResult {
     success: boolean;
@@ -17,12 +20,19 @@ export interface LinkItemResult {
     error?: string;
     suggestion?: string;
     validation_failed?: boolean;
+    validation_kind?: 'methodology' | 'conflict';
+    next?: {
+        unlink: string;
+        retry: string;
+    };
     sourceId?: string;
     targetId?: string;
     relation?: RelationType;
     source_type?: string;
     target_type?: string;
     methodology?: string;
+    /** Reminders that never block the link: the epic's decision count (EPIC-059). */
+    warnings?: string[];
 }
 /**
  * Create a bi-directional relationship between two items.

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

@@ -1 +1 @@
-{"version":3,"file":"link.d.ts","sourceRoot":"","sources":["../../src/core/link.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAUxD,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,YAAY,CAAC;IAC3B,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAiBD;;;;GAIG;AACH,wBAAsB,QAAQ,CAC5B,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,YAAY,GACjB,OAAO,CAAC,cAAc,CAAC,CA2FzB"}
+{"version":3,"file":"link.d.ts","sourceRoot":"","sources":["../../src/core/link.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAYxD,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,YAAY,CAAC;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,kFAAkF;IAClF,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,eAAe,CAAC,EAAE,aAAa,GAAG,UAAU,CAAC;IAC7C,IAAI,CAAC,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IACzC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iFAAiF;IACjF,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AAED;;;;GAIG;AACH,wBAAsB,QAAQ,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,cAAc,CAAC,CAsB/F"}

package/dist/core/link.js

@@ -5,92 +5,79 @@
  * Core link creation — extracted from MCP link handler
  * Implements TASK-216 (createLink in shared) and TASK-219 (link.ts refactor)
  */
-import { existsSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
-import { getCurrentTimestamp, parseItemId, TYPE_TO_DIRECTORY, } from '../utils/index.js';
+import { existsSync } from 'node:fs';
+import { parseItemId } from '../utils/index.js';
 import { getConfig } from './config.js';
+import { decisionLinkReminders } from './decision-count.js';
 import { getItem } from './get.js';
-import { validateRelationConflict, validateRelationship } from './validation.js';
-/** Bi-directional inverse relation map. */
-const INVERSE_RELATIONS = {
-    implements: 'implemented-by',
-    'implemented-by': 'implements',
-    'tested-by': 'tests',
-    tests: 'tested-by',
-    blocks: 'blocked-by',
-    'blocked-by': 'blocks',
-    'depends-on': 'required-by',
-    'required-by': 'depends-on',
-    'relates-to': 'relates-to',
-    supersedes: 'superseded-by',
-    'superseded-by': 'supersedes',
-};
+import { itemPaths } from './item-paths.js';
+import { prepareLinkEndpoints } from './link-conflicts.js';
+import { writeLinkEndpoints } from './link-write.js';
+import { withRelationshipLock } from './relationship-lock.js';
+import { INVERSE_RELATIONS } from './relationship-map.js';
+import { validateRelationship } from './validation.js';
 /**
  * Create a bi-directional relationship between two items.
  * Validates methodology rules and conflict constraints before writing.
  * Idempotent: adding an already-existing link returns success without re-writing.
  */
 export async function linkItem(devstepsDir, args) {
-    const { sourceId, relationType, targetId } = args;
+    const { sourceId, targetId } = args;
     const sourceParsed = parseItemId(sourceId);
     const targetParsed = parseItemId(targetId);
     if (!sourceParsed)
         throw new Error(`Invalid source item ID: ${sourceId}`);
     if (!targetParsed)
         throw new Error(`Invalid target item ID: ${targetId}`);
-    const sourceFolder = TYPE_TO_DIRECTORY[sourceParsed.type];
-    const targetFolder = TYPE_TO_DIRECTORY[targetParsed.type];
-    const sourcePath = join(devstepsDir, sourceFolder, `${sourceId}.json`);
-    const targetPath = join(devstepsDir, targetFolder, `${targetId}.json`);
-    if (!existsSync(sourcePath))
+    if (!existsSync(itemPaths(devstepsDir, sourceId).metadata)) {
         throw new Error(`Source item not found: ${sourceId}`);
-    if (!existsSync(targetPath))
+    }
+    if (!existsSync(itemPaths(devstepsDir, targetId).metadata)) {
         throw new Error(`Target item not found: ${targetId}`);
-    const { metadata: sourceMeta } = await getItem(devstepsDir, sourceId);
-    const { metadata: targetMeta } = await getItem(devstepsDir, targetId);
+    }
+    const result = await withRelationshipLock([sourceId, targetId], () => writeLink(devstepsDir, args));
+    if (!result.success)
+        return result;
+    const warnings = decisionLinkReminders(devstepsDir, sourceId, targetId);
+    return warnings.length > 0 ? { ...result, warnings } : result;
+}
+/** Validate and write both directions of one link; runs under the relationship lock. */
+async function writeLink(devstepsDir, args) {
+    const { sourceId, relationType, targetId } = args;
+    // The stamps guard both writes against a concurrent writer (STORY-428)
+    const source = await getItem(devstepsDir, sourceId);
+    const target = await getItem(devstepsDir, targetId);
+    const sourceMeta = structuredClone(source.metadata);
+    const targetMeta = structuredClone(target.metadata);
     const config = await getConfig(devstepsDir);
     const methodology = (config.settings?.methodology ?? 'hybrid');
     // Validate methodology hierarchy rules
-    const validation = validateRelationship({ id: sourceMeta.id, type: sourceMeta.type }, { id: targetMeta.id, type: targetMeta.type }, relationType, methodology);
-    if (!validation.valid) {
-        return {
-            success: false,
-            error: validation.error,
-            suggestion: validation.suggestion,
-            validation_failed: true,
-            source_type: sourceMeta.type,
-            target_type: targetMeta.type,
-            relation: relationType,
-            methodology,
-        };
-    }
-    // Validate no conflicting relations to the same target
-    const conflictCheck = validateRelationConflict(targetId, relationType, sourceMeta.linked_items);
-    if (!conflictCheck.valid) {
-        return {
-            success: false,
-            error: conflictCheck.error,
-            suggestion: conflictCheck.suggestion,
-            validation_failed: true,
-        };
-    }
-    // Write forward relation (idempotent)
-    const forwardArray = sourceMeta.linked_items[relationType];
-    if (!forwardArray.includes(targetId)) {
-        forwardArray.push(targetId);
-        sourceMeta.updated = getCurrentTimestamp();
-        writeFileSync(sourcePath, JSON.stringify(sourceMeta, null, 2));
-    }
-    // Write inverse relation (idempotent)
-    const inverseRelation = INVERSE_RELATIONS[relationType];
-    if (inverseRelation) {
-        const inverseArray = targetMeta.linked_items[inverseRelation];
-        if (!inverseArray.includes(sourceId)) {
-            inverseArray.push(sourceId);
-            targetMeta.updated = getCurrentTimestamp();
-            writeFileSync(targetPath, JSON.stringify(targetMeta, null, 2));
+    if (!args.skipValidation) {
+        const forward = validateRelationship(sourceMeta, targetMeta, relationType, methodology);
+        const validation = forward.valid
+            ? validateRelationship(targetMeta, sourceMeta, INVERSE_RELATIONS[relationType], methodology)
+            : forward;
+        if (!validation.valid) {
+            return {
+                success: false,
+                error: validation.error,
+                suggestion: validation.suggestion,
+                validation_failed: true,
+                validation_kind: 'methodology',
+                source_type: sourceMeta.type,
+                target_type: targetMeta.type,
+                relation: relationType,
+                methodology,
+            };
         }
     }
+    const conflict = prepareLinkEndpoints(args, sourceMeta, targetMeta);
+    if (conflict)
+        return conflict;
+    writeLinkEndpoints(devstepsDir, [
+        { original: source, planned: sourceMeta },
+        { original: target, planned: targetMeta },
+    ]);
     return {
         success: true,
         message: `Linked ${sourceId} --${relationType}--> ${targetId}`,

package/dist/core/link.js.map

@@ -1 +1 @@
-{"version":3,"file":"link.js","sourceRoot":"","sources":["../../src/core/link.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"link.js","sourceRoot":"","sources":["../../src/core/link.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAErC,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AACnC,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AA6BvD;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,WAAmB,EAAE,IAAkB;IACpE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,GAAG,IAAI,CAAC;IAEpC,MAAM,YAAY,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC;IAC3C,MAAM,YAAY,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC;IAE3C,IAAI,CAAC,YAAY;QAAE,MAAM,IAAI,KAAK,CAAC,2BAA2B,QAAQ,EAAE,CAAC,CAAC;IAC1E,IAAI,CAAC,YAAY;QAAE,MAAM,IAAI,KAAK,CAAC,2BAA2B,QAAQ,EAAE,CAAC,CAAC;IAE1E,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC3D,MAAM,IAAI,KAAK,CAAC,0BAA0B,QAAQ,EAAE,CAAC,CAAC;IACxD,CAAC;IACD,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC3D,MAAM,IAAI,KAAK,CAAC,0BAA0B,QAAQ,EAAE,CAAC,CAAC;IACxD,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,oBAAoB,CAAC,CAAC,QAAQ,EAAE,QAAQ,CAAC,EAAE,GAAG,EAAE,CACnE,SAAS,CAAC,WAAW,EAAE,IAAI,CAAC,CAC7B,CAAC;IACF,IAAI,CAAC,MAAM,CAAC,OAAO;QAAE,OAAO,MAAM,CAAC;IACnC,MAAM,QAAQ,GAAG,qBAAqB,CAAC,WAAW,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC;IACxE,OAAO,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC;AAChE,CAAC;AAED,wFAAwF;AACxF,KAAK,UAAU,SAAS,CAAC,WAAmB,EAAE,IAAkB;IAC9D,MAAM,EAAE,QAAQ,EAAE,YAAY,EAAE,QAAQ,EAAE,GAAG,IAAI,CAAC;IAClD,uEAAuE;IACvE,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC;IACpD,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC;IACpD,MAAM,UAAU,GAAG,eAAe,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IACpD,MAAM,UAAU,GAAG,eAAe,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAEpD,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,WAAW,CAAC,CAAC;IAC5C,MAAM,WAAW,GAAG,CAAC,MAAM,CAAC,QAAQ,EAAE,WAAW,IAAI,QAAQ,CAGjD,CAAC;IAEb,uCAAuC;IACvC,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE,CAAC;QACzB,MAAM,OAAO,GAAG,oBAAoB,CAAC,UAAU,EAAE,UAAU,EAAE,YAAY,EAAE,WAAW,CAAC,CAAC;QACxF,MAAM,UAAU,GAAG,OAAO,CAAC,KAAK;YAC9B,CAAC,CAAC,oBAAoB,CAAC,UAAU,EAAE,UAAU,EAAE,iBAAiB,CAAC,YAAY,CAAC,EAAE,WAAW,CAAC;YAC5F,CAAC,CAAC,OAAO,CAAC;QACZ,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;YACtB,OAAO;gBACL,OAAO,EAAE,KAAK;gBACd,KAAK,EAAE,UAAU,CAAC,KAAK;gBACvB,UAAU,EAAE,UAAU,CAAC,UAAU;gBACjC,iBAAiB,EAAE,IAAI;gBACvB,eAAe,EAAE,aAAa;gBAC9B,WAAW,EAAE,UAAU,CAAC,IAAI;gBAC5B,WAAW,EAAE,UAAU,CAAC,IAAI;gBAC5B,QAAQ,EAAE,YAAY;gBACtB,WAAW;aACZ,CAAC;QACJ,CAAC;IACH,CAAC;IAED,MAAM,QAAQ,GAAG,oBAAoB,CAAC,IAAI,EAAE,UAAU,EAAE,UAAU,CAAC,CAAC;IACpE,IAAI,QAAQ;QAAE,OAAO,QAAQ,CAAC;IAC9B,kBAAkB,CAAC,WAAW,EAAE;QAC9B,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE;QACzC,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE;KAC1C,CAAC,CAAC;IAEH,OAAO;QACL,OAAO,EAAE,IAAI;QACb,OAAO,EAAE,UAAU,QAAQ,MAAM,YAAY,OAAO,QAAQ,EAAE;QAC9D,QAAQ;QACR,QAAQ;QACR,QAAQ,EAAE,YAAY;KACvB,CAAC;AACJ,CAAC"}

package/dist/core/list-page.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Paged item listing with an honest envelope.
+ *
+ * `listItems()` returns everything that matches, which is what the board, the
+ * export, and the CLI need. A client that carries the answer in its context
+ * needs a slice instead, and it needs to know that it received one: without a
+ * total it cannot tell 25 items from the first 25 of 1500, and asks again
+ * without a limit.
+ *
+ * @see EPIC-055 STORY-388 TASK-788
+ */
+import { type ListItemEntry, type ListItemsArgs } from './list.js';
+/** Items returned when the caller names no limit. */
+export declare const LIST_DEFAULT_LIMIT = 25;
+/** Statuses left out when the caller names no status. */
+export declare const CLOSED_STATUSES: ["done", "obsolete", "cancelled"];
+type ClosedStatus = (typeof CLOSED_STATUSES)[number];
+export type ListOmitted = Partial<Record<ClosedStatus | 'beyond_limit', number>>;
+export interface ListPage {
+    /** Items matching the filters, before the closed-status default and the limit. */
+    total: number;
+    returned: number;
+    /** Why the difference between `total` and `returned` exists; absent when none. */
+    omitted?: ListOmitted;
+    /** How to reach what was omitted; absent when nothing was. */
+    more?: string;
+    items: ListItemEntry[];
+    unreadable: string[];
+}
+/**
+ * List one page of items.
+ *
+ * Without `status`, closed items are left out (archived listings excepted, since
+ * they are closed by definition). Without `limit`, at most
+ * {@link LIST_DEFAULT_LIMIT} items are returned. Both omissions are counted.
+ */
+export declare function listItemsPage(devstepsDir: string, args: ListItemsArgs): Promise<ListPage>;
+export {};
+//# sourceMappingURL=list-page.d.ts.map

package/dist/core/list-page.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"list-page.d.ts","sourceRoot":"","sources":["../../src/core/list-page.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,EAAE,KAAK,aAAa,EAAE,KAAK,aAAa,EAAa,MAAM,WAAW,CAAC;AAE9E,qDAAqD;AACrD,eAAO,MAAM,kBAAkB,KAAK,CAAC;AAErC,yDAAyD;AACzD,eAAO,MAAM,eAAe,mCAAoE,CAAC;AAEjG,KAAK,YAAY,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AAErD,MAAM,MAAM,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,YAAY,GAAG,cAAc,EAAE,MAAM,CAAC,CAAC,CAAC;AAEjF,MAAM,WAAW,QAAQ;IACvB,kFAAkF;IAClF,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,kFAAkF;IAClF,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,8DAA8D;IAC9D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,aAAa,EAAE,CAAC;IACvB,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAkBD;;;;;;GAMG;AACH,wBAAsB,aAAa,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,QAAQ,CAAC,CA8B/F"}