kibi-cli 2.29.0 → 2.30.0

package/dist/public/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/dist/public/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.

package/dist/public/skills/kibi-decisions/resources/decision-records.md

@@ -0,0 +1,142 @@
+# Decision records
+
+Reference for `kibi-decisions`: what the hooks say, the payloads that record
+or change a rule, what Kibi refuses, and the `kb_compile_intent` review loop.
+
+## What the hooks say
+
+| Hook | Text you see | What it means |
+| --- | --- | --- |
+| Prompt submit | `Kibi: this request reads as a rule or decision (it says "<phrase>").` | The phrase matched words such as "must", "never", "always", "from now on", "has to". It only asks whether there is something to record; check with `kb_search`. |
+| Before an edit (Claude Code) | A permission prompt: `Kibi: this edit changes <symbol>, which implements a firm requirement recorded in the knowledge base: <ID>: <title>. Allow it if ...` | The person decides. You are also told: if the edit was declined or could not be confirmed, the requirement stands; if allowed and the change alters what the requirement says, update the requirement with `kb_upsert` in this change. |
+| Before an edit (Codex, Cursor, ZCode) | `Kibi: this edit changes <where>, which implements a firm requirement, a rule the person set: ...` | The host cannot prompt the person, so you must: unless the edit keeps the rule, ask before making it and name the rule. |
+| Stop | `Kibi: this session changed source files and recorded nothing in the knowledge base.` (or the variant naming a rule-like request) | Record the decision the person stated or the change made (a rule, a limit, a default, who may do what) as a requirement linked to its code, or say in one line that there was none. Asked once per session. |
+
+The firm-edit prompt covers current requirements whose effective firmness is
+`firm` and that the edited symbol (or, for a whole-file write, any symbol of
+the file) implements. Superseded and retired requirements never ask. An
+operator can turn the prompt off with `KIBI_CONFIRM_FIRM_EDITS=0`; that does
+not make a firm rule negotiable.
+
+`kb_check` with `sourceFiles` and `includeImpactDiagnostics: true` reports
+`requirement_statement_unverified` (warning) for each current requirement a
+changed behavioral symbol implements, quoting its statement and firmness.
+Kibi never compares code with prose: you do. A change that no longer does what
+the quote says is a conflict with a recorded rule.
+
+## Effective firmness
+
+| `firmness` | `origin.kind` | Effective |
+| --- | --- | --- |
+| `firm`, `default` or `exploratory` | any | as written |
+| absent | `agent` | `default` |
+| absent | `human`, `import`, `migration`, or no origin | `firm` |
+
+`kb_search` answers and `kb_query` rows show the effective value. Hook
+snippets label firm decisions `[firm: ask before changing]` and exploratory
+ones `[exploratory]`; an unlabeled decision is `default`.
+
+## Record a rule the person stated
+
+Discover first (`kb_search`, `kb_query`). If a current requirement already
+says it, link to it instead of restating it. Otherwise write the scenario
+first, then the requirement (the requirement's write sends `specified_by`):
+
+```json
+{"type":"req","id":"REQ-billing-refund-approval","properties":{"title":"Refunds above 500 EUR need a finance approval","status":"open","priority":"must","firmness":"firm","origin":{"kind":"agent","ref":"session request: \"from now on refunds above 500 EUR must be approved by finance\""}},"relationships":[{"type":"specified_by","from":"REQ-billing-refund-approval","to":"SCEN-billing-refund-approval"}],"document":{"body":"Refunds above 500 EUR need a finance approval.\n\n## Context\n\nThe person asked for this rule while changing the refund flow; reason not stated.\n\n## Source\n\n> from now on refunds above 500 EUR must be approved by finance\n\nSession request."}}
+```
+
+Then link the enforcing symbol with `implements` (and its test with
+`covered_by`). Preview with `dryRun: true` when unsure; a passing dry run is
+validation, not the write.
+
+- `origin.ref` is where the words are and the words themselves: a ticket URL,
+  a document path with line, or the session request quoted. Kibi checks that a
+  reference exists, not that it is genuine, so never write words nobody said.
+- `kb_upsert` records `origin.kind: agent` when you omit `origin`; the explicit
+  `firmness: firm` is what makes the rule the person's. Leave
+  `origin.approved_by` to the person.
+- A rule from a document, test or ticket a person wrote is `firm` too, with
+  `origin.ref` to that source.
+- Your own choice is `default`; a guess is `exploratory`. Write the value
+  explicitly whenever you record a decision.
+- For strict modeling (claim keys, predicate facts) follow `kibi-usage`,
+  "Second-agent edits", recipe 1.
+
+## Supersede a rule
+
+Only when the person said to change that rule (firm), or on evidence (default):
+
+1. Write the new scenario, then the new requirement with `supersedes` to the
+   old one (direction new -> old), `firmness: firm` when the old one was firm,
+   `origin.ref` to the person's instruction, and a body section:
+
+   ```markdown
+   ## Why this changed
+
+   The person asked on 2026-10-21 to raise the approval threshold to 1000 EUR
+   because finance now reviews refunds weekly; the old 500 EUR limit predates
+   that review.
+   ```
+
+   At least 12 words, naming the evidence and answering the old decision's
+   reasoning.
+2. Upsert the old requirement with `status: closed` in the same change (its
+   stored `title`, the new status; status and links stay editable on a firm
+   decision).
+3. Re-point or close the old scenario, and move `implements` links to the new
+   requirement when the code now enforces it.
+4. Run `kb_check`.
+
+A preference ("this would be cleaner") is not evidence: propose it in the
+report instead of superseding. An authored requirement is never deleted:
+`kb_delete` returns `outcome: supersession_required`.
+
+## Correct a firm rule in place
+
+When the person asks for a correction that keeps the rule's meaning (a typo, a
+clearer title), update the existing requirement with a new `origin.ref` citing
+their words. Without new human words, Kibi refuses to change a firm decision's
+title, statement (or an ADR's body) or to lower its firmness.
+
+## What Kibi refuses or blocks
+
+| Where | Code or message | Fix |
+| --- | --- | --- |
+| `kb_upsert`, `dryRun`, `kb_apply_plan` step | `Entity validation failed: <ID> is a firm decision, so kb_upsert does not change its <fields> in place.` | Ask the person; then cite their words in `origin.ref`, or supersede with a firm decision. |
+| `kb_upsert` | `firmness: firm` without `origin.ref` (or `approval_ref` on a requirement) | Add the reference to the person's words. |
+| `kb_upsert` | `firmness is only valid on req and adr entities` | Remove `firmness` from facts, scenarios, tests and symbols. |
+| `kb_check` | `decision-firm-unreferenced` | As above. |
+| `kb_check` | `decision-firm-superseded` | The superseding decision must be `firm` too. |
+| `kb_check` | `decision-firm-edited` | A firm decision's claim changed in the working tree since `HEAD` without new words; revert, or cite their words. |
+| `kb_check` | `supersedes-reason-missing` | Add `## Why this changed` (12+ words). |
+| `kb_check` | `superseded-requirement-open` | Close the superseded requirement. |
+
+## The kb_compile_intent review loop
+
+`kb_compile_intent` (`mode: "create"` or `"update"`, the complete intent,
+`context` when creating) is read-only and returns a plan.
+
+- `contradictionAnalysis.outcome`:
+  - `no_conflict`: the check could decide and found none.
+  - `conflict`: a witness or your own verdict says the intent contradicts a
+    current requirement. The plan `status` is `blocked`.
+  - `unresolved`: Kibi could not decide. `reasons` say why
+    (`unmodeled_target`, `unmodeled_related`, `analysis_unavailable`). Never
+    read it as consistent.
+- `reviewCandidates[]`: up to five current requirements Kibi could not compare
+  logically, each with `requirementId`, `title`, `sentence` (the closest
+  sentence), `statement`, `score`, `modeled` and `review` (`pending`,
+  `conflict` or `no_conflict`).
+- Compare the intent with each candidate's `statement`, then compile again
+  with the same input plus
+  `conflictReviews: [{"requirementId": "...", "verdict": "conflict" | "no_conflict", "note": "..."}]`.
+  A verdict may also name a requirement discovery did not rank.
+- On `conflict`: ask the person which rule holds. Then supersede or change
+  the requirement (as above), or change the intent, and compile again.
+- Plan `status` is `ready`, `needs_resolution` (ambiguous or unmodeled
+  propositions, missing targets) or `blocked`. Apply only a `ready` plan the
+  person approved, with `kb_apply_plan` and its full `planHash`.
+- A compiled plan records the new requirement as an agent's. When the intent
+  is the person's stated rule, follow the apply with a `kb_upsert` that sets
+  `firmness: firm` and `origin.ref` on that requirement.

package/dist/public/skills/kibi-decisions/resources/signoff-views.md

@@ -0,0 +1,66 @@
+# Signoff views
+
+`kibi signoff` renders what a person signs off, so the agent never retypes
+requirement text from memory. It is a CLI command, not an MCP tool.
+
+| View | Command | When |
+| --- | --- | --- |
+| Decisions to confirm | `kibi signoff --questions <file or ->` | Mid-work: rules to record as firm, a change to a recorded rule, a conflict |
+| Requirements signoff | `kibi signoff` (`--staged` for the index) | End of work: before asking to commit |
+
+Both print plain Markdown by default (`--format chat`): headings, quoted
+statements and lists that render in any chat or messaging surface. Put it in
+your reply unchanged: never wrap it in a code block, summarize it or retell a
+requirement in your own words. Every run also writes
+`.kb/briefs/signoff/latest.json`, `latest.md` and `latest.html` (git-ignored);
+`latest.html` is a self-contained page with the full view.
+
+## Showing it on your host
+
+| Host | Best view |
+| --- | --- |
+| Claude Code, Codex, Cursor, ZCode, VS Code chat | Paste the default output; `/kibi-signoff` (Claude Code, Cursor, ZCode) runs it. Offer `kibi signoff --format html --open` for the page |
+| OpenCode terminal | `kibi signoff --format md` and paste the fenced block unchanged: kibi-opencode draws it as a card, and `/kibi-signoff` reopens it |
+| Replies sent through a messaging tool (cloud or project threads, chat bots) | Pass the default output as the message text, and attach or publish `.kb/briefs/signoff/latest.html` next to it when the tool can carry a file or a page |
+| VS Code or Cursor with the kibi-vscode extension | The **Kibi: Show Requirements Signoff** panel follows every run |
+| Remote machine, no browser | Give the person the path of `latest.html` |
+
+`--format md` wraps the same Markdown in a ```` ```kibi-signoff ```` or
+```` ```kibi-questions ```` fence for host renderers; use it only where one
+draws it, because everywhere else a fence shows as raw code.
+`KIBI_SIGNOFF_FORMAT` sets the default for a host. `--format html --open`
+writes and opens the page; `--format json` prints the view.
+
+## Questions input
+
+`{"questions":[...]}` or a bare array. Each question:
+
+| Field | Required | Meaning |
+| --- | --- | --- |
+| `statement` | yes | The rule as it would be recorded |
+| `title` | no | A short name for the card |
+| `id` | no | The recorded requirement the question would change; the view quotes its current statement and firmness |
+| `quote` | no | The person's words that would go in `origin.ref` |
+| `firmness` | no | `firm`, `default` or `exploratory`, as it would be recorded |
+| `governs` | no | Files or symbols the rule governs |
+| `conflictsWith` | no | Recorded requirement ids it conflicts with; the view quotes them |
+| `question` | no | What you ask, when it is more than "record this?" |
+| `answer` | no | The person's answer; answered questions are struck out |
+
+The person answers by number ("1 yes, 2 exploratory, 3 reword: ..."). Copy
+each answer into `answer`, render again, and record the rules only once every
+question is answered. An answer is the person's words: quote it in
+`origin.ref`; a view itself is never an approval.
+
+## Summary contents
+
+| Section | Meaning |
+| --- | --- |
+| New | Requirement documents the change adds |
+| Changed | Rewritten requirements; a changed statement shows before and after |
+| Affected by the code change | Unchanged requirements whose implementing code changed (the `requirement_statement_unverified` set) |
+| Superseded or retired | Requirements the change retires, supersedes or deletes |
+
+Each requirement shows its firmness, origin, superseded rules, changed code
+symbols, scenarios and proof state (the earliest unmet proof gate). Parts
+Kibi could not compute are named in a `Note:` line instead of failing.

package/dist/public/skills/kibi-freshness/SKILL.md

@@ -53,6 +53,8 @@ echo '{}' | npx --no-install kibi status --input -
   `committed_with_repairs`, follow required typed `nextActions`; never retry the
   original operation.
 
+For every freshness, branch, or completion question, call `kb_status` first, then `kb_query` the entities and source files that status names, then `kb_check` as the last Kibi call before answering. Never skip the query step, even when status alone seems to answer the question. If another query or write follows a check, run `kb_check` again before answering. When asked whether requirements are consistent or proven, run `kb_query`, then `kb_check` with the domain-contradictions rule, then `kb_coverage`, and read whether the analysis was complete. Report any unmodeled or unknown clause as incomplete analysis, not as consistent. Only when every clause is fully modeled and compatible, state plainly that no conflict was found. For authorized knowledge changes, keep the exact supplied target and intended relationship edges, and discover and query those targets first. Validate the payload with `kb_upsert` and `dryRun: true`, then perform the authorized `kb_upsert` with that same payload and read the result back exactly before the final checks. A passing dry run is validation, not completion. Distinct authorized payloads may need several sequential writes, each validated and read back, but never retry a mutation that already committed. If a mutation returns `committed_with_repairs`, follow its typed `nextActions` instead of repeating the original operation.
+
 ## Guidance
 
 - Treat MCP and the trusted project-local CLI as equal peer surfaces.

package/dist/public/skills/kibi-traceability/SKILL.md

@@ -29,6 +29,8 @@ interfaces. Select the surface by capability; neither is semantically preferred.
 For CLI JSON, use a dedicated route such as
 `printf '%s\n' '{}' | kibi status --input -`.
 
+For every traceability answer, begin with `kb_search` even when an identifier is already named, then exact-filter with `kb_query`, inspect relationships with `kb_graph`, and make `kb_status` the final Kibi call, including after `kb_graph` or `kb_coverage`; report no conclusions until that closing `kb_status` returns. When judging scenario feasibility, ground each step in the queried requirements, scenarios, tests, and symbols, and state missing links, ambiguity, or stale evidence explicitly rather than inferring them. For authorized coverage or link work, keep the exact supplied target and intended edges, discover and query those targets, then validate the payload with `kb_upsert` and `dryRun: true`. A passing dry run is only validation, not completion: next perform the real `kb_upsert` with the same payload, exact-read the result back with `kb_query`, run `kb_check` and `kb_coverage`, report the resulting proof state, and finish with `kb_status`. Distinct authorized payloads may each need their own sequential dry run and write, so there is no single-write limit, but never retry a mutation that already committed; on `committed_with_repairs`, execute the typed repair action instead.
+
 ## Workflow
 
 Use the visible approved MCP tools or trusted project-local CLI as equal peer
@@ -50,6 +52,8 @@ plan_returned` with a hash-bound plan whose `nextActions[0].input` is the exact
 through a new requirement linked with `supersedes`. Relationship deletes patch
 shards while preserving unrelated records.
 
+For executable coverage work, keep the production symbol's implements link to its requirement and link that same production symbol to its qualifying test with covered_by; reserve executable_for for a symbol that stands for the executable test itself, and never put executable_for on a symbol that also carries production ownership or coverage. Preserve the exact supplied target and intended edges, discover and query those targets, validate the payload with `kb_upsert` and `dryRun: true`, then perform the authorized real `kb_upsert` with the same payload and exact-read the result with `kb_query` before final checks, because validation alone is not completion. A passing dry run does not guarantee the commit: if the real `kb_upsert` returns an error, read its message and correct only the conflicting relationship on the same target rather than working around it with a new entity, then validate again with `dryRun: true`, write again, and exact-read it back. Distinct authorized payloads may each need their own sequential validation and write, so there is no single write limit, but never retry a mutation that already committed; on `committed_with_repairs`, execute the typed repair action instead. Then run `kb_check` and `kb_coverage`, report the proof and verification state they return, treating a dirty verification snapshot after a write as expected rather than as a failure, and finish with `kb_status`.
+
 ## Typed recovery and proof
 
 Parse `kibiProtocol`, `resultVersion`, `status`, `effects`, diagnostics, and

package/dist/public/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.20.0
+version: 2.22.0
 kibiCompatibility: ">=1.0.0"
 tags:
   - kibi
@@ -121,6 +121,10 @@ component that renders it) with `implements` through `kb_upsert`. Without a read
 still answers and `kibi sync` regenerates the manifest. The search tip and the
 `.kb/` note appear once per session and need no action.
 
+Before you edit a source file that Kibi tracks, run `kb_search` with that file in `sourceLocations`, and treat both its ranked results and its `data.answer` layer as discovery only, not as the governing text. Then call `kb_query` by `id` on each current governing requirement that the search names, read what each one requires, and make the edit only after those exact reads. A `kb_check`, `kb_status` or `kb_coverage` result does not replace that `kb_query` read. This rule only adds an exact read before the edit and does not change the order of any other step in this workflow. It adds nothing to a modeling or write task: that task still ends with the real `kb_upsert` of every planned fact and requirement and the closing `kb_check`.
+
+For an edit that keeps the governing rule, limit the consultation before the edit to exactly two Kibi calls: `kb_search` with the file in `sourceLocations`, then one `kb_query` (by the governing requirement's `id`, or by `sourceFile` when several requirements govern the file). Do not start with `kb_status`, and do not repeat the search or the query before editing; run `kb_status`, `kb_check` and `kb_coverage` after the edit. This limit applies only to source edits. A task that models a claim keeps its full order, one step after the other: `kb_search`, then the exact `kb_query` of the supplied target, then `kb_model` with `mode: "analyze"` on the complete claim, then `mode: "predicates"` for each relational clause, then `kb_model` with `mode: "requirement"` for a strict or typed-rule clause, and only then the real `kb_upsert` of every planned fact and requirement and the closing `kb_check`. Never call `kb_model` before that exact `kb_query`, and never stop at a dry run.
+
 ## Safe workflow
 
 1. Always discover before you mutate: start with `kb_search`, then exact-filter with `kb_query`. Use
@@ -356,7 +360,9 @@ authored. Each one is the order the write path accepts.
 
 Entities record `origin` (`kind`: `human`, `agent`, `migration`, or `import`,
 plus optional `ref` and `approved_by`). `kb_upsert` records `kind: agent` on
-entities you create; leave `origin.approved_by` to the person who reviews them.
+entities you create; leave `origin.approved_by` to the person who reviews them,
+and ask for that review with `kibi signoff` (see `kibi-decisions`), never with
+a summary in your own words.
 An exception (a requirement that `exempts` another) exempts nothing until a
 human sets `approved_by`; `kb_check` flags approvals an agent recorded without
 corroboration. Never fill in an approval yourself. Record why a requirement
@@ -365,6 +371,8 @@ exists in `rationale`, or link the ADR that explains it.
 ## Decision firmness
 
 Requirements and ADRs carry `firmness`, which says what you may do with them.
+Load `kibi-decisions` when a person states a rule, a hook asks before an edit
+of firm code, or a request conflicts with a recorded rule.
 Search answers, `kb_query` rows and hook snippets show it (snippets label only
 `[firm: ask before changing]` and `[exploratory]`; an unlabeled decision is
 `default`).
@@ -394,17 +402,12 @@ task or in reply: then supersede it with `firmness: firm` and `origin.ref` to
 their words (or, for a correction they asked for in place, update it with
 `origin.ref` to those words), and say in the final answer which rule changed.
 
-Set `firmness` from what a human actually said: only their stated rule is
-`firm` (with `origin.ref`); "do whatever" or your own pick is `default`; a
-guess is `exploratory`. Write it explicitly whenever you record a decision,
-including when importing rules from documents, tests or tickets (a rule a
-person wrote there is `firm`, with `origin.ref` to that document). A
-supersede needs `## Why this changed` in the new entity's body (at least 12
-words): name the evidence (a failing test, a measured cost, a constraint the
-old decision missed, a new requirement, the person's instruction) and answer
-the old decision's reasoning; `kb_check` blocks it otherwise. A preference is
-not evidence: propose it instead of superseding. Kibi checks only that a firm
-decision has a reference; never cite words nobody said.
+Set `firmness` explicitly from what a human actually said: only their stated
+rule is `firm` (with `origin.ref` to their words); your own pick is `default`;
+a guess is `exploratory`. A supersede needs a `## Why this changed` section of
+at least 12 words naming the evidence; a preference is not evidence. Never
+cite words nobody said. `kibi-decisions` has the recording and supersede
+payloads.
 
 Conditional clauses ("only when", "only if", "must not ... unless") compile
 into typed `forbid` rules linked by `requires_rule`, not property facts; one
@@ -418,7 +421,8 @@ read `unresolved` as consistent. Compare the intent with each candidate's
 `statement`, then compile again with `conflictReviews`
 (`{requirementId, verdict: "conflict" | "no_conflict", note}`). On a conflict
 the plan is `blocked`: ask the human which rule holds (a firm requirement is
-theirs), then supersede or change it, or change the intent.
+theirs), then supersede or change it, or change the intent (see
+`kibi-decisions`).
 
 ## Semantic and proof guardrails
 
