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

package/dist/core/trace.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Shared relationship traversal for graph and traceability consumers.
+ */
+import { ItemMetadata, type RelationType } from '../schemas/index.js';
+export type TraceDirection = 'forward' | 'backward' | 'both';
+export interface TraceOptions {
+    maxDepth?: number;
+    maxNodes?: number;
+    relationTypes?: RelationType[];
+    direction?: TraceDirection;
+}
+export interface TraceNode {
+    id: string;
+    type: ItemMetadata['type'];
+    title: string;
+    status: ItemMetadata['status'];
+    priority: ItemMetadata['eisenhower'];
+    depth: number;
+    /** The item sits in `.devsteps/archive/`; trace shows it but does not expand it. */
+    archived?: true;
+}
+export interface TraceEdge {
+    source: string;
+    target: string;
+    relation: RelationType;
+}
+export interface TraceDiagnostic {
+    kind: 'missing-item' | 'cycle' | 'duplicate-edge' | 'truncated';
+    item_id: string;
+    target_id?: string;
+    relation?: RelationType;
+    message: string;
+}
+export interface TraceResult {
+    root_id: string;
+    max_depth: number;
+    nodes: TraceNode[];
+    edges: TraceEdge[];
+    diagnostics: TraceDiagnostic[];
+    acquisition: {
+        attempted: number;
+        loaded: number;
+        omitted_frontier: number;
+    };
+}
+/** Traverse relationship metadata without mutating the DevSteps store. */
+export declare function traceRelationships(devstepsDir: string, itemId: string, options?: TraceOptions): Promise<TraceResult>;
+//# sourceMappingURL=trace.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"trace.d.ts","sourceRoot":"","sources":["../../src/core/trace.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,YAAY,EAAE,KAAK,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAKtE,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,UAAU,GAAG,MAAM,CAAC;AAE7D,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,YAAY,EAAE,CAAC;IAC/B,SAAS,CAAC,EAAE,cAAc,CAAC;CAC5B;AAED,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,YAAY,CAAC,MAAM,CAAC,CAAC;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,YAAY,CAAC,QAAQ,CAAC,CAAC;IAC/B,QAAQ,EAAE,YAAY,CAAC,YAAY,CAAC,CAAC;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,oFAAoF;IACpF,QAAQ,CAAC,EAAE,IAAI,CAAC;CACjB;AAED,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,YAAY,CAAC;CACxB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,cAAc,GAAG,OAAO,GAAG,gBAAgB,GAAG,WAAW,CAAC;IAChE,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,WAAW,EAAE,eAAe,EAAE,CAAC;IAC/B,WAAW,EAAE;QACX,SAAS,EAAE,MAAM,CAAC;QAClB,MAAM,EAAE,MAAM,CAAC;QACf,gBAAgB,EAAE,MAAM,CAAC;KAC1B,CAAC;CACH;AAwDD,0EAA0E;AAC1E,wBAAsB,kBAAkB,CACtC,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC,WAAW,CAAC,CAgJtB"}

package/dist/core/trace.js

