kibi-cli 0.10.0 → 0.11.0

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;
+}

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);
+}