kibi-cli 2.24.0 → 2.26.1

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

@@ -1 +1 @@
-{"version":3,"file":"staged-diagnostics.d.ts","sourceRoot":"","sources":["../../src/traceability/staged-diagnostics.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AACnE,OAAO,EAGL,KAAK,kBAAkB,EAKxB,MAAM,qBAAqB,CAAC;AAQ7B,MAAM,MAAM,sBAAsB,GAC9B,8BAA8B,GAC9B,wBAAwB,GACxB,8BAA8B,GAC9B,+BAA+B,GAC/B,iCAAiC,GACjC,oCAAoC,GACpC,gCAAgC,GAChC,0BAA0B,GAC1B,2BAA2B,GAC3B,6BAA6B,GAC7B,yBAAyB,GACzB,wCAAwC,GACxC,wBAAwB,CAAC;AAE7B,MAAM,WAAW,oBAAqB,SAAQ,iBAAiB;IAC7D,uDAAuD;IACvD,EAAE,EAAE,sBAAsB,CAAC;IAC3B,QAAQ,EAAE,iBAAiB,CAAC,UAAU,CAAC,CAAC;IACxC,iEAAiE;IACjE,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,gDAAgD;IAChD,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACxB,2CAA2C;IAC3C,OAAO,EAAE,MAAM,CAAC;IAChB,0CAA0C;IAC1C,UAAU,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7B;AAsID,wBAAgB,wCAAwC,CACtD,QAAQ,EAAE,kBAAkB,GAC3B,oBAAoB,CAoBtB;AAED;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAC1C,QAAQ,EAAE,kBAAkB,EAC5B,mBAAmB,GAAE,MAAmC,GACvD,oBAAoB,EAAE,CAiDxB"}
+{"version":3,"file":"staged-diagnostics.d.ts","sourceRoot":"","sources":["../../src/traceability/staged-diagnostics.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AACnE,OAAO,EAGL,KAAK,kBAAkB,EAKxB,MAAM,qBAAqB,CAAC;AAQ7B,MAAM,MAAM,sBAAsB,GAC9B,8BAA8B,GAC9B,wBAAwB,GACxB,8BAA8B,GAC9B,+BAA+B,GAC/B,qBAAqB,GACrB,iCAAiC,GACjC,oCAAoC,GACpC,gCAAgC,GAChC,0BAA0B,GAC1B,2BAA2B,GAC3B,6BAA6B,GAC7B,yBAAyB,GACzB,wCAAwC,GACxC,wBAAwB,CAAC;AAE7B,MAAM,WAAW,oBAAqB,SAAQ,iBAAiB;IAC7D,uDAAuD;IACvD,EAAE,EAAE,sBAAsB,CAAC;IAC3B,QAAQ,EAAE,iBAAiB,CAAC,UAAU,CAAC,CAAC;IACxC,iEAAiE;IACjE,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,gDAAgD;IAChD,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACxB,2CAA2C;IAC3C,OAAO,EAAE,MAAM,CAAC;IAChB,0CAA0C;IAC1C,UAAU,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7B;AAsID,wBAAgB,wCAAwC,CACtD,QAAQ,EAAE,kBAAkB,GAC3B,oBAAoB,CAoBtB;AAED;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAC1C,QAAQ,EAAE,kBAAkB,EAC5B,mBAAmB,GAAE,MAAmC,GACvD,oBAAoB,EAAE,CAiDxB"}

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

@@ -0,0 +1,13 @@
+/**
+ * True when the staged commit carries a `kibi migrate` run: the staged
+ * `.kb/manifest.json` records a schema generation newer than the base, or the
+ * commit retires the legacy `.kb/config.json`. The audit record migrate writes
+ * under `.kb/migrations/` is ignored by Git, so the schema bump is the
+ * committed evidence; it cannot be repeated once a KB is at the latest schema,
+ * so it cannot be used to waive later edits.
+ *
+ * `readBase` and `readStaged` return a file's content in the base and the
+ * staged tree, or null when the file does not exist there.
+ */
+export declare function stagedCommitCarriesMigration(readBase: (filePath: string) => string | null, readStaged: (filePath: string) => string | null): boolean;
+//# sourceMappingURL=staged-migration.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"staged-migration.d.ts","sourceRoot":"","sources":["../../src/traceability/staged-migration.ts"],"names":[],"mappings":"AAoCA;;;;;;;;;;GAUG;AAEH,wBAAgB,4BAA4B,CAC1C,QAAQ,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,EAC7C,UAAU,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,GAC9C,OAAO,CAWT"}

package/dist/traceability/staged-migration.js

@@ -0,0 +1,59 @@
+/*
+ Kibi — repo-local, per-branch, queryable long-term memory for software projects
+ Copyright (C) 2026 Piotr Franczyk
+
+ This program is free software: you can redistribute it and/or modify
+ it under the terms of the GNU Affero General Public License as published by
+ the Free Software Foundation, either version 3 of the License, or
+ (at your option) any later version.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ GNU Affero General Public License for more details.
+
+ 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/>.
+*/
+import { normalizeSchemaVersion } from "../utils/schema-version.js";
+const KB_MANIFEST_PATH = ".kb/manifest.json";
+const LEGACY_CONFIG_PATH = ".kb/config.json";
+function schemaVersionOf(text) {
+    if (text === null)
+        return null;
+    try {
+        const parsed = JSON.parse(text);
+        const raw = parsed?.schemaVersion;
+        return typeof raw === "number" || typeof raw === "string"
+            ? normalizeSchemaVersion(raw)
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * True when the staged commit carries a `kibi migrate` run: the staged
+ * `.kb/manifest.json` records a schema generation newer than the base, or the
+ * commit retires the legacy `.kb/config.json`. The audit record migrate writes
+ * under `.kb/migrations/` is ignored by Git, so the schema bump is the
+ * committed evidence; it cannot be repeated once a KB is at the latest schema,
+ * so it cannot be used to waive later edits.
+ *
+ * `readBase` and `readStaged` return a file's content in the base and the
+ * staged tree, or null when the file does not exist there.
+ */
+// implements REQ-cli-migration-first-commit
+export function stagedCommitCarriesMigration(readBase, readStaged) {
+    const staged = schemaVersionOf(readStaged(KB_MANIFEST_PATH));
+    if (staged === null)
+        return false;
+    const baseConfig = readBase(LEGACY_CONFIG_PATH);
+    if (baseConfig !== null && readStaged(LEGACY_CONFIG_PATH) === null)
+        return true;
+    const baseVersions = [
+        schemaVersionOf(readBase(KB_MANIFEST_PATH)),
+        schemaVersionOf(baseConfig),
+    ].filter((version) => version !== null);
+    return baseVersions.length === 0 || Math.min(...baseVersions) < staged;
+}

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

@@ -20,6 +20,11 @@ export interface StagedAuthoredSymbolsManifestEvidence {
         entityIds: string[];
     }>;
     changedEntityIds: string[];
+    /**
+     * Records whose only differences from the base are fields `kibi migrate`
+     * writes mechanically; set only for a commit that carries a migration.
+     */
+    migrationOnlyEntityIds?: string[];
 }
 export declare function parsedCoordinateOrNull(parse: () => ParsedCoordinateArtifact): ParsedCoordinateArtifact | null;
 export declare function manifestRecordSourcePath(record: {
@@ -37,5 +42,11 @@ export declare function collectStagedAuthoredSymbolsManifestEvidence(options: {
     sourceFiles: StagedFile[];
     stagedFiles: StagedFile[];
     readBaseFile?: (filePath: string) => string | null;
+    /**
+     * The commit carries a `kibi migrate` run: records it changed only in
+     * migration-owned fields are reported in `migrationOnlyEntityIds` instead
+     * of `changedEntityIds`.
+     */
+    ignoreMigrationOwnedEdits?: boolean;
 }): StagedAuthoredSymbolsManifestEvidence;
 //# sourceMappingURL=staged-symbols-manifest.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"staged-symbols-manifest.d.ts","sourceRoot":"","sources":["../../src/traceability/staged-symbols-manifest.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,oBAAoB,EAErB,MAAM,iBAAiB,CAAC;AAKzB,OAAO,EACL,KAAK,wBAAwB,EAG9B,MAAM,qCAAqC,CAAC;AAI7C,OAAO,KAAK,EAAE,mCAAmC,EAAE,MAAM,qBAAqB,CAAC;AAC/E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AA0ClD,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;IACb;;;;OAIG;IACH,WAAW,CAAC,EAAE,mCAAmC,EAAE,CAAC;CACrD;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;IAC5D,gBAAgB,EAAE,MAAM,EAAE,CAAC;CAC5B;AA6ED,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,MAAM,wBAAwB,GACpC,wBAAwB,GAAG,IAAI,CAOjC;AAED,wBAAgB,wBAAwB,CAAC,MAAM,EAAE;IAC/C,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB,GAAG,MAAM,GAAG,IAAI,CAMhB;AAoTD,wBAAgB,2BAA2B,CAAC,OAAO,EAAE;IACnD,mBAAmB,EAAE,MAAM,CAAC;IAC5B,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,YAAY,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;IACnD,aAAa,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,oBAAoB,CAAC;CAC7E,GAAG,+BAA+B,CAoLlC;AAED,wBAAgB,4CAA4C,CAAC,OAAO,EAAE;IACpE,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,YAAY,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;CACpD,GAAG,qCAAqC,CAqExC"}
+{"version":3,"file":"staged-symbols-manifest.d.ts","sourceRoot":"","sources":["../../src/traceability/staged-symbols-manifest.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,oBAAoB,EAErB,MAAM,iBAAiB,CAAC;AAMzB,OAAO,EACL,KAAK,wBAAwB,EAG9B,MAAM,qCAAqC,CAAC;AAI7C,OAAO,KAAK,EAAE,mCAAmC,EAAE,MAAM,qBAAqB,CAAC;AAC/E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AA0ClD,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;IACb;;;;OAIG;IACH,WAAW,CAAC,EAAE,mCAAmC,EAAE,CAAC;CACrD;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;IAC5D,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B;;;OAGG;IACH,sBAAsB,CAAC,EAAE,MAAM,EAAE,CAAC;CACnC;AA6ED,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,MAAM,wBAAwB,GACpC,wBAAwB,GAAG,IAAI,CAOjC;AAED,wBAAgB,wBAAwB,CAAC,MAAM,EAAE;IAC/C,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB,GAAG,MAAM,GAAG,IAAI,CAMhB;AA2VD,wBAAgB,2BAA2B,CAAC,OAAO,EAAE;IACnD,mBAAmB,EAAE,MAAM,CAAC;IAC5B,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,YAAY,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;IACnD,aAAa,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,oBAAoB,CAAC;CAC7E,GAAG,+BAA+B,CAoLlC;AAED,wBAAgB,4CAA4C,CAAC,OAAO,EAAE;IACpE,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,YAAY,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;IACnD;;;;OAIG;IACH,yBAAyB,CAAC,EAAE,OAAO,CAAC;CACrC,GAAG,qCAAqC,CA4ExC"}

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

@@ -1,5 +1,6 @@
 import { execFileSync } from "node:child_process";
 import * as path from "node:path";
+import { CONTEXT_MISSING_TAG } from "../entity-body-context.js";
 import { extractManifestSymbolRecordsString, } from "../extractors/manifest.js";
 import { mergeCoordinatesWithManifest, parseCoordinateArtifact as parseStrict, } from "../extractors/symbol-coordinates.js";
 import { analyzeSourceText } from "../extractors/symbols-coordinator.js";
@@ -199,21 +200,50 @@ function normalizeAuthoredManifestSymbolsForSourceFile(records, sourceFile) {
 function getAuthoredSymbolComparisonKey(symbol) {
     return symbol.id ?? `${symbol.sourceFile}:${symbol.title}`;
 }
-function getChangedAuthoredEntityIds(headSymbols, stagedSymbols) {
-    const headSignatures = new Map(headSymbols.map((symbol) => [
+/**
+ * The staged record with the edits `kibi migrate` makes mechanically undone
+ * against its base record: a `granularity_reason: legacy-link` the base did
+ * not have, and a `review:context-missing` tag the base did not carry. The
+ * other migration-owned fields (`origin`, a removed dead `source`, a pinned
+ * `semantic_text`) are not part of the authored symbol signature.
+ */
+// implements REQ-cli-migration-first-commit
+function withoutMigrationOwnedEdits(head, staged) {
+    return {
+        ...staged,
+        granularityReason: staged.granularityReason === "legacy-link" &&
+            head.granularityReason === null
+            ? null
+            : staged.granularityReason,
+        tags: staged.tags.filter((tag) => tag !== CONTEXT_MISSING_TAG || head.tags.includes(tag)),
+    };
+}
+function getChangedAuthoredEntityIds(headSymbols, stagedSymbols, ignoreMigrationOwnedEdits = false) {
+    const headByKey = new Map(headSymbols.map((symbol) => [
         getAuthoredSymbolComparisonKey(symbol),
-        JSON.stringify(symbol),
+        symbol,
     ]));
-    const changedIds = stagedSymbols.flatMap((symbol) => {
+    const changed = [];
+    const migrationOnly = [];
+    for (const symbol of stagedSymbols) {
         if (symbol.id === null)
-            return [];
-        const stagedSignature = JSON.stringify(symbol);
-        return headSignatures.get(getAuthoredSymbolComparisonKey(symbol)) ===
-            stagedSignature
-            ? []
-            : [symbol.id];
-    });
-    return uniqueSorted(changedIds);
+            continue;
+        const head = headByKey.get(getAuthoredSymbolComparisonKey(symbol));
+        if (head !== undefined && JSON.stringify(head) === JSON.stringify(symbol))
+            continue;
+        if (ignoreMigrationOwnedEdits &&
+            head !== undefined &&
+            JSON.stringify(head) ===
+                JSON.stringify(withoutMigrationOwnedEdits(head, symbol))) {
+            migrationOnly.push(symbol.id);
+            continue;
+        }
+        changed.push(symbol.id);
+    }
+    return {
+        changed: uniqueSorted(changed),
+        migrationOnly: uniqueSorted(migrationOnly),
+    };
 }
 function normalizeExpectedSymbolsForStagedFile(stagedFile, analyze, authoredTitles = new Set()) {
     const analysis = (analyze ?? analyzeSourceText)(stagedFile.path, stagedFile.content ?? "");
@@ -430,13 +460,14 @@ export function collectStagedAuthoredSymbolsManifestEvidence(options) {
                 : null;
         return sourceFile === null ? [] : [sourceFile];
     }));
+    const migrationOnlyEntityIds = new Set();
     const changedEntityIdsBySourcePath = new Map(sourcePaths.map((sourcePath) => {
         const headSymbols = normalizeAuthoredManifestSymbolsForSourceFile(headManifestRecords, sourcePath);
         const stagedSymbols = normalizeAuthoredManifestSymbolsForSourceFile(stagedManifestRecords, sourcePath);
-        return [
-            sourcePath,
-            getChangedAuthoredEntityIds(headSymbols, stagedSymbols),
-        ];
+        const { changed, migrationOnly } = getChangedAuthoredEntityIds(headSymbols, stagedSymbols, options.ignoreMigrationOwnedEdits === true);
+        for (const id of migrationOnly)
+            migrationOnlyEntityIds.add(id);
+        return [sourcePath, changed];
     }));
     const entries = [];
     for (const sourceFile of sourceFiles) {
@@ -449,5 +480,8 @@ export function collectStagedAuthoredSymbolsManifestEvidence(options) {
         path: paths.symbolsPath,
         entries,
         changedEntityIds: uniqueSorted(Array.from(changedEntityIdsBySourcePath.values()).flat()),
+        ...(migrationOnlyEntityIds.size > 0
+            ? { migrationOnlyEntityIds: uniqueSorted(migrationOnlyEntityIds) }
+            : {}),
     };
 }

package/dist/utils/rule-registry.generated.d.ts

@@ -243,6 +243,11 @@ export declare const GENERATED_RULES: readonly [{
     readonly description: "A requirement or ADR that supersedes a firm decision, retired or not, must itself be firm (and so carry a ref to the human who changed the rule); a default or exploratory replacement cannot overrule a firm decision";
     readonly enforcementClass: "canonical";
     readonly category: "lifecycle";
+}, {
+    readonly name: "decision-firm-edited";
+    readonly description: "A current requirement or ADR that was firm at HEAD must not have its claim (title, stated meaning, the statement its body derives, an ADR's body, or its firmness) changed in place unless the edit cites new human words (a changed origin.ref, or approval_ref on a requirement); supersede it with a firm decision instead";
+    readonly enforcementClass: "canonical";
+    readonly category: "lifecycle";
 }, {
     readonly name: "supersedes-reason-missing";
     readonly description: "A current requirement or ADR that supersedes another must explain why under a 'Why this changed' heading (at least 12 words of prose naming the evidence and answering the old decision's reasoning); supersede edges recorded before schema 9 are acknowledged in the manifest and exempt";

package/dist/utils/rule-registry.generated.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rule-registry.generated.d.ts","sourceRoot":"","sources":["../../src/utils/rule-registry.generated.ts"],"names":[],"mappings":"AAUA,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAgXlB,CAAC"}
+{"version":3,"file":"rule-registry.generated.d.ts","sourceRoot":"","sources":["../../src/utils/rule-registry.generated.ts"],"names":[],"mappings":"AAUA,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAuXlB,CAAC"}

package/dist/utils/rule-registry.generated.js

@@ -301,6 +301,12 @@ export const GENERATED_RULES = [
         enforcementClass: "canonical",
         category: "lifecycle",
     },
+    {
+        name: "decision-firm-edited",
+        description: "A current requirement or ADR that was firm at HEAD must not have its claim (title, stated meaning, the statement its body derives, an ADR's body, or its firmness) changed in place unless the edit cites new human words (a changed origin.ref, or approval_ref on a requirement); supersede it with a firm decision instead",
+        enforcementClass: "canonical",
+        category: "lifecycle",
+    },
     {
         name: "supersedes-reason-missing",
         description: "A current requirement or ADR that supersedes another must explain why under a 'Why this changed' heading (at least 12 words of prose naming the evidence and answering the old decision's reasoning); supersede edges recorded before schema 9 are acknowledged in the manifest and exempt",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-cli",
-  "version": "2.24.0",
+  "version": "2.26.1",
   "type": "module",
   "description": "Kibi CLI for knowledge base management",
   "engines": {
@@ -235,7 +235,7 @@
     "fast-glob": "^3.2.12",
     "gray-matter": "^4.0.3",
     "js-yaml": "^4.1.0",
-    "kibi-core": "^0.22.1",
+    "kibi-core": "^0.22.2",
     "kibi-plugin-builtin": "^0.5.2",
     "kibi-plugin-sdk": "^0.5.0",
     "kibi-swipl": "^1.0.1",

package/src/public/impact/analyzer.ts

@@ -32,6 +32,7 @@ import type {
   ChangedFileImpactOptions,
   ChangedFileImpactResult,
 } from "./types.js";
+import { createUnownedFileDiagnostics } from "./unowned-files.js";
 
 export async function analyzeChangedFileImpact(
   options: ChangedFileImpactOptions,
@@ -139,10 +140,27 @@ export async function analyzeChangedFileImpact(
       result.sourceFile !== undefined &&
       activeSourceFiles.has(result.sourceFile),
   );
+  const linkedSourceFiles = new Set(
+    manifestResults
+      .filter((result) =>
+        result.relationships.some((relationship) =>
+          isTraceabilityRelationshipType(relationship.type),
+        ),
+      )
+      .map((result) => result.sourceFile)
+      .filter((file): file is string => file !== undefined),
+  );
   const impactDiagnostics =
     options.includeImpactDiagnostics === false
       ? []
       : [
+          // Named files first: a file without links is the answer a scoped
+          // check most easily misreads as "no rule applies".
+          ...createUnownedFileDiagnostics({
+            workspaceRoot,
+            requestedFiles: [...filter],
+            linkedSourceFiles,
+          }),
           ...createSymbolGranularityDiagnostics({
             manifestResults: activeManifestResults,
             symbolsByFile,
@@ -157,13 +175,9 @@ export async function analyzeChangedFileImpact(
           ...createSemanticReviewDiagnostics({
             symbolsByFile,
             linkedSourceFiles: new Set(
-              activeManifestResults
-                .filter((result) =>
-                  result.relationships.some((relationship) =>
-                    isTraceabilityRelationshipType(relationship.type),
-                  ),
-                )
-                .map((result) => result.sourceFile as string),
+              [...linkedSourceFiles].filter((file) =>
+                activeSourceFiles.has(file),
+              ),
             ),
           }),
         ];

package/src/public/impact/diagnostics.ts

@@ -207,7 +207,7 @@ export function createSemanticReviewDiagnostics(
           ? `Changed behavioral symbol ${symbol.name} is in a file no requirement owns, so no recorded intent covers the behavior it has after this change`
           : `Changed behavioral symbol ${symbol.name} needs semantic review against linked Kibi coverage: ${linkedTargets}`,
         suggestion: unlinked
-          ? `If the change adds or alters behavior, record it with the change: kb_search({query:"<the behavior>", sourceLocations:[{path:"${file}"}]}) for a requirement that already describes it and link ${symbol.name} to it; if none does, kb_upsert a requirement with a scenario and link the symbol with implements. If behavior is unchanged (a refactor, renaming), say so in the final report instead.`
+          ? `If the change adds or alters behavior, record it as part of this change; that is part of finishing it, not a separate request, so it needs no permission: kb_search({query:"<the behavior>", sourceLocations:[{path:"${file}"}]}) for a requirement that already describes it and link ${symbol.name} to it; if none does, kb_upsert a requirement with a scenario and link the symbol with implements. If behavior is unchanged (a refactor, renaming), say so in the final report instead.`
           : `Use kb_search and kb_query for ${file}, then verify that ${linkedTargets} actually describe and test the changed behavior or UI copy. Update Kibi links or requirements/tests while the edit context is fresh.`,
       });
     }

package/src/public/impact/unowned-files.ts

@@ -0,0 +1,229 @@
+import { closeSync, openSync, readSync, readdirSync } from "node:fs";
+import * as path from "node:path";
+import type { KibiImpactDiagnostic } from "../../traceability/staged-diagnostics.js";
+
+/**
+ * A file `kb_check` was asked about that no symbol links to a requirement.
+ * No link is not no rule, so the check says so and names the current
+ * requirements whose titles share the file's path words: candidates to
+ * confirm, never owners. Kibi's hooks name the same candidates before an edit
+ * (kibi-agent-core `requirement-candidates`), with the same word rules.
+ */
+
+const REQUIREMENTS_DIR = path.join(".kb", "requirements");
+const HEAD_BYTES = 4096;
+const MAX_CANDIDATES = 3;
+const MAX_TITLE = 100;
+
+/** Path words that name a layout, a language or a role, not a behavior. */
+const LAYOUT_WORDS = new Set(
+  (
+    "src app apps lib libs source page pages component components view views " +
+    "screen screens package packages main index shared common core util utils " +
+    "helper helpers public static asset assets web client server frontend " +
+    "backend module modules feature features internal service services test " +
+    "tests spec specs dist build html htm tsx jsx mjs cjs vue svelte css scss " +
+    "less json yaml yml java swift php"
+  ).split(" "),
+);
+
+/** Words of a title or path that carry no topic. */
+const FILLER_WORDS = new Set(
+  (
+    "the and for with must should shall may can are its their that this " +
+    "from into when each every all not req auto"
+  ).split(" "),
+);
+
+const RETIRED_STATUS =
+  /supersed|deprecat|reject|obsolete|retired|archived|removed/i;
+
+/** Lowercase word stems of an identifier, path segment or title. */
+function words(text: string): string[] {
+  return text
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .toLowerCase()
+    .split(/[^a-z0-9]+/)
+    .filter((word) => word.length >= 3 && !/\d/.test(word))
+    .map((word) =>
+      word.length > 4 && word.endsWith("s") && !word.endsWith("ss")
+        ? word.slice(0, -1)
+        : word,
+    );
+}
+
+// implements REQ-kb-unowned-file-candidates
+/**
+ * The topic words of a workspace path, without layout, language and role
+ * words (`src/app/pages/coach-dashboard/coach-dashboard.html` -> `coach`,
+ * `dashboard`).
+ */
+export function pathTopicWords(relativePath: string): string[] {
+  const segments = relativePath.split(/[\\/]/).filter(Boolean);
+  const last = segments.pop() ?? "";
+  const dot = last.indexOf(".");
+  const parts = dot >= 0 ? [last.slice(0, dot), last.slice(dot + 1)] : [last];
+  const found = [...segments, ...parts]
+    .flatMap(words)
+    .filter((word) => !LAYOUT_WORDS.has(word) && !FILLER_WORDS.has(word));
+  return [...new Set(found)];
+}
+
+// implements REQ-kb-unowned-file-candidates
+export type RequirementCandidate = {
+  readonly id: string;
+  readonly title: string;
+  readonly status?: string;
+};
+
+// implements REQ-kb-unowned-file-candidates
+/**
+ * Current requirements ranked by how many of the path's topic words their
+ * title shares, then by how often the title uses them, then by id; only
+ * those sharing at least one word.
+ */
+export function rankRequirementCandidates(
+  relativePath: string,
+  requirements: readonly RequirementCandidate[],
+  limit: number = MAX_CANDIDATES,
+): RequirementCandidate[] {
+  const topic = new Set(pathTopicWords(relativePath));
+  if (topic.size === 0) return [];
+  const scored: {
+    requirement: RequirementCandidate;
+    shared: number;
+    uses: number;
+  }[] = [];
+  for (const requirement of requirements) {
+    if (
+      requirement.status !== undefined &&
+      RETIRED_STATUS.test(requirement.status)
+    )
+      continue;
+    const matched = words(requirement.title).filter((word) => topic.has(word));
+    const shared = new Set(matched).size;
+    if (shared > 0) scored.push({ requirement, shared, uses: matched.length });
+  }
+  scored.sort(
+    (a, b) =>
+      b.shared - a.shared ||
+      b.uses - a.uses ||
+      a.requirement.id.localeCompare(b.requirement.id),
+  );
+  return scored.slice(0, limit).map((entry) => entry.requirement);
+}
+
+function unquote(value: string): string {
+  const trimmed = value.trim();
+  return /^(["']).*\1$/.test(trimmed) ? trimmed.slice(1, -1) : trimmed;
+}
+
+function readRequirementHead(file: string): RequirementCandidate | undefined {
+  let head: string;
+  try {
+    const descriptor = openSync(file, "r");
+    try {
+      const buffer = Buffer.alloc(HEAD_BYTES);
+      const bytes = readSync(descriptor, buffer, 0, buffer.length, 0);
+      head = buffer.subarray(0, bytes).toString("utf8");
+    } finally {
+      closeSync(descriptor);
+    }
+  } catch {
+    return undefined;
+  }
+  const lines = head.split(/\r?\n/);
+  if (lines[0]?.trim() !== "---") return undefined;
+  const fields: Record<string, string> = {};
+  for (const line of lines.slice(1)) {
+    if (line.trim() === "---") break;
+    const match = /^(id|title|status):\s*(.+)$/.exec(line);
+    if (match?.[1] && match[2]) fields[match[1]] = unquote(match[2]);
+  }
+  if (!fields.id || !fields.title) return undefined;
+  return {
+    id: fields.id,
+    title: fields.title,
+    ...(fields.status ? { status: fields.status } : {}),
+  };
+}
+
+function readRequirementHeads(workspaceRoot: string): RequirementCandidate[] {
+  const directory = path.join(workspaceRoot, REQUIREMENTS_DIR);
+  let names: string[];
+  try {
+    names = readdirSync(directory).filter((name) => name.endsWith(".md"));
+  } catch {
+    return [];
+  }
+  return names
+    .map((name) => readRequirementHead(path.join(directory, name)))
+    .filter(
+      (requirement): requirement is RequirementCandidate =>
+        requirement !== undefined,
+    );
+}
+
+function truncate(text: string, limit: number): string {
+  return text.length > limit ? `${text.slice(0, limit - 1)}…` : text;
+}
+
+/** Files the unowned note does not apply to: the KB itself and prose. */
+function isKnowledgeOrProse(file: string): boolean {
+  return file.startsWith(".kb/") || /\.mdx?$/i.test(file);
+}
+
+// implements REQ-kb-unowned-file-candidates
+export type UnownedFileDiagnosticsOptions = {
+  readonly workspaceRoot: string;
+  /** Workspace-relative files the check was asked about. */
+  readonly requestedFiles: readonly string[];
+  /** Files where some manifest symbol carries a traceability link. */
+  readonly linkedSourceFiles: ReadonlySet<string>;
+};
+
+// implements REQ-kb-unowned-file-candidates
+/**
+ * One `source_file_unowned` note per requested file without a linked symbol,
+ * naming the current requirements whose titles share its path words.
+ */
+export function createUnownedFileDiagnostics(
+  options: UnownedFileDiagnosticsOptions,
+): KibiImpactDiagnostic[] {
+  const files = [...new Set(options.requestedFiles)].filter(
+    (file) => !options.linkedSourceFiles.has(file) && !isKnowledgeOrProse(file),
+  );
+  if (files.length === 0) return [];
+  const requirements = readRequirementHeads(options.workspaceRoot);
+  return files.map((file) => {
+    const candidates = rankRequirementCandidates(file, requirements);
+    const named = candidates
+      .map(
+        (candidate) =>
+          `${candidate.id} (${truncate(candidate.title, MAX_TITLE)})`,
+      )
+      .join("; ");
+    const lead = `No symbol in ${file} is linked to a requirement, so this check finds no owner for it; that does not mean no recorded rule covers the behavior it implements.`;
+    const record =
+      "If none does and the change adds behavior, record a requirement with a scenario and link it with implements as part of this change; if behavior is unchanged, say so in the final report.";
+    return {
+      id: "source_file_unowned",
+      severity: "info",
+      blocking: false,
+      category: "requirement",
+      files: [file],
+      docs: ["docs/symbol-traceability-taxonomy.md"],
+      message:
+        candidates.length > 0
+          ? `${lead} Requirements whose titles share its path words: ${named}.`
+          : lead,
+      suggestion:
+        candidates.length > 0
+          ? `kb_query each candidate to see whether it describes the changed behavior; when one does, link the symbol that implements it (for markup, the component that renders it) with implements and name the requirement in the final report. ${record}`
+          : `kb_search({query:"<the behavior>", sourceLocations:[{path:${JSON.stringify(file)}}]}) for a requirement that already describes it. ${record}`,
+      evidence: {
+        candidates: candidates.map(({ id, title }) => ({ id, title })),
+      },
+    };
+  });
+}