kibi-cursor 2.0.1 → 2.1.1

package/.cursor-plugin/plugin.json

@@ -1,8 +1,8 @@
 {
   "name": "kibi-cursor",
   "displayName": "Kibi",
-  "version": "2.0.1",
-  "description": "Optional Cursor adapter for Kibi. Requires SWI-Prolog 9+ and project-local kibi-cli, kibi-mcp, and kibi-core before the bundled MCP server can start.",
+  "version": "2.1.1",
+  "description": "Optional Cursor adapter for Kibi. Requires project-local kibi-cli, kibi-mcp, and kibi-core (SWI-Prolog is bundled on Linux and macOS) before the bundled MCP server can start.",
   "license": "AGPL-3.0-or-later",
   "author": {
     "name": "Kibi"

package/CHANGELOG.md

@@ -1,23 +1,98 @@
 # kibi-cursor
 
+## 2.1.1
+
+### Patch Changes
+
+- 7aa1471: Kibi can now run without a hand-installed SWI-Prolog. It looks for an explicit `KIBI_SWIPL` executable first, then the tested SWI-Prolog build shipped in the new `kibi-swipl` platform packages, and only then `swipl` on `PATH` (9.0 or newer). `KIBI_SWIPL=system` skips the bundle. `kibi doctor` now reports which runtime was chosen (source, path, version), checks that every required library loads, and explains which platform package to add when the bundle is missing. A running Kibi engine that was started with a different SWI-Prolog is restarted instead of reused. Release builds now ship the tested SWI-Prolog for Linux x64, Linux arm64, macOS arm64, and macOS x64 inside the `kibi-swipl-<platform>` packages, and an install that skips optional dependencies still succeeds and explains which package to add.
+  - kibi-cli: add `resolveSwipl()` (env, bundled with manifest and SHA-256 verification, PATH), a per-process cache, and `SWI_HOME_DIR` for bundled builds in both `PrologProcess` spawn paths.
+  - kibi-cli: engine handshake and requests carry the resolved `<bin>@<version>`; the daemon rejects mismatches and clients replace a mismatched daemon.
+  - kibi-cli: `doctor` SWI-Prolog check uses the resolver and loads all required libraries.
+  - kibi-runtime: depend on `kibi-swipl`; keep it and the platform packages external in both bundles.
+  - kibi-cursor: the worktree resolver accepts `KIBI_SWIPL` or a bundled `kibi-swipl-*` binary in the candidate's installed packages.
+  - Release: the publish workflow builds the SWI-Prolog archives in its own run, verifies each SHA-256 sidecar, pinned provenance, and binary checksum, materializes symlinks (npm drops them), packs the four platform packages, and installs the packed tarballs with npm on runners with no SWI-Prolog before publishing; a separate dry-run workflow packs without any publish path.
+  - New packages `kibi-swipl` and `kibi-swipl-<platform>` start at 1.0.0 outside this changeset and version together through a changesets fixed group.
+
+- db5376c: Projects can now opt into impact reviews that bind a change to its exact source, knowledge decisions and trusted analysis policy. Kibi validates both staged changes and a complete pull-request diff, rejects stale review evidence, and lets agents prepare an unauthored review template through the CLI or MCP instead of hand-assembling one. Every decision and reviewer field stays for an agent to write; preparation never approves or proves anything.
+  - Add versioned impact policy and review schemas, immutable review fingerprints, reviewed Python decorator coordinate migration and the trusted aggregate `check-diff` command.
+  - Add the read-only `prepare-impact-review --input` CLI route and `kb_prepare_impact_review` MCP operation; regenerate the bundled operation-access catalog for the agent integrations.
+  - Keep the sample CI workflow inactive until it is adopted on a protected target.
+
+- 3d78159: Setting up Kibi no longer starts with installing SWI-Prolog. The documentation now says that Linux (x64 and arm64, glibc 2.28 or newer) and macOS (Apple silicon and Intel) need nothing beyond Node.js 22, explains the lookup order and the `KIBI_SWIPL` and `KIBI_SWIPL=system` overrides, and shows how `kibi doctor` reports which SWI-Prolog is in use and what to do when an install skipped the bundled runtime (`--omit=optional`, pnpm `supportedArchitectures`). Manual instructions stay for Alpine and native Windows. The GitHub Pages report workflows that `kibi init` can write no longer install SWI-Prolog by hand, because `npm ci` brings the bundled runtime with it.
+  - kibi-cli: drop the `apt-get install swi-prolog` step from the shipped `kibi-report.yml` and `kibi-badge.yml` workflow templates.
+  - kibi-cursor, kibi-claude: README and plugin manifest prerequisites say SWI-Prolog is bundled on supported platforms and only needed on `PATH` elsewhere.
+  - Kibi's own CI and proof now run the pipeline-built bundled SWI-Prolog (one job keeps a system install with `KIBI_SWIPL=system`), and the release dry run follows the README quick start with the packed tarballs on four platforms; neither ships in a package.
+
+## 2.1.0
+
+### Minor Changes
+
+- f01838e: The Cursor plugin now asks the agent to consult Kibi before it edits a file, not only after. Every nudge used to fire once the change was already written — the post-edit message opened with "After editing" twice — so the plugin could only ever prompt repair, never inform the change. Before an edit, the plugin now names only requirements the file explicitly implements and asks for them to be read first, which is the one point where retrieval can still change what gets written.
+  - Emit source-linked pre-edit guidance from `preToolUse` for edit-like tools, resolved synchronously from the symbol manifest so no KB round-trip is added to the edit path.
+  - Name up to three `implements` requirement targets for the file, or ask for discovery and ownership when no requirement ownership is known.
+  - Narrow the post-edit message to the impact review that only becomes possible once the change exists, and stop repeating the retrieval ask there.
+  - Track pre-edit guidance in its own hook-state bucket so it is emitted once per path without suppressing the post-edit review.
+
+### Patch Changes
+
+- 35cd120: The ZCode, Codex, and Cursor plugins now recognize Kibi tools when the host
+  reports them with a prefix, such as `mcp__kibi__kb_check`. Before this fix,
+  an agent that correctly ran an impact check through a prefixed tool name
+  still got a stop reminder to run it, because the plugin never saw the check.
+  - `kb-mcp-tools.ts` in each adapter gains `canonicalKbToolName`, which strips
+    `mcp__<server>__`, `MCP:`, and `kibi_` prefixes before matching `kb_*`
+    operations.
+  - The Codex hook bundle is regenerated.
+
+- 25f11b1: The badge that `kibi init --github` adds to your README now links to the published explanation of the `% proven` metric at https://looted.github.io/kibi/ instead of the GitHub rendering of the Markdown source. The Kibi documentation site moved to the root of that domain, with the requirement-health report still under `/kibi-report/`. The Cursor and OpenCode package READMEs also link to the published guides, so the links work when you read them on npm.
+  - cli: `KIBI_METRIC_DOCS_URL` points at `https://looted.github.io/kibi/guide/github-integration.html#what-the-badge-means`.
+  - cursor, opencode: README setup and troubleshooting links point at the published guide pages instead of repository-relative or GitHub blob URLs.
+  - repo tooling (not published): the docs site builds into the GitHub Pages root and renders `llms.txt` as one H2 link list per catalog group from the shared page metadata.
+
+- 5a06c03: Kibi's agent plugins now share one fast, consistent implementation for source-path classification, Kibi MCP tool recognition, and symbol-manifest indexing. Codex and ZCode now recognize production code outside `src/`, while Cursor reuses the same size-and-mtime-keyed scanner as Claude instead of parsing the full symbol manifest before an edit.
+  - Add `kibi-agent-core` as the common Node 18-compatible hook-helper package.
+  - Keep host adapters thin while preserving their host-specific event and state contracts.
+  - Replace Cursor's YAML parser dependency with the shared cached line scanner.
+
+- f01838e: Usage telemetry stays off by default for every client, and there is now a supported way to turn it on. Previously the only way to capture usage was to hand-write an MCP command line with `--diagnostic-mode`, which meant anyone using a shipped plugin recorded nothing at all and had no documented alternative. Operators can now opt in with an environment variable, and once they do, each row identifies the host, package version, and checkout that produced it, so behavior can be compared across editors, worktrees, and Kibi versions.
+  - Honor `KIBI_DIAGNOSTIC_MODE=1` alongside the existing `--diagnostic-mode` flag, for hosts where a plugin owns the MCP command line.
+  - Stamp `interface`, `host`, `package_version`, and `workspace_root` on every usage row.
+  - Set `KIBI_MCP_HOST` from the Cursor and Codex launchers for attribution only; it never enables logging, and installing or enabling a plugin never starts telemetry.
+  - Stop the bundled Cursor worktree resolver from hard-coding `--diagnostic-mode`, so a shipped launcher cannot enable capture on an operator's behalf.
+  - Document the opt-in, what a row contains, and how to opt out in `docs/mcp-reference.md`.
+
+- 0128b56: Kibi now helps agents keep one shared vocabulary instead of letting every requirement invent its own. `kibi check` warns when two unrelated requirements state the same obligation. Units are compared in canonical form, so "30 min" matches "1800 s", and each warning names the exact facts involved. It also flags subject keys copied from a requirement ID, subject keys that don't follow `component.aspect`, predicates whose arguments read like prose, and entity files whose name doesn't match their ID. All of these are non-blocking warnings or info notes, so existing knowledge bases keep passing.
+
+  When you model a new requirement, Kibi now ranks the subjects that already exist and either reuses one or explicitly declares a new one. It also flags claims that look like possible duplicates. An intentional restatement can be recorded with the new `restates` relationship. Skills and docs now recommend naming entities by the behavior they govern (`REQ-cli-gc`) instead of a sequence number (`REQ-042`). Existing numbered IDs stay valid.
+
+  Predicate schemas can now declare the allowed values for an argument, plus the old spellings that map onto them. New facts must use those values. `kibi check` reports predicate facts that don't match any schema, and `kibi migrate` can fix the mechanical cases after you approve the plan hash. It moves a fact to the only namespace whose schema matches, and rewrites old spellings to the declared value. Everything that needs judgment stays a review item.
+  - core: new `semantic_quality.pl` (`entity-id-style`, `domain-redundancy`, `domain-implication`, `subject-key-identity`, `subject-key-shape`, `ontology-quality`) and `units.pl`. Unit canonicalization is used for comparison only, and unknown or ambiguous units such as `KB` are never equated. Adds the `restates` req→req relationship and an optional `diagnosticSeverity` in the rule registry. Adds `:- encoding(utf8)` to modules that contain non-ASCII text.
+  - cli/mcp: `restates` is wired through the extractors, schemas, and mutation paths. `entity-id-style` warnings are reported on `kb_upsert` creates and on staged added or renamed entity files. `kb_model_requirement` returns `vocabularyAlignment` (subject decision, candidates, redundancy candidates, stamps, `fallbackUsed`). Ontology-quality thresholds can be set with `KIBI_ONTOLOGY_QUALITY_MAX_SINGLETON_RATIO` / `KIBI_ONTOLOGY_QUALITY_MIN_FACTS`. `kb_compile_intent` create mode now keeps a caller-supplied `requirementId`. `kibi check --staged` now also prints its pass line when metadata-only staged changes have only advisory findings, matching the staged-symbol path.
+  - cli/mcp: `predicate_schema` facts accept `argument_constants` and `argument_aliases`, stored like `rule_ir` as JSON. `kb_upsert` / `kb_validate_upsert` reject malformed vocabularies and predicate facts that use undeclared values or aliases. `kb_suggest_predicates` binds aliases to their constant and leaves undeclared values unbound. The new advisory TypeScript rule `predicate-schema-conformance` checks predicate facts against project schemas and the built-in catalog. Its mechanical repairs become automatic `predicate_schema_alignment` migration actions that carry the exact `kb_upsert` input and re-read the fact before writing.
+  - core: `ontology-quality` findings name the prose-like arguments.
+  - plugin-sdk: new `kibi.vocabulary-alignment.v1` capability (`rankSubjects`, `compareClaims`) with result validators.
+  - plugin-builtin: deterministic offline provider (IDF-weighted subject ranking and negation- and quantity-aware claim similarity).
+  - plugin-jev: Jev-backed provider. It runs in replace, augment, or shadow mode with builtin fallback, and makes network calls only when it is activated for `kb_model_requirement`. `kb_check` never calls a provider.
+  - runtime and agent adapters: regenerated skill mirrors with the naming guidance and `restates` direction docs.
+
+- Updated dependencies [5a06c03]
+  - kibi-agent-core@0.1.0
+
 ## 2.0.1
 
 ### Patch Changes
 
 - 96a1ebd: Local Cursor MCP builds now compile plugin SDK/builtin dist before the CLI, so a fresh checkout no longer fails with a missing `kibi-plugin-builtin` type package.
-
   - `build:cli-stack` runs plugin-sdk + plugin-builtin + CLI
   - Worktree resolver uses that stack instead of `build:cli` alone
 
 - 188f875: No user-facing behavior change: `kibi-runtime` now resolves its bundled-skills directory lazily on first use instead of at import time, `isWithinRoot` drops a redundant same-path comparison, `kibi-cursor` drops a provably dead `planDelivered` early return and an always-true stdin branch, and the hook runners' stdin buffering is simplified to an unconditional `Buffer.from`. The reshaping lets the new mutation-testing suite (`docs/mutation-testing.md`, run via `bun run test:mutation`) prove these paths exhaustively — the suite holds a 100% mutation score over `kibi-runtime`, `kibi-codex`, and `kibi-cursor` sources.
 - db07d8f: Proof diagnostics now agree with the Prolog decision: a structural type-shape unit contract is shown as qualifying, `kibi proof impact` compares against the Git HEAD baseline and exits 0 after a successful report, and mixed-role symbols fail the strict proof integrity gate.
-
   - Mode-aware candidate evaluation in Prolog; receipt fallback uses `test_receipt_evidence(Context, TestId, Evidence)`.
   - `proof impact` reads `HEAD:proof/baseline.json` with no worktree fallback; diagnostic exit 0.
   - Strict proof workflow and baseline checker include canonical `symbol-traceability`.
 
 - f33a665: Proof failures now name the exact requirement, symbol, and why each `covered_by` candidate did not qualify, without changing what counts as proven. Agents can inspect a requirement with `kibi proof explain` and compare current proof state to the committed `proof/baseline.json` snapshot with `kibi proof impact`, instead of reverse-engineering Prolog or guessing from aggregate counts.
-
   - Keep `kibi.requirement-proof.v3` and add additive production-symbol `explanations` plus TEST `testResolutions` on the same Proof.
   - Ratchet `proof/baseline.json` to v2 with compact requirement fingerprints; aggregate counts stay the ratchet.
   - Add `kibi proof explain` and `kibi proof impact` as Proof projections, mixed-role leftovers in `symbol-traceability`, and advisory `proof-contract-symbols`.
@@ -28,7 +103,6 @@
 ### Major Changes
 
 - 812c201: Kibi's proof layer is now runner-neutral: any test runner, script, or harness can prove requirements, and Playwright is no longer built into the proof model.
-
   - `kibi prove` replaces `kibi verify` as the single command to run configured proof producers and record evidence. Proof contracts (`kibi.proof-contract.v1`) declare explicit obligations (`symbol_id` + `target`) executed by a configured integration in `.kb/proof/integrations.json`; `kibi proof inspect` discovers test infrastructure deterministically; one producer run can satisfy many test contracts, and re-ingestion is idempotent.
   - Evidence moves to the `kibi.proof-run.v1` artifact (typed environment, run-level outcome, factual attempt history with `native_case`/`aggregate_run` provenance) evaluated into `kibi.proof-receipt.v1` receipts bound to the live snapshot, contract hash, and effective execution fingerprint. Command proof is the universal fallback, so every project can prove requirements without a first-party framework adapter; strict first-attempt policy never upgrades unknown attempt history into passing evidence.
   - Breaking removals: `kibi verify`, `kb_ingest_verification`, `kibi.playwright-run.v1`, `verification_contract`/`verification_receipts` entity fields (replaced by `proof_contract`/`proof_bindings`/`proof_receipts`), the `required_case_symbols`×`required_projects` Cartesian contract, and `retries` fields. Migrate by re-running `kibi prove` after bootstrap configures proof for your repository.
@@ -38,12 +112,10 @@
 ### Patch Changes
 
 - b0271ac: Cursor now starts the bundled Kibi MCP server reliably when it launches plugin processes from a home directory or another unrelated working directory. Consumer workspaces with spaces continue to resolve their project-local `kibi-mcp` installation, while the portable Agent Plugin keeps its separate `npx --no-install` configuration.
-
   - Fix `kibi-cursor` MCP launcher arguments to use Cursor's `${CURSOR_PLUGIN_ROOT}` expansion.
   - Add source-install manifest regression coverage for consumer-local resolution from unrelated host directories.
 
 - b1682f1: Agents receive clearer guidance for repairing the actual supplied mutation request and preserving approved predicate bindings. The scoped additions retain the existing workflow while separating payload recovery from conditional relational modeling.
-
   - Update `kibi-usage` to 2.1.2 in CLI/runtime sources and the generated Codex/Cursor distributions.
   - Preserve the other three skills and all existing resource content.
   - Retain production-adoption safeguards; development comparisons are not held-out evidence.
@@ -52,12 +124,10 @@
   same entry paths tests already spawn as processes. In-process coverage can
   exercise stdin, CLI guards, and realpath failures instead of leaving those
   lines invisible to Codecov.
-
   - Export hook CLI helpers and Agent Plugin / launcher internals for tests.
   - Use a namespace `fs` import in skill validation so realpath errors are testable.
 
 - 5999143: Agent-facing skill docs now use the current status field names, so agents following the freshness and E2E receipt workflows look for fields that actually exist in `kb_status` output instead of stale ones.
-
   - Bundled `kibi-freshness` and `kibi-usage` skills (all agent mirrors) now reference `proofSnapshotChanges` and `proofSnapshot` (previously `verificationSnapshotChanges`/`verificationSnapshot` from the pre-proof-architecture status schema).
   - The skillopt-eval harness reads `proofSnapshot*` status fields and its held-out eval prompts name the current fields, so "dirty editor path" evidence gathering works against live status output again.
 
@@ -68,7 +138,6 @@
 ### Patch Changes
 
 - Cursor agents now get an always-on CLI recipe when Kibi MCP tools are missing, instead of treating Kibi as unavailable.
-
   - Put the exact `npx --no-install kibi <route> --input -` command, MCP-to-CLI name mapping, and Shell-approval language in the always-applied workflow rule.
   - Keep published plugin hooks advisory and untrusted by default; dogfood still opts into `--trusted-workspace` locally.
   - Document the operator prerequisites (Agent mode, Shell, trusted workspace, project-local CLI) for the fallback to run.
@@ -80,7 +149,6 @@
 - 9e6fb3f: Kibi now uses one opinionated project contract: all Kibi-managed knowledge lives under `.kb/`, check enforcement is owned by the installed Kibi version, and projects can no longer weaken health by disabling rules or relocating entity paths in `.kb/config.json`. Existing repositories must run `kibi migrate --yes` to move legacy `documentation/...` knowledge into the canonical layout and adopt `.kb/manifest.json`.
 
   Advisory modeling checks still run by default, but they report as non-blocking quality diagnostics instead of failing `kibi check`. Migration rewrites the old blanket `.kb/` gitignore stanza so authored lanes are trackable, and a malformed leftover `config.json` blocks the one-way cutover instead of guessing default paths.
-
   - Remove user-configurable entity paths and persistent `checks.rules` overrides; retire `.kb/config.json` after migration.
   - Introduce `.kb/manifest.json` for Kibi-owned lifecycle metadata (schema version, semantic backfill state).
   - Add one-way legacy storage migration (`documentation/` and custom configured paths → `.kb/<lane>/`).
@@ -94,7 +162,6 @@
   - Pending relationship shards are not treated as symbols manifests during source discovery.
 
 - 4c75e4d: Kibi onboarding now separates repository initialization from teaching Kibi about an existing codebase. After `kibi init`, an agent can run the `kibi-bootstrap` workflow to produce a reviewable, hash-bound plan and apply the exact approved plan safely. The old autopilot and init-kibi public names are removed so new users see one clear bootstrap path.
-
   - Replace `kb_autopilot_generate`/`autopilot-generate` with `kb_plan_bootstrap`/`plan-bootstrap`.
   - Add `kibi.bootstrap-plan.v1` validation, deterministic approval hashes, dependency ordering, stale-plan checks, and typed bootstrap recovery through `kb_apply_plan`.
   - Synchronize the four canonical skill mirrors and update client adapters, docs, fixtures, and SkillOpt cases.
@@ -106,7 +173,6 @@
   effect and repair information, while branch stores are hashed and explicitly
   identity-bound. The mutation path can author tracked source documents and
   canonical relationship shards without staging or committing them.
-
   - Add the `kibi-runtime` first-party integration package.
   - Add exact branch-store manifests, explicit legacy migration/quarantine, and
     typed result/effect contracts.
@@ -114,24 +180,20 @@
     approval plans.
 
 - 3d7d04f: Generic MCP and CLI agents now discover Kibi's operating rules from bundled skills instead of a long copy-paste prompt. Improving an existing product KB is covered by a `kibi-usage` resource rather than a second manual, so agent guidance stays in one place and cannot drift from the packaged workflow.
-
   - Add `kibi-usage` `resources/kb-improvement.md` and bump that skill to 2.1.0.
   - Replace `docs/prompts/llm-rules.md` with `docs/generic-agent-onboarding.md`.
   - Remove the obsolete retroactive-init prompt; bootstrap stays in the `kibi-bootstrap` skill.
 
 - 29793c7: The Cursor stop hook no longer starts an extra Kibi follow-up after you only deliver a plan. Reads and search no longer look like source edits, so plan mode can finish without an impact-check nudge. If that same turn actually edited source or updated the knowledge base, the existing follow-up still runs.
-
   - Record dirty paths only from known editable tools.
   - Treat `CreatePlan` as plan delivery and stay silent at stop unless that turn also edited source or mutated the KB.
   - Skip follow-up when `stop.status` is `aborted` or `error`.
 
 - 8db2e37: Cursor plugin users can now enable Kibi without adding a separate project MCP configuration. The plugin finds the `kibi-mcp` version installed in the opened project, starts it inside that workspace, and reports a clear setup error when the dependency is missing. It never downloads or falls back to a global Kibi runtime.
-
   - Replace the plugin MCP `npx --no-install` command with the packaged consumer-workspace launcher.
   - Cover isolated and packed plugin launches, workspace selection, package-layout resolution, exit codes, and signal forwarding.
 
 - 535dea8: Agents can now keep working in synthetic, detached, or unreadable workspaces while Kibi reports the migration work it can evaluate. Coverage and checks preserve their useful domain results when branch status is unavailable, and the Codex/Cursor skill assets now stay aligned with their published plugin metadata.
-
   - Keep status-derived migration actions read-only and append them only when branch resolution succeeds.
   - Preserve the shared migration-plan contract across coverage and checks without requiring a Prolog-backed status query in non-Git harnesses.
   - Synchronize plugin manifests and freshness skill CLI examples for the next coordinated patch release.
@@ -141,7 +203,6 @@
   edges can no longer hide a newer contradictory policy merely by making that
   newer requirement non-current. Relationship checks also block authored links
   that have silently disappeared from compiled knowledge.
-
   - Document `supersedes` as new-to-old across bundled and generated skills.
   - Reject reversed supersession when tracked source history proves that the
     purported replacement predates its target.
@@ -192,7 +253,6 @@
 ### Patch Changes
 
 - The published Cursor plugin now launches the `kibi-mcp` installed in the opened project, even when Cursor starts plugin processes from the plugin installation directory. The launcher preserves the consumer workspace as the child cwd and `KIBI_WORKSPACE`, and fails with an actionable message when the project-local package is missing.
-
   - Replace plugin MCP's ambient `npx --no-install` invocation with the packaged consumer-local resolver.
   - Add isolated and packed-artifact coverage for workspace resolution, package layouts, exit codes, signals, and missing-runtime failures.
 
@@ -201,7 +261,6 @@
 ### Patch Changes
 
 - Existing Kibi installations now receive an agent-guided migration workflow instead of opaque repair advice. Status, checks, and coverage expose one deterministic, hash-bound action plan; agents can safely apply only explicitly approved automatic repairs while semantic, proof, package, and operator work remains visible for review. This makes damaged or legacy KBs recoverable without direct `.kb` edits and gives every run an auditable post-application readback.
-
   - Add `kibi.migration-plan.v2` fragments to the 21-operation surfaces and support hash/action authorization in `kb_apply_plan` and `kibi migrate --apply-safe`.
   - Add lazy status/planning and deterministic schema, branch, storage, coordinate, and recovery action execution with workspace-root-safe CLI/MCP parity.
   - Refresh agent skills, traceability fixtures, and SkillOpt coverage for migration safety boundaries and five-axis closeout reporting.
@@ -211,13 +270,11 @@
 ### Patch Changes
 
 - de7b85a: Verification contracts can now evolve without forcing projects to erase valid historical test evidence. Kibi preserves every earlier receipt, accepts a newly appended receipt for the current contract, and only treats evidence matching both the current contract and live code snapshot as proof.
-
   - Separate immutable receipt-history validation from current-contract binding during verification ingest.
   - Report `verification_contract_mismatch` as an explicit proof gap until current-contract evidence is appended.
   - Teach the usage skill and SkillOpt evaluator to preserve older-contract receipts and forbid history rewrites.
 
 - 584336b: Agents now get consistent guidance when execution proof, structural coverage, and KB freshness disagree. Current-contract E2E evidence is recorded as v2 without rewriting history, and full checks no longer report a contradictory weak-depth warning when the same live receipt already proves the scenario-backed test. Receipt freshness repairs also identify the affected requirements and tests so agents can rerun the exact contract.
-
   - Share snapshot-bound proof evidence with full quality diagnostics.
   - Add bounded receipt-gap telemetry and v2-native remediation guidance.
   - Document and test the new receipt and proof-aware diagnostic requirements.
@@ -225,13 +282,11 @@
   - Keep the MCP package contract verifier self-contained with an explicit semver development dependency and matching workspace lock ranges.
 
 - Kibi can now explain a missing or damaged branch-local KB without changing it. Agents receive a precise recovery path, preserving the existing store before a deliberate rebuild, and no longer need to guess whether a clean check also means a clean, fresh KB.
-
   - Add non-mutating branch-store inspection to status and a preview-first `kibi branch recover --apply` workflow.
   - Restrict branch migration to the detected historical `master` -> legacy `main` compatibility attachment; arbitrary branch moves are refused.
   - Refresh CLI/MCP status documentation, mirrored agent skills, and release-gate packed consumer coverage.
 
 - ef75929: Kibi’s release checks now validate compiled package APIs and dependency ranges in isolated npm and pnpm consumers, while the usage skill and private SkillOpt evaluator report task completion, KB freshness, verification, proof, and accepted limitations independently. Consumer repositories keep ownership of their local artifact update scripts and dependency overrides.
-
   - Remove library-side consumer dogfood installers and retain release-only packed checks.
   - Add deterministic closeout expectations and dogfood-derived held-out cases.
 
@@ -240,7 +295,6 @@
 ### Patch Changes
 
 - Dogfood projects now get branch-local knowledge bases that follow the exact Git ref, actionable stale-source diagnostics, and a sanctioned relationship cleanup path. Verification receipts and packed package provenance are stricter and reproducible, while agents receive conservative symbol-recovery guidance and explicit interim-state signals. This prevents silent `master`/`main` drift and makes passing E2E evidence distinguishable from complete semantic proof.
-
   - Remove implicit branch-name normalization and add previewed legacy branch migration.
   - Add exact relationship deletion, v2 receipt/schema parity, status diagnostics, dogfood package manifests, and SkillOpt cases.
 
@@ -263,7 +317,6 @@
   Diagnostic workflows now produce correlated evidence through both CLI JSON and MCP surfaces. Operators can run a read-only versioned remediation report that points to exact unmatched log events, preserves explicit missing-coverage work, and prevents advisor or preflight evidence from a different identified session or actor from counting as proof.
 
   Legacy prose can now be inspected one requirement at a time through a deterministic migration preview. The preview preserves existing code evidence, binds every extracted proposition to exact authored source, ranks project-local ontology candidates, and never emits an auto-applicable write.
-
   - Add the shared `kibi.requirement-proof.v2` Prolog evaluator and expose its rows, fresh receipt evidence, and summary counts through CLI and MCP coverage.
   - Persist generated symbol coordinates and symbol metadata into normal and staged RDF projections.
   - Preserve semantic-inventory JSON through mutation, sync, RDF storage, and query round trips, and refresh coordinates before extracting their manifest overlay.
@@ -285,26 +338,22 @@
 ### Patch Changes
 
 - 5e4e126: Agents no longer treat Kibi's CLI as an MCP fallback. MCP tools and the trusted project-local CLI are presented as peer surfaces over the same 18 operations, and agent guidance now selects whichever interface is visible and approved in the current environment. The CLI's `--input` JSON routes remain first-class for agent automation, with no preference order implied.
-
   - Reframe `kibi-usage` Interface Selection and the operation-access preference column to peer surfaces.
   - Update OpenCode prompt injection, enforcement, and init-kibi guidance.
   - Update the MCP init-kibi prompt and the staged-impact evidence resolution text.
   - Re-sync the Cursor and Codex skill bundles.
 
 - Codex and Cursor users now receive the same verified prose-to-logic guidance as the Kibi CLI. The bundled `kibi-usage` skill explains proposition coverage, typed Logic IR safety, predicate recovery, and contradiction-aware validation without relying on repository-specific release conventions.
-
   - Synchronize the Logic IR, fact-lane, workflow, and portable skill guidance into both agent bundles.
   - Keep the bundled skill manifests and canonical hashes aligned with the CLI public skill.
 
 - 5e4e126: Kibi now ships as a portable Agent Plugin alongside the existing Cursor Plugin. The open Agent Plugins standard (agent-plugins.org) packages Kibi's Agent Skills and MCP server so any compatible client — Cursor, Copilot, OpenCode, and others — loads Kibi's capabilities without client-specific adaptation. The Cursor Plugin keeps Cursor-only components (rules, commands, hooks), and both formats are listed in the same marketplace.
-
   - Add a committed portable Agent Plugin artifact at `agent-plugin/` with a conformant `plugin.json` manifest (plugin.schema.json 1.0.0).
   - Generate the artifact's `mcp.json` with the required `$schema` and `stdio` server type.
   - List the Agent Plugin (`plugins/kibi-agent-plugin`) in the repo marketplace alongside `kibi-cursor`.
   - Add `scripts/build-agent-plugin.ts` to regenerate the artifact and keep its skills in sync with the canonical bundle.
 
 - 2a85fc8: Kibi can now track whether every atomic clause in a normative requirement has a queryable logical representation. Readable prose remains intact, while stable claim keys, linked strict-property or predicate facts, and a requirement manifest expose incomplete modeling before it silently weakens contradiction detection. Exact opposite polarities over the same ground predicate now produce a contradiction.
-
   - Remove repository-specific release and optimizer-corpus text from `kibi-usage`.
   - Add portable clause-complete prose-to-ground-predicate/property guidance and examples.
   - Preserve logical claim and predicate-schema fields through Markdown sync.
@@ -322,7 +371,6 @@
 - 2f9073c: Kibi now ships optional guidance for recording UI and visual expectations, so agents working on a screen can discover "where things live" and cannot silently drift the layout. A prose requirement anchors the full visual description, checkable positions, alignment, and header ordering decompose into strict facts that reject conflicting writes, and relational alignment uses the built-in `visual_layout_rule` predicate. The lane is per-project: non-UI projects simply never model UI subjects, and no validation rule requires them.
 
   Also, `kb_status` within a long-lived MCP session now observes same-session file and KB changes instead of returning a stale cached result. Compound Prolog goals (such as the status query) are no longer cached in one-shot mode, so a status check after a source or documentation edit reports the current freshness state.
-
   - Add `docs/ui-requirements.md` with the three-layer UI modeling guide, payload-shaped examples, and the check workflow.
   - Point the modeling cheatsheet decision tree, agent LLM rules, and the AGENTS quick references at the new UI lane.
   - Add a self-contained `kibi-usage` skill resource (`resources/ui-requirements.md`), declare it in the skill manifest, and add a UI modeling workflow section.
@@ -334,14 +382,12 @@
 ### Minor Changes
 
 - b2b1792: Kibi guidance now helps agents distinguish suitable relational predicates from scalar constraints and review-only claims without replacing readable requirements. CLI, Codex, and Cursor users receive the same predicate-first decision tree and authoritative examples, reducing invented predicates and unsafe modeling.
-
   - Add built-in, project-local, deny, strict-scalar, ambiguity, false-positive, and ontology-gap guidance to the canonical `kibi-usage` skill.
   - Regenerate the Codex and Cursor mirrors with matching canonical hashes.
 
 ### Patch Changes
 
 - 610b5be: The improved Kibi guidance skills will ship to CLI, Codex, and Cursor users in the next package release. This keeps the canonical CLI skill bundle and the generated client-plugin mirrors aligned for downstream installs.
-
   - Release the canonical skills bundled by `kibi-cli`.
   - Release the generated `kibi-codex` and `kibi-cursor` skill mirrors.
 
@@ -350,24 +396,20 @@
 ### Minor Changes
 
 - a0fee4a: The Cursor plugin now supports capability-based Kibi interface selection, using visible MCP tools first and a trusted project-local CLI fallback when needed. Deterministic worktree resolution keeps both interface choices anchored to the intended repository.
-
   - Add MCP-first, CLI-fallback agent guidance.
   - Resolve trusted worktree runtime paths deterministically.
 
 ### Patch Changes
 
 - cafa25f: Agents can now select Kibi by available capability instead of stopping at MCP-specific guidance. The bundled skills prefer approved MCP tools, fall back safely to a project-local non-installing CLI runner, and provide executable JSON recipes plus an exact 18-operation access catalog.
-
   - Document every shared MCP operation's dedicated CLI route, input mode, effects, Prolog requirement, mutability, and telemetry handling.
   - Regenerate Cursor and Codex skill mirrors from the canonical capability-based source.
 
 - 23e815a: Agents can now keep using Kibi when MCP tools are unavailable but a trusted project-local CLI is ready. Guidance across Cursor, OpenCode, and MCP documentation now selects the interface by capability and stops for operator action only when neither safe surface is available.
-
   - Replace MCP-exclusive guidance with the visible-MCP, trusted-CLI JSON route, and blocked state machine.
   - Preserve direct `.kb/` access prohibitions, discovery-before-mutation, sequential writes, and completion validation gates.
 
 - e71f1ce: Cursor dogfood sessions now keep each linked worktree as the Kibi data workspace while launching a compatible built MCP runtime from that worktree or its primary checkout. Invalid, stale, or unrelated builds are rejected without installing packages, and Cursor hooks offer the project-local CLI only as advisory guidance after explicit workspace trust.
-
   - Add deterministic build, runtime, SWI-Prolog, and package-version checks to the Cursor worktree resolver.
   - Preserve an explicit `KIBI_WORKSPACE` when the MCP diagnostic launcher starts from another runtime root.
   - Track MCP capability as `observed` or `unknown` and keep hook-driven CLI fallback non-executing.
@@ -379,7 +421,6 @@
 - f1db710: Kibi check outputs now have a stable advisory diagnostics lane for auditability review signals. Operators and MCP clients can receive `qualityDiagnostics` alongside hard `violations` without advisory-only findings changing pass/fail counts or exit behavior. Existing staged impact failures, including symbol granularity violations, remain blocking. Source impact analysis now also highlights overly broad symbols, indistinguishable symbol coordinates, and mixed-purpose component/class ownership as review-only guidance.
 
   Technical summary:
-
   - Add the public `QualityDiagnostic` type with `error`, `warning`, `review`, and `info` severities plus explicit `blocking` semantics.
   - Preserve existing `violations`, `diagnostics`, and `impactDiagnostics` fields while adding MCP structured `qualityDiagnostics` output support.
   - Preserve explicitly filtered MCP `kb_check` rule semantics so advisory full-KB quality scans only run for unfiltered checks or requested impact diagnostics.
@@ -394,7 +435,6 @@
 - Kibi now gives agents source-impact feedback while they are still editing, instead of waiting for the commit hook to be the first signal. Meaningful source edits can be checked through MCP with changed-file impact diagnostics, so agents see coarse symbol ownership, stale symbol evidence, and semantic-review prompts while the source context is fresh. OpenCode, Cursor, and Codex adapters now steer agents toward that MCP-first workflow and keep CLI/hooks as the later safety net.
 
   Technical summary:
-
   - Add reusable CLI changed-file impact diagnostics and export them for MCP consumption.
   - Extend MCP `kb_check` with source-file impact options and structured impact output.
   - Update OpenCode, Cursor, and Codex guidance/hooks to request impact-enabled `kb_check` after source edits.
@@ -407,7 +447,6 @@
 - Kibi now gives agents clearer guidance for the diagnostics flow, so the release notes should reflect that the bundled usage text and MCP logging story were tightened together.
 
   This update also keeps the package mirrors aligned where applicable, which helps downstream plugin consumers stay in sync with the canonical guidance.
-
   - Hardened bundled skill guidance for kibi usage.
   - Improved MCP diagnostic logging shape and validation hints.
   - Synced packaged skill copies where they are shipped with the release.
@@ -417,14 +456,12 @@
 ### Patch Changes
 
 - 5d2975a: Cursor stop hooks no longer inject a long multi-line Kibi freshness reminder after every agent response. Follow-ups are now one line, and most sessions stay silent.
-
   - Track `kb_upsert`, `kb_delete`, and `kb_check` MCP usage during the session.
   - Emit no stop follow-up when nothing KB-relevant changed, or when `kb_check` already ran after edits.
   - Emit a short summary (`Kibi KB updated (kb_upsert).`) after KB mutations, or a single-line sync nudge when source files changed without KB activity.
   - Fix publish workflow to build and pack `kibi-cursor` tarballs before npm publish.
 
 - Cursor sessions now use Cursor's documented workspace root payload when deciding whether Kibi is already configured. This prevents the plugin from telling agents that Kibi needs bootstrapping just because the hook process is running from the plugin install directory instead of the actual workspace. The bootstrap reminder now names the missing `.kb/config.json` condition directly instead of implying MCP is unavailable.
-
   - Parse `workspace_roots` from Cursor hook payloads and prefer the first workspace root for Kibi config detection.
   - Add a regression test covering `sessionStart` without `cwd` when `workspace_roots` points at a configured workspace.
   - Reword the bootstrap reminder to describe a missing workspace config rather than generic initialization failure.
@@ -434,7 +471,6 @@
 ### Minor Changes
 
 - Cursor users can now install an optional Kibi adapter plugin that bundles MCP configuration, workflow rules, skills, slash commands, and advisory editor hooks. The plugin builds on the existing `kibi-cli` and `kibi-mcp` foundation without replacing them, and teams that prefer manual setup can continue configuring the local `kibi-mcp` server directly.
-
   - Add the publishable `kibi-cursor` package with Cursor plugin manifest assets, rules, skills, commands, hook declarations, and MCP config.
   - Add advisory hooks for bootstrap reminders, direct `.kb` edit warnings, read/write guidance, and session freshness follow-ups.
   - Wire `kibi-cursor` into workspace build, pack, release-state, publish, CI unit coverage, docs, and marketplace verification.
@@ -444,7 +480,6 @@
 ### Minor Changes
 
 - Cursor users can install an optional Kibi adapter plugin that bundles MCP configuration, workflow rules, skills, slash commands, and advisory editor hooks. The plugin builds on `kibi-core`, `kibi-cli`, and `kibi-mcp` without replacing them, and teams that prefer manual setup can continue configuring the local `kibi-mcp` server directly.
-
   - Add the publishable `kibi-cursor` package with Cursor plugin manifest assets, bundled skills, rules, commands, hook declarations, and MCP config.
   - Add a conservative hook runner with bounded session state, bootstrap reminders, direct `.kb` edit warnings, read/write guidance, and freshness follow-ups.
   - Wire `kibi-cursor` into workspace build, pack, release-state, publish, CI unit coverage, docs, and marketplace verification.

package/README.md

@@ -10,18 +10,17 @@ Install these **before** enabling the plugin MCP server:
 
 | Requirement | Why |
 | --- | --- |
-| **SWI-Prolog 9+** (`swipl` on `PATH`) | Powers Kibi inference and validation |
+| **SWI-Prolog 9+** | Powers Kibi inference and validation. Bundled with `kibi-cli` on Linux (x64, arm64) and macOS; install it with `swipl` on `PATH` only on other platforms |
 | **`kibi-cli`** | Project CLI (`kibi` command) |
 | **`kibi-mcp`** | MCP server installed in the opened project; the plugin launcher resolves this package without downloading it |
 | **`kibi-core`** | Shared graph/runtime dependency |
 
 ```bash
 npm install --save-dev kibi-cli kibi-mcp kibi-core
-swipl --version
 npm exec -- kibi doctor
 ```
 
-Full setup: [docs/install.md](https://github.com/Looted/kibi/blob/develop/docs/install.md).
+Full setup: [installation guide](https://looted.github.io/kibi/guide/install.html#optional-cursor-plugin).
 
 Add this plugin only after the base packages work in your project.
 
@@ -105,7 +104,7 @@ agent-plugin/
 
 - Cursor loads the portable build directly; Cursor-only components (rules, commands, hooks) remain in the `.cursor-plugin` Cursor Plugin build.
 - Both formats are listed in the same marketplace; pick the format your client needs.
-- The portable build still requires the project-local `kibi-cli`, `kibi-mcp`, and `kibi-core` packages plus SWI-Prolog 9+ (see Prerequisites above).
+- The portable build still requires the project-local `kibi-cli`, `kibi-mcp`, and `kibi-core` packages plus SWI-Prolog 9+ (bundled on supported platforms; see Prerequisites above).
 
 ## Features
 

package/agent-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "kibi",
-  "version": "2.0.1",
+  "version": "2.1.1",
   "description": "Repo-local, per-branch, queryable knowledge base. Portable Agent Plugin packaging Kibi's Agent Skills and MCP server.",
   "author": { "name": "Kibi" },
   "homepage": "https://github.com/Looted/kibi/blob/develop/docs/install.md",

package/agent-plugin/skills/kibi-usage/SKILL.md

@@ -2,7 +2,7 @@
 id: kibi-usage
 name: Kibi Usage
 description: Use Kibi's source-first, exact-Git, migration-aware, proof-aware operations safely across MCP or the trusted local CLI, including partial completion repair.
-version: 2.1.3
+version: 2.2.0
 kibiCompatibility: ">=1.0.0"
 tags:
   - kibi
@@ -59,7 +59,11 @@ mutability, and Prolog requirements of each operation.
 ## Safe workflow
 
 1. Always discover before you mutate: start with `kb_search`, then exact-filter with `kb_query`. Use
-   `kb_status` when branch or freshness confidence matters.
+   `kb_status` when branch or freshness confidence matters. `kb_search` ranks
+   lexically unless you pass `rankingMode: "intent-v1"`, `semanticFacets`, or
+   `sourceLocations`; use intent mode with grounded facets for conceptual
+   questions and before changing a source file, and keep lexical search for
+   literal identifiers. See `resources/workflows.md` for the mode recipe.
 2. Resolve genuine ambiguity with the human; use semantic advisor/modeling
    operations for deterministic interpretation and typed facts.
 3. Create endpoints before relationships and upsert small batches sequentially.
@@ -160,7 +164,7 @@ Represent implementation ownership with a `symbol` entity that has
 `sourceFile`, `implements` to the requirement, and `covered_by` to the test.
 Prolog `symbol-coverage` also requires the test to `validates` the requirement
 (or the requirement `verified_by` the test). `covered_by` alone is not
-enough. Do not rely on legacy `// implements REQ-xxx` comments as the
+enough. Do not rely on legacy `// implements REQ-<area>-<behavior>` comments as the
 traceability record.
 
 ## Complete Logical Coverage

package/agent-plugin/skills/kibi-usage/resources/fact-lanes.md

@@ -55,6 +55,10 @@ relationship: { type: requires_predicate, from: REQ-EDITOR-DRAFT-AUTOSAVE, to: F
 
 The project-local schema endpoint must exist before this fact is linked. When ontology extension is explicitly authorized, define it first with `fact_kind: predicate_schema`, `predicate_name`, `predicate_arity`, and equally sized `argument_names` and `argument_types`. Without an authorized stable signature, record `review:ontology-gap` instead of inventing a schema.
 
+### Closed argument vocabularies
+
+A schema can close an argument with `argument_constants` (allowed values keyed by argument name) and map older spellings with `argument_aliases`. Reuse a declared constant; `kb_upsert` rejects any other value and names the constant to use for an alias. When a genuinely new value is needed, extend `argument_constants` on the schema first. To converge existing facts, declare aliases for their spellings and let `kibi migrate` rewrite them (`predicate_schema_alignment` actions). Close only arguments with a natural shared vocabulary, such as the governed component or a severity; forcing distinct obligations into a few constants makes different requirements share one ground term.
+
 ### Deny predicate
 
 Claim: “Suspended users must not publish articles.” When `permission_rule` fits, preserve its positive schema name and encode prohibition as polarity:

package/agent-plugin/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/agent-plugin/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