kibi-cursor 2.8.1 → 2.9.0

package/.cursor-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "kibi-cursor",
   "displayName": "Kibi",
-  "version": "2.8.1",
+  "version": "2.9.0",
   "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": {

package/CHANGELOG.md

@@ -1,5 +1,55 @@
 # kibi-cursor
 
+## 2.9.0
+
+### Minor Changes
+
+- 5e3541e: Two new bundled skills cover the moments where agents most often went wrong with Kibi.
+  - `kibi-decisions` loads when a person states a rule ("must", "never", "from now on"), when a hook asks before an edit to code that implements a firm requirement, when the session ends without recording what changed, or when a request conflicts with a recorded rule. It shows how to read a requirement's firmness and origin, record a person's rule as firm with a reference to their words, supersede a rule with a "Why this changed" section, work through `kb_compile_intent` review candidates, and ask before overriding a firm rule.
+  - `kibi-commit-review` loads when `kibi check --staged` or the pre-commit hook blocks a commit, or when preparing a commit or pull-request impact review. It explains the per-file `Detail:` lines, how to add the missing symbols and refresh coordinates, which Kibi files to stage, how to prepare an impact-review record with `kb_prepare_impact_review`, and how merge commits and migration renames are judged.
+
+  `kibi-usage` now points to these skills instead of repeating their detail, and the OpenCode guidance routes rule and commit questions to them.
+
+- 180196c: The requirements signoff view now reads well on every host, not only in the hosts that draw Kibi's fenced block.
+  - `kibi signoff` prints plain Markdown by default (`--format chat`): headings, quoted statements and lists that render in any chat window, and in messaging tools for agents whose replies go through one (cloud and project sessions). The path of the self-contained page `.kb/briefs/signoff/latest.html` goes to stderr, so an agent can attach or publish it next to the message. `--format md` keeps the fenced block for the OpenCode terminal card, and `KIBI_SIGNOFF_FORMAT` sets the default per host.
+  - After a session writes a requirement, the Claude Code, Codex, Cursor and ZCode stop hooks ask once for the signoff view before the work is reported done, unless `kibi signoff` already ran since. A requirement the agent wrote is put to the person through the view, not retold in the agent's words.
+  - `/kibi-signoff` is a new command in Claude Code, Cursor and ZCode.
+  - The `kibi-decisions` and `kibi-commit-review` skills (1.2.0) say how to show the view on each host, and `kibi-usage` (2.22.0) points to `kibi signoff` when it says to leave `approved_by` to the person. The OpenCode guidance asks for `--format md` so the terminal card still renders.
+  - The Claude Code plugin README shows the `.claude/settings.json` snippet that loads the plugin in cloud sessions.
+
+### Patch Changes
+
+- 7a3edce: Signoff is now one readable view instead of loose chat text. `kibi signoff` lists the requirements a change adds, rewrites, retires or affects, each quoted with its firmness, origin, scenarios and proof state, and `kibi signoff --questions` numbers the decisions waiting for you next to the recorded rule each one would change or conflict with. The output is a fenced Markdown block for the agent's reply, a self-contained HTML page (`--format html --open`) or JSON, and every run keeps the latest view in `.kb/briefs/signoff/`.
+
+  Claude Code renders the block as Markdown through a new `MessageDisplay` hook (`KIBI_SIGNOFF_DISPLAY=0` turns it off), OpenCode 2 draws it as a framed card with a `/kibi-signoff` command and a toast, and VS Code offers a **Kibi: Show Requirements Signoff** panel that refreshes as the agent updates it. The `kibi-decisions` and `kibi-commit-review` skills now tell agents when to run it.
+
+- 3b43238: The `kibi-decisions` skill now makes a conflict with a recorded rule the verdict of the answer, naming the rule and what it requires before asking the person anything. A stated rule counts as recorded only once its requirement, scenario and `implements` link have actually been written and `kb_check` is clean. After a `kb_compile_intent` plan is applied, the skill makes the new requirement firm with `origin.ref`, gives a must-priority requirement its `specified_by` scenario, and reruns `kb_check` until nothing is reported about it. In the 2026-10-22c SkillOpt campaign the mean rose from 71.33 to 89.5 and hard passes from 16 to 24 of 30. Compile-intent review went from 31.67 to 85.83. One closeout cell dropped from 100 to 90.
+- 8493b53: The `kibi-freshness` and `kibi-traceability` skills now spell out the order of Kibi calls the agent should make and how to finish authorized writes.
+  - `kibi-freshness` runs `kb_status`, then `kb_query`, then `kb_check` before it answers. Consistency questions run `kb_query`, `kb_check` and then `kb_coverage`, and any unmodeled clause is reported as incomplete analysis rather than consistent.
+  - `kibi-traceability` starts with `kb_search`, then runs `kb_query` and `kb_graph`, and ends with `kb_status`. It grounds scenario feasibility in the queried entities.
+  - Both skills treat a passing `dryRun` upsert as validation only. They then perform the real write and read it back before the final checks.
+
+  In the 2026-10-21 SkillOpt campaign, on the Claude Code host, the freshness mean rose from 68.67 to 96.67 and the traceability mean from 45.67 to 76.67, with no family regressing. The campaign report is `documentation/evaluations/skillopt/reports/2026-10-21-report.md`.
+
+- 98254ef: The `kibi-traceability` skill now explains which edge belongs on which symbol when linking coverage. A production symbol keeps its `implements` link and gets `covered_by` to its test, and `executable_for` is reserved for a symbol that stands for the test itself. If a real `kb_upsert` is refused after a dry run passed, the skill repairs the same target instead of working around it with a new entity. In the 2026-10-21b SkillOpt campaign the traceability mean rose from 82.33 to 93.17, and executable coverage from 51.67 to 95.83, with no family regressing.
+- 0a9c431: Two skills pick up SkillOpt-confirmed guidance.
+  - `kibi-usage`: before editing a source file Kibi tracks, the skill runs `kb_search` with that file and then reads each governing requirement by id with `kb_query`. It treats the search answer as discovery only. In the 2026-10-22 campaign the mean rose from 85.5 to 88, and intent consultation rose from 47.5 to 60.
+  - `kibi-commit-review`: the skill never reads files under `.kb` directly, even read-only. It reads the governing requirement before deciding what a staged change is, and it sends an authorized write exactly once, after a dry run with the same payload. In the 2026-10-22b campaign the mean rose from 44.67 to 72.67, hard passes rose from 7 to 16 of 30, and security failures (all direct `.kb` reads) fell from 8 to 0.
+
+- 06fb484: The `kibi-usage` skill now limits the consultation before a source edit that keeps the governing rule to two calls: `kb_search` with the file, then one `kb_query`. Status, check and coverage run after the edit. For a modeling task, the skill spells out the full order: the exact `kb_query` of the target comes before any `kb_model` call, and the task does not stop at a dry run. In the 2026-10-22d SkillOpt campaign, over 42 cells per arm, the mean rose from 89.64 to 95.95 and hard passes from 33 to 38. Intent consultation went from 50 to 100. Two fact-predicate modeling cells lost an argument (100 to 80).
+- Updated dependencies [180196c]
+  - kibi-agent-core@0.9.0
+
+## 2.8.2
+
+### Patch Changes
+
+- 10c158c: Bootstrap plans now name what to compare for intent claims they cannot model, not only for the claims they plan. A claim left as "Intent claim needs authoring" next to a prose-only current requirement on the same topic gets a `conflict-review:` diagnostic naming that requirement, with an instruction to compare the two when the claim is compiled with `kb_compile_intent` and to report the verdict through `conflictReviews`; the knowledge-source summary and `recommendedActions` count those claims. The pre-commit hook (`kibi check --staged`) now blocks an entity document the commit adds or edits without the body context that full `kibi check` requires (`entity-context-missing`), so a commit can no longer carry an entity `kb_upsert` warned about.
+
+  Migration: commits that add or edit a requirement, scenario, test, ADR or observation fact without body context are now refused by the hook. Entities that already lacked context at the last commit, and entities the schema 8 migration acknowledged in `.kb/manifest.json`, are not blocked, so migration commits and edits to legacy entities keep passing; add a `## Context` section (requirements) or a prose body to new entities.
+
+  A `kb_upsert` refused for a coarse symbol link now returns a coded error (`SYMBOL_GRANULARITY_VIOLATION`) in the MCP error envelope and the CLI JSON route, with the same message; before, only a dry run carried a code. The candidates in that message, and in the hook's `symbol_granularity_violation`, list functions, methods and accessors before properties. `kb_status` `schemaStatus.warning` on a legacy KB without a manifest now says to run `kibi migrate --yes`, matching `bootstrap.nextAction` and `kibi doctor`.
+
 ## 2.8.1
 
 ### Patch Changes

package/README.md

@@ -114,8 +114,8 @@ agent-plugin/
 ### Discovery-first rules and skills
 
 - **Rules**: always-on capability-based workflow guidance plus optional traceability rules for source files.
-- **Skills**: `kibi-usage`, `kibi-bootstrap`, `kibi-freshness`, and `kibi-traceability`.
-- **Commands**: `/kibi-bootstrap` documents the `kb_plan_bootstrap` bootstrap workflow.
+- **Skills**: `kibi-usage`, `kibi-bootstrap`, `kibi-freshness`, `kibi-traceability`, `kibi-decisions`, and `kibi-commit-review`.
+- **Commands**: `/kibi-bootstrap` documents the `kb_plan_bootstrap` bootstrap workflow, and `/kibi-signoff` shows the requirements signoff view (or the decisions waiting for you) as Markdown in the chat. The [kibi-vscode](../vscode/README.md) extension also installs in Cursor and adds the **Kibi: Show Requirements Signoff** panel.
 
 ### Advisory editor hooks
 
@@ -127,7 +127,7 @@ Hooks are warning-only and never replace MCP/CLI behavior:
 - **beforeReadFile** and **postToolUse (Read)**: inject source-linked lookup guidance once per path per session, with the same snippet minus the "must keep true" and "Decision" lines.
 - **postToolUse** (opt-in telemetry): with `KIBI_DIAGNOSTIC_MODE=1`, appends `interface: "hook"` rows with `host: "cursor"` to `.kb/usage.log` for `kb_*` lookups (MCP or `kibi <route>` in Shell) and for edited files with the requirements they implement, keyed by `conversation_id`. `kibi usage-metrics` reads them for the `lookup_before_first_edit` metric. Nothing is written without the variable.
 - **postToolUse (Write/Edit)**: inject traceability and freshness guidance once per path per session, including `kb_check({sourceFiles:[...], includeImpactDiagnostics:true, includeWorkingTreeDiff:true})` for meaningful source edits.
-- **stop**: emits a single freshness or impact-check follow-up when meaningful paths were **edited** during the turn (reads and search do not count). Plan delivery (`CreatePlan`) stays silent unless that same turn also edited source or mutated the KB. When the conversation changed source files and recorded nothing with `kb_upsert`, the follow-up also asks, once, for the decision behind the change to be recorded.
+- **stop**: emits a single freshness or impact-check follow-up when meaningful paths were **edited** during the turn (reads and search do not count). Plan delivery (`CreatePlan`) stays silent unless that same turn also edited source or mutated the KB. When the conversation changed source files and recorded nothing with `kb_upsert`, the follow-up also asks, once, for the decision behind the change to be recorded. When the conversation wrote a requirement and `kibi signoff` has not run since, it asks, once, for the signoff view to be shown before the work is reported done.
 
 ### What the plugin does not do
 

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.8.1",
+  "version": "2.9.0",
   "description": "Repo-local, per-branch, queryable knowledge base. Portable Agent Plugin packaging Kibi's Agent Skills and MCP server.",
   "author": { "name": "Kibi" },
   "homepage": "https://looted.github.io/kibi/",

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

@@ -2,7 +2,7 @@
 id: kibi-bootstrap
 name: kibi-bootstrap
 description: "Use for any Kibi bootstrap or onboarding task: seeding a new or thin knowledge base; reviewing a bootstrap or onboarding plan, preview, or evidence; judging approval readiness or coverage; diagnosing a blocked, partial, or failed bootstrap or its repair; applying an approved bootstrap plan; or asking the human which knowledge sources hold intent. Covers kb_status first, source interview, cited intent claims, read-only kb_plan_bootstrap preview, explicit approval, exact-plan kb_apply_plan, and repair-safe close-out."
-version: 3.15.0
+version: 3.16.0
 kibiCompatibility: ">=1.0.0"
 tags:
   - kibi
@@ -37,7 +37,7 @@ Seed branch-local Kibi knowledge from cited product intent, without creating a p
 3. **Declare** `bootstrapContext`: `projectSummary`; `knowledgeSources` (id, kind, title, locator, authority, optional connector, optional `component`); `intentClaims` (statement, sourceId, reference, `excerpt` required for `intent` and `observation` claims and optional for `open_question`, optional `kind`, default `intent`, optional `component` overriding the source's, optional `rationale` with the reason the source or the human gave, never invented); `conflicts` (`claimReferences` naming two or more declared claims by sourceId and reference, plus a one-sentence `note`). Only intent claims can become requirements, and they are recorded as the people's rules: `origin.kind: import` with `sourceId:reference` as `origin.ref`, and `firmness: firm`, so a later agent asks before changing one (normative lines from repository Markdown get the same, citing `path#Lline`). Observations, open questions (tagged `review:open-question`) and conflicts (tagged `review:conflict`) become cited observation facts. Generated subject keys take the shape `component.aspect`: name the component each source or claim is about (for example `recorder`; set `component` on the knowledge source, or on a claim to override it; repository Markdown takes its file or directory name), because an intent claim whose subject is neither one word nor already dotted, with no component, is reported in the plan diagnostics and left as an authoring follow-up instead of a malformed key. The aspect is the claim's subject, or its constrained property when the subject is the component itself. An aspect over four words or 40 characters is shortened to a noun phrase (words before `when`, `while`, `for`, `and`, ...; `support_inbox.update_in_real_time_when_a_new_ticket_is_assigned...` becomes `support_inbox.update_in_real_time`) and reported as `subject-key-shortened:` with both keys; two different subjects that shorten alike get a third segment (`editor.discard_a_draft.leaving`) and a `subject-key-disambiguated:` diagnostic; claims about one subject share one subject fact, and a `subject-key-shared:` diagnostic names the key and its sources. Show these diagnostics to the human with the plan so they can rename a key before approval. Kibi never contacts these sources. It binds your declaration into the plan hash.
 4. **Preview** with `kb_plan_bootstrap` (or `plan-bootstrap --input`), read-only. On `needs_context`, ask only its bounded questions (four at most), then preview again. When `pluginOffers` is non-empty (for example `kibi-plugin-ui` because UI component files exist), ask the human once whether to enable each offered plugin, naming its evidence files. On yes, install it as a dev dependency and add it to `package.json` `kibi.plugins` with the offered capability in `augment` mode; on no, add its name to `kibi.declinedPlugins` so it is not offered again. Either way the human decides; never enable a plugin unasked. For `kibi-plugin-ui`, step 11 also captures the UI pattern inventory (see `kibi-usage` `resources/ui-requirements.md`).
 5. **Narrow with filters, not caps.** Read the `tldr` and the `Suppressed candidates by reason` diagnostic before individual rows. If the output is too large or mostly tooling or metadata, re-preview with `entityTypes` or declared `sourceOfTruthPaths`. Generic Markdown is off by default once you declare intent claims; set `includeGenericMarkdown: true` only for repository docs the human named. Keep confirmed intent claims: they are never capped and never use `maxCandidates`, which is the separate budget for candidates Kibi discovers (symbols, tests, repository docs). Raise it only when discovered candidates you need are `over_limit`, and never for provenance stubs: a provider entry with no claim (`Source module: …`, repository metadata, layout roots) is planned last as a `meta` fact tagged `bootstrap:provenance-stub`, `discoverySummary.provenanceStubs` counts them apart from `candidatesWithClaims`, and the `over_limit` diagnostic says how many suppressed candidates are stubs; they add no knowledge, so a plan that is mostly stubs needs `entityTypes` or declared sources, not a higher cap. Read the per-source `Knowledge source …` diagnostics: each splits the claims not planned by reason (suppressed by the activation mode, a `suppressedCandidates` row, a `sourceOnlySignals` follow-up). Report them per source and restate them before approval, or carry them to step 11 with their citation.
-6. **Request approval.** Show the complete `structuredContent.plan`, the full hash (never abbreviated), which candidates cite which sources, what was omitted, the open questions and declared conflicts it records for the human to decide, and any claim that contradicts code. If you find an undeclared contradiction now, add it to `conflicts` and preview again rather than resolving it. A `conflict-review:` diagnostic (and `review_against:<id>` evidence on the candidate) names current requirements Kibi could not check a planned claim against because they have no logic: compare each pair yourself and show any contradiction to the human with the plan; they decide whether to drop the claim or keep it and supersede the requirement after apply. With no answer, stop as "awaiting approval." If declined, replan and ask again with the new hash.
+6. **Request approval.** Show the complete `structuredContent.plan`, the full hash (never abbreviated), which candidates cite which sources, what was omitted, the open questions and declared conflicts it records for the human to decide, and any claim that contradicts code. If you find an undeclared contradiction now, add it to `conflicts` and preview again rather than resolving it. A `conflict-review:` diagnostic (and `review_against:<id>` evidence on the candidate) names current requirements Kibi could not check a planned claim against because they have no logic: compare each pair yourself and show any contradiction to the human with the plan; they decide whether to drop the claim or keep it and supersede the requirement after apply. A claim left for authoring gets the same diagnostic (and `review_against:<id>` evidence on its follow-up): when you compile it with `kb_compile_intent` in step 11, compare it with the named requirements and send your verdicts in `conflictReviews`. With no answer, stop as "awaiting approval." If declined, replan and ask again with the new hash.
 7. **Pre-apply check.** The plan you send must equal the returned plan: every top-level field, including `suppressedCandidates`, `diagnostics`, `candidates`, `actions`, and `expected`, with every array the same length and order. Never rebuild it from preview fields. If the host cannot pass the exact object, stop and say so.
 8. **Apply once** with `kb_apply_plan`, the exact plan, and `approvedPlanHash`. The operation owns dependency ordering, source-first writes, sequential mutation, and recovery journaling. A plan with hundreds of actions can run for minutes: pass a `progressToken` (Kibi sends progress after each action) with a client that resets its timeout on progress, or pass `async: true` and poll `kb_job_status` when the host has it. If the apply is cut off, call `kb_apply_plan` with only the `recoveryJournalId` from `kb_status` or the error; it resumes an action interrupted mid-write and reclaims a lock left by a dead process. Never edit or delete `.kb/recovery` files; if recovery is refused, stop and report it.
 9. **Read back** with `kb_query` and `kb_search` to confirm writes and citations.

package/agent-plugin/skills/kibi-commit-review/SKILL.md

@@ -0,0 +1,125 @@
+---
+id: kibi-commit-review
+name: kibi-commit-review
+description: "Use when kibi check --staged or the Kibi pre-commit hook blocks a commit (kibi_impact_evidence_missing, symbols_manifest_stale, symbol_granularity_violation, symbol-coverage, kibi check-generated drift, Staged impact review failed), or when preparing a commit or pull-request impact review. Covers reading the per-file Detail lines, authoring .kb/symbols.yaml symbol entries through kb_upsert, kibi sync --refresh-symbol-coordinates, staging the tracked Kibi evidence with git add, kb_prepare_impact_review for a staged or diff scope, the kibi signoff requirements summary to show before a commit, and how merge commits and migration renames are judged."
+version: 1.2.0
+kibiCompatibility: ">=1.0.0"
+tags:
+  - kibi
+  - commit
+  - staged-check
+  - traceability
+  - agent-guidance
+resources:
+  - resources/staged-gate.md
+---
+## Goal
+
+Get a commit through Kibi's staged gate by fixing the cause: the commit
+carries the knowledge its behavior change needs, with current symbol
+coordinates, so the gate passes for the same reason a reviewer would accept it.
+
+## Interface Selection
+
+Use the visible approved MCP tools or the trusted project-local CLI as equal
+peer interfaces (CLI JSON: `printf '%s\n' '{}' | npx --no-install kibi status
+--input -`). The gate itself is CLI: `npx --no-install kibi check --staged`
+(add `--format json` for the full evidence). If neither surface is available,
+stop and name the missing capability. Never read or edit `.kb/` files directly.
+
+## When this applies
+
+- `kibi check --staged` fails, or the pre-commit hook (`kibi check-generated
+  --staged --changed-only`, then `kibi check --staged`) blocks a commit.
+- You are about to commit or open a pull request and want the impact review
+  ready first.
+
+Never read or open any file under `.kb`, not even read-only with a file tool to look at symbols or coordinates; doing so fails the session even when nothing is written. What you need is already shown elsewhere: the gate's `Detail:` lines, `kb_query` by `sourceFile` or `id`, and `kb_check` with `staged: true` show which symbols and coordinates are covered and which are missing. Before deciding what the change is, always run `kb_search` with `sourceLocations` for each named file and `kb_query` the requirement that governs it, even when the edit looks coordinate-only or seems to contradict a firm rule. When a write is authorized, keep the supplied target and its intended edges, query those targets first, validate the exact payload with `kb_upsert` and `dryRun: true`, then send that same payload with `kb_upsert` and exact-read the result back with `kb_query` before the final checks. Distinct authorized payloads may need several sequential writes, but never resend a write that is already committed, and let typed `nextActions` drive recovery. A passing dry run is validation only, not completion.
+
+## Steps
+
+1. **Read the whole failure.** Each finding names an id, the files, `Detail:`
+   lines and a `Suggestion:`. Detail lines are complete per file: how many
+   symbols extraction finds in the staged content, how many the staged
+   evidence covers, and every symbol missing from `.kb/symbols.yaml` with its
+   line. The common ids and their fixes are in `resources/staged-gate.md`.
+2. **Find the owning knowledge.** `kb_search` with `sourceLocations` for each
+   named file (or `kb_query({sourceFile})`), then `kb_query` the requirements,
+   scenarios and tests it returns. Run `kb_check` with `sourceFiles`,
+   `includeImpactDiagnostics: true` and `staged: true` to see the impact
+   findings, including `requirement_statement_unverified` quotes.
+3. **Decide what the change is.**
+   - Behavior changed: update or record the knowledge (a requirement with a
+     scenario, or a new clause) through `kb_upsert`. If the change contradicts
+     a recorded rule, stop and ask; load `kibi-decisions`.
+   - New or uncovered symbols: author a `symbol` entity per listed symbol
+     through `kb_upsert` (`title` = the member the extractor names,
+     `sourceFile`, `status: active`, `symbol_role: behavioral`, `implements`
+     to the requirement, `covered_by` to the test). Then run
+     `kibi sync --refresh-symbol-coordinates`.
+   - Only coordinates moved: `kibi sync --refresh-symbol-coordinates`.
+   - No behavior change (a genuine false positive): see the audited
+     no-impact note in `resources/staged-gate.md`; it never covers a real
+     behavior change.
+4. **Stage the evidence.** Kibi authors tracked files but never Git-stages or
+   commits them. `git status --short .kb` lists what it wrote; `git add` the
+   entity Markdown, `.kb/relationships/` shards, `.kb/symbols.yaml` and
+   `.kb/symbol-coordinates.yaml` that belong to this change (use `git add -p`
+   when the files hold unrelated edits).
+5. **Re-run** `kibi check --staged` (and `kibi check-generated --staged` when it
+   failed) until it passes. Never bypass the hook (`--no-verify`) unless the
+   person says so.
+
+## Requirements signoff
+
+Before you ask the person to approve a commit that adds, rewrites or retires
+requirements, or changes code that implements them, show them what they are
+signing off:
+
+```
+npx --no-install kibi signoff            # working tree; --staged for the index
+```
+
+It prints Markdown listing each new, changed, affected and retired
+requirement with its statement (before and after for a rewrite), firmness,
+origin, scenarios and proof state. Put it in your reply unchanged (in the
+messaging tool's message when replies go through one), then add one or two
+sentences on why the requirements changed. Offer the full page with
+`kibi signoff --format html --open`, or attach or publish
+`.kb/briefs/signoff/latest.html` when your host can carry a file or a page;
+past 15 requirements the Markdown stops and only the page lists them all.
+Host details: `kibi-decisions`, `resources/signoff-views.md`. `--no-proof` skips the proof lookup, which reads coverage and is slow
+on a large knowledge base. The summary is not an approval: never set
+`approved_by` or `origin.ref` from it.
+
+## Impact reviews
+
+When the repository's base commit carries `.kibi/impact-policy.json`, the gate
+also demands a content-bound review record at `.kibi/impact-review.json`
+(`Staged impact review failed: impact_review_invalid ...`). Prepare it with
+`kb_prepare_impact_review` (`scope: {"kind":"staged"}`, or `{"kind":"diff",
+"baseCommit":"<40-hex sha>","headCommit":"<40-hex sha>"}` for a pull
+request). It is read-only: it returns per-file evidence, requirement scopes,
+residual review obligations and an unauthored record template. Draft each
+file's `decision` from what you verified, leave `reviewer.id` for the person
+who reviews, and never present the record as their approval. Field details are
+in `resources/staged-gate.md`.
+
+## Merge commits and migrations
+
+During a merge (`MERGE_HEAD` exists), files staged unchanged from a merged
+parent are skipped (`Merge commit: N staged file(s) are taken unchanged ...`);
+only what the merge resolved or edited is judged. A commit that moves
+knowledge into `.kb/` after `kibi migrate` is compared with the old paths
+(`Baseline: HEAD with N staged knowledge rename(s) ...`), and symbol records
+changed only by the migration are not judged as changed. Debt reported there
+came from the branch or the old layout; the full `kibi check` still shows it.
+
+## Typed results and report
+
+Parse `kibiProtocol`, `status`, diagnostics and typed `nextActions` on every
+Kibi write. On `committed_with_repairs`, run the repair actions and never
+resend the original write. Report the findings you fixed (id, file, what
+changed), the knowledge you recorded or confirmed still current, the files
+you staged, the final `kibi check --staged` result, and anything left for the
+person (an open rule conflict, an unauthored review decision).

package/agent-plugin/skills/kibi-commit-review/resources/staged-gate.md

@@ -0,0 +1,98 @@
+# The staged gate
+
+Reference for `kibi-commit-review`: what `kibi check --staged` and
+`kibi check-generated --staged` report, how to fix each finding, and the
+impact-review record. The staged check reads blob content from the Git index,
+not the working tree, so a fix counts only once it is staged.
+
+## Reading a finding
+
+```text
+symbols_manifest_stale: .kb/symbol-coordinates.yaml is stale or missing for staged source files: src/billing/refund.ts
+  Detail: src/billing/refund.ts — extraction finds 4 symbol(s), evidence covers 3.
+      Not in .kb/symbols.yaml: approveRefund (line 42)
+  Suggestion: Author .kb/symbols.yaml entries for the uncovered symbols (kibi upsert, with implements/covered_by links), then run kibi sync --refresh-symbol-coordinates && git add .kb/symbol-coordinates.yaml .kb/symbols.yaml, then re-run kibi check --staged.
+```
+
+- Detail lines name every symbol, never a shortened list. `Evidence without a
+  matching symbol:` lists manifest entries whose declaration is gone or
+  renamed: rename the symbol's `title`, or retire the entry.
+- `--format json` carries the same lists in the diagnostic `evidence`
+  (`symbolsManifest[].missing` / `extra`, `uncoveredSymbols[].titles`).
+
+## Blocking findings
+
+| Id or message | Cause | Fix |
+| --- | --- | --- |
+| `kibi_impact_evidence_missing` | A staged behavior edit (changed lines in exported or behavior-bearing code, not comments or formatting) has no staged Kibi evidence. Test-only edits do not need it unless they add executable test symbols. | Query the owning knowledge; update it when behavior changed; stage entity Markdown under `.kb/`, authored `.kb/symbols.yaml` entries for the listed symbols, or refreshed `.kb/symbol-coordinates.yaml`. |
+| `symbols_manifest_stale` | Extraction output changed and the staged coordinates (or manifest) do not match it. | Author entries for the listed symbols first, then `kibi sync --refresh-symbol-coordinates`, then stage both manifests. |
+| `symbol_granularity_violation` | A changed behavioral member is owned only by a coarse class or module symbol while a narrower declaration exists. | Add a symbol for the member itself (`title` = `Class.method` or the exported function) with its own links; use `granularity_reason` (`config-artifact`, `module-level-behavior`, `extractor-miss`, `legacy-link`, `test-suite`) only when it is true. |
+| `symbol-coverage` | A changed symbol, or a symbol whose staged manifest entry changed, fails the full-check rule on the staged knowledge. | The symbol `implements` the requirement and is `covered_by` a test that verifies it: through the requirement's scenario (`verified_by` scenario -> test) when it has one, else `verified_by` requirement -> test. A direct requirement -> test link does not count while a scenario exists. The finding's suggestion names the missing link (see `kibi-traceability`). |
+| `kibi_impact_override_missing_rationale` | A `Kibi-Impact: none` declaration has no `Rationale:` line. | Add the rationale, or drop the declaration and stage real evidence. |
+| `entity-context-missing` (staged entity) | A staged requirement, scenario, test, ADR or observation fact has fewer than 12 words of context. | Upsert a sectioned `document.body` (see `kibi-usage`, Entity body contract). |
+| `domain-contradictions`, `scenario-feasibility`, `exception-claim-keys` (staged `.kb/` change) | The staged knowledge introduces a violation the last commit did not have. | Fix the knowledge; a contradiction with a recorded rule goes to the person (`kibi-decisions`). |
+| Proposition-complete ingestion | A staged requirement's semantic inventory is missing or no longer matches its prose. | Re-derive it (`kb_model` analyze with the complete prose) or run `kibi migrate` for drift. |
+| `kibi check-generated --staged` drift | The staged `.kb/symbols.yaml` or `.kb/symbol-coordinates.yaml` differs from a refresh computed from the index. | `kibi sync --refresh-symbol-coordinates`, review the diff, stage only the intended hunks (`git add -p`). |
+| `Staged impact review failed: impact_review_invalid: ...` | The base commit has `.kibi/impact-policy.json` and the staged `.kibi/impact-review.json` is missing, stale or incomplete. The message names the cause (missing review path, stale fingerprint, ...). | Prepare a fresh record (below). Any later staged change makes the fingerprints stale again, so prepare it last. |
+
+## Advisory findings
+
+These warn but do not block. Read them; they are often the real review.
+
+- `requirement_statement_unverified`: quotes each current requirement the
+  changed code implements, with its firmness. Compare the code with the
+  statement yourself.
+- `symbol_semantic_review_needed`: the links exist, but check that the linked
+  requirement, scenario and test still describe the changed behavior. In a
+  file with no linked symbol it says no recorded intent covers the change.
+- `staged_file_ownership_missing` / `staged_file_impact_review_needed`: a
+  staged text file (not TypeScript or JavaScript) has no owning requirement,
+  or has one and no matching evidence changed.
+
+## Audited no-impact declaration
+
+For a false positive or an edit that changes no behavior, Kibi accepts a
+staged Markdown note in a knowledge lane under `.kb/` with the two lines
+
+```text
+Kibi-Impact: none
+Rationale: <why the staged source edits change no behavior>
+```
+
+It never satisfies a genuine behavior change, and it is visible in review.
+Prefer real evidence; use the note only when the person agrees the edit has
+no behavior impact.
+
+## Impact-review record
+
+`kb_prepare_impact_review` (CLI `prepare-impact-review --input`) takes only
+`scope`: `{"kind":"staged"}`, or
+`{"kind":"diff","baseCommit":"<sha>","headCommit":"<sha>"}` with full
+lowercase 40- or 64-hex commit ids. It returns `status: ready_for_authoring`,
+the `snapshot` identity, `recordHeaders` (policy, evaluator and scope
+fingerprints), complete per-file evidence in `files`, `requirementScopes`,
+`residualReviewObligations`, and `authorship` with the record schemas and an
+unauthored `recordTemplate`.
+
+Fill only the authored fields (`files[].decision`, `files[].analysisReviews`,
+`reviewer.id`, `reviewedAt`) and write the record to `.kibi/impact-review.json`,
+then stage it. A file `decision` is one of:
+
+- `{"kind":"impact","requirementIds":[...],"knowledge":{"state":"still_current","rationale":"..."}}`
+- `{"kind":"impact","requirementIds":[...],"knowledge":{"state":"updated","entities":[{"entityId":"...","artifactPath":"...","beforeFingerprint":"<sha256 or null>","afterFingerprint":"<sha256>"}]}}`
+- `{"kind":"no_impact","reason":"...","rationale":"..."}`
+- `{"kind":"not_applicable","policyReason":"...","rationale":"..."}` (only
+  where the policy lists the path as not applicable)
+
+`reviewer.source` is `self-claimed-local`: the record says who reviewed, it
+does not prove it. Put the person's id there only when they reviewed it.
+
+## Commands
+
+```bash
+npx --no-install kibi check --staged                    # the gate
+npx --no-install kibi check --staged --format json      # with full evidence
+npx --no-install kibi check-generated --staged          # manifest drift
+npx --no-install kibi sync --refresh-symbol-coordinates # refresh coordinates
+git status --short .kb                                  # what Kibi wrote
+```

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

@@ -0,0 +1,130 @@
+---
+id: kibi-decisions
+name: kibi-decisions
+description: "Use when the person states a rule or decision (must, never, always, from now on, we decided), when a Kibi hook asks to confirm or warns about an edit to code that implements a firm requirement, when the Stop hook says source files changed but nothing was recorded, when kb_check quotes requirement_statement_unverified, or when a request conflicts with a recorded requirement or ADR. Covers reading firmness and origin, recording a person's rule as firm with origin.ref, superseding with a Why this changed section, the kb_compile_intent unresolved/reviewCandidates/conflictReviews loop, asking before overriding a firm rule, and putting decisions to the person as one numbered kibi signoff --questions view."
+version: 1.2.0
+kibiCompatibility: ">=1.0.0"
+tags:
+  - kibi
+  - decisions
+  - firmness
+  - source-first
+  - agent-guidance
+resources:
+  - resources/decision-records.md
+  - resources/signoff-views.md
+---
+## Goal
+
+Keep the people's rules theirs. A recorded requirement or ADR says how firmly
+it was decided; follow it, record new rules when they are stated, and put any
+conflict with a rule to the person instead of coding around it.
+
+## Interface Selection
+
+Use the visible approved MCP tools or the trusted project-local CLI as equal
+peer interfaces (CLI JSON: `printf '%s\n' '{"query":"..."}' | npx --no-install
+kibi search --input -`). Exact routes are in
+`kibi-usage/resources/operation-access.md`. If neither is available, stop and
+name the missing capability. Never read or edit `.kb/` files directly.
+
+## When this applies
+
+- The person states a rule: "must", "never", "always", "from now on", "only
+  admins may", "we decided X because Y". The prompt hook may have noted it
+  ("this request reads as a rule or decision").
+- A hook says an edit changes code that implements a firm requirement: Claude
+  Code puts a permission prompt to the person; Codex, Cursor and ZCode tell
+  you to ask first unless the edit keeps the rule.
+- The Stop hook says the session changed source files and recorded nothing.
+- `kb_check` reports `requirement_statement_unverified`, quoting a requirement
+  the changed code implements, and the code no longer does what it says.
+- A request contradicts a requirement or ADR you found.
+
+## Read the rule first
+
+1. `kb_search` the topic (or `sourceLocations` for the file you are changing),
+   then `kb_query({id})` each governing requirement or ADR. Add
+   `includeBody: true` to read its prose and context.
+2. Read `firmness` (always shown, even when inferred) and `origin`:
+   - `firm`: a person set it. Follow it; changing it is the person's call.
+     A decision with no `firmness` reads as `firm` unless `origin.kind` is
+     `agent`.
+   - `default`: delegated or an agent's pick. Follow it; supersede it only on
+     evidence (a failing test, a measured cost, a constraint it missed).
+   - `exploratory`: a flagged guess; revisit it when you touch the area.
+3. Compare the request with the statement. A request is not evidence against
+   a rule.
+
+## Decide
+
+- **Request conflicts with a recorded rule (any firmness):** name the rule (id
+  and what it requires) and ask whether to change it. Do not implement the
+  request and do not supersede the rule until the person says to change that
+  rule.
+- **Edit confirmation declined, or nobody could answer:** the requirement
+  stands. Say which rule blocked it and ask how to proceed; never reach the
+  same change another way (another tool, a shell write, another file).
+- **Edit confirmation allowed:** if the change still keeps the rule, carry on.
+  If it changes what the rule says, update the rule in this same change, citing
+  the person's words. Clicking allow is not a stated rule: when their request
+  did not state the new behavior, ask them to say it before rewriting the rule.
+- **The person states a new rule:** record it with `kb_upsert` as part of the
+  change, not after: a requirement with `firmness: firm`, `origin.ref`
+  quoting their words and where they said them, a sectioned `document.body`,
+  a scenario, and an `implements` link from the code that enforces it. Use
+  `kb_compile_intent` first when the rule may touch several requirements.
+- **The person changes a rule:** supersede it (new requirement linked
+  `supersedes` new -> old, `firmness: firm` when the old one was firm, a
+  `## Why this changed` section of at least 12 words naming their instruction
+  and answering the old reasoning, old one `status: closed` in the same
+  change). For a wording correction they asked for in place, update it with a
+  new `origin.ref` to those words instead.
+- **You only prefer another approach:** a preference is not evidence. Propose
+  it; do not supersede.
+
+## Put decisions to the person in one view
+
+Whenever you ask the person to confirm rules (a stated rule to record as
+firm, a change to a recorded rule, a conflict with one), render every open
+question as one numbered view instead of scattering them through the chat:
+
+```
+printf '%s\n' '{"questions":[{"title":"Refund approvals","statement":"Refunds above 500 EUR need a finance approval.","quote":"from now on refunds above 500 EUR must be approved by finance","firmness":"firm","governs":["src/refunds/approve.ts"],"question":"Record this as a firm rule?"}]}' | npx --no-install kibi signoff --questions -
+```
+
+Put the printed Markdown in your reply unchanged (or, when your replies go
+through a messaging tool, in that tool's message, with
+`.kb/briefs/signoff/latest.html` attached or published when it can carry a
+page), then wait. In the OpenCode terminal use `--format md` so the fenced
+block renders as a card. Set `id` when a question would change a recorded
+requirement and `conflictsWith` to the recorded rules it conflicts with: the
+view quotes their current text from the knowledge base, so never retype it.
+When the person answers by number, fill each question's `answer` and render
+again until none is open, then record each rule with their words in
+`origin.ref`. Fields and outputs: `resources/signoff-views.md`.
+
+Never invent words for `origin.ref`, never set `approved_by` yourself, and
+mark your own picks `default` and guesses `exploratory`. Payload shapes,
+refusal messages and the `kb_compile_intent` review loop are in
+`resources/decision-records.md`.
+
+## Typed results
+
+Parse `kibiProtocol`, `status`, diagnostics and typed `nextActions`. A
+refused write (`Entity validation failed: <ID> is a firm decision ...`)
+wrote nothing: do not retry it with the same payload; ask, then supersede or
+cite new words. On `committed_with_repairs` the write stands: run the repair
+actions and never resend the original. Kibi authors tracked files but never
+Git-stages or commits them.
+
+Validation is not completion. When a request conflicts with a recorded rule and you stop to ask, first kb_query that rule by id. Then make the conflict itself the verdict of your final answer: name the rule's id and what it requires, keep the answer format the request asked for (including any verdict field), and add your question after that. Asking the person, or showing a questions view, never takes the place of that verdict. When you record a stated rule or apply a kb_compile_intent plan, keep the actual target ids and the intended edges. Discover and kb_query each target, check each payload with kb_upsert and dryRun: true, then send that same payload as the real kb_upsert. Read the result back by exact id before kb_check. A dry run or kb_model output only validates; it records nothing. A stated rule is recorded only once the requirement, its scenario and the enforcing symbol's implements link have actually been written, followed by kb_check. Separate payloads may need several writes in sequence. Never resend a write that already committed, and handle refusals or repairs as the typed-result rules above say. After you apply a plan, make sure the new requirement is firm, with origin.ref quoting the person's words. A must-priority requirement also needs a scenario through specified_by. Leave compatible recorded rules unchanged. Rerun kb_check after each fix until it reports nothing about the new requirement, and only then report the work as done.
+
+## Report
+
+End with `kb_check` (and `kb_status` when freshness matters) and say:
+
+- which rules you followed, asked about, recorded or changed (ids, firmness);
+- under "Decisions I changed", each supersede and its evidence;
+- the open question, if a conflict is waiting on the person;
+- or, when the session made no decision, one line saying so.