kibi-cli 2.1.0 → 2.3.0

package/dist/public/skills/kibi-usage/resources/operation-access.md

@@ -23,6 +23,7 @@ per operation. Effects are authoritative for mutability and adapter annotations.
 | `kb_upsert` | `upsert` | --input JSON | write | yes | kb-write, workspace-write | peer; capability-selected | kibi.kb_upsert.v1 | yes | unsafe | no | yes |
 | `kb_delete` | `delete` | --input JSON | write | yes | kb-write, workspace-write | peer; capability-selected | kibi.kb_delete.v1 | yes | unsafe | no | yes |
 | `kb_check` | `check` | --input JSON or flags | read | yes | kb-read, workspace-read | peer; capability-selected | kibi.kb_check.v1 | no | safe | no | yes |
+| `kb_prepare_impact_review` | `prepare-impact-review` | --input JSON | read | no | workspace-read, kb-read | peer; capability-selected | kibi.kb_prepare_impact_review.v1 | no | safe | no | yes |
 | `kb_sparql_remote` | `sparql-remote` | --input JSON | read | no | network-read | peer; capability-selected | kibi.kb_sparql_remote.v1 | no | safe | yes | yes |
 | `kb_compile_intent` | `compile-intent` | --input JSON | read | yes | kb-read, workspace-read | peer; capability-selected | kibi.kb_compile_intent.v1 | no | safe | no | yes |
 | `kb_apply_plan` | `apply-plan` | --input JSON | write | yes | kb-read, kb-write, workspace-read, workspace-write | peer; capability-selected | kibi.kb_apply_plan.v1 | yes | unsafe | no | yes |

package/dist/public/skills/kibi-usage/resources/relationship-directions.md

@@ -12,6 +12,7 @@
 | `constrains` | req -> fact(subject) | Requirement constrains a strict-lane domain fact |
 | `requires_property` | req -> fact(property_value) | Requirement requires a specific property value fact |
 | `supersedes` | new-req -> old-req | New requirement formally replaces an old requirement |
+| `restates` | req -> req | Requirement intentionally restates another current requirement (for example a product requirement echoed in a platform requirement); suppresses `domain-redundancy` for that pair without retiring either side |
 | `covered_by` | symbol -> test | Production symbol has test coverage evidence |
 
 ## Valid Payload Examples
@@ -20,32 +21,32 @@
 ```yaml
 relationships:
   - type: implements
-    from: SYM-001
-    to: REQ-001
+    from: SYM-operation-execute-check
+    to: REQ-cli-check
 ```
 
 ### specified_by
 ```yaml
 relationships:
   - type: specified_by
-    from: REQ-001
-    to: SCEN-001
+    from: REQ-mcp-search-discovery
+    to: SCEN-mcp-search-discovery
 ```
 
 ### verified_by
 ```yaml
 relationships:
   - type: verified_by
-    from: REQ-001
-    to: TEST-001
+    from: REQ-mcp-search-discovery
+    to: TEST-mcp-search-discovery
 ```
 
 ### validates
 ```yaml
 relationships:
   - type: validates
-    from: TEST-001
-    to: SCEN-001
+    from: TEST-mcp-search-discovery
+    to: SCEN-mcp-search-discovery
 ```
 
 ### executable_for
@@ -53,39 +54,56 @@ relationships:
 relationships:
   - type: executable_for
     from: SYM-test-login
-    to: TEST-001
+    to: TEST-mcp-search-discovery
 ```
 
 ### constrains
 ```yaml
 relationships:
   - type: constrains
-    from: REQ-019
-    to: FACT-USER-ROLE
+    from: REQ-cli-check
+    to: FACT-SUBJECT-KIBI-CHECK
 ```
 
 ### requires_property
 ```yaml
 relationships:
   - type: requires_property
-    from: REQ-019
-    to: FACT-LIMIT-3
+    from: REQ-cli-check
+    to: FACT-PROP-CHECK-FAILURE-EXIT-CODE
 ```
 
 ### supersedes
 ```yaml
 relationships:
   - type: supersedes
