kibi-cli 0.10.0 → 0.10.1

package/dist/traceability/staged-impact-contract.d.ts

@@ -0,0 +1,57 @@
+export declare const KIBI_IMPACT_DIAGNOSTIC_IDS: readonly ["kibi_impact_evidence_missing", "symbols_manifest_stale", "kibi_impact_override_missing_rationale"];
+export type KibiImpactDiagnosticId = (typeof KIBI_IMPACT_DIAGNOSTIC_IDS)[number];
+export type KibiImpactEvidenceKind = "entity_markdown" | "symbols_manifest" | "audited_no_impact";
+export interface KibiImpactDiagnosticContract {
+    id: KibiImpactDiagnosticId;
+    title: string;
+    resolution: [string, string, string];
+}
+export interface KibiImpactEvidenceInput {
+    filePath?: string;
+    extractionOutputChanged?: boolean;
+    overrideDeclared?: boolean;
+    overrideRationale?: string | null;
+    symbolsManifestPath?: string;
+}
+export interface BehaviorSourceEditInput {
+    path: string;
+    diffText: string;
+    intersectsBehaviorBearingSymbol: boolean;
+    knownUserFacingSurface?: boolean;
+}
+export interface ParsedKibiImpactOverride {
+    declared: boolean;
+    rationale: string | null;
+}
+export interface AuditedNoImpactOverrideInput {
+    behaviorSourceEdit: boolean;
+    override: ParsedKibiImpactOverride;
+}
+/**
+ * Staged Kibi impact contract for `kibi check --staged`.
+ *
+ * This is intentionally a small, stable contract for tests and future staged
+ * enforcement wiring:
+ * - `behavior_source_edit` is a supported source-file edit whose staged hunks
+ *   intersect exported or other behavior-bearing/user-facing surfaces and whose
+ *   changed lines are not comment-only or formatting-only.
+ * - `kibi_impact_evidence` is staged entity markdown, staged authored
+ *   `documentation/symbols.yaml` metadata, refreshed
+ *   `documentation/symbol-coordinates.yaml` when extraction output changes, or
+ *   an explicit audited `Kibi-Impact: none` declaration with
+ *   rationale for false positives/non-behavior-only edits.
+ * - `Kibi-Impact: none` never satisfies a genuine behavior change.
+ * - Test-only edits do not require new KB evidence unless they introduce
+ *   executable test symbols that need traceability.
+ *
+ * This contract deliberately avoids broad semantic diffing and stays
+ * conservative so later staged-check enforcement can share exact diagnostic IDs
+ * and operator-facing remediation steps.
+ */
+export declare const KIBI_IMPACT_DIAGNOSTICS: Record<KibiImpactDiagnosticId, KibiImpactDiagnosticContract>;
+export declare function classifyKibiImpactEvidence(input: KibiImpactEvidenceInput): KibiImpactEvidenceKind | null;
+export declare function parseKibiImpactOverride(text: string): ParsedKibiImpactOverride;
+export declare function isAuditedNoImpactOverrideAllowed(input: AuditedNoImpactOverrideInput): boolean;
+export declare function isBehaviorSourceEdit(input: BehaviorSourceEditInput): boolean;
+export declare function isSupportedBehaviorSourcePath(filePath: string): boolean;
+//# sourceMappingURL=staged-impact-contract.d.ts.map