@@ -0,0 +1,193 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Shared relationship traversal for graph and traceability consumers.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { ItemMetadata } from '../schemas/index.js';
+import { getItem } from './get.js';
+import { archivedItemPaths } from './item-paths.js';
+import { INVERSE_RELATIONS } from './relationship-map.js';
+const DEFAULT_MAX_DEPTH = 3;
+const MAX_ALLOWED_DEPTH = 100;
+const DEFAULT_MAX_NODES = 1000;
+const MAX_ALLOWED_NODES = 10000;
+function normalizeOptions(options) {
+    const maxDepth = options.maxDepth ?? DEFAULT_MAX_DEPTH;
+    if (!Number.isInteger(maxDepth) || maxDepth < 0 || maxDepth > MAX_ALLOWED_DEPTH) {
+        throw new RangeError(`Trace depth must be an integer between 0 and ${MAX_ALLOWED_DEPTH}`);
+    }
+    const maxNodes = options.maxNodes ?? DEFAULT_MAX_NODES;
+    if (!Number.isInteger(maxNodes) || maxNodes < 1 || maxNodes > MAX_ALLOWED_NODES) {
+        throw new RangeError(`Trace node limit must be an integer between 1 and ${MAX_ALLOWED_NODES}`);
+    }
+    return {
+        maxDepth,
+        maxNodes,
+        relationTypes: options.relationTypes ?? [],
+        direction: options.direction ?? 'forward',
+    };
+}
+function relationAllowed(relation, relationTypes) {
+    return relationTypes.length === 0 || relationTypes.includes(relation);
+}
+function orientedRelations(relationTypes, direction) {
+    if (relationTypes.length === 0)
+        return [];
+    if (direction === 'forward')
+        return relationTypes;
+    if (direction === 'backward')
+        return relationTypes.map((relation) => INVERSE_RELATIONS[relation]);
+    return [
+        ...new Set([...relationTypes, ...relationTypes.map((relation) => INVERSE_RELATIONS[relation])]),
+    ];
+}
+/** An archived item is history, not a missing one (BUG-181): read it from the archive. */
+function readArchivedMetadata(devstepsDir, id) {
+    try {
+        const path = archivedItemPaths(devstepsDir, id).metadata;
+        if (!existsSync(path))
+            return undefined;
+        const parsed = ItemMetadata.safeParse(JSON.parse(readFileSync(path, 'utf8')));
+        return parsed.success ? parsed.data : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Traverse relationship metadata without mutating the DevSteps store. */
+export async function traceRelationships(devstepsDir, itemId, options = {}) {
+    const normalized = normalizeOptions(options);
+    const metadataById = new Map();
+    const nodes = new Map();
+    const edges = new Map();
+    const diagnostics = [];
+    const visitedAtDepth = new Map();
+    const queued = new Set([itemId]);
+    const attempted = new Set();
+    const archivedIds = new Set();
+    const queue = [{ id: itemId, depth: 0 }];
+    let omittedFrontier = 0;
+    while (queue.length > 0) {
+        const current = queue.shift();
+        if (!current)
+            continue;
+        queued.delete(current.id);
+        if (attempted.size >= normalized.maxNodes && !attempted.has(current.id)) {
+            omittedFrontier += 1;
+            continue;
+        }
+        attempted.add(current.id);
+        let metadata = metadataById.get(current.id);
+        try {
+            metadata ??= (await getItem(devstepsDir, current.id)).metadata;
+            metadataById.set(current.id, metadata);
+        }
+        catch (error) {
+            if (current.id === itemId)
+                throw error;
+            metadata = readArchivedMetadata(devstepsDir, current.id);
+            if (!metadata) {
+                diagnostics.push({
+                    kind: 'missing-item',
+                    item_id: itemId,
+                    target_id: current.id,
+                    message: `Referenced item ${current.id} could not be loaded`,
+                });
+                continue;
+            }
+            metadataById.set(current.id, metadata);
+            archivedIds.add(current.id);
+        }
+        const archived = archivedIds.has(current.id);
+        const previousDepth = visitedAtDepth.get(current.id);
+        if (previousDepth !== undefined) {
+            if (current.depth >= previousDepth)
+                continue;
+        }
+        visitedAtDepth.set(current.id, current.depth);
+        nodes.set(metadata.id, {
+            id: metadata.id,
+            type: metadata.type,
+            title: metadata.title,
+            status: metadata.status,
+            priority: metadata.eisenhower,
+            depth: current.depth,
+            ...(archived ? { archived: true } : {}),
+        });
+        if (archived || current.depth >= normalized.maxDepth)
+            continue;
+        const outgoing = [];
+        const allowed = orientedRelations(normalized.relationTypes, normalized.direction);
+        for (const [relation, targets] of Object.entries(metadata.linked_items)) {
+            if (!relationAllowed(relation, allowed))
+                continue;
+            const typedRelation = relation;
+            for (const target of targets) {
+                const backward = normalized.direction === 'backward' ||
+                    (normalized.direction === 'both' &&
+                        normalized.relationTypes.length > 0 &&
+                        !normalized.relationTypes.includes(typedRelation) &&
+                        normalized.relationTypes.includes(INVERSE_RELATIONS[typedRelation]));
+                outgoing.push({
+                    source: metadata.id,
+                    target,
+                    relation: backward ? INVERSE_RELATIONS[typedRelation] : typedRelation,
+                });
+            }
+        }
+        outgoing.sort((left, right) => `${left.relation}:${left.target}:${left.source}`.localeCompare(`${right.relation}:${right.target}:${right.source}`));
+        for (const edge of outgoing) {
+            const edgeKey = `${edge.source}|${edge.relation}|${edge.target}`;
+            if (edges.has(edgeKey)) {
+                diagnostics.push({
+                    kind: 'duplicate-edge',
+                    item_id: edge.source,
+                    target_id: edge.target,
+                    relation: edge.relation,
+                    message: `Duplicate relationship ${edge.source} --${edge.relation}--> ${edge.target}`,
+                });
+                continue;
+            }
+            edges.set(edgeKey, edge);
+            const nextId = edge.target;
+            if (visitedAtDepth.has(nextId)) {
+                diagnostics.push({
+                    kind: 'cycle',
+                    item_id: edge.source,
+                    target_id: nextId,
+                    relation: edge.relation,
+                    message: `Cycle encountered at ${edge.target}`,
+                });
+                continue;
+            }
+            if (!queued.has(nextId)) {
+                queue.push({ id: nextId, depth: current.depth + 1 });
+                queued.add(nextId);
+            }
+        }
+    }
+    if (omittedFrontier > 0) {
+        diagnostics.push({
+            kind: 'truncated',
+            item_id: itemId,
+            message: `Trace node limit of ${normalized.maxNodes} reached; ${omittedFrontier} frontier item(s) omitted`,
+        });
+    }
+    return {
+        root_id: itemId,
+        max_depth: normalized.maxDepth,
+        nodes: [...nodes.values()].sort((left, right) => left.id.localeCompare(right.id, 'en', { numeric: true })),
+        edges: [...edges.values()]
+            .filter((edge) => nodes.has(edge.source) && nodes.has(edge.target))
+            .sort((left, right) => `${left.source}|${left.relation}|${left.target}`.localeCompare(`${right.source}|${right.relation}|${right.target}`)),
+        diagnostics,
+        acquisition: {
+            attempted: attempted.size,
+            loaded: metadataById.size,
+            omitted_frontier: omittedFrontier,
+        },
+    };
+}
+//# sourceMappingURL=trace.js.map

package/dist/core/trace.js.map

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

package/dist/core/traceability-narrative.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Read-only intent-to-delivery traceability projection.
+ */
+import { type RunEvidenceDiagnostic } from '../runtime/run-store.js';
+import type { ItemMetadata } from '../schemas/index.js';
+import { type TraceDiagnostic, type TraceResult } from './trace.js';
+export interface NarrativeItem {
+    id: string;
+    type: ItemMetadata['type'];
+    title: string;
+    status: ItemMetadata['status'];
+    affected_paths: string[];
+    commits: string[];
+}
+export interface NarrativeEvidence {
+    run_id: string;
+    definition_id: string;
+    state: string;
+    terminal: boolean;
+    updated_at: string;
+    events: Array<{
+        sequence: number;
+        type: string;
+        actor: 'agent' | 'human' | 'system';
+        occurred_at: string;
+        result?: string;
+        evidence_id?: string;
+    }>;
+}
+export interface NarrativeDiagnostic {
+    kind: TraceDiagnostic['kind'] | RunEvidenceDiagnostic['kind'] | 'relationship-pending' | 'relationship-invalid' | 'missing-verification' | 'failed-evidence' | 'nonterminal-evidence' | 'stale-evidence';
+    message: string;
+    item_id?: string;
+}
+export interface TraceabilityNarrative {
+    root_id: string;
+    graph: TraceResult;
+    stages: {
+        intent: NarrativeItem[];
+        planning: NarrativeItem[];
+        implementation: NarrativeItem[];
+        verification: NarrativeItem[];
+    };
+    relationship_outcomes: Array<{
+        item_id: string;
+        outcome: 'complete' | 'pending' | 'invalid' | 'not-applicable';
+    }>;
+    delivery: {
+        commits: Array<{
+            item_id: string;
+            sha: string;
+        }>;
+        successful_runs: NarrativeEvidence[];
+    };
+    evidence: NarrativeEvidence[];
+    diagnostics: NarrativeDiagnostic[];
+}
+export interface TraceabilityNarrativeOptions {
+    maxDepth?: number;
+    maxEvidenceRuns?: number;
+}
+/** Build the bounded narrative model from authoritative local DevSteps data. */
+export declare function buildTraceabilityNarrative(devstepsDir: string, rootId: string, options?: TraceabilityNarrativeOptions): Promise<TraceabilityNarrative>;
+//# sourceMappingURL=traceability-narrative.d.ts.map

package/dist/core/traceability-narrative.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"traceability-narrative.d.ts","sourceRoot":"","sources":["../../src/core/traceability-narrative.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EACL,KAAK,qBAAqB,EAG3B,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,YAAY,EAAe,MAAM,qBAAqB,CAAC;AAIrE,OAAO,EAAE,KAAK,eAAe,EAAE,KAAK,WAAW,EAAsB,MAAM,YAAY,CAAC;AAExF,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,YAAY,CAAC,MAAM,CAAC,CAAC;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,YAAY,CAAC,QAAQ,CAAC,CAAC;IAC/B,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,OAAO,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,KAAK,CAAC;QACZ,QAAQ,EAAE,MAAM,CAAC;QACjB,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,EAAE,OAAO,GAAG,OAAO,GAAG,QAAQ,CAAC;QACpC,WAAW,EAAE,MAAM,CAAC;QACpB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,CAAC,CAAC;CACJ;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EACA,eAAe,CAAC,MAAM,CAAC,GACvB,qBAAqB,CAAC,MAAM,CAAC,GAC7B,sBAAsB,GACtB,sBAAsB,GACtB,sBAAsB,GACtB,iBAAiB,GACjB,sBAAsB,GACtB,gBAAgB,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,WAAW,CAAC;IACnB,MAAM,EAAE;QACN,MAAM,EAAE,aAAa,EAAE,CAAC;QACxB,QAAQ,EAAE,aAAa,EAAE,CAAC;QAC1B,cAAc,EAAE,aAAa,EAAE,CAAC;QAChC,YAAY,EAAE,aAAa,EAAE,CAAC;KAC/B,CAAC;IACF,qBAAqB,EAAE,KAAK,CAAC;QAC3B,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,EAAE,UAAU,GAAG,SAAS,GAAG,SAAS,GAAG,gBAAgB,CAAC;KAChE,CAAC,CAAC;IACH,QAAQ,EAAE;QACR,OAAO,EAAE,KAAK,CAAC;YAAE,OAAO,EAAE,MAAM,CAAC;YAAC,GAAG,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QACjD,eAAe,EAAE,iBAAiB,EAAE,CAAC;KACtC,CAAC;IACF,QAAQ,EAAE,iBAAiB,EAAE,CAAC;IAC9B,WAAW,EAAE,mBAAmB,EAAE,CAAC;CACpC;AAED,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AA4CD,gFAAgF;AAChF,wBAAsB,0BAA0B,CAC9C,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,4BAAiC,GACzC,OAAO,CAAC,qBAAqB,CAAC,CAiHhC"}

package/dist/core/traceability-narrative.js

@@ -0,0 +1,149 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Read-only intent-to-delivery traceability projection.
+ */
+import { join } from 'node:path';
+import { readRunsByDefinition, } from '../runtime/run-store.js';
+import { getConfig } from './config.js';
+import { getItem } from './get.js';
+import { evaluateRelationshipCompleteness } from './relationship-completeness.js';
+import { traceRelationships } from './trace.js';
+function itemFromMetadata(metadata) {
+    return {
+        id: metadata.id,
+        type: metadata.type,
+        title: metadata.title,
+        status: metadata.status,
+        affected_paths: metadata.affected_paths,
+        commits: metadata.commits,
+    };
+}
+function stageFor(item, rootId) {
+    if (item.type === 'requirement' || item.type === 'epic' || item.type === 'feature')
+        return 'intent';
+    if (item.type === 'test')
+        return 'verification';
+    if (item.type === 'task' || item.type === 'bug')
+        return 'implementation';
+    if (item.id === rootId)
+        return 'planning';
+    return 'planning';
+}
+function summarizeRun(record) {
+    const bounded = (value) => typeof value === 'string' ? value.slice(0, 500) : undefined;
+    return {
+        run_id: record.run.run_id,
+        definition_id: record.run.definition_id,
+        state: record.run.state,
+        terminal: record.run.terminal,
+        updated_at: record.run.updated_at,
+        events: record.events.map((event) => ({
+            sequence: event.sequence,
+            type: event.type,
+            actor: event.actor,
+            occurred_at: event.occurred_at,
+            ...(bounded(event.payload.result) ? { result: bounded(event.payload.result) } : {}),
+            ...(bounded(event.payload.evidence_id)
+                ? { evidence_id: bounded(event.payload.evidence_id) }
+                : {}),
+        })),
+    };
+}
+/** Build the bounded narrative model from authoritative local DevSteps data. */
+export async function buildTraceabilityNarrative(devstepsDir, rootId, options = {}) {
+    const config = await getConfig(devstepsDir);
+    const graph = await traceRelationships(devstepsDir, rootId, {
+        maxDepth: options.maxDepth,
+        direction: 'both',
+    });
+    const metadata = new Map();
+    for (const node of graph.nodes) {
+        const item = await getItem(devstepsDir, node.id);
+        metadata.set(node.id, item.metadata);
+    }
+    const stages = {
+        intent: [],
+        planning: [],
+        implementation: [],
+        verification: [],
+    };
+    for (const item of metadata.values()) {
+        const projected = itemFromMetadata(item);
+        stages[stageFor(projected, rootId)].push(projected);
+    }
+    for (const stage of Object.values(stages))
+        stage.sort((left, right) => left.id.localeCompare(right.id, 'en', { numeric: true }));
+    const parentTypes = Object.fromEntries([...metadata].map(([id, item]) => [id, item.type]));
+    const diagnostics = graph.diagnostics.map((diagnostic) => ({
+        kind: diagnostic.kind,
+        message: diagnostic.message,
+        item_id: diagnostic.item_id,
+    }));
+    const relationshipOutcomes = [];
+    for (const item of metadata.values()) {
+        const completeness = evaluateRelationshipCompleteness(item, (config.settings?.methodology ?? 'hybrid'), parentTypes);
+        relationshipOutcomes.push({ item_id: item.id, outcome: completeness.outcome });
+        if (completeness.pending || completeness.invalid) {
+            diagnostics.push({
+                kind: completeness.pending ? 'relationship-pending' : 'relationship-invalid',
+                message: completeness.message ?? 'Incomplete parent relationship',
+                item_id: item.id,
+            });
+        }
+    }
+    if (stages.verification.length === 0) {
+        diagnostics.push({
+            kind: 'missing-verification',
+            message: 'No linked verification item is available',
+            item_id: rootId,
+        });
+    }
+    const definitionIds = new Set(metadata.keys());
+    const runResult = await readRunsByDefinition(join(devstepsDir, 'runs'), definitionIds, options.maxEvidenceRuns);
+    diagnostics.push(...runResult.diagnostics.map((diagnostic) => ({
+        kind: diagnostic.kind,
+        message: diagnostic.message,
+        item_id: diagnostic.definition_id,
+    })));
+    for (const record of runResult.runs) {
+        if (record.run.state === 'failed')
+            diagnostics.push({
+                kind: 'failed-evidence',
+                message: `Run ${record.run.run_id} failed`,
+                item_id: record.run.definition_id,
+            });
+        if (!record.run.terminal)
+            diagnostics.push({
+                kind: 'nonterminal-evidence',
+                message: `Run ${record.run.run_id} is not terminal`,
+                item_id: record.run.definition_id,
+            });
+        if (record.run.state === 'stale')
+            diagnostics.push({
+                kind: 'stale-evidence',
+                message: `Run ${record.run.run_id} is stale`,
+                item_id: record.run.definition_id,
+            });
+    }
+    const evidence = runResult.runs.map(summarizeRun);
+    const commits = [...metadata.values()]
+        .flatMap((item) => item.commits
+        .filter((sha) => /^[0-9a-f]{40}$/i.test(sha))
+        .map((sha) => ({ item_id: item.id, sha })))
+        .sort((left, right) => `${left.item_id}:${left.sha}`.localeCompare(`${right.item_id}:${right.sha}`));
+    return {
+        root_id: rootId,
+        graph,
+        stages,
+        relationship_outcomes: relationshipOutcomes.sort((left, right) => left.item_id.localeCompare(right.item_id, 'en', { numeric: true })),
+        delivery: {
+            commits,
+            successful_runs: evidence.filter((run) => run.terminal && run.state === 'succeeded'),
+        },
+        evidence,
+        diagnostics,
+    };
+}
+//# sourceMappingURL=traceability-narrative.js.map

package/dist/core/traceability-narrative.js.map

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

package/dist/core/unlink.d.ts

@@ -17,10 +17,14 @@ export interface UnlinkItemResult {
     sourceId: string;
     targetId: string;
     relation: RelationType;
+    /** The target no longer exists: only the source's dangling entry was removed (BUG-145). */
+    target_missing?: true;
 }
 /**
  * Remove a relationship between two items bi-directionally.
  * Idempotent: calling when the relation already does not exist returns success.
+ * A target that no longer exists has no inverse to remove, so only the source's dangling entry
+ * goes, which is the repair `doctor` advises for a broken reference (BUG-145).
  */
 export declare function unlinkItem(devstepsDir: string, args: UnlinkItemArgs): Promise<UnlinkItemResult>;
 //# sourceMappingURL=unlink.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"unlink.d.ts","sourceRoot":"","sources":["../../src/core/unlink.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EAAe,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAIrE,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,YAAY,CAAC;IAC3B,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,YAAY,CAAC;CACxB;AAiBD;;;GAGG;AACH,wBAAsB,UAAU,CAC9B,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,cAAc,GACnB,OAAO,CAAC,gBAAgB,CAAC,CAsD3B"}
+{"version":3,"file":"unlink.d.ts","sourceRoot":"","sources":["../../src/core/unlink.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAe,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAOrE,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,YAAY,CAAC;IAC3B,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,YAAY,CAAC;IACvB,2FAA2F;IAC3F,cAAc,CAAC,EAAE,IAAI,CAAC;CACvB;AAED;;;;;GAKG;AACH,wBAAsB,UAAU,CAC9B,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,cAAc,GACnB,OAAO,CAAC,gBAAgB,CAAC,CAsE3B"}