-    from: REQ-001-v2
-    to: REQ-001
+    from: REQ-opencode-kibi-briefing-v2
+    to: REQ-opencode-kibi-briefing-v1
 ```
 
+A `-v2` suffix is acceptable only for a direct superseding replacement like
+this one; otherwise name the new requirement by the behavior it governs.
+
+### restates
+```yaml
+# Illustrative: a product requirement echoes a platform requirement verbatim.
+relationships:
+  - type: restates
+    from: REQ-billing-invoice-retention
+    to: REQ-platform-record-retention
+```
+
+Use `restates` only when two current requirements deliberately ground the same
+logical term (same predicate, property tuple, or rule semantic key). It keeps
+both requirements current and tells `domain-redundancy` the duplication is
+intentional. If one requirement replaces the other, use `supersedes` instead.
+
 ### covered_by
 ```yaml
 relationships:
   - type: covered_by
-    from: SYM-handler
-    to: TEST-005
+    from: SYM-operation-execute-check
+    to: TEST-mcp-search-discovery
 ```
 
 ## Invalid Test-Fact Shortcuts

package/dist/public/skills/kibi-usage/resources/source-authoring.md

@@ -29,3 +29,39 @@ Cancellation follows the same rule: wait for the terminal journal state. A
 pre-commit rollback is retryable, a committed source with a failed derivative
 is repairable, and an indeterminate outcome is non-retryable until its recovery
 action resolves the journal.
+
+## Naming entities
+
+Name every entity by what it governs, the way you would name a source file.
+Never choose "the next number": parallel branches pick the same next number and
+collide even when they touch unrelated behavior.
+
+- Use `<TYPE>-<area>-<behavior>` in kebab-case, with the type prefix kept
+  uppercase: `REQ-cli-gc`, `SCEN-mcp-search-discovery`,
+  `TEST-mcp-search-discovery`, `ADR-capability-plugins-v1`,
+  `EVT-exact-branch-store-ensure`, and a flag named after its gate such as
+  `FLAG-scip-symbol-extraction`.
+- The filename stem equals the frontmatter `id`
+  (`.kb/requirements/REQ-cli-gc.md` has `id: REQ-cli-gc`). Always set `id`
+  explicitly; a missing `id` falls back to a path-and-title hash that changes
+  when the file is renamed.
+- Before creating an entity, `kb_search` the area. If an existing entity already
+  covers the behavior, update it, or create a replacement and link it with
+  `supersedes`. A `-v2` suffix is acceptable only for that direct superseding
+  replacement.
+- A name collision with another branch usually means the same work was done
+  twice. Reconcile the two entities; do not rename one of them to dodge the
+  collision.
+- The area prefix is for humans. Whether two requirements are about the same
+  thing is decided by their facts: a shared `subject_key` and identical
+  predicate or property signatures, which `domain-redundancy` and
+  `domain-contradictions` compare deterministically. Reuse existing subject keys
+  (dotted `component.aspect[.sub]`, lowercase snake segments such as
+  `kibi.cli.check.staged`) instead of deriving a subject from the requirement
+  ID.
+
+`entity-id-style` reports new purely numeric IDs (`REQ-123`) and IDs whose
+filename stem differs from `id` as non-blocking quality diagnostics. Legacy
+numbered entities created before the naming standard are grandfathered and are
+not renamed, because code comments such as `// implements REQ-003` still
+reference them.

package/dist/public/skills/kibi-usage/resources/workflows.md

@@ -33,11 +33,62 @@ surfaces are a release defect: require a new package version and label any
 project override temporary. This skill never selects a package manager or
 edits dependency configuration.
 