@@ -558,4 +562,5 @@ retrying the same payload; inspect the typed error and `nextActions`.
 Kibi may now author tracked Markdown/YAML evidence transactionally. The former
 statement “Kibi operation writes do not automatically stage markdown evidence”
 means Kibi writes do not Git-stage it: review and commit remain ordinary Git
-workflows.
+workflows. When `kibi check --staged` or the pre-commit hook blocks a commit,
+load `kibi-commit-review`.

package/dist/signoff/collect.d.ts

@@ -0,0 +1,39 @@
+import { type ExtractedEntity } from "../extractors/markdown.js";
+import { type SignoffProof, type SignoffQuestionInput, type SignoffQuestions, type SignoffSummary } from "./model.js";
+export type SignoffScope = "staged" | "working";
+/** Changed code symbols per requirement they implement. */
+export type AffectedRequirements = ReadonlyMap<string, readonly string[]>;
+export type SignoffCollectDeps = Readonly<{
+    /** Run git in the workspace and return stdout; throws on failure. */
+    git?: (args: readonly string[]) => string;
+    /** Requirements the changed code implements, from the impact analysis. */
+    loadAffected?: (scope: SignoffScope) => Promise<AffectedRequirements>;
+    /** Proof rows by requirement id, from coverage. */
+    loadProof?: () => Promise<ReadonlyMap<string, SignoffProof>>;
+    now?: () => Date;
+}>;
+/** The requirement's statement: its semantic text, else its title. */
+export declare function requirementStatement(entity: ExtractedEntity): string;
+/**
+ * The end-of-work signoff summary: the requirements the change adds, rewrites,
+ * retires, or leaves unchanged while changing code that implements them, each
+ * with its statement, firmness, origin, scenarios and proof state.
+ */
+export declare function collectSignoffSummary(workspaceRoot: string, scope: SignoffScope, deps?: SignoffCollectDeps): Promise<SignoffSummary>;
+/**
+ * Requirements whose implementing code the change edits, read from the
+ * `requirement_statement_unverified` impact diagnostics of `kibi check`.
+ */
+export declare function loadAffectedForScope(workspaceRoot: string, scope: SignoffScope): Promise<AffectedRequirements>;
+/**
+ * The mid-work decision questions, numbered, with the recorded requirement a
+ * question would change and the recorded rules it conflicts with quoted from
+ * the knowledge base rather than from the agent's memory.
+ */
+export declare function collectSignoffQuestions(workspaceRoot: string, inputs: readonly SignoffQuestionInput[], now?: () => Date): SignoffQuestions;
+/**
+ * Parse the questions input: `{"questions":[{statement, id?, title?, quote?,
+ * firmness?, governs?, conflictsWith?, question?, answer?}]}` or a bare array.
+ */
+export declare function parseSignoffQuestionsInput(raw: string): SignoffQuestionInput[];
+//# sourceMappingURL=collect.d.ts.map

