kibi-cli 0.10.0 → 0.10.1

package/dist/extractors/manifest.js

@@ -16,8 +16,11 @@
  along with this program.  If not, see <https://www.gnu.org/licenses/>.
 */
 import { createHash } from "node:crypto";
-import { readFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
+import * as path from "node:path";
 import { load as parseYAML } from "js-yaml";
+import { DEFAULT_COORDINATES_PATH } from "../utils/manifest-paths.js";
+import { mergeCoordinatesWithManifest, readCoordinateArtifact, } from "./symbol-coordinates.js";
 export class ManifestError extends Error {
     filePath;
     constructor(message, filePath) {
@@ -26,6 +29,12 @@ export class ManifestError extends Error {
         this.name = "ManifestError";
     }
 }
+function getManifestSymbols(manifest, filePath) {
+    if (!manifest.symbols || !Array.isArray(manifest.symbols)) {
+        throw new ManifestError("No symbols array found in manifest", filePath);
+    }
+    return manifest.symbols;
+}
 function extractRelationships(id, symbol) {
     const relationships = [];
     if (Array.isArray(symbol.links)) {
@@ -66,10 +75,10 @@ function extractRelationships(id, symbol) {
     return relationships;
 }
 function extractFromParsedManifest(manifest, filePath) {
-    if (!manifest.symbols || !Array.isArray(manifest.symbols)) {
-        throw new ManifestError("No symbols array found in manifest", filePath);
-    }
-    return manifest.symbols.map((symbol) => {
+    return extractFromManifestSymbolRecords(getManifestSymbols(manifest, filePath), filePath);
+}
+function extractFromManifestSymbolRecords(manifestSymbols, filePath) {
+    return manifestSymbols.map((symbol) => {
         if (!symbol.title) {
             throw new ManifestError("Missing required field: title", filePath);
         }
@@ -96,6 +105,9 @@ function extractFromParsedManifest(manifest, filePath) {
         };
     });
 }
+function cloneManifestSymbols(manifest, filePath) {
+    return getManifestSymbols(manifest, filePath).map((symbol) => ({ ...symbol }));
+}
 // implements REQ-007
 export function extractFromManifestString(content, filePath) {
     try {
@@ -112,9 +124,50 @@ export function extractFromManifestString(content, filePath) {
         throw error;
     }
 }
+export function extractManifestSymbolRecordsString(content, filePath) {
+    try {
+        const manifest = parseYAML(content);
+        return cloneManifestSymbols(manifest, filePath);
+    }
+    catch (error) {
+        if (error instanceof ManifestError) {
+            throw error;
+        }
+        if (error instanceof Error) {
+            throw new ManifestError(`Failed to parse manifest: ${error.message}`, filePath);
+        }
+        throw error;
+    }
+}
 export function extractFromManifest(filePath) {
-    const content = readFileSync(filePath, "utf8");
-    return extractFromManifestString(content, filePath);
+    return extractFromManifestSymbolRecords(readManifestWithCoordinateOverlay(filePath), filePath);
+}
+function resolveCoordinatesPath(manifestPath, coordinatesPath) {
+    if (coordinatesPath) {
+        return coordinatesPath;
+    }
+    return path.join(path.dirname(manifestPath), path.basename(DEFAULT_COORDINATES_PATH));
+}
+function readCoordinateArtifactFromFile(coordinatesPath) {
+    if (!existsSync(coordinatesPath)) {
+        return null;
+    }
+    try {
+        return readCoordinateArtifact(readFileSync(coordinatesPath, "utf8"));
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            throw new ManifestError(`Failed to parse coordinate artifact: ${error.message}`, coordinatesPath);
+        }
+        throw error;
+    }
+}
+// implements REQ-core-extractors
+export function readManifestWithCoordinateOverlay(manifestPath, coordinatesPath) {
+    const manifestContent = readFileSync(manifestPath, "utf8");
+    const manifestRecords = extractManifestSymbolRecordsString(manifestContent, manifestPath);
+    const coordinateArtifact = readCoordinateArtifactFromFile(resolveCoordinatesPath(manifestPath, coordinatesPath));
+    return mergeCoordinatesWithManifest(manifestRecords, coordinateArtifact);
 }
 function generateId(filePath, title) {
     const hash = createHash("sha256");

package/dist/extractors/symbol-coordinates.d.ts

@@ -0,0 +1,15 @@
+import type { ManifestSymbolRecord } from "./manifest.js";
+export interface SymbolCoordinatesRecord {
+    sourceFile: string;
+    sourceLine: number;
+    sourceColumn: number;
+    sourceEndLine: number;
+    sourceEndColumn: number;
+}
+export interface SymbolCoordinatesArtifact {
+    coordinates: Record<string, SymbolCoordinatesRecord>;
+}
+export declare function readCoordinateArtifact(content: string): SymbolCoordinatesArtifact;
+export declare function writeCoordinateArtifact(coordinates: Record<string, SymbolCoordinatesRecord>): string;
+export declare function mergeCoordinatesWithManifest(symbolRecords: ManifestSymbolRecord[], coordinateArtifact: SymbolCoordinatesArtifact | null): ManifestSymbolRecord[];
+//# sourceMappingURL=symbol-coordinates.d.ts.map

package/dist/extractors/symbol-coordinates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"symbol-coordinates.d.ts","sourceRoot":"","sources":["../../src/extractors/symbol-coordinates.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAE1D,MAAM,WAAW,uBAAuB;IACtC,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,yBAAyB;IACxC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,uBAAuB,CAAC,CAAC;CACtD;AA0DD,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,MAAM,GACd,yBAAyB,CAkB3B;AAGD,wBAAgB,uBAAuB,CACrC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,uBAAuB,CAAC,GACnD,MAAM,CAUR;AAGD,wBAAgB,4BAA4B,CAC1C,aAAa,EAAE,oBAAoB,EAAE,EACrC,kBAAkB,EAAE,yBAAyB,GAAG,IAAI,GACnD,oBAAoB,EAAE,CAoBxB"}

package/dist/extractors/symbol-coordinates.js

@@ -0,0 +1,83 @@
+import { dump as dumpYAML, load as parseYAML } from "js-yaml";
+const SYMBOL_COORDINATES_COMMENT_BLOCK = `# symbol-coordinates.yaml
+# GENERATED coordinate artifact — do not edit manually.
+# Run \`kibi sync --refresh-symbol-coordinates\` to refresh.
+`;
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function normalizeCoordinateRecord(value) {
+    if (!isRecord(value)) {
+        return null;
+    }
+    const { sourceColumn, sourceEndColumn, sourceEndLine, sourceFile, sourceLine } = value;
+    if (typeof sourceFile !== "string" ||
+        typeof sourceLine !== "number" ||
+        typeof sourceColumn !== "number" ||
+        typeof sourceEndLine !== "number" ||
+        typeof sourceEndColumn !== "number") {
+        return null;
+    }
+    return {
+        sourceFile,
+        sourceLine,
+        sourceColumn,
+        sourceEndLine,
+        sourceEndColumn,
+    };
+}
+function sortCoordinates(coordinates) {
+    const sortedCoordinates = {};
+    for (const symbolId of Object.keys(coordinates).sort((left, right) => left.localeCompare(right))) {
+        const record = normalizeCoordinateRecord(coordinates[symbolId]);
+        if (!record) {
+            continue;
+        }
+        sortedCoordinates[symbolId] = record;
+    }
+    return sortedCoordinates;
+}
+// implements REQ-core-extractors
+export function readCoordinateArtifact(content) {
+    const parsed = parseYAML(content);
+    if (!isRecord(parsed) || !isRecord(parsed.coordinates)) {
+        return { coordinates: {} };
+    }
+    const coordinates = {};
+    for (const [symbolId, record] of Object.entries(parsed.coordinates)) {
+        const normalizedRecord = normalizeCoordinateRecord(record);
+        if (!normalizedRecord) {
+            continue;
+        }
+        coordinates[symbolId] = normalizedRecord;
+    }
+    return { coordinates };
+}
+// implements REQ-core-extractors
+export function writeCoordinateArtifact(coordinates) {
+    const artifact = {
+        coordinates: sortCoordinates(coordinates),
+    };
+    return `${SYMBOL_COORDINATES_COMMENT_BLOCK}${dumpYAML(artifact, {
+        lineWidth: -1,
+        noRefs: true,
+        sortKeys: true,
+    })}`;
+}
+// implements REQ-core-extractors
+export function mergeCoordinatesWithManifest(symbolRecords, coordinateArtifact) {
+    const coordinates = coordinateArtifact?.coordinates ?? {};
+    return symbolRecords.map((symbolRecord) => {
+        const legacyRecord = { ...symbolRecord };
+        const symbolId = typeof symbolRecord.id === "string" ? symbolRecord.id : undefined;
+        const coordinateRecord = symbolId ? coordinates[symbolId] : undefined;
+        if (!coordinateRecord) {
+            return legacyRecord;
+        }
+        const { coordinatesGeneratedAt: _coordinatesGeneratedAt, ...mergedRecord } = legacyRecord;
+        return {
+            ...mergedRecord,
+            ...coordinateRecord,
+        };
+    });
+}

package/dist/public/extractors/manifest.d.ts

@@ -1,2 +1,2 @@
-export { extractFromManifest, extractFromManifestString, type ExtractionResult, type ManifestError, } from "../../extractors/manifest.js";
+export { extractFromManifest, extractFromManifestString, readManifestWithCoordinateOverlay, type ExtractionResult, type ManifestError, type ManifestSymbolRecord, } from "../../extractors/manifest.js";
 //# sourceMappingURL=manifest.d.ts.map

package/dist/public/extractors/manifest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../../src/public/extractors/manifest.ts"],"names":[],"mappings":"AAkBA,OAAO,EACL,mBAAmB,EACnB,yBAAyB,EACzB,KAAK,gBAAgB,EACrB,KAAK,aAAa,GACnB,MAAM,8BAA8B,CAAC"}
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../../src/public/extractors/manifest.ts"],"names":[],"mappings":"AAkBA,OAAO,EACL,mBAAmB,EACnB,yBAAyB,EACzB,iCAAiC,EACjC,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,KAAK,oBAAoB,GAC1B,MAAM,8BAA8B,CAAC"}

package/dist/public/extractors/manifest.js

@@ -15,4 +15,4 @@
  You should have received a copy of the GNU Affero General Public License
  along with this program.  If not, see <https://www.gnu.org/licenses/>.
 */
-export { extractFromManifest, extractFromManifestString, } from "../../extractors/manifest.js";
+export { extractFromManifest, extractFromManifestString, readManifestWithCoordinateOverlay, } from "../../extractors/manifest.js";

package/dist/traceability/evidence-model.d.ts

@@ -0,0 +1,142 @@
+/**
+ * Stable contract for staged Kibi impact evidence.
+ *
+ * This module is intentionally explicit and non-heuristic. Upstream staged-file
+ * analysis decides whether a source edit is behavior-changing; this contract only
+ * records that decision and the staged KB artifacts that cover it.
+ */
+/** User-facing KB schema documentation cited by staged diagnostics. */
+export declare const KIBI_ENTITY_SCHEMA_DOC = "docs/entity-schema.md";
+/** Canonical symbols manifest path used by staged traceability enforcement. */
+export declare const KIBI_SYMBOLS_MANIFEST_PATH = "documentation/symbols.yaml";
+/** Canonical symbol coordinates artifact used by staged traceability enforcement. */
+export declare const KIBI_SYMBOL_COORDINATES_PATH = "documentation/symbol-coordinates.yaml";
+/** Explicit declaration string for audited no-impact overrides. */
+export declare const KIBI_NO_IMPACT_DECLARATION = "Kibi-Impact: none";
+/** Canonical Kibi entity types that can provide staged evidence. */
+export type KibiEntityType = "req" | "scenario" | "test" | "adr" | "flag" | "event" | "symbol" | "fact";
+/**
+ * Explicit source-edit classification from upstream staged analysis.
+ *
+ * - `behavior_source_edit`: a supported staged source change already classified
+ *   as behavior-changing or traceability-relevant by the caller.
+ * - `non_behavior_source_edit`: a supported staged source change that remains in
+ *   scope for auditing but does not require KB changes.
+ */
+export type SourceChangeKind = "behavior_source_edit" | "non_behavior_source_edit";
+/** One staged source file participating in Kibi impact evaluation. */
+export interface KibiImpactSourceChange {
+    /** Repo-relative staged source path. */
+    path: string;
+    /** Explicit upstream classification; this module does not infer it. */
+    kind: SourceChangeKind;
+}
+/**
+ * Staged KB markdown evidence linked to one or more staged source files.
+ *
+ * Evidence is explicit only when the staged artifact names concrete KB entities
+ * and lists the staged source paths it is intended to cover.
+ */
+export interface KibiImpactKbArtifact {
+    /** Artifact category. Kept narrow to avoid heuristic interpretation. */
+    kind: "entity_markdown" | "symbols_manifest";
+    /** Repo-relative staged KB artifact path. */
+    path: string;
+    /** Canonical Kibi entity types present in the staged artifact. */
+    entityTypes: KibiEntityType[];
+    /** Concrete KB entities updated by the staged artifact. */
+    entityIds: string[];
+    /** Repo-relative source paths explicitly covered by this artifact. */
+    sourcePaths: string[];
+}
+/**
+ * Deterministic symbol coordinates artifact state for the staged change-set.
+ *
+ * - `not_required`: symbol extraction output did not change for the listed
+ *   staged source paths.
+ * - `fresh`: a staged coordinate refresh covers the listed source paths.
+ * - `stale`: coordinate artifact content is reverted, outdated, or otherwise does not match
+ *   the staged symbol extraction result.
+ * - `missing`: a refresh is required but no staged coordinate artifact exists.
+ */
+export interface KibiImpactSymbolsManifest {
+    /** Canonical repo-relative symbol coordinate artifact path. */
+    path: string;
+    /** Explicit manifest freshness state. */
+    state: "not_required" | "fresh" | "stale" | "missing";
+    /** Repo-relative staged source paths whose symbol output this state describes. */
+    sourcePaths: string[];
+}
+/** Supported audited reasons for a no-impact override. */
+export type KibiNoImpactReason = "false_positive" | "non_behavioral_source_edit";
+/**
+ * Explicit no-impact override record.
+ *
+ * Overrides are only valid for non-behavioral edits or classifier false
+ * positives. They never satisfy real behavior-changing source edits.
+ */
+export interface KibiNoImpactOverride {
+    /** Required literal declaration. */
+    declaration: typeof KIBI_NO_IMPACT_DECLARATION;
+    /** Repo-relative staged record path carrying the override. */
+    path: string;
+    /** Repo-relative source paths covered by the override record. */
+    sourcePaths: string[];
+    /** Audited reason for allowing the override. */
+    reason: KibiNoImpactReason;
+    /** Human-readable justification stored with the override record. */
+    rationale: string;
+}
+/** Explicit evidence state: staged KB artifacts are present. */
+export interface KibiImpactKbChangesMode {
+    kind: "kb_changes";
+    /** Staged KB markdown artifacts linked to staged source changes. */
+    kbArtifacts: KibiImpactKbArtifact[];
+}
+/** Explicit evidence state: a staged no-impact override is being used. */
+export interface KibiImpactNoImpactOverrideMode {
+    kind: "no_impact_override";
+    /** Staged override record for false positives or non-behavioral edits. */
+    override: KibiNoImpactOverride;
+}
+/** Explicit evidence state: no staged KB evidence or override exists. */
+export interface KibiImpactMissingMode {
+    kind: "missing";
+}
+/** Discriminated union describing how the staged change-set is justified. */
+export type KibiImpactMode = KibiImpactKbChangesMode | KibiImpactNoImpactOverrideMode | KibiImpactMissingMode;
+/**
+ * Full evidence snapshot for staged Kibi impact enforcement.
+ *
+ * `sourceChanges` is always required so diagnostics can cite exact staged source
+ * files. `mode` captures whether those files are backed by KB changes, by an
+ * audited no-impact override, or by nothing. `symbolsManifest` records whether a
+ * staged manifest refresh is part of that evidence.
+ */
+export interface KibiImpactEvidence {
+    /** All staged source files in scope for Kibi impact enforcement. */
+    sourceChanges: KibiImpactSourceChange[];
+    /** Deterministic staged symbols manifest state for the same change-set. */
+    symbolsManifest: KibiImpactSymbolsManifest;
+    /** Explicit evidence mode for the staged change-set. */
+    mode: KibiImpactMode;
+}
+/** Returns staged behavior-changing source paths only. */
+export declare function getBehaviorSourcePaths(evidence: KibiImpactEvidence): string[];
+/** Returns staged source paths covered by explicit KB artifacts. */
+export declare function getKbCoveredSourcePaths(evidence: KibiImpactEvidence): string[];
+/** Returns staged source paths covered by a fresh symbol coordinate refresh. */
+export declare function getFreshSymbolsManifestSourcePaths(evidence: KibiImpactEvidence): string[];
+/**
+ * Returns all staged evidence file paths that a later CLI integration can cite
+ * in diagnostics or logs.
+ */
+export declare function getKbEvidencePaths(evidence: KibiImpactEvidence): string[];
+/** True when a staged no-impact override includes a non-empty rationale. */
+export declare function hasOverrideRationale(evidence: KibiImpactEvidence): boolean;
+/**
+ * Returns behavior-changing staged source files that still lack valid Kibi
+ * impact evidence.
+ */
+export declare function getMissingBehaviorSourcePaths(evidence: KibiImpactEvidence): string[];
+//# sourceMappingURL=evidence-model.d.ts.map

package/dist/traceability/evidence-model.d.ts.map

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

package/dist/traceability/evidence-model.js

@@ -0,0 +1,70 @@
+/**
+ * Stable contract for staged Kibi impact evidence.
+ *
+ * This module is intentionally explicit and non-heuristic. Upstream staged-file
+ * analysis decides whether a source edit is behavior-changing; this contract only
+ * records that decision and the staged KB artifacts that cover it.
+ */
+/** User-facing KB schema documentation cited by staged diagnostics. */
+export const KIBI_ENTITY_SCHEMA_DOC = "docs/entity-schema.md";
+/** Canonical symbols manifest path used by staged traceability enforcement. */
+export const KIBI_SYMBOLS_MANIFEST_PATH = "documentation/symbols.yaml";
+/** Canonical symbol coordinates artifact used by staged traceability enforcement. */
+export const KIBI_SYMBOL_COORDINATES_PATH = "documentation/symbol-coordinates.yaml";
+/** Explicit declaration string for audited no-impact overrides. */
+export const KIBI_NO_IMPACT_DECLARATION = "Kibi-Impact: none";
+function uniqueSorted(values) {
+    return Array.from(new Set(values)).sort();
+}
+/** Returns staged behavior-changing source paths only. */
+export function getBehaviorSourcePaths(evidence) {
+    return evidence.sourceChanges
+        .filter((change) => change.kind === "behavior_source_edit")
+        .map((change) => change.path)
+        .sort();
+}
+/** Returns staged source paths covered by explicit KB artifacts. */
+export function getKbCoveredSourcePaths(evidence) {
+    if (evidence.mode.kind !== "kb_changes") {
+        return [];
+    }
+    return uniqueSorted(evidence.mode.kbArtifacts.flatMap((artifact) => artifact.sourcePaths));
+}
+/** Returns staged source paths covered by a fresh symbol coordinate refresh. */
+export function getFreshSymbolsManifestSourcePaths(evidence) {
+    if (evidence.symbolsManifest.state !== "fresh") {
+        return [];
+    }
+    return [...evidence.symbolsManifest.sourcePaths].sort();
+}
+/**
+ * Returns all staged evidence file paths that a later CLI integration can cite
+ * in diagnostics or logs.
+ */
+export function getKbEvidencePaths(evidence) {
+    const paths = [];
+    if (evidence.mode.kind === "kb_changes") {
+        paths.push(...evidence.mode.kbArtifacts.map((artifact) => artifact.path));
+    }
+    if (evidence.symbolsManifest.state === "fresh") {
+        paths.push(evidence.symbolsManifest.path);
+    }
+    return uniqueSorted(paths);
+}
+/** True when a staged no-impact override includes a non-empty rationale. */
+export function hasOverrideRationale(evidence) {
+    return (evidence.mode.kind === "no_impact_override" &&
+        evidence.mode.override.rationale.trim().length > 0);
+}
+/**
+ * Returns behavior-changing staged source files that still lack valid Kibi
+ * impact evidence.
+ */
+export function getMissingBehaviorSourcePaths(evidence) {
+    const behaviorPaths = getBehaviorSourcePaths(evidence);
+    const coveredPaths = new Set([
+        ...getKbCoveredSourcePaths(evidence),
+        ...getFreshSymbolsManifestSourcePaths(evidence),
+    ]);
+    return behaviorPaths.filter((path) => !coveredPaths.has(path));
+}

package/dist/traceability/git-staged.d.ts

@@ -8,6 +8,7 @@ export interface StagedFile {
     status: Status;
     oldPath?: string;
     hunkRanges: HunkRange[];
+    diffText?: string;
     content?: string;
 }
 type ExecFn = (cmd: string, opts: {

package/dist/traceability/git-staged.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"git-staged.d.ts","sourceRoot":"","sources":["../../src/traceability/git-staged.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,MAAM,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;AAE3C,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,SAAS,EAAE,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,KAAK,MAAM,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,KAAK,MAAM,CAAC;AAalE;;GAEG;AAEH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,MAAM,GACZ,KAAK,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CAwB5C;AAiDD;;GAEG;AACH,wBAAgB,kBAAkB,CAEhC,QAAQ,EAAE,MAAM,EAChB,SAAS,UAAQ,GAChB,SAAS,EAAE,CAuBb;AAED;;GAEG;AAEH,wBAAgB,cAAc,CAAC,IAAI,GAAE,MAAiB,GAAG,UAAU,EAAE,CAuGpE;AAED,eAAe,cAAc,CAAC"}
+{"version":3,"file":"git-staged.d.ts","sourceRoot":"","sources":["../../src/traceability/git-staged.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,MAAM,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;AAE3C,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,SAAS,EAAE,CAAC;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,KAAK,MAAM,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,KAAK,MAAM,CAAC;AAalE;;GAEG;AAEH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,MAAM,GACZ,KAAK,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CAwB5C;AAsED;;GAEG;AACH,wBAAgB,kBAAkB,CAEhC,QAAQ,EAAE,MAAM,EAChB,SAAS,UAAQ,GAChB,SAAS,EAAE,CAuBb;AAED;;GAEG;AAEH,wBAAgB,cAAc,CAAC,IAAI,GAAE,MAAiB,GAAG,UAAU,EAAE,CAwGpE;AAED,eAAe,cAAc,CAAC"}

package/dist/traceability/git-staged.js

@@ -1,5 +1,6 @@
 import { execSync } from "node:child_process";
 import { isCliTraceOrDebugEnabled } from "../env.js";
+import { loadConfig } from "../utils/config.js";
 function runGit(cmd, exec) {
     try {
         return exec(cmd, { encoding: "utf8" });
@@ -47,8 +48,20 @@ const SUPPORTED_EXT = new Set([
     ".mjs",
     ".cjs",
 ]);
-const SUPPORTED_MANIFEST = new Set(["symbols.yaml", "symbols.yml"]);
-const ENTITY_MARKDOWN_DIRS = ["/requirements/", "/scenarios/", "/tests/"];
+const SUPPORTED_MANIFEST = new Set([
+    "symbols.yaml",
+    "symbols.yml",
+    "symbol-coordinates.yaml",
+]);
+const ENTITY_MARKDOWN_DIRS = [
+    "/requirements/",
+    "/scenarios/",
+    "/tests/",
+    "/facts/",
+    "/adr/",
+    "/flags/",
+    "/events/",
+];
 function shouldLogTraceDebug() {
     return isCliTraceOrDebugEnabled();
 }
@@ -72,13 +85,24 @@ function isEntityMarkdown(p) {
     return false;
 }
 function isManifestFile(p) {
-    const base = p.split(/[\/]/).pop();
+    const base = p.split(/[\\/]/).pop();
     if (!base)
         return false;
     for (const name of SUPPORTED_MANIFEST) {
         if (base === name)
             return true;
     }
+    try {
+        const config = loadConfig(process.cwd());
+        if (config.paths.symbols) {
+            const configuredBase = config.paths.symbols.split(/[\\/]/).pop();
+            if (configuredBase && base === configuredBase)
+                return true;
+        }
+    }
+    catch {
+        // ignore config read errors
+    }
     return false;
 }
 /**
@@ -198,6 +222,7 @@ export function getStagedFiles(exec = execSync) {
             status,
             ...(oldPath !== undefined ? { oldPath } : {}),
             hunkRanges,
+            diffText,
             content,
         });
     }

package/dist/traceability/staged-diagnostics.d.ts

@@ -0,0 +1,25 @@
+import { type KibiImpactEvidence } from "./evidence-model.js";
+export type KibiImpactDiagnosticId = "kibi_impact_evidence_missing" | "symbols_manifest_stale" | "kibi_impact_override_missing_rationale";
+export interface KibiImpactDiagnostic {
+    /** Stable staged-enforcement diagnostic identifier. */
+    id: KibiImpactDiagnosticId;
+    /** Hard-gate severity for staged enforcement. */
+    severity: "error";
+    /** Repo-relative files that explain why the diagnostic fired. */
+    files: string[];
+    /** User-facing docs that explain the policy. */
+    docs: string[];
+    /** Exact CLI-facing diagnostic message. */
+    message: string;
+    /** Deterministic remediation guidance. */
+    suggestion: string;
+}
+/**
+ * Collects deterministic staged diagnostics for Kibi impact enforcement.
+ *
+ * This function assumes upstream staged analysis has already classified source
+ * files and manifest freshness. It only evaluates explicit predicates recorded in
+ * `KibiImpactEvidence`.
+ */
+export declare function collectStagedKibiDiagnostics(evidence: KibiImpactEvidence): KibiImpactDiagnostic[];
+//# sourceMappingURL=staged-diagnostics.d.ts.map

package/dist/traceability/staged-diagnostics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"staged-diagnostics.d.ts","sourceRoot":"","sources":["../../src/traceability/staged-diagnostics.ts"],"names":[],"mappings":"AAAA,OAAO,EAOL,KAAK,kBAAkB,EACxB,MAAM,qBAAqB,CAAC;AAE7B,MAAM,MAAM,sBAAsB,GAC9B,8BAA8B,GAC9B,wBAAwB,GACxB,wCAAwC,CAAC;AAE7C,MAAM,WAAW,oBAAoB;IACnC,uDAAuD;IACvD,EAAE,EAAE,sBAAsB,CAAC;IAC3B,iDAAiD;IACjD,QAAQ,EAAE,OAAO,CAAC;IAClB,iEAAiE;IACjE,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,gDAAgD;IAChD,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,2CAA2C;IAC3C,OAAO,EAAE,MAAM,CAAC;IAChB,0CAA0C;IAC1C,UAAU,EAAE,MAAM,CAAC;CACpB;AAsDD;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAC1C,QAAQ,EAAE,kBAAkB,GAC3B,oBAAoB,EAAE,CAoCxB"}

package/dist/traceability/staged-diagnostics.js

@@ -0,0 +1,67 @@
+import { KIBI_ENTITY_SCHEMA_DOC, KIBI_SYMBOL_COORDINATES_PATH, KIBI_SYMBOLS_MANIFEST_PATH, getBehaviorSourcePaths, getMissingBehaviorSourcePaths, hasOverrideRationale, } from "./evidence-model.js";
+function formatFileList(paths) {
+    return paths.join(", ");
+}
+function createMissingEvidenceDiagnostic(paths) {
+    return {
+        id: "kibi_impact_evidence_missing",
+        severity: "error",
+        files: [...paths],
+        docs: [KIBI_ENTITY_SCHEMA_DOC],
+        message: `Behavior-changing staged files are missing Kibi impact evidence (see ${KIBI_ENTITY_SCHEMA_DOC}): ${formatFileList(paths)}`,
+        suggestion: `Query Kibi via MCP before deciding, then stage requirement/scenario/test/fact/symbol markdown evidence, staged authored ${KIBI_SYMBOLS_MANIFEST_PATH} metadata, or refreshed ${KIBI_SYMBOL_COORDINATES_PATH}. Re-run kibi check --staged after staging the evidence.`,
+    };
+}
+function createSymbolsManifestStaleDiagnostic(paths) {
+    return {
+        id: "symbols_manifest_stale",
+        severity: "error",
+        files: [KIBI_SYMBOL_COORDINATES_PATH, ...paths],
+        docs: [KIBI_ENTITY_SCHEMA_DOC],
+        message: `${KIBI_SYMBOL_COORDINATES_PATH} is stale or missing for staged source files: ${formatFileList(paths)}`,
+        suggestion: `Run kibi sync --refresh-symbol-coordinates && git add ${KIBI_SYMBOL_COORDINATES_PATH} ${KIBI_SYMBOLS_MANIFEST_PATH}, then re-run kibi check --staged.`,
+    };
+}
+function createMissingOverrideRationaleDiagnostic(evidence) {
+    if (evidence.mode.kind !== "no_impact_override") {
+        throw new Error("Override rationale diagnostic requires a no-impact override");
+    }
+    const paths = [...evidence.mode.override.sourcePaths].sort();
+    return {
+        id: "kibi_impact_override_missing_rationale",
+        severity: "error",
+        files: [evidence.mode.override.path, ...paths],
+        docs: [KIBI_ENTITY_SCHEMA_DOC],
+        message: `Kibi-Impact: none override is missing rationale for staged source files: ${formatFileList(paths)}`,
+        suggestion: "Add a non-empty rationale in the same staged override record, keep overrides limited to false positives or non-behavioral source edits, and re-run kibi check --staged.",
+    };
+}
+/**
+ * Collects deterministic staged diagnostics for Kibi impact enforcement.
+ *
+ * This function assumes upstream staged analysis has already classified source
+ * files and manifest freshness. It only evaluates explicit predicates recorded in
+ * `KibiImpactEvidence`.
+ */
+export function collectStagedKibiDiagnostics(evidence) {
+    const diagnostics = [];
+    if (evidence.mode.kind === "no_impact_override" &&
+        !hasOverrideRationale(evidence)) {
+        diagnostics.push(createMissingOverrideRationaleDiagnostic(evidence));
+    }
+    if ((evidence.symbolsManifest.state === "stale" ||
+        evidence.symbolsManifest.state === "missing") &&
+        evidence.symbolsManifest.sourcePaths.length > 0) {
+        diagnostics.push(createSymbolsManifestStaleDiagnostic([...evidence.symbolsManifest.sourcePaths].sort()));
+    }
+    const missingBehaviorPaths = getMissingBehaviorSourcePaths(evidence);
+    if (missingBehaviorPaths.length > 0) {
+        diagnostics.push(createMissingEvidenceDiagnostic(missingBehaviorPaths));
+    }
+    if (evidence.mode.kind === "no_impact_override" &&
+        evidence.mode.override.sourcePaths.length === 0 &&
+        getBehaviorSourcePaths(evidence).length === 0) {
+        return diagnostics;
+    }
+    return diagnostics;
+}