+## Choosing a discovery mode
+
+`kb_search` is not one behavior. It selects deterministic intent ranking when
+you pass `rankingMode: "intent-v1"`, `semanticFacets`, or `sourceLocations`,
+and legacy lexical ranking otherwise. Naming the tool is not enough; the inputs
+decide the path.
+
+- **Exact identity** — you already know the ID. Use `kb_query`, not search.
+- **Literal token** — a symbol, file, or error string that appears verbatim.
+  Use lexical `kb_search` and keep the query close to the literal text.
+- **Conceptual or behavioral** — "how does checkout handle a declined card".
+  Use intent mode and ground it in what you actually know:
+
+```json
+{
+  "query": "declined card during checkout",
+  "rankingMode": "intent-v1",
+  "semanticFacets": {
+    "actors": ["shopper"],
+    "actions": ["pay"],
+    "objects": ["card"],
+    "constraints": ["declined"]
+  }
+}
+```
+
+- **Before changing code** — pass the file you are about to edit as a source
+  location, so results are matched against source-linked symbols and return
+  source evidence:
+
+```json
+{
+  "query": "checkout total rounding",
+  "rankingMode": "intent-v1",
+  "sourceLocations": [{ "path": "src/checkout.ts", "symbol": "computeTotal" }]
+}
+```
+
+Supply facets only from the request, the code, or prior results. Inventing
+facets fabricates evidence and biases ranking. Intent mode abstains below
+`minScore` instead of returning weak matches; an abstention is an explicit
+no-answer, so widen the query or drop to lexical search rather than treating it
+as "nothing exists". There is no target percentage of intent-mode calls — a
+literal identifier lookup is still best served lexically.
+
+Results are summaries by default: identifying metadata, score, reasons, and a
+snippet. Read them to pick candidates, then `kb_query` those IDs for full
+bodies, or pass `fields: "full"` when you genuinely need every body. Extract
+the relevant existing constraints and decisions from the response before
+planning a behavior change; a search receipt is not comprehension.
+
 ## Discovery to Validation Sequence
 
 The canonical workflow for any KB operation follows this pattern:
 
-1. **Discover**: `kb_search` with focused probes
+1. **Discover**: `kb_search` with focused probes; pick the mode above
 2. **Confirm**: `kb_query` for exact IDs and state
 3. **Inspect**: `kb_status` when freshness matters
 4. **Decompose**: `kb_semantic_advisor` on the complete normative prose; verify or supply every atomic clause

package/dist/public/telemetry-acceptance.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"telemetry-acceptance.d.ts","sourceRoot":"","sources":["../../src/public/telemetry-acceptance.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAC3D,OAAO,KAAK,EAEV,yBAAyB,EACzB,yBAAyB,EAGzB,qBAAqB,EACrB,mBAAmB,EACpB,MAAM,iCAAiC,CAAC;AAEzC,YAAY,EACV,yBAAyB,EACzB,yBAAyB,EACzB,yBAAyB,EACzB,yBAAyB,EACzB,iBAAiB,EACjB,qBAAqB,EACrB,mBAAmB,GACpB,MAAM,iCAAiC,CAAC;AAEzC,eAAO,MAAM,4BAA4B,EACvC,8BAAuC,CAAC;AAE1C,eAAO,MAAM,mCAAmC;;;;;;;;;;;;CAYF,CAAC;AAgB/C,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,MAAM,GACf,mBAAmB,EAAE,CAsBvB;AA0DD,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,QAAQ,EAAE,IAAI,GAAG,IAAI,GAAG,GAAG,EAC3B,QAAQ,EAAE,MAAM,GACf,qBAAqB,CAKvB;AA2bD,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,SAAS,mBAAmB,EAAE,EACtC,GAAG,GAAE,IAAiB,EACtB,MAAM,GAAE,yBAA+D,GACtE,yBAAyB,CA6D3B;AA+DD,wBAAgB,oCAAoC,CAClD,MAAM,EAAE,yBAAyB,GAChC,SAAS,iBAAiB,EAAE,CA+E9B"}
+{"version":3,"file":"telemetry-acceptance.d.ts","sourceRoot":"","sources":["../../src/public/telemetry-acceptance.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAC3D,OAAO,KAAK,EAEV,yBAAyB,EACzB,yBAAyB,EAGzB,qBAAqB,EACrB,mBAAmB,EACpB,MAAM,iCAAiC,CAAC;AAEzC,YAAY,EACV,yBAAyB,EACzB,yBAAyB,EACzB,yBAAyB,EACzB,yBAAyB,EACzB,iBAAiB,EACjB,qBAAqB,EACrB,mBAAmB,GACpB,MAAM,iCAAiC,CAAC;AAEzC,eAAO,MAAM,4BAA4B,EACvC,8BAAuC,CAAC;AAE1C,eAAO,MAAM,mCAAmC;;;;;;;;;;;;CAYF,CAAC;AAgB/C,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,MAAM,GACf,mBAAmB,EAAE,CAsBvB;AA0DD,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,QAAQ,EAAE,IAAI,GAAG,IAAI,GAAG,GAAG,EAC3B,QAAQ,EAAE,MAAM,GACf,qBAAqB,CAKvB;AA0dD,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,SAAS,mBAAmB,EAAE,EACtC,GAAG,GAAE,IAAiB,EACtB,MAAM,GAAE,yBAA+D,GACtE,yBAAyB,CA6D3B;AA+DD,wBAAgB,oCAAoC,CAClD,MAAM,EAAE,yBAAyB,GAChC,SAAS,iBAAiB,EAAE,CA+E9B"}

package/dist/public/telemetry-acceptance.js

@@ -251,14 +251,30 @@ function advisorBeforeRequirementWriteMetric(all, recentStart, policy) {
         },
     };
 }