package/dist/traceability/staged-impact-contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"staged-impact-contract.d.ts","sourceRoot":"","sources":["../../src/traceability/staged-impact-contract.ts"],"names":[],"mappings":"AAqBA,eAAO,MAAM,0BAA0B,+GAI7B,CAAC;AAEX,MAAM,MAAM,sBAAsB,GAChC,CAAC,OAAO,0BAA0B,CAAC,CAAC,MAAM,CAAC,CAAC;AAE9C,MAAM,MAAM,sBAAsB,GAC9B,iBAAiB,GACjB,kBAAkB,GAClB,mBAAmB,CAAC;AAExB,MAAM,WAAW,4BAA4B;IAC3C,EAAE,EAAE,sBAAsB,CAAC;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;CACtC;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAClC,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,+BAA+B,EAAE,OAAO,CAAC;IACzC,sBAAsB,CAAC,EAAE,OAAO,CAAC;CAClC;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,EAAE,OAAO,CAAC;IAClB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,MAAM,WAAW,4BAA4B;IAC3C,kBAAkB,EAAE,OAAO,CAAC;IAC5B,QAAQ,EAAE,wBAAwB,CAAC;CACpC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,uBAAuB,EAAE,MAAM,CAC1C,sBAAsB,EACtB,4BAA4B,CA6B7B,CAAC;AAEF,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,uBAAuB,GAC7B,sBAAsB,GAAG,IAAI,CAsB/B;AAED,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,MAAM,GACX,wBAAwB,CAS1B;AAED,wBAAgB,gCAAgC,CAC9C,KAAK,EAAE,4BAA4B,GAClC,OAAO,CAMT;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,uBAAuB,GAAG,OAAO,CA8B5E;AAED,wBAAgB,6BAA6B,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAQvE"}

package/dist/traceability/staged-impact-contract.js