package/dist/signoff/collect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collect.d.ts","sourceRoot":"","sources":["../../src/signoff/collect.ts"],"names":[],"mappings":"AAIA,OAAO,EACL,KAAK,eAAe,EAErB,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EAIL,KAAK,YAAY,EAEjB,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EAGrB,KAAK,cAAc,EACpB,MAAM,YAAY,CAAC;AASpB,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,SAAS,CAAC;AAEhD,2DAA2D;AAC3D,MAAM,MAAM,oBAAoB,GAAG,WAAW,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC;AAE1E,MAAM,MAAM,kBAAkB,GAAG,QAAQ,CAAC;IACxC,qEAAqE;IACrE,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,KAAK,MAAM,CAAC;IAC1C,0EAA0E;IAC1E,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,OAAO,CAAC,oBAAoB,CAAC,CAAC;IACtE,mDAAmD;IACnD,SAAS,CAAC,EAAE,MAAM,OAAO,CAAC,WAAW,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC;IAC7D,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;CAClB,CAAC,CAAC;AAuCH,sEAAsE;AACtE,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CAEpE;AAyGD;;;;GAIG;AACH,wBAAsB,qBAAqB,CACzC,aAAa,EAAE,MAAM,EACrB,KAAK,EAAE,YAAY,EACnB,IAAI,GAAE,kBAAuB,GAC5B,OAAO,CAAC,cAAc,CAAC,CA6JzB;AAGD;;;GAGG;AACH,wBAAsB,oBAAoB,CACxC,aAAa,EAAE,MAAM,EACrB,KAAK,EAAE,YAAY,GAClB,OAAO,CAAC,oBAAoB,CAAC,CA8B/B;AAGD;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,aAAa,EAAE,MAAM,EACrB,MAAM,EAAE,SAAS,oBAAoB,EAAE,EACvC,GAAG,GAAE,MAAM,IAAuB,GACjC,gBAAgB,CA4BlB;AA+BD;;;GAGG;AACH,wBAAgB,0BAA0B,CACxC,GAAG,EAAE,MAAM,GACV,oBAAoB,EAAE,CAkDxB"}