kibi-cli 2.21.2 → 2.22.0

package/dist/public/operations/migration-plan.js

@@ -261,14 +261,80 @@ function predicateSchemaAlignmentAction(diagnostic) {
 }
 /** Migration code for mechanical predicate namespace/alias repairs. */
 export const PREDICATE_SCHEMA_ALIGNMENT_CODE = "predicate_schema_alignment";
+/** Migration code of the grouped untracked-source parity findings. */
+export const UNTRACKED_KNOWLEDGE_SOURCES_CODE = "untracked_knowledge_sources";
+/**
+ * Every source-relationship-parity finding explained by untracked files
+ * (evidence `untrackedSources`) has one cause and one fix: the files Git
+ * does not track and no pending-source receipt covers. After a storage move
+ * that can be thousands of relationships, so they become one review action
+ * naming the files instead of one per relationship.
+ */
+// implements REQ-agent-guided-migration-orchestration, REQ-kibi-source-relationship-parity
+function untrackedSourceActionFromViolations(violations) {
+    const consumed = new Set();
+    const files = new Set();
+    const entityIds = new Set();
+    const relationships = [];
+    for (const [index, violation] of violations.entries()) {
+        if (violation.rule !== "source-relationship-parity")
+            continue;
+        const evidence = isRecord(violation.evidence) ? violation.evidence : {};
+        const sources = Array.isArray(evidence.untrackedSources)
+            ? evidence.untrackedSources.filter(isRecord)
+            : [];
+        if (sources.length === 0)
+            continue;
+        consumed.add(index);
+        for (const source of sources) {
+            if (typeof source.file === "string")
+                files.add(source.file);
+            if (typeof source.entityId === "string")
+                entityIds.add(source.entityId);
+        }
+        if (evidence.relationship !== undefined)
+            relationships.push(evidence.relationship);
+    }
+    if (consumed.size === 0)
+        return null;
+    const listed = [...files].sort();
+    return {
+        consumed,
+        action: migrationAction({
+            id: "untracked-knowledge-sources",
+            code: UNTRACKED_KNOWLEDGE_SOURCES_CODE,
+            category: "relationship",
+            safety: "review",
+            invocation: {
+                kind: "review",
+                instruction: `${consumed.size} authored relationship(s) are missing from the compiled KB because ${listed.length} file(s) declaring their endpoints are not tracked by Git and no pending-source receipt covers them: ${listed.join(", ")}. Stage them (git add; staging is enough, Kibi never stages files itself) or rewrite the entities with kb_upsert, then run kibi sync and rerun kibi migrate.`,
+            },
+            affectedEntityIds: [...entityIds],
+            affectedFiles: listed,
+            postconditions: [{ rule: "source-relationship-parity", findings: 0 }],
+            evidence: {
+                relationshipCount: consumed.size,
+                files: listed,
+                // A sample; the count above is the full number.
+                relationships: relationships.slice(0, 20),
+            },
+            dispositionRequired: true,
+        }),
+    };
+}
 // implements REQ-agent-guided-migration-orchestration, REQ-kibi-predicate-vocabulary-migration, REQ-cli-schema-migration
 export function buildActionsFromCheck(input) {
     const actions = [];
     const lifecycle = lifecycleActionsFromViolations(input.violations ?? []);
     actions.push(...lifecycle.actions.map(migrationAction));
+    const untracked = untrackedSourceActionFromViolations(input.violations ?? []);
+    if (untracked !== null)
+        actions.push(untracked.action);
     for (const [index, violation] of (input.violations ?? []).entries()) {
         if (lifecycle.consumed.has(index))
             continue;
+        if (untracked?.consumed.has(index))
+            continue;
         const rule = typeof violation.rule === "string" ? violation.rule : "check";
         const entityId = typeof violation.entityId === "string" ? violation.entityId : "";
         const suggestion = typeof violation.suggestion === "string"
@@ -442,6 +508,17 @@ function readLegacySchemaVersion(workspaceRoot) {
 // implements REQ-agent-guided-migration-orchestration
 /** Migration action code of the automatic recompile of changed sources. */
 export const FRESHNESS_RESYNC = "freshness_resync";
+// implements REQ-cli-status-pre-first-sync
+/**
+ * Stale reasons one `kibi sync` clears: sources whose content changed since
+ * the last compilation, and a store compiled under another compiler contract
+ * (the sync discards that cache, re-imports every source and stamps the
+ * current contract).
+ */
+const RESYNC_REASON_CODES = new Set([
+    ...MTIME_SOURCE_REASON_CODES,
+    "compiler_changed",
+]);
 export function buildActionsFromStatus(input) {
     const actions = [];
     const attachment = input.branchAttachment;
@@ -488,14 +565,19 @@ export function buildActionsFromStatus(input) {
         }));
     }
     const storeState = typeof store?.state === "string" ? store.state : null;
-    const legacyStorageMigrationRequired = legacyConfigExists(input.workspaceRoot);
+    // Legacy storage is evaluated whether or not the legacy config survives:
+    // legacy copies left beside a migrated .kb/ (moved, identical or stale)
+    // are the same finding 'kibi doctor' and 'kibi migrate' report.
+    // implements REQ-cli-schema-migration
+    const legacyStorage = planLegacyStorageMigration(input.workspaceRoot);
+    const legacyStorageMigrationRequired = legacyConfigExists(input.workspaceRoot) ||
+        legacyStorage.moves.length > 0 ||
+        legacyStorage.removals.length > 0 ||
+        legacyStorage.blockers.length > 0;
     // A legacy cutover that cannot move its files (a destination already
     // exists, a malformed config) is an operator decision, not an automatic
     // step that fails when applied and takes the compile with it.
-    const legacyStorage = legacyStorageMigrationRequired
-        ? planLegacyStorageMigration(input.workspaceRoot)
-        : null;
-    const legacyStorageBlocked = legacyStorage !== null && legacyStorage.blockers.length > 0;
+    const legacyStorageBlocked = legacyStorage.blockers.length > 0;
     if (storeState === "missing") {
         actions.push(migrationAction({
             id: "branch-store-ensure",
@@ -542,26 +624,29 @@ export function buildActionsFromStatus(input) {
             invocation: legacyStorageBlocked
                 ? {
                     kind: "review",
-                    instruction: `The legacy .kb/config.json still names knowledge files outside .kb/ and Kibi cannot move them: ${legacyStorage?.blockers.join(" ")} Compare each legacy copy with its .kb/ copy and keep the current one: replace the .kb/ copy when the legacy one is newer, or remove (git rm) the legacy copy when it is a stale duplicate. Then run 'kibi migrate --yes' to retire .kb/config.json.`,
+                    instruction: `Legacy knowledge files outside .kb/ cannot be migrated automatically: ${legacyStorage.blockers.join(" ")} Then run 'kibi migrate --yes'.`,
                 }
                 : { kind: "cli", command_argv: ["kibi", "migrate", "--yes"] },
             affectedFiles: [
                 ".kb/manifest.json",
                 ".kb/migrations",
                 ".kb/config.json",
-                ...(legacyStorage?.moves.map((move) => move.from) ?? []),
+                ...legacyStorage.moves.map((move) => move.from),
+                ...legacyStorage.removals.map((removal) => removal.path),
             ],
             evidence: {
                 configStatus,
-                ...(legacyStorage === null
-                    ? {}
-                    : {
+                ...(legacyStorageMigrationRequired
+                    ? {
                         legacyStorage: {
                             moves: legacyStorage.moves,
+                            removals: legacyStorage.removals,
+                            conflicts: legacyStorage.conflicts,
                             blockers: legacyStorage.blockers,
                             legacyConfig: legacyStorage.legacyConfig,
                         },
-                    }),
+                    }
+                    : {}),
             },
             dependsOn: storeState === "missing" ? ["branch-store-ensure"] : [],
             autoApplicable: !operatorOnly,
@@ -598,10 +683,10 @@ export function buildActionsFromStatus(input) {
     // implements REQ-cli-status-pre-first-sync
     // Sources whose content changed since the last compilation (kb_status has
     // already dropped mtime-only reasons) are fixed by recompiling them: one
-    // automatic `kibi sync`, not a review per file. An uncompiled store is
-    // compiled by the step above, which also covers these files.
-    const resyncReasons = (input.staleReasons ?? []).filter((reason) => typeof reason.code === "string" &&
-        MTIME_SOURCE_REASON_CODES.has(reason.code));
+    // automatic `kibi sync`, not a review per file. A store compiled under
+    // another compiler contract is fixed by the same sync. An uncompiled store
+    // is compiled by the step above, which also covers these reasons.
+    const resyncReasons = (input.staleReasons ?? []).filter((reason) => typeof reason.code === "string" && RESYNC_REASON_CODES.has(reason.code));
     if (resyncReasons.length > 0 && uncompiled === undefined) {
         actions.push(migrationAction({
             id: "freshness-resync",
@@ -626,7 +711,7 @@ export function buildActionsFromStatus(input) {
         if (code === BRANCH_STORE_NOT_COMPILED)
             continue;
         // Planned above as one automatic resync (or covered by the compile).
-        if (MTIME_SOURCE_REASON_CODES.has(code))
+        if (RESYNC_REASON_CODES.has(code))
             continue;
         const file = typeof reason.path === "string" ? reason.path : "";
         actions.push(migrationAction({

package/dist/public/operations/result-envelope.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"result-envelope.d.ts","sourceRoot":"","sources":["../../../src/public/operations/result-envelope.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE7E,eAAO,MAAM,qBAAqB,EAAG,CAAU,CAAC;AAoChD,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,eAAe,EACvB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,UAAU,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,CAS/B;AAoFD,wBAAgB,aAAa,CAAC,IAAI,EAAE;IAClC,QAAQ,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,CAAC;IACtC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC,GAAG,MAAM,CAET;AAYD,wBAAgB,YAAY,CAAC,CAAC,EAC5B,IAAI,EAAE;IACJ,QAAQ,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,CAAC;IACtC,QAAQ,CAAC,OAAO,EAAE,SAAS,eAAe,EAAE,CAAC;IAC7C,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC,EACD,IAAI,EAAE,CAAC,EACP,OAAO,GAAE,OAAO,CACd,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,QAAQ,GAAG,aAAa,GAAG,aAAa,GAAG,OAAO,CAAC,CACxE,GAAG;IACF;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;CACzB,GACL,UAAU,CAAC,CAAC,CAAC,CAmDf;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAKrD;AAGD,MAAM,WAAW,uBAAuB;IACtC,sEAAsE;IACtE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC5C,2EAA2E;IAC3E,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACzC;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,OAAO,GACd,uBAAuB,CAYzB;AAaD;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAC3C,IAAI,CAKN"}
+{"version":3,"file":"result-envelope.d.ts","sourceRoot":"","sources":["../../../src/public/operations/result-envelope.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE7E,eAAO,MAAM,qBAAqB,EAAG,CAAU,CAAC;AAkEhD,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,eAAe,EACvB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,UAAU,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,CAS/B;AAoFD,wBAAgB,aAAa,CAAC,IAAI,EAAE;IAClC,QAAQ,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,CAAC;IACtC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC,GAAG,MAAM,CAET;AAYD,wBAAgB,YAAY,CAAC,CAAC,EAC5B,IAAI,EAAE;IACJ,QAAQ,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,CAAC;IACtC,QAAQ,CAAC,OAAO,EAAE,SAAS,eAAe,EAAE,CAAC;IAC7C,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC,EACD,IAAI,EAAE,CAAC,EACP,OAAO,GAAE,OAAO,CACd,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,QAAQ,GAAG,aAAa,GAAG,aAAa,GAAG,OAAO,CAAC,CACxE,GAAG;IACF;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;CACzB,GACL,UAAU,CAAC,CAAC,CAAC,CAsDf;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAKrD;AAGD,MAAM,WAAW,uBAAuB;IACtC,sEAAsE;IACtE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC5C,2EAA2E;IAC3E,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACzC;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,OAAO,GACd,uBAAuB,CAYzB;AAaD;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAC3C,IAAI,CAKN"}

package/dist/public/operations/result-envelope.js

@@ -14,6 +14,29 @@ function diagnostics(value) {
         return [entry];
     });
 }
+// Discovery operations whose empty answer may come from an uncompiled store.
+const STORE_READ_OPERATIONS = new Set(["kb_search", "kb_query"]);
+/**
+ * A search or query answered from a branch store that was never compiled
+ * reads an empty KB. The payload already names the store state; the envelope
+ * also raises it as a warning, so a caller that reads only `status` and
+ * `diagnostics` does not take the empty answer as "nothing governs this".
+ */
+// implements REQ-cli-status-pre-first-sync, REQ-mcp-search-discovery
+function uncompiledStoreDiagnostics(operation, row) {
+    const store = row?.branchStore;
+    if (!STORE_READ_OPERATIONS.has(operation) ||
+        !record(store) ||
+        store.state !== "not_compiled")
+        return [];
+    return [
+        {
+            ...(typeof store.code === "string" ? { code: store.code } : {}),
+            severity: "warning",
+            message: `${typeof store.detail === "string" ? `${store.detail} ` : ""}An empty answer here does not mean no requirement governs this; run \`kibi sync\` and ask again.`,
+        },
+    ];
+}
 function nextActions(value) {
     if (!Array.isArray(value))
         return [];
@@ -152,7 +175,10 @@ export function toKibiResult(spec, data, options = {}) {
             ...spec.effects.map((effect) => effectStatus(effect, row, outcome)),
             ...extraFailedEffects(spec.effects, row),
         ],
-        diagnostics: options.diagnostics ?? diagnostics(row?.diagnostics),
+        diagnostics: options.diagnostics ?? [
+            ...diagnostics(row?.diagnostics),
+            ...uncompiledStoreDiagnostics(String(spec.name), row),
+        ],
         nextActions: options.nextActions ?? nextActions(row?.nextActions),
         ...(resultError ? { error: resultError } : {}),
     };

package/dist/public/operations/specs/check-rules.generated.d.ts

@@ -1,5 +1,5 @@
 /** Every selectable kb_check rule name, registry order. */
 export declare const SELECTABLE_RULE_NAMES: readonly string[];
 /** Comma-separated "Allowed:" fragment for the kb_check rules description. */
-export declare const SELECTABLE_RULES_ALLOWED = "must-priority-coverage, symbol-coverage, symbol-traceability, no-dangling-refs, source-relationship-parity, branch-store-not-compiled, source-path-dangling, no-cycles, required-fields, deprecated-adr-no-successor, superseded-requirement-open, scenario-feasibility, scenario-feasibility-unknown, exception-claim-keys, numeric-string-value, rule-key-arguments-missing, domain-contradictions, logic-coverage, rule-safety, rule-verifiability, query-plan-safety, req-status-vocabulary, strict-fact-shape, strict-req-fact-pairing, predicate-verifiability, strict-readiness, semantic-completeness, related-requirement-unmodeled, proof-contract-symbols, entity-id-style, domain-redundancy, domain-implication, subject-key-identity, subject-key-shape, ontology-quality, exception-unapproved, exception-approval-self-attested, agent-requirement-unapproved, requirement-rationale-missing, symbol-owner-superseded, adr-unlinked, adr-proposed, predicate-schema-conformance, entity-context-missing, entity-context-acknowledged, decision-firm-unreferenced, decision-firm-superseded, supersedes-reason-missing, supersedes-reason-acknowledged, policy-ownership, policy-markers";
+export declare const SELECTABLE_RULES_ALLOWED = "must-priority-coverage, symbol-coverage, symbol-traceability, symbol-granularity, no-dangling-refs, source-relationship-parity, branch-store-not-compiled, source-path-dangling, no-cycles, required-fields, deprecated-adr-no-successor, superseded-requirement-open, scenario-feasibility, scenario-feasibility-unknown, exception-claim-keys, numeric-string-value, rule-key-arguments-missing, domain-contradictions, logic-coverage, rule-safety, rule-verifiability, query-plan-safety, req-status-vocabulary, strict-fact-shape, strict-req-fact-pairing, predicate-verifiability, strict-readiness, semantic-completeness, related-requirement-unmodeled, proof-contract-symbols, entity-id-style, domain-redundancy, domain-implication, subject-key-identity, subject-key-shape, ontology-quality, exception-unapproved, exception-approval-self-attested, agent-requirement-unapproved, requirement-rationale-missing, symbol-owner-superseded, adr-unlinked, adr-proposed, predicate-schema-conformance, entity-context-missing, entity-context-acknowledged, decision-firm-unreferenced, decision-firm-superseded, supersedes-reason-missing, supersedes-reason-acknowledged, policy-ownership, policy-markers";
 //# sourceMappingURL=check-rules.generated.d.ts.map

package/dist/public/operations/specs/check-rules.generated.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"check-rules.generated.d.ts","sourceRoot":"","sources":["../../../../src/public/operations/specs/check-rules.generated.ts"],"names":[],"mappings":"AAUA,2DAA2D;AAC3D,eAAO,MAAM,qBAAqB,EAAE,SAAS,MAAM,EAoDlD,CAAC;AAGF,8EAA8E;AAC9E,eAAO,MAAM,wBAAwB,4oCACsmC,CAAC"}
+{"version":3,"file":"check-rules.generated.d.ts","sourceRoot":"","sources":["../../../../src/public/operations/specs/check-rules.generated.ts"],"names":[],"mappings":"AAUA,2DAA2D;AAC3D,eAAO,MAAM,qBAAqB,EAAE,SAAS,MAAM,EAqDlD,CAAC;AAGF,8EAA8E;AAC9E,eAAO,MAAM,wBAAwB,gqCAC0nC,CAAC"}

package/dist/public/operations/specs/check-rules.generated.js

@@ -12,6 +12,7 @@ export const SELECTABLE_RULE_NAMES = [
     "must-priority-coverage",
     "symbol-coverage",
     "symbol-traceability",
+    "symbol-granularity",
     "no-dangling-refs",
     "source-relationship-parity",
     "branch-store-not-compiled",
@@ -63,4 +64,4 @@ export const SELECTABLE_RULE_NAMES = [
 ];
 // implements REQ-006
 /** Comma-separated "Allowed:" fragment for the kb_check rules description. */
-export const SELECTABLE_RULES_ALLOWED = "must-priority-coverage, symbol-coverage, symbol-traceability, no-dangling-refs, source-relationship-parity, branch-store-not-compiled, source-path-dangling, no-cycles, required-fields, deprecated-adr-no-successor, superseded-requirement-open, scenario-feasibility, scenario-feasibility-unknown, exception-claim-keys, numeric-string-value, rule-key-arguments-missing, domain-contradictions, logic-coverage, rule-safety, rule-verifiability, query-plan-safety, req-status-vocabulary, strict-fact-shape, strict-req-fact-pairing, predicate-verifiability, strict-readiness, semantic-completeness, related-requirement-unmodeled, proof-contract-symbols, entity-id-style, domain-redundancy, domain-implication, subject-key-identity, subject-key-shape, ontology-quality, exception-unapproved, exception-approval-self-attested, agent-requirement-unapproved, requirement-rationale-missing, symbol-owner-superseded, adr-unlinked, adr-proposed, predicate-schema-conformance, entity-context-missing, entity-context-acknowledged, decision-firm-unreferenced, decision-firm-superseded, supersedes-reason-missing, supersedes-reason-acknowledged, policy-ownership, policy-markers";
+export const SELECTABLE_RULES_ALLOWED = "must-priority-coverage, symbol-coverage, symbol-traceability, symbol-granularity, no-dangling-refs, source-relationship-parity, branch-store-not-compiled, source-path-dangling, no-cycles, required-fields, deprecated-adr-no-successor, superseded-requirement-open, scenario-feasibility, scenario-feasibility-unknown, exception-claim-keys, numeric-string-value, rule-key-arguments-missing, domain-contradictions, logic-coverage, rule-safety, rule-verifiability, query-plan-safety, req-status-vocabulary, strict-fact-shape, strict-req-fact-pairing, predicate-verifiability, strict-readiness, semantic-completeness, related-requirement-unmodeled, proof-contract-symbols, entity-id-style, domain-redundancy, domain-implication, subject-key-identity, subject-key-shape, ontology-quality, exception-unapproved, exception-approval-self-attested, agent-requirement-unapproved, requirement-rationale-missing, symbol-owner-superseded, adr-unlinked, adr-proposed, predicate-schema-conformance, entity-context-missing, entity-context-acknowledged, decision-firm-unreferenced, decision-firm-superseded, supersedes-reason-missing, supersedes-reason-acknowledged, policy-ownership, policy-markers";

package/dist/public/operations/specs/check.d.ts

@@ -12,7 +12,7 @@ export declare const checkSpec: {
                     readonly type: "string";
                     readonly enum: readonly string[];
                 };
-                readonly description: "Optional rule subset. Allowed: must-priority-coverage, symbol-coverage, symbol-traceability, no-dangling-refs, source-relationship-parity, branch-store-not-compiled, source-path-dangling, no-cycles, required-fields, deprecated-adr-no-successor, superseded-requirement-open, scenario-feasibility, scenario-feasibility-unknown, exception-claim-keys, numeric-string-value, rule-key-arguments-missing, domain-contradictions, logic-coverage, rule-safety, rule-verifiability, query-plan-safety, req-status-vocabulary, strict-fact-shape, strict-req-fact-pairing, predicate-verifiability, strict-readiness, semantic-completeness, related-requirement-unmodeled, proof-contract-symbols, entity-id-style, domain-redundancy, domain-implication, subject-key-identity, subject-key-shape, ontology-quality, exception-unapproved, exception-approval-self-attested, agent-requirement-unapproved, requirement-rationale-missing, symbol-owner-superseded, adr-unlinked, adr-proposed, predicate-schema-conformance, entity-context-missing, entity-context-acknowledged, decision-firm-unreferenced, decision-firm-superseded, supersedes-reason-missing, supersedes-reason-acknowledged, policy-ownership, policy-markers. If omitted, server runs canonical and advisory rules plus the full-KB qualityDiagnostics audit scan, including usage telemetry acceptance when evidence exists; migration rules run only when explicitly selected. Advisory and migration findings are non-blocking qualityDiagnostics. If supplied, server preserves scoped validation and skips the full-KB advisory scan.";
+                readonly description: "Optional rule subset. Allowed: must-priority-coverage, symbol-coverage, symbol-traceability, symbol-granularity, no-dangling-refs, source-relationship-parity, branch-store-not-compiled, source-path-dangling, no-cycles, required-fields, deprecated-adr-no-successor, superseded-requirement-open, scenario-feasibility, scenario-feasibility-unknown, exception-claim-keys, numeric-string-value, rule-key-arguments-missing, domain-contradictions, logic-coverage, rule-safety, rule-verifiability, query-plan-safety, req-status-vocabulary, strict-fact-shape, strict-req-fact-pairing, predicate-verifiability, strict-readiness, semantic-completeness, related-requirement-unmodeled, proof-contract-symbols, entity-id-style, domain-redundancy, domain-implication, subject-key-identity, subject-key-shape, ontology-quality, exception-unapproved, exception-approval-self-attested, agent-requirement-unapproved, requirement-rationale-missing, symbol-owner-superseded, adr-unlinked, adr-proposed, predicate-schema-conformance, entity-context-missing, entity-context-acknowledged, decision-firm-unreferenced, decision-firm-superseded, supersedes-reason-missing, supersedes-reason-acknowledged, policy-ownership, policy-markers. If omitted, server runs canonical and advisory rules plus the full-KB qualityDiagnostics audit scan, including usage telemetry acceptance when evidence exists; migration rules run only when explicitly selected. Advisory and migration findings are non-blocking qualityDiagnostics. If supplied, server preserves scoped validation and skips the full-KB advisory scan.";
             };
             readonly sourceFiles: {
                 readonly type: "array";

package/dist/public/operations/specs/planning.d.ts

@@ -270,7 +270,7 @@ export declare const applyPlanSpec: {
             readonly plan: {
                 readonly type: "object";
                 readonly required: readonly ["version", "planHash"];
-                readonly description: "The complete kibi.bootstrap-plan.v1, kibi.compile-plan.v1, kibi.migration-plan.v2, or hash-bound kibi.entity-deletion-plan.v1 object. Migration plans require approvedActionIds and reject blocked/non-automatic actions.";
+                readonly description: "The complete kibi.bootstrap-plan.v1, kibi.compile-plan.v1, kibi.migration-plan.v2, or hash-bound kibi.entity-deletion-plan.v1 object. Migration plans require approvedActionIds and reject blocked actions and review actions Kibi cannot execute.";
             };
             readonly approvedActionIds: {
                 readonly type: "array";
@@ -278,7 +278,7 @@ export declare const applyPlanSpec: {
                     readonly type: "string";
                     readonly minLength: 1;
                 };
-                readonly description: "Required for migration-plan.v2. Exact automatic action IDs explicitly approved for this application.";
+                readonly description: "Required for migration-plan.v2. Exact action IDs explicitly approved for this application: automatic actions, or review actions with a cli invocation that Kibi executes only when approved by id (for example semantic_inventory_rederive_drop_grounding).";
             };
             readonly recoveryJournalId: {
                 readonly type: "string";

package/dist/public/operations/specs/planning.js

@@ -188,12 +188,12 @@ export const applyPlanSpec = {
             plan: {
                 type: "object",
                 required: ["version", "planHash"],
-                description: "The complete kibi.bootstrap-plan.v1, kibi.compile-plan.v1, kibi.migration-plan.v2, or hash-bound kibi.entity-deletion-plan.v1 object. Migration plans require approvedActionIds and reject blocked/non-automatic actions.",
+                description: "The complete kibi.bootstrap-plan.v1, kibi.compile-plan.v1, kibi.migration-plan.v2, or hash-bound kibi.entity-deletion-plan.v1 object. Migration plans require approvedActionIds and reject blocked actions and review actions Kibi cannot execute.",
             },
             approvedActionIds: {
                 type: "array",
                 items: { type: "string", minLength: 1 },
-                description: "Required for migration-plan.v2. Exact automatic action IDs explicitly approved for this application.",
+                description: "Required for migration-plan.v2. Exact action IDs explicitly approved for this application: automatic actions, or review actions with a cli invocation that Kibi executes only when approved by id (for example semantic_inventory_rederive_drop_grounding).",
             },
             recoveryJournalId: {
                 type: "string",

package/dist/public/operations/symbol-granularity-check.d.ts

@@ -0,0 +1,18 @@
+import type { Violation } from "../../utils/rule-registry.js";
+import type { PrologPort } from "./runtime-types.js";
+/**
+ * Full-check form of the staged gate's `symbol_granularity_violation`: a
+ * symbol with traceability relationships must not link its source file
+ * coarsely while narrower behavioral symbols are available, unless it carries
+ * an allowed granularity_reason.
+ */
+export declare const SYMBOL_GRANULARITY_RULE = "symbol-granularity";
+/**
+ * `symbol-granularity`: the staged gate's granularity predicate, evaluated
+ * for every symbol against its whole working-tree file, every declaration a
+ * candidate as if the file were fully staged. Only files of symbols the gate
+ * would judge are analyzed; a file the source analyzers cannot fully analyze
+ * is skipped.
+ */
+export declare function collectSymbolGranularityViolations(prolog: Pick<PrologPort, "query">, workspaceRoot: string, rules: ReadonlySet<string>): Promise<Violation[]>;
+//# sourceMappingURL=symbol-granularity-check.d.ts.map

package/dist/public/operations/symbol-granularity-check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"symbol-granularity-check.d.ts","sourceRoot":"","sources":["../../../src/public/operations/symbol-granularity-check.ts"],"names":[],"mappings":"AAgCA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAQ9D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAErD;;;;;GAKG;AAEH,eAAO,MAAM,uBAAuB,uBAAuB,CAAC;AA+J5D;;;;;;GAMG;AAEH,wBAAsB,kCAAkC,CACtD,MAAM,EAAE,IAAI,CAAC,UAAU,EAAE,OAAO,CAAC,EACjC,aAAa,EAAE,MAAM,EACrB,KAAK,EAAE,WAAW,CAAC,MAAM,CAAC,GACzB,OAAO,CAAC,SAAS,EAAE,CAAC,CAYtB"}

package/dist/public/operations/symbol-granularity-check.js

@@ -0,0 +1,175 @@
+/*
+ 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 { readFileSync, statSync } from "node:fs";
+import * as path from "node:path";
+import { createMaintenanceSourceAnalysisService } from "../../plugins/maintenance-source-analysis.js";
+import { normalizeEntityId, parseEntityFromList, parseListOfLists, parseTriples, } from "../../prolog/codec.js";
+import { extractSymbolsFromStagedFileAsync, } from "../../traceability/symbol-extract.js";
+import { createSymbolGranularityDiagnostics } from "../impact/diagnostics.js";
+import { createImpactManifestLookup } from "../impact/manifest.js";
+import { normalizeSourceFile } from "../impact/source-changes.js";
+import { isAllowedGranularityReason, isTraceabilityRelationshipType, } from "../symbol-granularity.js";
+/**
+ * Full-check form of the staged gate's `symbol_granularity_violation`: a
+ * symbol with traceability relationships must not link its source file
+ * coarsely while narrower behavioral symbols are available, unless it carries
+ * an allowed granularity_reason.
+ */
+// implements REQ-cli-check, REQ-cli-staged-impact-enforcement
+export const SYMBOL_GRANULARITY_RULE = "symbol-granularity";
+const SYMBOL_ROWS_QUERY = "findall([Id,symbol,Fields], (kb_entity(Id, symbol, Props), include([Key=_]>>memberchk(Key, [title,status,source,sourceFile,granularity_reason]), Props, Fields)), Rows)";
+const SYMBOL_RELATIONSHIPS_QUERY = "findall([From,To,Type], (member(Type, [implements,covered_by,executable_for]), kb_relationship(Type, From, To), kb_entity(From, symbol, _)), Rels)";
+function stringField(entity, key) {
+    const value = entity[key];
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+// implements REQ-cli-check
+async function loadSymbolResults(prolog, workspaceRoot) {
+    const rows = await prolog.query(SYMBOL_ROWS_QUERY);
+    if (!rows.success) {
+        throw new Error(`symbol-granularity symbol projection failed: ${rows.error ?? "unknown error"}`);
+    }
+    const rels = await prolog.query(SYMBOL_RELATIONSHIPS_QUERY);
+    if (!rels.success) {
+        throw new Error(`symbol-granularity relationship projection failed: ${rels.error ?? "unknown error"}`);
+    }
+    const relationships = new Map();
+    for (const [rawFrom, rawTo, type] of parseTriples(rels.bindings.Rels ?? "[]")) {
+        const from = normalizeEntityId(rawFrom);
+        const current = relationships.get(from) ?? [];
+        current.push({ from, to: normalizeEntityId(rawTo), type });
+        relationships.set(from, current);
+    }
+    const results = [];
+    for (const row of parseListOfLists(rows.bindings.Rows ?? "[]")) {
+        const entity = parseEntityFromList(row);
+        const id = stringField(entity, "id");
+        const sourceFile = stringField(entity, "sourceFile");
+        if (id === undefined || sourceFile === undefined)
+            continue;
+        const granularityReason = stringField(entity, "granularity_reason");
+        results.push({
+            entity: {
+                id,
+                type: "symbol",
+                title: stringField(entity, "title") ?? "",
+                status: stringField(entity, "status") ?? "",
+                created_at: "",
+                updated_at: "",
+                source: stringField(entity, "source") ?? "",
+                ...(granularityReason !== undefined
+                    ? { granularity_reason: granularityReason }
+                    : {}),
+            },
+            relationships: relationships.get(id) ?? [],
+            sourceFile: normalizeSourceFile(workspaceRoot, sourceFile),
+        });
+    }
+    return results;
+}
+/**
+ * The symbols the staged gate would judge: they carry a traceability
+ * relationship and no allowed granularity_reason. Other symbols are exempt,
+ * so their source files need no analysis.
+ */
+// implements REQ-cli-check
+function granularityCandidates(results) {
+    return results.filter((result) => result.relationships.some((relationship) => isTraceabilityRelationshipType(relationship.type)) && !isAllowedGranularityReason(result.entity.granularity_reason));
+}
+function readRegularFile(absolutePath) {
+    try {
+        if (!statSync(absolutePath).isFile())
+            return null;
+        return readFileSync(absolutePath, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+// implements REQ-cli-check
+async function analyzeFiles(files, results, workspaceRoot) {
+    const manifestLookup = createImpactManifestLookup(results);
+    const service = createMaintenanceSourceAnalysisService(workspaceRoot);
+    const analyses = new Map();
+    for (const file of files) {
+        const content = readRegularFile(path.resolve(workspaceRoot, file));
+        if (content === null)
+            continue;
+        try {
+            const analysis = await service.analyzeTextV2(file, content);
+            // Only a complete parser-backed analysis decides; the staged gate
+            // reports an incomplete one itself when the file is touched.
+            if (analysis.status !== "ok")
+                continue;
+            const symbols = await extractSymbolsFromStagedFileAsync({
+                path: file,
+                status: "M",
+                content,
+                hunkRanges: [{ start: 1, end: Number.MAX_SAFE_INTEGER }],
+            }, manifestLookup, { analyzeText: async () => analysis });
+            analyses.set(file, symbols);
+        }
+        catch {
+            // An analysis failure cannot decide anything for this file.
+        }
+    }
+    return analyses;
+}
+// implements REQ-cli-check
+function granularityViolations(candidates, sourceSymbolsByFile, workspaceRoot) {
+    return createSymbolGranularityDiagnostics({
+        manifestResults: candidates.filter((result) => result.sourceFile !== undefined &&
+            sourceSymbolsByFile.has(result.sourceFile)),
+        symbolsByFile: new Map(),
+        sourceSymbolsByFile,
+        workspaceRoot,
+    }).map((diagnostic) => ({
+        rule: SYMBOL_GRANULARITY_RULE,
+        entityId: diagnostic.entityId ?? "",
+        description: diagnostic.message,
+        suggestion: diagnostic.suggestion,
+        ...(diagnostic.source !== undefined ? { source: diagnostic.source } : {}),
+        evidence: {
+            diagnosticId: diagnostic.id,
+            ...(diagnostic.evidence ?? {}),
+        },
+    }));
+}
+/**
+ * `symbol-granularity`: the staged gate's granularity predicate, evaluated
+ * for every symbol against its whole working-tree file, every declaration a
+ * candidate as if the file were fully staged. Only files of symbols the gate
+ * would judge are analyzed; a file the source analyzers cannot fully analyze
+ * is skipped.
+ */
+// implements REQ-cli-check, REQ-cli-staged-impact-enforcement
+export async function collectSymbolGranularityViolations(prolog, workspaceRoot, rules) {
+    if (!rules.has(SYMBOL_GRANULARITY_RULE))
+        return [];
+    const results = await loadSymbolResults(prolog, workspaceRoot);
+    const candidates = granularityCandidates(results);
+    const files = [
+        ...new Set(candidates.map((result) => result.sourceFile ?? "")),
+    ]
+        .filter((file) => file.length > 0)
+        .sort();
+    if (files.length === 0)
+        return [];
+    const analyses = await analyzeFiles(files, results, workspaceRoot);
+    return granularityViolations(candidates, analyses, workspaceRoot);
+}

package/dist/public/symbol-granularity.d.ts

@@ -17,5 +17,22 @@ export declare function isCoarseGranularityReason(value: unknown): value is Coar
 export declare function getSymbolRole(candidate: GranularSymbolCandidate): SymbolRole;
 export declare function isBehavioralSymbol(candidate: GranularSymbolCandidate): boolean;
 export declare function getBehavioralSymbolNames(candidates: GranularSymbolCandidate[]): string[];
+/**
+ * The candidates that are narrower than a manifest symbol: members of it
+ * (`Title.member`), or, when the source declares no symbol named like it,
+ * every other declaration in the file.
+ */
+export declare function narrowerSymbols<T extends {
+    name: string;
+}>(manifestSymbolName: string, candidates: readonly T[], sourceSymbols: readonly {
+    name: string;
+}[]): T[];
+/**
+ * The behavioral symbols that make a traceability link on
+ * `manifestSymbolName` coarse: the staged granularity gate blocks such a
+ * link unless it carries a granularity_reason, and `kibi migrate` marks
+ * exactly these links legacy-link. Empty when the link is narrow enough.
+ */
+export declare function coarseLinkBehavioralNames(manifestSymbolName: string, sourceSymbols: readonly GranularSymbolCandidate[]): string[];
 export declare function getNonBehavioralSymbolNames(candidates: GranularSymbolCandidate[]): string[];
 //# sourceMappingURL=symbol-granularity.d.ts.map

package/dist/public/symbol-granularity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"symbol-granularity.d.ts","sourceRoot":"","sources":["../../src/public/symbol-granularity.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,2BAA2B,EAC3B,iCAAiC,EACjC,0BAA0B,EAC1B,wCAAwC,EACxC,gCAAgC,EAChC,KAAK,uBAAuB,EAC5B,KAAK,iBAAiB,EACtB,cAAc,EACd,YAAY,EACZ,KAAK,UAAU,EACf,+BAA+B,EAC/B,KAAK,4BAA4B,EAClC,MAAM,mCAAmC,CAAC;AAK3C,OAAO,EACL,2BAA2B,EAC3B,iCAAiC,EACjC,0BAA0B,EAC1B,wCAAwC,EACxC,gCAAgC,EAChC,cAAc,EACd,YAAY,EACZ,+BAA+B,GAChC,CAAC;AACF,YAAY,EACV,uBAAuB,EACvB,iBAAiB,EACjB,UAAU,EACV,4BAA4B,GAC7B,MAAM,mCAAmC,CAAC;AAE3C,MAAM,MAAM,UAAU,GAClB,UAAU,GACV,OAAO,GACP,QAAQ,GACR,UAAU,GACV,UAAU,GACV,WAAW,GACX,MAAM,GACN,UAAU,GACV,MAAM,GACN,SAAS,CAAC;AAEd,MAAM,MAAM,gBAAgB,GAAG,UAAU,CAAC;AAE1C,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,IAAI,CAAC,EAAE,UAAU,CAAC;CACnB;AAYD,wBAAgB,eAAe,CAAC,IAAI,EAAE,UAAU,GAAG,UAAU,CAE5D;AAED,eAAO,MAAM,uBAAuB,wBAAkB,CAAC;AAEvD,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,UAAU,CAIhE;AAED,wBAAgB,8BAA8B,CAC5C,KAAK,EAAE,OAAO,GACb,KAAK,IAAI,4BAA4B,CAIvC;AAED,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,OAAO,GACb,KAAK,IAAI,iBAAiB,CAE5B;AAED,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,OAAO,GACb,KAAK,IAAI,uBAAuB,CAElC;AAED,wBAAgB,aAAa,CAAC,SAAS,EAAE,uBAAuB,GAAG,UAAU,CAI5E;AAED,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,uBAAuB,GACjC,OAAO,CAET;AAED,wBAAgB,wBAAwB,CACtC,UAAU,EAAE,uBAAuB,EAAE,GACpC,MAAM,EAAE,CAMV;AAED,wBAAgB,2BAA2B,CACzC,UAAU,EAAE,uBAAuB,EAAE,GACpC,MAAM,EAAE,CAQV"}
+{"version":3,"file":"symbol-granularity.d.ts","sourceRoot":"","sources":["../../src/public/symbol-granularity.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,2BAA2B,EAC3B,iCAAiC,EACjC,0BAA0B,EAC1B,wCAAwC,EACxC,gCAAgC,EAChC,KAAK,uBAAuB,EAC5B,KAAK,iBAAiB,EACtB,cAAc,EACd,YAAY,EACZ,KAAK,UAAU,EACf,+BAA+B,EAC/B,KAAK,4BAA4B,EAClC,MAAM,mCAAmC,CAAC;AAK3C,OAAO,EACL,2BAA2B,EAC3B,iCAAiC,EACjC,0BAA0B,EAC1B,wCAAwC,EACxC,gCAAgC,EAChC,cAAc,EACd,YAAY,EACZ,+BAA+B,GAChC,CAAC;AACF,YAAY,EACV,uBAAuB,EACvB,iBAAiB,EACjB,UAAU,EACV,4BAA4B,GAC7B,MAAM,mCAAmC,CAAC;AAE3C,MAAM,MAAM,UAAU,GAClB,UAAU,GACV,OAAO,GACP,QAAQ,GACR,UAAU,GACV,UAAU,GACV,WAAW,GACX,MAAM,GACN,UAAU,GACV,MAAM,GACN,SAAS,CAAC;AAEd,MAAM,MAAM,gBAAgB,GAAG,UAAU,CAAC;AAE1C,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,IAAI,CAAC,EAAE,UAAU,CAAC;CACnB;AAYD,wBAAgB,eAAe,CAAC,IAAI,EAAE,UAAU,GAAG,UAAU,CAE5D;AAED,eAAO,MAAM,uBAAuB,wBAAkB,CAAC;AAEvD,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,UAAU,CAIhE;AAED,wBAAgB,8BAA8B,CAC5C,KAAK,EAAE,OAAO,GACb,KAAK,IAAI,4BAA4B,CAIvC;AAED,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,OAAO,GACb,KAAK,IAAI,iBAAiB,CAE5B;AAED,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,OAAO,GACb,KAAK,IAAI,uBAAuB,CAElC;AAED,wBAAgB,aAAa,CAAC,SAAS,EAAE,uBAAuB,GAAG,UAAU,CAI5E;AAED,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,uBAAuB,GACjC,OAAO,CAET;AAED,wBAAgB,wBAAwB,CACtC,UAAU,EAAE,uBAAuB,EAAE,GACpC,MAAM,EAAE,CAMV;AAED;;;;GAIG;AAEH,wBAAgB,eAAe,CAAC,CAAC,SAAS;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,EACxD,kBAAkB,EAAE,MAAM,EAC1B,UAAU,EAAE,SAAS,CAAC,EAAE,EACxB,aAAa,EAAE,SAAS;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,EAAE,GACzC,CAAC,EAAE,CASL;AAED;;;;;GAKG;AAEH,wBAAgB,yBAAyB,CACvC,kBAAkB,EAAE,MAAM,EAC1B,aAAa,EAAE,SAAS,uBAAuB,EAAE,GAChD,MAAM,EAAE,CAIV;AAED,wBAAgB,2BAA2B,CACzC,UAAU,EAAE,uBAAuB,EAAE,GACpC,MAAM,EAAE,CAQV"}

package/dist/public/symbol-granularity.js

@@ -37,6 +37,27 @@ export function getBehavioralSymbolNames(candidates) {
         ...new Set(candidates.filter(isBehavioralSymbol).map((candidate) => candidate.name)),
     ].sort();
 }
+/**
+ * The candidates that are narrower than a manifest symbol: members of it
+ * (`Title.member`), or, when the source declares no symbol named like it,
+ * every other declaration in the file.
+ */
+// implements REQ-symbol-behavioral-anchors, REQ-cli-schema-migration
+export function narrowerSymbols(manifestSymbolName, candidates, sourceSymbols) {
+    const declared = sourceSymbols.some((symbol) => symbol.name === manifestSymbolName);
+    return candidates.filter((candidate) => candidate.name !== manifestSymbolName &&
+        (candidate.name.startsWith(`${manifestSymbolName}.`) || !declared));
+}
+/**
+ * The behavioral symbols that make a traceability link on
+ * `manifestSymbolName` coarse: the staged granularity gate blocks such a
+ * link unless it carries a granularity_reason, and `kibi migrate` marks
+ * exactly these links legacy-link. Empty when the link is narrow enough.
+ */
+// implements REQ-symbol-behavioral-anchors, REQ-cli-schema-migration
+export function coarseLinkBehavioralNames(manifestSymbolName, sourceSymbols) {
+    return getBehavioralSymbolNames(narrowerSymbols(manifestSymbolName, sourceSymbols, sourceSymbols));
+}
 export function getNonBehavioralSymbolNames(candidates) {
     return [
         ...new Set(candidates

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

@@ -61,14 +61,18 @@ export interface KibiImpactSymbolsManifestFileDetail {
     path: string;
     /** Symbol count extraction finds in the staged source content. */
     expectedCount: number;
-    /** Symbol count the staged manifest+coordinates evidence covers. */
+    /**
+     * Extracted symbols that have a matching staged manifest+coordinates entry
+     * (`expectedCount - missing.length`); evidence-only entries in `extra` are
+     * not counted.
+     */
     coveredCount: number;
-    /** Extracted symbols with no evidence entry (title + definition line). */
+    /** Every extracted symbol with no evidence entry (title + definition line). */
     missing: Array<{
         title: string;
         line: number;
     }>;
-    /** Evidence entries the extractor no longer finds at the recorded shape. */
+    /** Every evidence entry the extractor no longer finds at the recorded shape. */
     extra: string[];
 }
 /**

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

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