kibi-cli 2.4.0 → 2.5.1

package/dist/traceability/impact-knowledge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"impact-knowledge.d.ts","sourceRoot":"","sources":["../../src/traceability/impact-knowledge.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAElE,OAAO,EACL,KAAK,WAAW,EAIjB,MAAM,oBAAoB,CAAC;AAI5B,4EAA4E;AAE5E,MAAM,MAAM,SAAS,GAAG,QAAQ,CAAC;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,WAAW,CAAC;IACzB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC,CAAC;AA6EH,wBAAgB,UAAU,CACxB,QAAQ,EAAE,iBAAiB,EAC3B,IAAI,EAAE,MAAM,EACZ,SAAS,yDAAoE,GAC5E,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAyCxB;AAGD,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,iBAAiB,EAC3B,IAAI,EAAE,MAAM,GACX,WAAW,CAiBb;AAGD,wBAAgB,4BAA4B,CAC1C,IAAI,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,CAAC,GACnC,WAAW,CAoBb;AAGD,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,CAAC,EACpC,cAAc,EAAE,SAAS,MAAM,EAAE,GAChC,MAAM,EAAE,CAsBV;AAeD,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,iBAAiB,EAC3B,IAAI,EAAE,MAAM,GACX,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAiBxB"}
+{"version":3,"file":"impact-knowledge.d.ts","sourceRoot":"","sources":["../../src/traceability/impact-knowledge.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAElE,OAAO,EACL,KAAK,WAAW,EAIjB,MAAM,oBAAoB,CAAC;AAI5B,4EAA4E;AAE5E,MAAM,MAAM,SAAS,GAAG,QAAQ,CAAC;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,WAAW,CAAC;IACzB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC,CAAC;AAoFH,wBAAgB,UAAU,CACxB,QAAQ,EAAE,iBAAiB,EAC3B,IAAI,EAAE,MAAM,EACZ,SAAS,yDAAoE,GAC5E,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAyCxB;AAGD,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,iBAAiB,EAC3B,IAAI,EAAE,MAAM,GACX,WAAW,CAiBb;AAGD,wBAAgB,4BAA4B,CAC1C,IAAI,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,CAAC,GACnC,WAAW,CAoBb;AAGD,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,CAAC,EACpC,cAAc,EAAE,SAAS,MAAM,EAAE,GAChC,MAAM,EAAE,CAsBV;AAeD,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,iBAAiB,EAC3B,IAAI,EAAE,MAAM,GACX,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAiBxB"}

package/dist/traceability/impact-knowledge.js

@@ -18,6 +18,8 @@ function semanticEntityFingerprint(result) {
             "updated_at",
             "title",
             "proof_receipts",
+            // Provenance metadata, not authored meaning.
+            "origin",
         ].includes(key))
             .sort(([a], [b]) => a.localeCompare(b)));
     if (entity.type === "req") {
@@ -27,11 +29,16 @@ function semanticEntityFingerprint(result) {
             semantic.text_ref = entity.text_ref;
         else
             semantic.semantic_text = entity.semantic_text;
+        // rationale explains why a requirement exists; it is not checked meaning,
+        // so editing it does not count as a semantic change.
         for (const key of [
             "semantic_clauses",
             "logic_claims",
             "proof_exempt",
             "proof_exempt_reason",
+            "approved_by",
+            "approval_ref",
+            "exempts_claims",
             "proof_contract",
             "proof_bindings",
         ])

package/dist/traceability/symbol-extract.js

@@ -11,7 +11,7 @@ const REQUIREMENT_ID_PATTERN = /^[A-Za-z][A-Za-z0-9\-_]*$/;
 const LOCAL_MANIFEST_NAMES = ["symbols.yaml", "symbols.yml"];
 const MANIFEST_SENTINEL_PREFIX = "__manifest__:";
 export function createManifestLookupSentinelKey(manifestPath) {
-    // implements REQ-008
+    // implements REQ-cli-staged-impact-enforcement
     return `${MANIFEST_SENTINEL_PREFIX}${manifestPath}`;
 }
 function getCandidateManifestPaths(filePath) {
@@ -164,7 +164,7 @@ function analyzeWithBuiltinFallback(filePath, content) {
     return provider.analyzeText(filePath, content);
 }
 export function extractSymbolsFromStagedFile(
-// implements REQ-008
+// implements REQ-cli-staged-impact-enforcement
 stagedFile, manifestLookup, options) {
     const content = stagedFile.content ?? "";
     const sha = computeContentSha(`${content}|${stagedFile.path}|${options?.analyzeText ? "custom" : "builtin"}`);
@@ -260,7 +260,7 @@ function intersectingHunks(startLine, endLine, hunks) {
     }
     return out;
 }
-// implements REQ-008
+// implements REQ-cli-staged-impact-enforcement
 function sourceSymbolLocator(symbol, symbols, filePath, lookup) {
     const qualified = symbol.qualifiedName;
     if (!qualified || qualified === symbol.name)

package/dist/traceability/temp-kb.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"temp-kb.d.ts","sourceRoot":"","sources":["../../src/traceability/temp-kb.ts"],"names":[],"mappings":"AAMA,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,GACZ,OAAO,CAET;AACD,OAAO,KAAK,EAGV,gBAAgB,EACjB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE7C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAExD,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,aAAa,CAAC;CACvB;AAMD;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,IAAI,CASvC;AAQD;;;GAGG;AACH,wBAAgB,iBAAiB,CAE/B,OAAO,EAAE,CAAC,IAAI,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,KAAK,CAAA;CAAE,KAAK,aAAa,GACpE,IAAI,CAEN;AA4QD,iBAAe,cAAc,CAAC,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAgB/D;AAED,OAAO,EAAE,cAAc,EAAE,CAAC;AAe1B,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,gBAAgB,EAAE,GAC1B,OAAO,CAAC,IAAI,CAAC,CA4Df;AAED,wBAAsB,YAAY,CAChC,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,aAAa,CAAC,CA+CxB;AAGD,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,eAAe,EAAE,GAAG,MAAM,CAkBrE;AAED,wBAAsB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA2BlE"}
+{"version":3,"file":"temp-kb.d.ts","sourceRoot":"","sources":["../../src/traceability/temp-kb.ts"],"names":[],"mappings":"AAMA,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,GACZ,OAAO,CAET;AACD,OAAO,KAAK,EAGV,gBAAgB,EACjB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE7C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAExD,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,aAAa,CAAC;CACvB;AAMD;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,IAAI,CASvC;AAQD;;;GAGG;AACH,wBAAgB,iBAAiB,CAE/B,OAAO,EAAE,CAAC,IAAI,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,KAAK,CAAA;CAAE,KAAK,aAAa,GACpE,IAAI,CAEN;AAyRD,iBAAe,cAAc,CAAC,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAgB/D;AAED,OAAO,EAAE,cAAc,EAAE,CAAC;AAe1B,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,gBAAgB,EAAE,GAC1B,OAAO,CAAC,IAAI,CAAC,CA4Df;AAED,wBAAsB,YAAY,CAChC,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,aAAa,CAAC,CA+CxB;AAGD,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,eAAe,EAAE,GAAG,MAAM,CAkBrE;AAED,wBAAsB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA2BlE"}

package/dist/traceability/temp-kb.js

@@ -74,6 +74,7 @@ const FACT_STRING_ARRAY_FIELDS = new Set([
     "argument_names",
     "argument_types",
     "argument_descriptions",
+    "key_arguments",
     "aliases",
     "examples",
     "predicate_args",
@@ -185,6 +186,17 @@ function buildEntityAssertionGoal(entity, sourceFile) {
     if (entity.type === "req" && entity.semantic_inventory) {
         props.push(`semantic_inventory=${toPrologString(JSON.stringify(entity.semantic_inventory))}`);
     }
+    for (const field of ["approved_by", "approval_ref", "rationale"]) {
+        const value = entity.type === "req" ? entity[field] : undefined;
+        if (value !== undefined)
+            props.push(`${field}=${toPrologString(value)}`);
+    }
+    if (entity.type === "req" && entity.exempts_claims) {
+        props.push(`exempts_claims=[${entity.exempts_claims.map(toPrologAtom).join(",")}]`);
+    }
+    if (entity.origin !== undefined) {
+        props.push(`origin=${toPrologString(JSON.stringify(entity.origin))}`);
+    }
     if (sourceFile)
         props.push(`sourceFile=${toPrologString(sourceFile)}`);
     if (entity.type === "symbol") {

package/dist/types/entities.d.ts

@@ -1,3 +1,4 @@
+import type { EntityOrigin } from "../public/entity-origin.js";
 import type { ProofBinding, ProofContract } from "../public/proof-protocol.js";
 import type { ProofReceipt } from "../public/proof-receipt.js";
 export interface BaseEntity {
@@ -13,6 +14,8 @@ export interface BaseEntity {
     severity?: string;
     links?: string[];
     text_ref?: string;
+    /** Provenance: who authored the entity and on what authority. */
+    origin?: EntityOrigin;
 }
 export interface FactFields {
     fact_kind?: "subject" | "property_value" | "observation" | "meta" | "predicate_schema" | "predicate";
@@ -39,6 +42,8 @@ export interface FactFields {
     argument_names?: string[];
     argument_types?: string[];
     argument_descriptions?: string[];
+    /** predicate_schema only: argument names that determine the others. */
+    key_arguments?: string[];
     argument_constants?: Record<string, string[]>;
     argument_aliases?: Record<string, Record<string, string>>;
     aliases?: string[];
@@ -56,6 +61,14 @@ export type Requirement = BaseEntity & {
     type: "req";
     semantic_text?: string;
     logic_claims?: string[];
+    /** Exception requirements only: who approved the exception. */
+    approved_by?: string;
+    /** Optional reference to the approval decision record. */
+    approval_ref?: string;
+    /** Why the requirement exists; explanation, not checked meaning. */
+    rationale?: string;
+    /** Exception requirements only: claim keys of the exempted requirement it waives. */
+    exempts_claims?: string[];
 };
 export type Scenario = BaseEntity & {
     type: "scenario";

package/dist/types/entities.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"entities.d.ts","sourceRoot":"","sources":["../../src/types/entities.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"entities.d.ts","sourceRoot":"","sources":["../../src/types/entities.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC/D,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAC/E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAE/D,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iEAAiE;IACjE,MAAM,CAAC,EAAE,YAAY,CAAC;CACvB;AAGD,MAAM,WAAW,UAAU;IACzB,SAAS,CAAC,EACN,SAAS,GACT,gBAAgB,GAChB,aAAa,GACb,MAAM,GACN,kBAAkB,GAClB,WAAW,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,IAAI,GAAG,KAAK,GAAG,IAAI,GAAG,KAAK,GAAG,IAAI,GAAG,KAAK,CAAC;IACtD,UAAU,CAAC,EAAE,QAAQ,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;IAClD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,CAAC;IACpD,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,qBAAqB,CAAC,EAAE,MAAM,EAAE,CAAC;IACjC,uEAAuE;IACvE,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,kBAAkB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAC9C,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAC1D,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,sBAAsB;IACrC,kBAAkB,CAAC,EAAE,MAAM,GAAG,aAAa,GAAG,YAAY,CAAC;IAC3D,wBAAwB,CAAC,EAAE,UAAU,GAAG,UAAU,CAAC;IACnD,cAAc,CAAC,EAAE,aAAa,CAAC;IAC/B,cAAc,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;IACzC,cAAc,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;CAC1C;AAED,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG;IACrC,IAAI,EAAE,KAAK,CAAC;IACZ,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,+DAA+D;IAC/D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0DAA0D;IAC1D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,oEAAoE;IACpE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,qFAAqF;IACrF,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B,CAAC;AACF,MAAM,MAAM,QAAQ,GAAG,UAAU,GAAG;IAAE,IAAI,EAAE,UAAU,CAAA;CAAE,CAAC;AACzD,MAAM,MAAM,UAAU,GAAG,UAAU,GAAG,sBAAsB,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAChF,MAAM,MAAM,GAAG,GAAG,UAAU,GAAG;IAAE,IAAI,EAAE,KAAK,CAAA;CAAE,CAAC;AAC/C,MAAM,MAAM,IAAI,GAAG,UAAU,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AACjD,MAAM,MAAM,KAAK,GAAG,UAAU,GAAG;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC;AACnD,MAAM,MAAM,MAAM,GAAG,UAAU,GAAG;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,CAAC;AACrD,MAAM,MAAM,IAAI,GAAG,UAAU,GAAG,UAAU,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAE9D,MAAM,MAAM,MAAM,GACd,WAAW,GACX,QAAQ,GACR,UAAU,GACV,GAAG,GACH,IAAI,GACJ,KAAK,GACL,MAAM,GACN,IAAI,CAAC"}

package/dist/types/relationships.d.ts

@@ -1,5 +1,5 @@
 export interface BaseRelationship {
-    type: "depends_on" | "specified_by" | "verified_by" | "validates" | "implements" | "covered_by" | "executable_for" | "constrained_by" | "constrains" | "requires_property" | "requires_predicate" | "requires_rule" | "guards" | "publishes" | "consumes" | "supersedes" | "restates" | "relates_to";
+    type: "depends_on" | "specified_by" | "verified_by" | "validates" | "implements" | "covered_by" | "executable_for" | "constrained_by" | "constrains" | "requires_property" | "requires_predicate" | "requires_rule" | "guards" | "publishes" | "consumes" | "supersedes" | "restates" | "assumes" | "exempts" | "relates_to";
     from: string;
     to: string;
     created_at?: string;

package/dist/types/relationships.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"relationships.d.ts","sourceRoot":"","sources":["../../src/types/relationships.ts"],"names":[],"mappings":"AAkBA,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EACA,YAAY,GACZ,cAAc,GACd,aAAa,GACb,WAAW,GACX,YAAY,GACZ,YAAY,GACZ,gBAAgB,GAChB,gBAAgB,GAChB,YAAY,GACZ,mBAAmB,GACnB,oBAAoB,GACpB,eAAe,GACf,QAAQ,GACR,WAAW,GACX,UAAU,GACV,YAAY,GACZ,UAAU,GACV,YAAY,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,eAAe,gBAAgB,CAAC"}
+{"version":3,"file":"relationships.d.ts","sourceRoot":"","sources":["../../src/types/relationships.ts"],"names":[],"mappings":"AAkBA,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EACA,YAAY,GACZ,cAAc,GACd,aAAa,GACb,WAAW,GACX,YAAY,GACZ,YAAY,GACZ,gBAAgB,GAChB,gBAAgB,GAChB,YAAY,GACZ,mBAAmB,GACnB,oBAAoB,GACpB,eAAe,GACf,QAAQ,GACR,WAAW,GACX,UAAU,GACV,YAAY,GACZ,UAAU,GACV,SAAS,GACT,SAAS,GACT,YAAY,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,eAAe,gBAAgB,CAAC"}

package/dist/utils/branch-resolver.d.ts

@@ -12,9 +12,29 @@ export type BranchAttachment = {
     kbBranch: string;
     /** The resolved compiled-store path. Never derive this path at call sites. */
     storePath: string;
-    kind: "exact" | "explicit_override" | "legacy_compat";
+    kind: "exact" | "explicit_override" | "legacy_compat" | "detached_snapshot";
     migrationRequired: boolean;
+    /**
+     * Present only on a detached HEAD that no single local branch points at.
+     * The attachment then serves reads from a snapshot compiled from the
+     * checkout, and every write route must refuse it.
+     */
+    readOnly?: DetachedReadOnlyAttachment;
 };
+export type DetachedReadOnlyAttachment = {
+    /** The checked-out commit. */
+    head: string;
+    /** Local branches whose tip is HEAD (zero, or two or more). */
+    branchesAtHead: readonly string[];
+    /** Human-readable account of the store used and the write refusal. */
+    notice: string;
+};
+/**
+ * Store identity of the read-only snapshot compiled from a detached checkout.
+ * It is never a Git branch's KB: reads on a bare SHA (CI checkouts) use it so
+ * no branch identity is guessed, and writes are refused while it is attached.
+ */
+export declare const DETACHED_SNAPSHOT_KB_BRANCH = "kibi-internal/detached-head-snapshot";
 export type BranchErrorCode = "ENV_OVERRIDE" | "DETACHED_HEAD" | "UNBORN_BRANCH" | "GIT_NOT_AVAILABLE" | "NOT_A_GIT_REPO" | "AMBIGUOUS_ATTACHMENT" | "MIGRATION_RECOVERY_REQUIRED" | "UNKNOWN_ERROR";
 export interface BranchResolverDeps {
     execSync: typeof import("node:child_process").execSync;
@@ -31,6 +51,22 @@ export declare function _setBranchResolverDepsForTests(deps: Partial<BranchResol
  * @returns BranchResolutionResult with either the branch name or an error
  */
 export declare function resolveActiveBranch(workspaceRoot?: string): BranchResolutionResult;
+/**
+ * Resolve the attachment for a read-only operation.
+ *
+ * Identical to {@link resolveBranchAttachment} except on a detached HEAD that
+ * no single local branch points at (a CI checkout of a bare SHA, or a commit
+ * two branches share). Such a checkout has no exact branch identity, and no
+ * other branch's KB may stand in for it, so reads are served from a snapshot
+ * compiled from this checkout's tracked sources. The result carries a notice
+ * naming that store and stating that writes are refused.
+ */
+export declare function resolveReadBranchAttachment(workspaceRoot?: string): BranchAttachment | BranchResolutionError;
+/**
+ * Actionable refusal for a write attempted on a detached HEAD. Reads keep
+ * working through the snapshot; a write needs an exact branch identity.
+ */
+export declare function detachedHeadWriteRefusal(operation: string, workspaceRoot?: string): string;
 /**
  * Resolve the storage namespace without treating any branch as canonical.
  * Literal branch-named stores are read-compatible legacy storage only. The

package/dist/utils/branch-resolver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"branch-resolver.d.ts","sourceRoot":"","sources":["../../src/utils/branch-resolver.ts"],"names":[],"mappings":"AAsCA,MAAM,MAAM,uBAAuB,GAAG;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AACzD,MAAM,MAAM,qBAAqB,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,eAAe,CAAA;CAAE,CAAC;AAC7E,MAAM,MAAM,sBAAsB,GAC9B,uBAAuB,GACvB,qBAAqB,CAAC;AAE1B,wBAAgB,+BAA+B,CAC7C,WAAW,EAAE,MAAM,GAClB,qBAAqB,CAKvB;AAED,MAAM,MAAM,gBAAgB,GAAG;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,8EAA8E;IAC9E,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,OAAO,GAAG,mBAAmB,GAAG,eAAe,CAAC;IACtD,iBAAiB,EAAE,OAAO,CAAC;CAC5B,CAAC;AAEF,MAAM,MAAM,eAAe,GACvB,cAAc,GACd,eAAe,GACf,eAAe,GACf,mBAAmB,GACnB,gBAAgB,GAChB,sBAAsB,GACtB,6BAA6B,GAC7B,eAAe,CAAC;AAEpB,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,cAAc,oBAAoB,EAAE,QAAQ,CAAC;IACvD,YAAY,EAAE,cAAc,oBAAoB,EAAE,YAAY,CAAC;CAChE;AAOD,wBAAgB,8BAA8B,CAC5C,IAAI,EAAE,OAAO,CAAC,kBAAkB,CAAC,GAChC,IAAI,CAIN;AA8BD;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CACjC,aAAa,GAAE,MAAsB,GACpC,sBAAsB,CAoHxB;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,aAAa,GAAE,MAAsB,GACpC,gBAAgB,GAAG,qBAAqB,CAiE1C;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,aAAa,GAAE,MAAsB,GAAG,OAAO,CAgB7E;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,KAAK,EAAE,MAAM,GACZ,MAAM,CAuBR;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAkDvD;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,GACjB,IAAI,CAUN;AA6BD;;;;;GAKG;AACH,wBAAgB,2BAA2B,IAAI,MAAM,EAAE,CAMtD;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,GAAE,MAAsB,EAC3B,OAAO,CAAC,EAAE;IAAE,aAAa,CAAC,EAAE,MAAM,CAAA;CAAE,GACnC;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CA+BtD"}
+{"version":3,"file":"branch-resolver.d.ts","sourceRoot":"","sources":["../../src/utils/branch-resolver.ts"],"names":[],"mappings":"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"}

package/dist/utils/branch-resolver.js

@@ -26,12 +26,19 @@ export function unreadableMigrationJournalError(journalName) {
         code: "MIGRATION_RECOVERY_REQUIRED",
     };
 }
+/**
+ * Store identity of the read-only snapshot compiled from a detached checkout.
+ * It is never a Git branch's KB: reads on a bare SHA (CI checkouts) use it so
+ * no branch identity is guessed, and writes are refused while it is attached.
+ */
+// implements REQ-branch-store-recovery-v4
+export const DETACHED_SNAPSHOT_KB_BRANCH = "kibi-internal/detached-head-snapshot";
 const defaultDeps = {
     execSync: rawExecSync,
     execFileSync: rawExecFileSync,
 };
 export function _setBranchResolverDepsForTests(deps) {
-    // implements REQ-008
+    // implements REQ-branch-store-recovery-v4
     defaultDeps.execSync = deps.execSync ?? rawExecSync;
     defaultDeps.execFileSync = deps.execFileSync ?? rawExecFileSync;
 }
@@ -70,7 +77,7 @@ function isVolatileArtifact(fileName) {
  * @returns BranchResolutionResult with either the branch name or an error
  */
 export function resolveActiveBranch(workspaceRoot = process.cwd()) {
-    // implements REQ-008
+    // implements REQ-branch-store-recovery-v4
     // 1. Check KIBI_BRANCH env var first (highest precedence)
     const envBranch = getBranchOverride();
     if (envBranch) {
@@ -95,6 +102,9 @@ export function resolveActiveBranch(workspaceRoot = process.cwd()) {
             .trim();
         if (!branch) {
             // Empty result means detached HEAD
+            const atHead = uniqueBranchAtHead(workspaceRoot);
+            if (atHead)
+                return { branch: atHead };
             return {
                 error: getBranchDiagnostic(undefined, "Git is in detached HEAD state"),
                 code: "DETACHED_HEAD",
@@ -123,6 +133,9 @@ export function resolveActiveBranch(workspaceRoot = process.cwd()) {
             })
                 .trim();
             if (branch === "HEAD") {
+                const atHead = uniqueBranchAtHead(workspaceRoot);
+                if (atHead)
+                    return { branch: atHead };
                 return {
                     error: getBranchDiagnostic(undefined, "Git is in detached HEAD state"),
                     code: "DETACHED_HEAD",
@@ -165,6 +178,120 @@ export function resolveActiveBranch(workspaceRoot = process.cwd()) {
         }
     }
 }
+// implements REQ-branch-store-recovery-v4
+/**
+ * A detached HEAD that exactly one local branch points at is that branch's
+ * commit, so its knowledge base is the exact one for this checkout (a
+ * `git checkout <sha>` of a branch tip, or a tool that detaches before
+ * running). Zero or several candidates stay a DETACHED_HEAD diagnostic: no
+ * branch is guessed.
+ */
+function uniqueBranchAtHead(workspaceRoot) {
+    const names = branchesAtHead(workspaceRoot);
+    if (names.length !== 1)
+        return null;
+    const [name] = names;
+    return name !== undefined && isValidBranchName(name) ? name : null;
+}
+/** Local branch names whose tip is HEAD, sorted; empty when Git cannot say. */
+function branchesAtHead(workspaceRoot) {
+    try {
+        return defaultDeps
+            .execFileSync("git", ["branch", "--points-at", "HEAD", "--format=%(refname:short)"], {
+            cwd: workspaceRoot,
+            encoding: "utf8",
+            timeout: 5000,
+            stdio: ["pipe", "pipe", "pipe"],
+        })
+            .toString()
+            .split("\n")
+            .map((name) => name.trim())
+            .filter((name) => name.length > 0 && !name.startsWith("("))
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
+function headCommit(workspaceRoot) {
+    try {
+        const head = defaultDeps
+            .execFileSync("git", ["rev-parse", "--verify", "HEAD"], {
+            cwd: workspaceRoot,
+            encoding: "utf8",
+            timeout: 5000,
+            stdio: ["pipe", "pipe", "pipe"],
+        })
+            .toString()
+            .trim();
+        return /^[0-9a-f]{40,64}$/u.test(head) ? head : null;
+    }
+    catch {
+        return null;
+    }
+}
+function describeBranchesAtHead(branches) {
+    return branches.length === 0
+        ? "no local branch points at it"
+        : `${branches.length} local branches point at it (${branches.join(", ")}), so no single branch KB is implied`;
+}
+/**
+ * Resolve the attachment for a read-only operation.
+ *
+ * Identical to {@link resolveBranchAttachment} except on a detached HEAD that
+ * no single local branch points at (a CI checkout of a bare SHA, or a commit
+ * two branches share). Such a checkout has no exact branch identity, and no
+ * other branch's KB may stand in for it, so reads are served from a snapshot
+ * compiled from this checkout's tracked sources. The result carries a notice
+ * naming that store and stating that writes are refused.
+ */
+// implements REQ-branch-store-recovery-v4
+export function resolveReadBranchAttachment(workspaceRoot = process.cwd()) {
+    const attachment = resolveBranchAttachment(workspaceRoot);
+    if (!("error" in attachment) || attachment.code !== "DETACHED_HEAD") {
+        return attachment;
+    }
+    const head = headCommit(workspaceRoot);
+    if (head === null)
+        return attachment;
+    const branches = branchesAtHead(workspaceRoot);
+    const storePath = branchStorePath(workspaceRoot, DETACHED_SNAPSHOT_KB_BRANCH);
+    if (existsSync(storePath) &&
+        !branchStoreManifestMatches(storePath, DETACHED_SNAPSHOT_KB_BRANCH)) {
+        return {
+            error: `Detached HEAD snapshot store identity mismatch at ${storePath}; refusing to read it.`,
+            code: "AMBIGUOUS_ATTACHMENT",
+        };
+    }
+    return {
+        gitBranch: "HEAD",
+        kbBranch: DETACHED_SNAPSHOT_KB_BRANCH,
+        storePath,
+        kind: "detached_snapshot",
+        migrationRequired: false,
+        readOnly: {
+            head,
+            branchesAtHead: branches,
+            notice: `Detached HEAD at ${head.slice(0, 12)}: ${describeBranchesAtHead(branches)}. Read-only answers come from a snapshot compiled from this checkout's tracked sources (store ${storePath}); writes are refused until a branch is checked out.`,
+        },
+    };
+}
+/**
+ * Actionable refusal for a write attempted on a detached HEAD. Reads keep
+ * working through the snapshot; a write needs an exact branch identity.
+ */
+// implements REQ-branch-store-recovery-v4
+export function detachedHeadWriteRefusal(operation, workspaceRoot = process.cwd()) {
+    const head = headCommit(workspaceRoot);
+    const branches = branchesAtHead(workspaceRoot);
+    const where = head === null
+        ? "HEAD is detached"
+        : `HEAD is detached at ${head.slice(0, 12)} and ${describeBranchesAtHead(branches)}`;
+    const switchHint = branches.length > 0
+        ? `'git switch ${branches[0]}' (or another branch at HEAD)`
+        : "'git switch -c <branch>'";
+    return `${operation} writes the branch KB, but ${where}. Check out a branch first: ${switchHint}, or set KIBI_BRANCH to name the branch explicitly. Read-only operations (search, query, status, check, coverage, graph) keep working on a detached HEAD from a read-only snapshot of the checkout.`;
+}
 /**
  * Resolve the storage namespace without treating any branch as canonical.
  * Literal branch-named stores are read-compatible legacy storage only. The
@@ -237,7 +364,7 @@ export function resolveBranchAttachment(workspaceRoot = process.cwd()) {
  * @returns true if in detached HEAD, false otherwise
  */
 export function isDetachedHead(workspaceRoot = process.cwd()) {
-    // implements REQ-008
+    // implements REQ-branch-store-recovery-v4
     try {
         const branch = defaultDeps
             .execSync("git rev-parse --abbrev-ref HEAD", {

package/dist/utils/repo-relative-path.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Canonical repository-relative form of a recorded path, as proof freshness
+ * reads it: POSIX separators and no `.` segments. An absolute path that
+ * points inside `workspaceRoot` is re-expressed relative to it, so
+ * `packages/a.ts`, `./packages/a.ts`, `packages\a.ts` and
+ * `<root>/packages/a.ts` all name the same file. Returns null for a path that
+ * leaves the repository (a `..` escape, another machine's absolute path, a
+ * drive letter or UNC share outside the root): such a location exists on one
+ * machine only, so hashing it would make the same commit prove differently
+ * in CI and on a developer checkout.
+ *
+ * The Unicode form of each name is kept as recorded: the result is used to
+ * read the file, and a case- or normalization-sensitive filesystem only finds
+ * a name under the exact bytes git checked out. Where a path is an identity
+ * (the workspace snapshot), the caller compares it in NFC.
+ */
+export declare function normalizeRepoRelativePath(workspaceRoot: string, candidate: string): string | null;
+//# sourceMappingURL=repo-relative-path.d.ts.map

package/dist/utils/repo-relative-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repo-relative-path.d.ts","sourceRoot":"","sources":["../../src/utils/repo-relative-path.ts"],"names":[],"mappings":"AAoBA;;;;;;;;;;;;;;;GAeG;AAEH,wBAAgB,yBAAyB,CACvC,aAAa,EAAE,MAAM,EACrB,SAAS,EAAE,MAAM,GAChB,MAAM,GAAG,IAAI,CAsBf"}

package/dist/utils/repo-relative-path.js

@@ -0,0 +1,58 @@
+/*
+ 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 path from "node:path";
+/**
+ * Canonical repository-relative form of a recorded path, as proof freshness
+ * reads it: POSIX separators and no `.` segments. An absolute path that
+ * points inside `workspaceRoot` is re-expressed relative to it, so
+ * `packages/a.ts`, `./packages/a.ts`, `packages\a.ts` and
+ * `<root>/packages/a.ts` all name the same file. Returns null for a path that
+ * leaves the repository (a `..` escape, another machine's absolute path, a
+ * drive letter or UNC share outside the root): such a location exists on one
+ * machine only, so hashing it would make the same commit prove differently
+ * in CI and on a developer checkout.
+ *
+ * The Unicode form of each name is kept as recorded: the result is used to
+ * read the file, and a case- or normalization-sensitive filesystem only finds
+ * a name under the exact bytes git checked out. Where a path is an identity
+ * (the workspace snapshot), the caller compares it in NFC.
+ */
+// implements REQ-kibi-fresh-verification-receipts-v2
+export function normalizeRepoRelativePath(workspaceRoot, candidate) {
+    if (candidate.trim() === "")
+        return null;
+    let slashed = candidate.replaceAll("\\", "/");
+    const foreignAbsolute = /^[A-Za-z]:\//.test(slashed) || slashed.startsWith("//");
+    if (slashed.startsWith("/") || foreignAbsolute) {
+        if (foreignAbsolute && path.sep === "/")
+            return null;
+        const root = path.resolve(workspaceRoot);
+        const relative = path.relative(root, path.resolve(candidate));
+        if (relative === "" || path.isAbsolute(relative))
+            return null;
+        slashed = relative.replaceAll("\\", "/");
+    }
+    const normalized = path.posix.normalize(slashed).replace(/\/+$/, "");
+    if (normalized === "" ||
+        normalized === "." ||
+        normalized === ".." ||
+        normalized.startsWith("../")) {
+        return null;
+    }
+    return normalized;
+}

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

@@ -23,6 +23,11 @@ export declare const GENERATED_RULES: readonly [{
     readonly description: "Authored Markdown and relationship-shard edges must exactly match the compiled KB";
     readonly enforcementClass: "canonical";
     readonly category: "integrity";
+}, {
+    readonly name: "source-path-dangling";
+    readonly description: "An authored entity's source field must name an existing workspace path (a #anchor suffix is ignored), an existing entity id, or an http(s) URL; a missing source is allowed";
+    readonly enforcementClass: "canonical";
+    readonly category: "integrity";
 }, {
     readonly name: "no-cycles";
     readonly description: "No circular dependency chains in requirements";
@@ -38,6 +43,36 @@ export declare const GENERATED_RULES: readonly [{
     readonly description: "Deprecated ADRs must have a successor ADR that supersedes them";
     readonly enforcementClass: "canonical";
     readonly category: "lifecycle";
+}, {
+    readonly name: "superseded-requirement-open";
+    readonly description: "A requirement that another requirement supersedes must have status closed, and supersedes links between requirements must not form a cycle";
+    readonly enforcementClass: "canonical";
+    readonly category: "lifecycle";
+}, {
+    readonly name: "scenario-feasibility";
+    readonly description: "A scenario that expects success must not assume property values that cannot hold, alone or together, with what current requirements require through typed property values or rules, unless an approved exception requirement waives that requirement or the listed clauses";
+    readonly enforcementClass: "canonical";
+    readonly category: "integrity";
+}, {
+    readonly name: "scenario-feasibility-unknown";
+    readonly description: "Advisory: a scenario that expects success assumes nothing, assumes values that contradict each other, assumes a property value no governing requirement constrains comparably (type, unit or operator mismatch, or conflicting requirements), leaves a governing rule's conditions undecided, or conflicts only with constraints whose validity window may not cover it, so its feasibility cannot be decided";
+    readonly enforcementClass: "advisory";
+    readonly category: "integrity";
+}, {
+    readonly name: "exception-claim-keys";
+    readonly description: "An exception requirement's exempts_claims must name claim keys of a requirement it exempts, and requires an exempts link";
+    readonly enforcementClass: "canonical";
+    readonly category: "integrity";
+}, {
+    readonly name: "numeric-string-value";
+    readonly description: "Advisory: a property value stores a numeric-looking string where the comparison is numeric (ordering operator, or an int/number fact on the same property); the finding names the fact and the typed value, without converting it";
+    readonly enforcementClass: "advisory";
+    readonly category: "integrity";
+}, {
+    readonly name: "rule-key-arguments-missing";
+    readonly description: "Advisory: an opposing rule pair stays unresolved only because a body predicate declares no key_arguments; the finding names the predicate and the key positions that would decide the pair";
+    readonly enforcementClass: "advisory";
+    readonly category: "integrity";
 }, {
     readonly name: "domain-contradictions";
     readonly description: "Detect contradictions between requirements constraining the same fact";
@@ -71,7 +106,7 @@ export declare const GENERATED_RULES: readonly [{
 }, {
     readonly name: "strict-fact-shape";
     readonly description: "Detect malformed strict facts (facts with fact_kind that are missing required fields)";
-    readonly enforcementClass: "advisory";
+    readonly enforcementClass: "canonical";
     readonly category: "integrity";
 }, {
     readonly name: "strict-req-fact-pairing";
@@ -116,12 +151,12 @@ export declare const GENERATED_RULES: readonly [{
     readonly diagnosticSeverity: "info";
 }, {
     readonly name: "subject-key-identity";
-    readonly description: "Subject keys must name a shared component, not be derived from a requirement ID";
+    readonly description: "Subject keys must name a shared component, not be derived from a requirement ID, and one subject or claim must not be minted as several active subject facts or identical property_value facts";
     readonly enforcementClass: "advisory";
     readonly category: "integrity";
 }, {
     readonly name: "subject-key-shape";
-    readonly description: "Subject keys follow dotted component.aspect[.sub] with lowercase snake segments";
+    readonly description: "Subject keys follow dotted component.aspect[.sub] with lowercase snake segments, and property keys name a property rather than a numbered clause (clause_NN)";
     readonly enforcementClass: "advisory";
     readonly category: "integrity";
 }, {
@@ -130,6 +165,43 @@ export declare const GENERATED_RULES: readonly [{
     readonly enforcementClass: "advisory";
     readonly category: "integrity";
     readonly diagnosticSeverity: "info";
+}, {
+    readonly name: "exception-unapproved";
+    readonly description: "Advisory: a current exception requirement exempts another requirement but has no approved_by, so it exempts nothing until a human approves it";
+    readonly enforcementClass: "advisory";
+    readonly category: "integrity";
+}, {
+    readonly name: "exception-approval-self-attested";
+    readonly description: "Advisory: an agent-authored exception records approved_by but no human corroborated it (origin.approved_by or approval_ref is missing), so a human should confirm the approval";
+    readonly enforcementClass: "advisory";
+    readonly category: "integrity";
+}, {
+    readonly name: "agent-requirement-unapproved";
+    readonly description: "Informational: current requirements authored by an agent (origin.kind agent) that no human has approved (origin.approved_by), listed up to 25 per check";
+    readonly enforcementClass: "advisory";
+    readonly category: "lifecycle";
+    readonly diagnosticSeverity: "info";
+}, {
+    readonly name: "requirement-rationale-missing";
+    readonly description: "Advisory: a current requirement authored by a human or an agent (origin.kind human or agent) states no rationale: no rationale field, no Rationale or Why section in its body, and no link to an ADR; listed up to 25 per check plus one summary finding";
+    readonly enforcementClass: "advisory";
+    readonly category: "lifecycle";
+}, {
+    readonly name: "symbol-owner-superseded";
+    readonly description: "Advisory: a symbol whose every implements target is superseded or deprecated has no current owning requirement; listed up to 25 per check plus one summary finding";
+    readonly enforcementClass: "advisory";
+    readonly category: "traceability";
+}, {
+    readonly name: "adr-unlinked";
+    readonly description: "Advisory: an accepted ADR that no requirement or other ADR is linked with (relates_to, supersedes or any typed edge, in either direction)";
+    readonly enforcementClass: "advisory";
+    readonly category: "lifecycle";
+}, {
+    readonly name: "adr-proposed";
+    readonly description: "Informational: an ADR that is still proposed and not superseded, so nobody accepted or withdrew the decision";
+    readonly enforcementClass: "advisory";
+    readonly category: "lifecycle";
+    readonly diagnosticSeverity: "info";
 }, {
     readonly name: "predicate-schema-conformance";
     readonly description: "Predicate facts match a predicate_schema (project-local, or the built-in catalog in the default namespace) and use its declared argument constants";

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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA6LlB,CAAC"}
+{"version":3,"file":"rule-registry.generated.d.ts","sourceRoot":"","sources":["../../src/utils/rule-registry.generated.ts"],"names":[],"mappings":"AAUA,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAiSlB,CAAC"}