+function sourceLookupMessage(zeroResults, lookups, unobservable) {
+    const unreadable = unobservable > 0
+        ? `${unobservable} source-linked lookups recorded no readable result count.`
+        : "";
+    if (lookups === 0) {
+        return (unreadable ||
+            "No source-linked query or search calls occurred in the evaluated window.");
+    }
+    const observed = `${zeroResults}/${lookups} source-linked lookups returned zero results.`;
+    return unreadable ? `${observed} ${unreadable}` : observed;
+}
 function sourceLookupMetric(recent, policy) {
-    const lookups = recent.filter(({ event }) => {
+    const sourceLinked = recent.filter(({ event }) => {
         if ((event.tool !== "kb_query" && event.tool !== "kb_search") ||
             !eventSucceeded(event)) {
             return false;
         }
         return typeof eventArgs(event).sourceFile === "string";
     });
+    // A row whose count could not be read is unobservable, not a hit.  Counting
+    // it as a non-zero result would let a broken logger report a healthy rate.
+    const lookups = sourceLinked.filter(({ event }) => typeof event.result_count === "number" ||
+        typeof event.zero_results === "boolean");
+    const unobservable = sourceLinked.length - lookups.length;
     const zeroResults = lookups.filter(({ event }) => event.zero_results === true || event.result_count === 0);
     const actual = rate(zeroResults.length, lookups.length);
     const sourceCounts = new Map();
@@ -268,7 +284,9 @@ function sourceLookupMetric(recent, policy) {
     }
     return {
         id: "source_lookup_zero_result_rate",
-        status: thresholdStatus(actual, "<=", policy.sourceLookupZeroResultMaximum),
+        status: lookups.length === 0 && unobservable > 0
+            ? "insufficient_evidence"
+            : thresholdStatus(actual, "<=", policy.sourceLookupZeroResultMaximum),
         numerator: zeroResults.length,
         denominator: lookups.length,
         ...(actual !== undefined ? { rate: actual } : {}),
@@ -276,9 +294,7 @@ function sourceLookupMetric(recent, policy) {
             operator: "<=",
             value: policy.sourceLookupZeroResultMaximum,
         },
-        message: lookups.length === 0
-            ? "No source-linked query or search calls occurred in the evaluated window."
-            : `${zeroResults.length}/${lookups.length} source-linked lookups returned zero results.`,
+        message: sourceLookupMessage(zeroResults.length, lookups.length, unobservable),
         evidence: {
             zeroResultSourceFiles: [...sourceCounts.entries()]
                 .sort(([leftFile, leftCount], [rightFile, rightCount]) => rightCount - leftCount || leftFile.localeCompare(rightFile))

package/dist/relationships/shards.d.ts

@@ -50,6 +50,12 @@ export type RemovedRelationshipRecords = Readonly<{
  * Remove exact legacy-shard relationships using an atomic temp-file rename.
  * The caller is responsible for retracting the compiled RDF edge afterwards.
  */
+/**
+ * A shard's YAML without the selected relationships. The sequence is patched in
+ * place so comments, ordering, and unrelated records survive; callers that must
+ * approve the bytes before writing (deletion plans) render without writing.
+ */
+export declare function renderShardWithout(text: string, selectors: readonly RelationshipSelector[], shardPath: string): string;
 export declare function removeRelationshipsFromShards(kbRoot: string, selectors: readonly RelationshipSelector[]): RemovedRelationshipRecords[];
 /**
  * Appends a relationship to the appropriate shard.

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

@@ -1 +1 @@
-{"version":3,"file":"shards.d.ts","sourceRoot":"","sources":["../../src/relationships/shards.ts"],"names":[],"mappings":"AAwBA;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAGrD;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAGzE;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,kBAAkB,EAAE,CAsFjE;AAED;;;GAGG;AACH,wBAAgB,UAAU,CACxB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,kBAAkB,EAAE,GAC5B,IAAI,CAoBN;AAwBD,MAAM,MAAM,oBAAoB,GAAG,QAAQ,CAAC;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;CACZ,CAAC,CAAC;AAEH,MAAM,MAAM,0BAA0B,GAAG,QAAQ,CAAC;IAChD,QAAQ,EAAE,oBAAoB,CAAC;IAC/B,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9B,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,OAAO,EAAE,OAAO,CAAC;CAClB,CAAC,CAAC;AAEH;;;GAGG;AACH,wBAAgB,6BAA6B,CAC3C,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,SAAS,oBAAoB,EAAE,GACzC,0BAA0B,EAAE,CAwD9B;AAqCD;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,IAAI,CAAC,kBAAkB,EAAE,IAAI,CAAC,GAC3C;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAwCzC;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAUnD;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,kBAAkB,EAAE,CAUlE;AAED;;GAEG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,kBAAkB,EAAE,EAC7B,cAAc,EAAE,GAAG,CAAC,MAAM,CAAC,GAC1B,kBAAkB,EAAE,CAKtB;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,GACT,MAAM,CAMR;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAE1B,QAAQ,EAAE,kBAAkB,EAAE,EAC9B,QAAQ,EAAE,kBAAkB,EAAE,GAC7B,kBAAkB,EAAE,CAgCtB"}
+{"version":3,"file":"shards.d.ts","sourceRoot":"","sources":["../../src/relationships/shards.ts"],"names":[],"mappings":"AAwBA;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAGrD;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAGzE;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,kBAAkB,EAAE,CAsFjE;AAED;;;GAGG;AACH,wBAAgB,UAAU,CACxB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,kBAAkB,EAAE,GAC5B,IAAI,CAoBN;AAwBD,MAAM,MAAM,oBAAoB,GAAG,QAAQ,CAAC;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;CACZ,CAAC,CAAC;AAEH,MAAM,MAAM,0BAA0B,GAAG,QAAQ,CAAC;IAChD,QAAQ,EAAE,oBAAoB,CAAC;IAC/B,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9B,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,OAAO,EAAE,OAAO,CAAC;CAClB,CAAC,CAAC;AAEH;;;GAGG;AACH;;;;GAIG;AAEH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,SAAS,oBAAoB,EAAE,EAC1C,SAAS,EAAE,MAAM,GAChB,MAAM,CA2BR;AAED,wBAAgB,6BAA6B,CAC3C,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,SAAS,oBAAoB,EAAE,GACzC,0BAA0B,EAAE,CAwC9B;AAqCD;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,IAAI,CAAC,kBAAkB,EAAE,IAAI,CAAC,GAC3C;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAwCzC;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAUnD;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,kBAAkB,EAAE,CAUlE;AAED;;GAEG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,kBAAkB,EAAE,EAC7B,cAAc,EAAE,GAAG,CAAC,MAAM,CAAC,GAC1B,kBAAkB,EAAE,CAKtB;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,GACT,MAAM,CAMR;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAE1B,QAAQ,EAAE,kBAAkB,EAAE,EAC9B,QAAQ,EAAE,kBAAkB,EAAE,GAC7B,kBAAkB,EAAE,CAgCtB"}

package/dist/relationships/shards.js

@@ -163,6 +163,31 @@ function atomicWriteText(targetPath, body) {
  * Remove exact legacy-shard relationships using an atomic temp-file rename.
  * The caller is responsible for retracting the compiled RDF edge afterwards.
  */
+/**
+ * A shard's YAML without the selected relationships. The sequence is patched in
+ * place so comments, ordering, and unrelated records survive; callers that must
+ * approve the bytes before writing (deletion plans) render without writing.
+ */
+// implements REQ-kibi-operation-interface-parity
+export function renderShardWithout(text, selectors, shardPath) {
+    const wanted = new Set(selectors.map((selector) => `${selector.type}\0${selector.from}\0${selector.to}`));
+    const document = parseDocument(text);
+    const sequence = document.get("relationships", true);
+    if (!sequence || typeof sequence !== "object" || !("items" in sequence)) {
+        throw new Error(`Invalid shard file: missing 'relationships' array at ${shardPath}`);
+    }
+    const items = sequence.items;
+    for (let index = items.length - 1; index >= 0; index -= 1) {
+        const item = items[index];
+        if (!item || typeof item !== "object" || !("get" in item))
+            continue;
+        const get = item.get.bind(item);
+        if (wanted.has(`${String(get("type"))}\0${String(get("from"))}\0${String(get("to"))}`)) {
+            document.deleteIn(["relationships", index]);
+        }
+    }
+    return document.toString();
+}
 export function removeRelationshipsFromShards(kbRoot, selectors) {
     const wanted = new Set(selectors.map((selector) => `${selector.type}\0${selector.from}\0${selector.to}`));
     const removed = new Map();
@@ -171,25 +196,7 @@ export function removeRelationshipsFromShards(kbRoot, selectors) {
         const matching = records.filter((record) => wanted.has(`${record.type}\0${record.from}\0${record.to}`));
         if (matching.length === 0)
             continue;
-        // Patch the YAML sequence in place so comments, ordering, and unrelated
-        // records survive a relationship deletion. The compiled store is never
-        // the mutation target; this shard remains the canonical source artifact.
-        const document = parseDocument(fs.readFileSync(shardPath, "utf8"));
-        const sequence = document.get("relationships", true);
-        if (!sequence || typeof sequence !== "object" || !("items" in sequence)) {
-            throw new Error(`Invalid shard file: missing 'relationships' array at ${shardPath}`);
-        }
-        const items = sequence.items;
-        for (let index = items.length - 1; index >= 0; index -= 1) {
-            const item = items[index];
-            if (!item || typeof item !== "object" || !("get" in item))
-                continue;
-            const get = item.get.bind(item);
-            if (wanted.has(`${String(get("type"))}\0${String(get("from"))}\0${String(get("to"))}`)) {
-                document.deleteIn(["relationships", index]);
-            }
-        }
-        atomicWriteText(shardPath, document.toString());
+        atomicWriteText(shardPath, renderShardWithout(fs.readFileSync(shardPath, "utf8"), selectors, shardPath));
         for (const record of matching) {
             const key = `${record.type}\0${record.from}\0${record.to}`;
             const entry = removed.get(key) ?? { paths: [], sources: [] };

package/dist/schemas/entity.schema.json

@@ -1173,6 +1173,28 @@
                 "type": "string"
             }
         },
+        "argument_constants": {
+            "type": "object",
+            "additionalProperties": {
+                "type": "array",
+                "minItems": 1,
+                "uniqueItems": true,
+                "items": {
+                    "type": "string",
+                    "minLength": 1
+                }
+            }
+        },
+        "argument_aliases": {
+            "type": "object",
+            "additionalProperties": {
+                "type": "object",
+                "additionalProperties": {
+                    "type": "string",
+                    "minLength": 1
+                }
+            }
+        },
         "rule_ir": {
             "$ref": "#/$defs/logicRule"
         },
@@ -1373,6 +1395,16 @@
                                 "predicate_args"
                             ]
                         },
+                        {
+                            "required": [
+                                "argument_constants"
+                            ]
+                        },
+                        {
+                            "required": [
+                                "argument_aliases"
+                            ]
+                        },
                         {
                             "required": [
                                 "rule_ir"

package/dist/traceability/analysis-gate.d.ts

@@ -0,0 +1,39 @@
+import type { HunkRange } from "./git-staged.js";
+type LineRange = Readonly<{
+    startLine: number;
+    endLine: number;
+}>;
+export type GateAnalysis<Range extends LineRange> = Readonly<{
+    status: "ok" | "partial" | "unsupported" | "failed";
+    diagnosticCodes: readonly string[];
+    uncoveredRanges: readonly (Range & Readonly<{
+        reason: string;
+    }>)[];
+}>;
+/** What one side of a changed file needs before it can pass. */
+type AnalysisObligation<Range extends LineRange> = Readonly<{
+    kind: "none";
+}> | Readonly<{
+    kind: "blocked";
+    reason: string;
+}> | Readonly<{
+    kind: "unsupported_review";
+}> | Readonly<{
+    kind: "partial_review";
+    ranges: readonly Range[];
+}>;
+/**
+ * The single rule for when incomplete source analysis blocks a change.
+ *
+ * - The before side is historical and cannot be corrected by the author, so it
+ *   is informational and never blocks or needs review.
+ * - On the after side, failed analysis and non-local gaps (syntax, parse,
+ *   timeout, integrity) always block.
+ * - A local gap (a macro, decorator or other declared limitation) matters only
+ *   where it overlaps the changed lines; elsewhere the file was already in that
+ *   state and this change did not touch it.
+ * - Unsupported after-side analysis needs one whole-file review.
+ */
+export declare function analysisObligation<Range extends LineRange>(side: "before" | "after", analysis: GateAnalysis<Range> | null | undefined, newHunkRanges: readonly HunkRange[]): AnalysisObligation<Range>;
+export {};
+//# sourceMappingURL=analysis-gate.d.ts.map

package/dist/traceability/analysis-gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analysis-gate.d.ts","sourceRoot":"","sources":["../../src/traceability/analysis-gate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAUjD,KAAK,SAAS,GAAG,QAAQ,CAAC;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAGlE,MAAM,MAAM,YAAY,CAAC,KAAK,SAAS,SAAS,IAAI,QAAQ,CAAC;IAC3D,MAAM,EAAE,IAAI,GAAG,SAAS,GAAG,aAAa,GAAG,QAAQ,CAAC;IACpD,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,eAAe,EAAE,SAAS,CAAC,KAAK,GAAG,QAAQ,CAAC;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC,EAAE,CAAC;CACpE,CAAC,CAAC;AAEH,gEAAgE;AAChE,KAAK,kBAAkB,CAAC,KAAK,SAAS,SAAS,IAC3C,QAAQ,CAAC;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,GAC1B,QAAQ,CAAC;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,GAC7C,QAAQ,CAAC;IAAE,IAAI,EAAE,oBAAoB,CAAA;CAAE,CAAC,GACxC,QAAQ,CAAC;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,MAAM,EAAE,SAAS,KAAK,EAAE,CAAA;CAAE,CAAC,CAAC;AAuBnE;;;;;;;;;;;GAWG;AAEH,wBAAgB,kBAAkB,CAAC,KAAK,SAAS,SAAS,EACxD,IAAI,EAAE,QAAQ,GAAG,OAAO,EACxB,QAAQ,EAAE,YAAY,CAAC,KAAK,CAAC,GAAG,IAAI,GAAG,SAAS,EAChD,aAAa,EAAE,SAAS,SAAS,EAAE,GAClC,kBAAkB,CAAC,KAAK,CAAC,CAqB3B"}

package/dist/traceability/analysis-gate.js

@@ -0,0 +1,51 @@
+/**
+ * Diagnostics that make the whole parse unreliable rather than one region.
+ * A deleted brace can surface as a syntax error far from the edited lines, so
+ * these never narrow to the changed hunks and never accept a residual review.
+ */
+const NON_LOCAL_ANALYSIS_MARKER = /(?:syntax|parse|timeout|timed[\s_-]*out|integrity|checksum|failed|failure|error|input[\s_-]*limit)/i;
+function hasNonLocalAnalysisGap(analysis) {
+    return NON_LOCAL_ANALYSIS_MARKER.test([
+        ...analysis.diagnosticCodes,
+        ...analysis.uncoveredRanges.map((range) => range.reason),
+    ].join("\n"));
+}
+/** Uncovered ranges that overlap a changed line of the after side. */
+function rangesTouchingHunks(ranges, hunks) {
+    return ranges.filter((range) => hunks.some((hunk) => range.startLine <= hunk.end && hunk.start <= range.endLine));
+}
+/**
+ * The single rule for when incomplete source analysis blocks a change.
+ *
+ * - The before side is historical and cannot be corrected by the author, so it
+ *   is informational and never blocks or needs review.
+ * - On the after side, failed analysis and non-local gaps (syntax, parse,
+ *   timeout, integrity) always block.
+ * - A local gap (a macro, decorator or other declared limitation) matters only
+ *   where it overlaps the changed lines; elsewhere the file was already in that
+ *   state and this change did not touch it.
+ * - Unsupported after-side analysis needs one whole-file review.
+ */
+// implements REQ-source-analysis-v2
+export function analysisObligation(side, analysis, newHunkRanges) {
+    if (side === "before" || !analysis || analysis.status === "ok")
+        return { kind: "none" };
+    if (analysis.status === "failed")
+        return { kind: "blocked", reason: "source analysis failed" };
+    if (analysis.status === "unsupported")
+        return { kind: "unsupported_review" };
+    if (analysis.uncoveredRanges.length === 0)
+        return {
+            kind: "blocked",
+            reason: "partial analysis did not report which ranges it left uncovered",
+        };
+    if (hasNonLocalAnalysisGap(analysis))
+        return {
+            kind: "blocked",
+            reason: "a parser, syntax, timeout or integrity diagnostic affects the whole file",
+        };
+    const ranges = rangesTouchingHunks(analysis.uncoveredRanges, newHunkRanges);
+    return ranges.length === 0
+        ? { kind: "none" }
+        : { kind: "partial_review", ranges };
+}

package/dist/traceability/git-change-snapshot.d.ts

@@ -0,0 +1,27 @@
+import type { StagedPath } from "./git-staged.js";
+export type SnapshotGitReader = (args: readonly string[]) => Buffer;
+export interface GitChangeSnapshot {
+    /** Tree at the captured base commit, or the canonical empty tree when unborn. */
+    baseTree: string;
+    /** The single tree written from the captured index (staged snapshots). */
+    headTree: string;
+    /** Captured base commit, or null for an unborn repository. */
+    headCommit: string | null;
+    /** Run a Git command against immutable captured trees/blobs. */
+    readGit(args: readonly string[]): Buffer;
+    /** Read immutable object IDs in one process; no working-tree reads. */
+    readBlobs(oids: readonly string[]): ReadonlyMap<string, Buffer>;
+    /** Reject a changed HEAD or index tree after staged analysis. */
+    assertUnchanged(): void;
+    inventory: StagedPath[];
+}
+/** Capture one immutable tree from the index and inventory only Git objects. */
+export declare function captureStagedSnapshot(workspaceRoot: string): GitChangeSnapshot;
+/**
+ * Capture changes between explicit revisions. The caller chooses `base`; for
+ * merge-impact analysis this is commonly the merge base computed with
+ * `git merge-base target head`. This helper resolves each input once and does
+ * not silently choose a merge base of its own.
+ */
+export declare function captureDiffSnapshot(workspaceRoot: string, base: string, head: string): GitChangeSnapshot;
+//# sourceMappingURL=git-change-snapshot.d.ts.map

package/dist/traceability/git-change-snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-change-snapshot.d.ts","sourceRoot":"","sources":["../../src/traceability/git-change-snapshot.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAIV,UAAU,EAEX,MAAM,iBAAiB,CAAC;AAKzB,MAAM,MAAM,iBAAiB,GAAG,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,KAAK,MAAM,CAAC;AAGpE,MAAM,WAAW,iBAAiB;IAChC,iFAAiF;IACjF,QAAQ,EAAE,MAAM,CAAC;IACjB,0EAA0E;IAC1E,QAAQ,EAAE,MAAM,CAAC;IACjB,8DAA8D;IAC9D,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,gEAAgE;IAChE,OAAO,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAAC;IACzC,uEAAuE;IACvE,SAAS,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChE,iEAAiE;IACjE,eAAe,IAAI,IAAI,CAAC;IACxB,SAAS,EAAE,UAAU,EAAE,CAAC;CACzB;AA4cD,gFAAgF;AAEhF,wBAAgB,qBAAqB,CACnC,aAAa,EAAE,MAAM,GACpB,iBAAiB,CAuBnB;AAED;;;;;GAKG;AAEH,wBAAgB,mBAAmB,CACjC,aAAa,EAAE,MAAM,EACrB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,GACX,iBAAiB,CAyBnB"}