@@ -0,0 +1,202 @@
+const SUPPORTED_BEHAVIOR_SOURCE_EXTENSIONS = new Set([
+    ".ts",
+    ".tsx",
+    ".js",
+    ".jsx",
+    ".mts",
+    ".cts",
+    ".mjs",
+    ".cjs",
+]);
+const ENTITY_EVIDENCE_SEGMENTS = [
+    "/requirements/",
+    "/scenarios/",
+    "/tests/",
+    "/facts/",
+    "/adr/",
+    "/flags/",
+    "/events/",
+];
+export const KIBI_IMPACT_DIAGNOSTIC_IDS = [
+    "kibi_impact_evidence_missing",
+    "symbols_manifest_stale",
+    "kibi_impact_override_missing_rationale",
+];
+/**
+ * Staged Kibi impact contract for `kibi check --staged`.
+ *
+ * This is intentionally a small, stable contract for tests and future staged
+ * enforcement wiring:
+ * - `behavior_source_edit` is a supported source-file edit whose staged hunks
+ *   intersect exported or other behavior-bearing/user-facing surfaces and whose
+ *   changed lines are not comment-only or formatting-only.
+ * - `kibi_impact_evidence` is staged entity markdown, staged authored
+ *   `documentation/symbols.yaml` metadata, refreshed
+ *   `documentation/symbol-coordinates.yaml` when extraction output changes, or
+ *   an explicit audited `Kibi-Impact: none` declaration with
+ *   rationale for false positives/non-behavior-only edits.
+ * - `Kibi-Impact: none` never satisfies a genuine behavior change.
+ * - Test-only edits do not require new KB evidence unless they introduce
+ *   executable test symbols that need traceability.
+ *
+ * This contract deliberately avoids broad semantic diffing and stays
+ * conservative so later staged-check enforcement can share exact diagnostic IDs
+ * and operator-facing remediation steps.
+ */
+export const KIBI_IMPACT_DIAGNOSTICS = {
+    kibi_impact_evidence_missing: {
+        id: "kibi_impact_evidence_missing",
+        title: "Behavior edit requires staged Kibi impact evidence",
+        resolution: [
+            "Query Kibi via MCP first: use kb_search for discovery, then kb_query for exact follow-up.",
+            "Stage related KB entity markdown, stage authored documentation/symbols.yaml metadata, or refresh coordinates with kibi sync --refresh-symbol-coordinates and stage documentation/symbol-coordinates.yaml documentation/symbols.yaml.",
+            "Re-run or let the hook run kibi check --staged.",
+        ],
+    },
+    symbols_manifest_stale: {
+        id: "symbols_manifest_stale",
+        title: "Symbol coordinates evidence is stale for changed extraction output",
+        resolution: [
+            "Refresh symbol coordinates for the changed source file with kibi sync --refresh-symbol-coordinates.",
+            "Stage documentation/symbol-coordinates.yaml in the same change as the behavior edit, and stage documentation/symbols.yaml only if migration cleanup changed it.",
+            "Re-run or let the hook run kibi check --staged.",
+        ],
+    },
+    kibi_impact_override_missing_rationale: {
+        id: "kibi_impact_override_missing_rationale",
+        title: "Kibi no-impact override requires an explicit rationale",
+        resolution: [
+            "Use an audited declaration only for false positives or non-behavioral edits.",
+            "Include both 'Kibi-Impact: none' and a nearby 'Rationale:' line describing why the edit has no behavior impact.",
+            "Re-run or let the hook run kibi check --staged.",
+        ],
+    },
+};
+export function classifyKibiImpactEvidence(input) {
+    if (input.overrideDeclared && hasText(input.overrideRationale)) {
+        return "audited_no_impact";
+    }
+    const filePath = input.filePath ?? "";
+    if (!filePath) {
+        return null;
+    }
+    if (isEntityEvidenceMarkdown(filePath)) {
+        return "entity_markdown";
+    }
+    if (isSymbolsManifest(filePath, input.symbolsManifestPath) &&
+        input.extractionOutputChanged) {
+        return "symbols_manifest";
+    }
+    return null;
+}
+export function parseKibiImpactOverride(text) {
+    const declared = /^Kibi-Impact:\s*none\s*$/im.test(text);
+    const rationaleMatch = text.match(/^Rationale:\s*(.+)\s*$/im);
+    return {
+        declared,
+        rationale: hasText(rationaleMatch?.[1])
+            ? (rationaleMatch?.[1]?.trim() ?? null)
+            : null,
+    };
+}
+export function isAuditedNoImpactOverrideAllowed(input) {
+    return (input.override.declared &&
+        hasText(input.override.rationale) &&
+        !input.behaviorSourceEdit);
+}
+export function isBehaviorSourceEdit(input) {
+    if (!isSupportedBehaviorSourcePath(input.path)) {
+        return false;
+    }
+    if (!input.intersectsBehaviorBearingSymbol && !input.knownUserFacingSurface) {
+        return false;
+    }
+    const changes = extractChangedLines(input.diffText);
+    if (changes.length === 0) {
+        return false;
+    }
+    if (changes.every((line) => isIgnorableChangeLine(line))) {
+        return false;
+    }
+    const removed = normalizeChangedLines(changes.filter((line) => line.kind === "remove"));
+    const added = normalizeChangedLines(changes.filter((line) => line.kind === "add"));
+    if (removed.length > 0 && removed.join("\n") === added.join("\n")) {
+        return false;
+    }
+    return true;
+}
+export function isSupportedBehaviorSourcePath(filePath) {
+    for (const extension of SUPPORTED_BEHAVIOR_SOURCE_EXTENSIONS) {
+        if (filePath.endsWith(extension)) {
+            return true;
+        }
+    }
+    return false;
+}
+function isEntityEvidenceMarkdown(filePath) {
+    if (!filePath.endsWith(".md")) {
+        return false;
+    }
+    return ENTITY_EVIDENCE_SEGMENTS.some((segment) => filePath.includes(segment));
+}
+function isSymbolsManifest(filePath, symbolsManifestPath) {
+    const candidates = new Set([
+        "symbols.yaml",
+        "symbols.yml",
+        "documentation/symbols.yaml",
+        "documentation/symbols.yml",
+    ]);
+    if (symbolsManifestPath) {
+        candidates.add(symbolsManifestPath);
+        if (symbolsManifestPath.endsWith(".yaml")) {
+            candidates.add(`${symbolsManifestPath.slice(0, -5)}.yml`);
+        }
+        if (symbolsManifestPath.endsWith(".yml")) {
+            candidates.add(`${symbolsManifestPath.slice(0, -4)}.yaml`);
+        }
+    }
+    if (candidates.has(filePath)) {
+        return true;
+    }
+    return (filePath.endsWith("/symbols.yaml") ||
+        filePath.endsWith("/symbols.yml") ||
+        filePath === "symbols.yaml" ||
+        filePath === "symbols.yml");
+}
+function hasText(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+function extractChangedLines(diffText) {
+    const lines = diffText.split(/\r?\n/);
+    const changes = [];
+    for (const line of lines) {
+        if (line.startsWith("+++") ||
+            line.startsWith("---") ||
+            line.startsWith("@@")) {
+            continue;
+        }
+        if (line.startsWith("+")) {
+            changes.push({ kind: "add", text: line.slice(1) });
+            continue;
+        }
+        if (line.startsWith("-")) {
+            changes.push({ kind: "remove", text: line.slice(1) });
+        }
+    }
+    return changes;
+}
+function isIgnorableChangeLine(line) {
+    const trimmed = line.text.trim();
+    if (!trimmed) {
+        return true;
+    }
+    return (trimmed.startsWith("//") ||
+        trimmed.startsWith("/*") ||
+        trimmed.startsWith("*/") ||
+        trimmed.startsWith("*"));
+}
+function normalizeChangedLines(lines) {
+    return lines
+        .map((line) => line.text.replace(/\s+/g, ""))
+        .filter((line) => line.length > 0);
+}

package/dist/traceability/staged-symbols-manifest.d.ts

@@ -0,0 +1,23 @@
+import type { StagedFile } from "./git-staged.js";
+export interface StagedSymbolsManifestAssessment {
+    state: "fresh" | "stale" | "missing" | "not_required";
+    sourcePaths: string[];
+    path: string;
+}
+export interface StagedAuthoredSymbolsManifestEvidence {
+    path: string;
+    entries: Array<{
+        sourcePath: string;
+        entityIds: string[];
+    }>;
+}
+export declare function assessStagedSymbolsManifest(options: {
+    symbolsManifestPath: string;
+    sourceFiles: StagedFile[];
+    stagedFiles: StagedFile[];
+}): StagedSymbolsManifestAssessment;
+export declare function collectStagedAuthoredSymbolsManifestEvidence(options: {
+    sourceFiles: StagedFile[];
+    stagedFiles: StagedFile[];
+}): StagedAuthoredSymbolsManifestEvidence;
+//# sourceMappingURL=staged-symbols-manifest.d.ts.map

package/dist/traceability/staged-symbols-manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"staged-symbols-manifest.d.ts","sourceRoot":"","sources":["../../src/traceability/staged-symbols-manifest.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AA8BlD,MAAM,WAAW,+BAA+B;IAC9C,KAAK,EAAE,OAAO,GAAG,OAAO,GAAG,SAAS,GAAG,cAAc,CAAC;IACtD,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,qCAAqC;IACpD,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,KAAK,CAAC;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,CAAC;CAC7D;AAmQD,wBAAgB,2BAA2B,CAAC,OAAO,EAAE;IACnD,mBAAmB,EAAE,MAAM,CAAC;IAC5B,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,WAAW,EAAE,UAAU,EAAE,CAAC;CAC3B,GAAG,+BAA+B,CA0ElC;AAoBD,wBAAgB,4CAA4C,CAAC,OAAO,EAAE;IACpE,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,WAAW,EAAE,UAAU,EAAE,CAAC;CAC3B,GAAG,qCAAqC,CA6CxC"}

package/dist/traceability/staged-symbols-manifest.js

@@ -0,0 +1,269 @@
+import { execSync } from "node:child_process";
+import * as path from "node:path";
+import { extractManifestSymbolRecordsString, } from "../extractors/manifest.js";
+import { mergeCoordinatesWithManifest, readCoordinateArtifact, } from "../extractors/symbol-coordinates.js";
+import { analyzeSourceText } from "../extractors/symbols-coordinator.js";
+import { resolveSymbolsManifestPaths } from "../utils/manifest-paths.js";
+function toRepoRelativePath(absoluteOrRelativePath) {
+    if (!path.isAbsolute(absoluteOrRelativePath)) {
+        return absoluteOrRelativePath.replace(/\\/g, "/");
+    }
+    const relativePath = path.relative(process.cwd(), absoluteOrRelativePath);
+    return relativePath.replace(/\\/g, "/");
+}
+function resolveRelativeManifestPaths(symbolsManifestPath) {
+    if (symbolsManifestPath) {
+        const normalizedSymbolsPath = toRepoRelativePath(symbolsManifestPath);
+        return {
+            symbolsPath: normalizedSymbolsPath,
+            coordinatesPath: path
+                .join(path.dirname(normalizedSymbolsPath), "symbol-coordinates.yaml")
+                .replace(/\\/g, "/"),
+        };
+    }
+    const { coordinatesPath, symbolsPath } = resolveSymbolsManifestPaths(process.cwd());
+    return {
+        symbolsPath: toRepoRelativePath(symbolsPath),
+        coordinatesPath: toRepoRelativePath(coordinatesPath),
+    };
+}
+function readHeadFileContent(filePath) {
+    try {
+        return execSync(`git show HEAD:${filePath}`, {
+            encoding: "utf8",
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+    }
+    catch {
+        return null;
+    }
+}
+function parseManifestRecords(content, filePath) {
+    if (content === null || content === undefined) {
+        return [];
+    }
+    try {
+        return extractManifestSymbolRecordsString(content, filePath);
+    }
+    catch {
+        return null;
+    }
+}
+function parseCoordinateArtifact(content) {
+    if (content === null || content === undefined) {
+        return { coordinates: {} };
+    }
+    try {
+        return readCoordinateArtifact(content);
+    }
+    catch {
+        return null;
+    }
+}
+function normalizeNumber(value) {
+    return typeof value === "number" ? value : null;
+}
+function normalizeLinks(links) {
+    if (!Array.isArray(links)) {
+        return [];
+    }
+    const normalized = [];
+    for (const link of links) {
+        if (typeof link === "string") {
+            normalized.push(link);
+            continue;
+        }
+        if (link &&
+            typeof link === "object" &&
+            typeof link.type === "string" &&
+            typeof link.target === "string") {
+            normalized.push({ type: link.type, target: link.target });
+        }
+    }
+    return normalized.sort((left, right) => JSON.stringify(left).localeCompare(JSON.stringify(right)));
+}
+function normalizeRelationships(relationships) {
+    if (!Array.isArray(relationships)) {
+        return [];
+    }
+    return relationships
+        .flatMap((relationship) => {
+        if (relationship &&
+            typeof relationship.type === "string" &&
+            typeof relationship.target === "string") {
+            return [{ type: relationship.type, target: relationship.target }];
+        }
+        return [];
+    })
+        .sort((left, right) => JSON.stringify(left).localeCompare(JSON.stringify(right)));
+}
+function normalizeManifestSymbolsForSourceFile(records, sourceFile) {
+    return records
+        .filter((record) => {
+        const recordSource = typeof record.sourceFile === "string"
+            ? record.sourceFile
+            : typeof record.source === "string"
+                ? record.source
+                : null;
+        return recordSource === sourceFile && typeof record.title === "string";
+    })
+        .map((record) => ({
+        title: record.title,
+        sourceFile,
+        sourceLine: normalizeNumber(record.sourceLine),
+        sourceColumn: normalizeNumber(record.sourceColumn),
+        sourceEndLine: normalizeNumber(record.sourceEndLine),
+        sourceEndColumn: normalizeNumber(record.sourceEndColumn),
+    }))
+        .sort(compareNormalizedSymbols);
+}
+function normalizeAuthoredManifestSymbolsForSourceFile(records, sourceFile) {
+    return records
+        .filter((record) => {
+        const recordSource = typeof record.sourceFile === "string"
+            ? record.sourceFile
+            : typeof record.source === "string"
+                ? record.source
+                : null;
+        return recordSource === sourceFile && typeof record.title === "string";
+    })
+        .map((record) => ({
+        id: typeof record.id === "string" ? record.id : null,
+        title: record.title,
+        sourceFile,
+        status: typeof record.status === "string" ? record.status : null,
+        links: normalizeLinks(record.links),
+        relationships: normalizeRelationships(record.relationships),
+        tags: Array.isArray(record.tags)
+            ? record.tags.filter((tag) => typeof tag === "string").sort()
+            : [],
+        owner: typeof record.owner === "string" ? record.owner : null,
+        priority: typeof record.priority === "string" ? record.priority : null,
+        severity: typeof record.severity === "string" ? record.severity : null,
+        textRef: typeof record.text_ref === "string" ? record.text_ref : null,
+    }))
+        .sort((left, right) => JSON.stringify(left).localeCompare(JSON.stringify(right)));
+}
+function normalizeExpectedSymbolsForStagedFile(stagedFile) {
+    const analysis = analyzeSourceText(stagedFile.path, stagedFile.content ?? "");
+    return analysis.symbols
+        .map((symbol) => ({
+        title: symbol.name,
+        sourceFile: stagedFile.path,
+        sourceLine: symbol.startLine,
+        sourceColumn: symbol.startColumn,
+        sourceEndLine: symbol.endLine,
+        sourceEndColumn: symbol.endColumn,
+    }))
+        .sort(compareNormalizedSymbols);
+}
+function compareNormalizedSymbols(left, right) {
+    return JSON.stringify(left).localeCompare(JSON.stringify(right));
+}
+function signaturesEqual(left, right) {
+    return JSON.stringify(left) === JSON.stringify(right);
+}
+function uniqueSorted(paths) {
+    return Array.from(new Set(paths)).sort();
+}
+function mergeManifestRecordsWithCoordinates(manifestRecords, coordinateArtifact) {
+    return mergeCoordinatesWithManifest(manifestRecords ?? [], coordinateArtifact);
+}
+function getEffectiveManifestRecords(options) {
+    const { headCoordinateArtifact, headManifestRecords, paths, stagedFiles } = options;
+    const stagedManifestFile = stagedFiles.find((file) => file.path === paths.symbolsPath);
+    const stagedCoordinatesFile = stagedFiles.find((file) => file.path === paths.coordinatesPath);
+    const stagedManifestRecords = stagedManifestFile
+        ? parseManifestRecords(stagedManifestFile.content, paths.symbolsPath)
+        : headManifestRecords;
+    const stagedCoordinateArtifact = stagedCoordinatesFile
+        ? parseCoordinateArtifact(stagedCoordinatesFile.content)
+        : headCoordinateArtifact;
+    return {
+        stagedManifestFile,
+        stagedCoordinatesFile,
+        stagedManifestRecords,
+        stagedCoordinateArtifact,
+    };
+}
+export function assessStagedSymbolsManifest(options) {
+    const { sourceFiles, stagedFiles, symbolsManifestPath } = options;
+    const paths = resolveRelativeManifestPaths(symbolsManifestPath);
+    const headManifestRecords = parseManifestRecords(readHeadFileContent(paths.symbolsPath), paths.symbolsPath);
+    const headCoordinateArtifact = parseCoordinateArtifact(readHeadFileContent(paths.coordinatesPath));
+    const { stagedCoordinatesFile, stagedCoordinateArtifact, stagedManifestRecords, } = getEffectiveManifestRecords({
+        stagedFiles,
+        paths,
+        headManifestRecords,
+        headCoordinateArtifact,
+    });
+    const baselineMergedRecords = mergeManifestRecordsWithCoordinates(headManifestRecords, headCoordinateArtifact);
+    const stagedMergedRecords = mergeManifestRecordsWithCoordinates(stagedManifestRecords, stagedCoordinateArtifact);
+    const requiredRefreshPaths = [];
+    const freshPaths = new Set();
+    for (const sourceFile of sourceFiles) {
+        const expectedSymbols = normalizeExpectedSymbolsForStagedFile(sourceFile);
+        const baselineSymbols = normalizeManifestSymbolsForSourceFile(baselineMergedRecords, sourceFile.path);
+        if (signaturesEqual(expectedSymbols, baselineSymbols)) {
+            continue;
+        }
+        requiredRefreshPaths.push(sourceFile.path);
+        if (!stagedCoordinatesFile || stagedCoordinateArtifact === null) {
+            continue;
+        }
+        const stagedSymbols = normalizeManifestSymbolsForSourceFile(stagedMergedRecords, sourceFile.path);
+        if (signaturesEqual(expectedSymbols, stagedSymbols)) {
+            freshPaths.add(sourceFile.path);
+        }
+    }
+    const sourcePaths = uniqueSorted(requiredRefreshPaths);
+    if (sourcePaths.length === 0) {
+        return { state: "not_required", sourcePaths: [], path: paths.coordinatesPath };
+    }
+    if (sourcePaths.every((sourcePath) => freshPaths.has(sourcePath))) {
+        return { state: "fresh", sourcePaths, path: paths.coordinatesPath };
+    }
+    if (!stagedCoordinatesFile) {
+        return { state: "missing", sourcePaths, path: paths.coordinatesPath };
+    }
+    return { state: "stale", sourcePaths, path: paths.coordinatesPath };
+}
+function getEntityIdsForSourceFile(records, sourceFile) {
+    return records
+        .filter((record) => {
+        const recordSource = typeof record.sourceFile === "string"
+            ? record.sourceFile
+            : typeof record.source === "string"
+                ? record.source
+                : null;
+        return recordSource === sourceFile && typeof record.id === "string";
+    })
+        .map((record) => record.id)
+        .sort();
+}
+export function collectStagedAuthoredSymbolsManifestEvidence(options) {
+    const { sourceFiles, stagedFiles } = options;
+    const paths = resolveRelativeManifestPaths();
+    const stagedManifestFile = stagedFiles.find((file) => file.path === paths.symbolsPath);
+    if (!stagedManifestFile) {
+        return { path: paths.symbolsPath, entries: [] };
+    }
+    const headManifestRecords = parseManifestRecords(readHeadFileContent(paths.symbolsPath), paths.symbolsPath) ?? [];
+    const stagedManifestRecords = parseManifestRecords(stagedManifestFile.content, paths.symbolsPath);
+    if (stagedManifestRecords === null) {
+        return { path: paths.symbolsPath, entries: [] };
+    }
+    const entries = [];
+    for (const sourceFile of sourceFiles) {
+        const headSymbols = normalizeAuthoredManifestSymbolsForSourceFile(headManifestRecords, sourceFile.path);
+        const stagedSymbols = normalizeAuthoredManifestSymbolsForSourceFile(stagedManifestRecords, sourceFile.path);
+        if (signaturesEqual(headSymbols, stagedSymbols)) {
+            continue;
+        }
+        entries.push({
+            sourcePath: sourceFile.path,
+            entityIds: getEntityIdsForSourceFile(stagedManifestRecords, sourceFile.path),
+        });
+    }
+    return { path: paths.symbolsPath, entries };
+}

package/dist/traceability/symbol-extract.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"symbol-extract.d.ts","sourceRoot":"","sources":["../../src/traceability/symbol-extract.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE7D,KAAK,wBAAwB,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC;AAU7D,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,UAAU,GAAG,OAAO,GAAG,UAAU,GAAG,MAAM,GAAG,SAAS,CAAC;IAC7D,QAAQ,EAAE;QACR,IAAI,EAAE,MAAM,CAAC;QACb,SAAS,EAAE,MAAM,CAAC;QAClB,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;IACF,UAAU,EAAE,SAAS,EAAE,CAAC;IACxB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,aAAa,CAAC,EAAE,wBAAwB,EAAE,CAAC;CAC5C;AAED,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,aAAa,CAAC,EAAE,wBAAwB,EAAE,CAAC;CAC5C;AAED,MAAM,MAAM,cAAc,GAAG,GAAG,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;AAE9D,wBAAgB,+BAA+B,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAG5E;AA2LD,wBAAgB,4BAA4B,CAE1C,UAAU,EAAE,UAAU,EACtB,cAAc,CAAC,EAAE,cAAc,GAC9B,eAAe,EAAE,CA+JnB"}
+{"version":3,"file":"symbol-extract.d.ts","sourceRoot":"","sources":["../../src/traceability/symbol-extract.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE7D,KAAK,wBAAwB,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC;AAU7D,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,UAAU,GAAG,OAAO,GAAG,UAAU,GAAG,MAAM,GAAG,SAAS,CAAC;IAC7D,QAAQ,EAAE;QACR,IAAI,EAAE,MAAM,CAAC;QACb,SAAS,EAAE,MAAM,CAAC;QAClB,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;IACF,UAAU,EAAE,SAAS,EAAE,CAAC;IACxB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,aAAa,CAAC,EAAE,wBAAwB,EAAE,CAAC;CAC5C;AAED,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,aAAa,CAAC,EAAE,wBAAwB,EAAE,CAAC;CAC5C;AAED,MAAM,MAAM,cAAc,GAAG,GAAG,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;AAE9D,wBAAgB,+BAA+B,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAG5E;AA+ND,wBAAgB,4BAA4B,CAE1C,UAAU,EAAE,UAAU,EACtB,cAAc,CAAC,EAAE,cAAc,GAC9B,eAAe,EAAE,CA+JnB"}

package/dist/traceability/symbol-extract.js

@@ -1,6 +1,6 @@
 import { createHash } from "node:crypto";
 import { Project, ScriptKind } from "ts-morph";
-import { extractFromManifest } from "../extractors/manifest.js";
+import { readManifestWithCoordinateOverlay } from "../extractors/manifest.js";
 const TRACEABILITY_RELATIONSHIP_TYPES = new Set([
     "implements",
     "covered_by",
@@ -55,15 +55,12 @@ function resolveSymbolTraceability(filePath, name, manifestLookup) {
     }
     for (const manifestPath of candidateManifestPaths) {
         try {
-            const ents = extractFromManifest(manifestPath);
-            for (const e of ents) {
-                if (e.entity.title === name) {
+            const records = readManifestWithCoordinateOverlay(manifestPath);
+            for (const record of records) {
+                if (record.title === name && typeof record.id === "string") {
                     return {
-                        id: e.entity.id,
-                        relationships: filterTraceabilityRelationships(e.relationships.map((relationship) => ({
-                            type: relationship.type,
-                            to: relationship.to,
-                        }))),
+                        id: record.id,
+                        relationships: filterTraceabilityRelationships(extractRelationshipsFromManifestRecord(record)),
                     };
                 }
             }
@@ -74,6 +71,33 @@ function resolveSymbolTraceability(filePath, name, manifestLookup) {
     }
     return { id: createHashFallbackId(filePath, name) };
 }
+function extractRelationshipsFromManifestRecord(record) {
+    const relationships = [];
+    if (Array.isArray(record.links)) {
+        for (const link of record.links) {
+            if (typeof link === "string") {
+                relationships.push({ type: "implements", to: link });
+                continue;
+            }
+            if (link &&
+                typeof link === "object" &&
+                typeof link.type === "string" &&
+                typeof link.target === "string") {
+                relationships.push({ type: link.type, to: link.target });
+            }
+        }
+    }
+    if (Array.isArray(record.relationships)) {
+        for (const relationship of record.relationships) {
+            if (relationship &&
+                typeof relationship.type === "string" &&
+                typeof relationship.target === "string") {
+                relationships.push({ type: relationship.type, to: relationship.target });
+            }
+        }
+    }
+    return relationships;
+}
 function buildSymbolResult(stagedFile, name, kind, span, inlineReqLinks, manifestLookup) {
     const { id, relationships } = resolveSymbolTraceability(stagedFile.path, name, manifestLookup);
     const manifestReqLinks = getRequirementLinks(relationships);

package/dist/utils/manifest-paths.d.ts

@@ -0,0 +1,8 @@
+export declare const DEFAULT_SYMBOLS_PATH = "documentation/symbols.yaml";
+export declare const DEFAULT_COORDINATES_PATH = "documentation/symbol-coordinates.yaml";
+export declare function resolveSymbolsManifestPaths(workspaceRoot: string, configPath?: string): {
+    symbolsPath: string;
+    coordinatesPath: string;
+};
+export declare function resolveSymbolsManifestPath(workspaceRoot: string, configPath?: string): string;
+//# sourceMappingURL=manifest-paths.d.ts.map

package/dist/utils/manifest-paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest-paths.d.ts","sourceRoot":"","sources":["../../src/utils/manifest-paths.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,oBAAoB,+BAA+B,CAAC;AACjE,eAAO,MAAM,wBAAwB,0CAA0C,CAAC;AAuEhF,wBAAgB,2BAA2B,CACzC,aAAa,EAAE,MAAM,EACrB,UAAU,CAAC,EAAE,MAAM,GAClB;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,eAAe,EAAE,MAAM,CAAA;CAAE,CASlD;AAGD,wBAAgB,0BAA0B,CACxC,aAAa,EAAE,MAAM,EACrB,UAAU,CAAC,EAAE,MAAM,GAClB,MAAM,CAER"}