kibi-cli 2.29.0 → 2.30.0

package/dist/signoff/markdown.js

@@ -0,0 +1,203 @@
+import { SIGNOFF_CHANGE_LABELS, SIGNOFF_FENCES, approvalNumbers, approvalSentence, awaitsApproval, proofLabel, questionKind, questionOpen, statementSentenceDiff, } from "./model.js";
+/** Rows shown in chat before the rest is left to the HTML view. */
+export const SIGNOFF_MARKDOWN_LIMIT = 15;
+const CHANGE_ORDER = [
+    "new",
+    "changed",
+    "affected",
+    "retired",
+];
+function quote(text) {
+    return `> ${text.replace(/\s+/g, " ").trim()}`;
+}
+/**
+ * A rewritten statement as lines under a list item: the new statement with
+ * added sentences in bold and removed ones struck through when sentences
+ * survive the rewrite, or the old and new statements otherwise.
+ */
+function rewriteLines(previous, statement, labels = ["Was", "Now"]) {
+    const diff = statementSentenceDiff(previous, statement);
+    if (diff === undefined) {
+        return [
+            `- ${labels[0]}:`,
+            `  ${quote(previous)}`,
+            `- ${labels[1]}:`,
+            `  ${quote(statement)}`,
+        ];
+    }
+    const added = diff.filter((part) => part.change === "added").length;
+    const removed = diff.filter((part) => part.change === "removed").length;
+    const counts = [
+        added > 0 ? `${added} added in bold` : undefined,
+        removed > 0 ? `${removed} removed struck through` : undefined,
+    ].filter(Boolean);
+    const text = diff
+        .map((part) => part.change === "added"
+        ? `**${part.text}**`
+        : part.change === "removed"
+            ? `~~${part.text}~~`
+            : part.text)
+        .join(" ");
+    return [
+        `- ${labels[1]}, sentences ${counts.join(", ")}:`,
+        `  ${quote(text)}`,
+    ];
+}
+function firmnessTag(firmness) {
+    return firmness === "firm"
+        ? "firm"
+        : firmness === "exploratory"
+            ? "exploratory"
+            : "default";
+}
+function originLine(requirement) {
+    const parts = [];
+    if (requirement.originKind)
+        parts.push(requirement.originKind);
+    if (requirement.originRef)
+        parts.push(`"${requirement.originRef}"`);
+    if (requirement.approvedBy)
+        parts.push(`approved by ${requirement.approvedBy}`);
+    if (awaitsApproval(requirement))
+        parts.push("**awaiting your approval**");
+    return parts.length > 0 ? `- Origin: ${parts.join(", ")}` : undefined;
+}
+function requirementBlock(requirement, number) {
+    const lines = [
+        `**${number}. ${requirement.id}** · ${firmnessTag(requirement.firmness)} · ${requirement.title}`,
+    ];
+    if (requirement.previousStatement !== undefined) {
+        lines.push(...rewriteLines(requirement.previousStatement, requirement.statement));
+    }
+    else {
+        lines.push(quote(requirement.statement));
+    }
+    const origin = originLine(requirement);
+    if (origin)
+        lines.push(origin);
+    for (const superseded of requirement.supersedes) {
+        lines.push(`- Replaces ${superseded.id} (${firmnessTag(superseded.firmness)}): ${superseded.statement}`);
+    }
+    if (requirement.symbols.length > 0) {
+        lines.push(`- Changed code: ${requirement.symbols.join(", ")}`);
+    }
+    if (requirement.change !== "retired") {
+        lines.push(requirement.scenarios.length > 0
+            ? `- Scenarios: ${requirement.scenarios.map((scenario) => (scenario.title === scenario.id ? scenario.id : `${scenario.id} (${scenario.title})`)).join("; ")}`
+            : "- Scenarios: none yet");
+        lines.push(`- Proof: ${proofLabel(requirement.proof)}`);
+        for (const conflict of requirement.proof?.contradictions ?? []) {
+            lines.push(`- Contradiction: ${conflict}`);
+        }
+    }
+    return lines;
+}
+function headline(summary) {
+    const counts = CHANGE_ORDER.map((change) => [
+        change,
+        summary.requirements.filter((row) => row.change === change).length,
+    ])
+        .filter(([, count]) => count > 0)
+        .map(([change, count]) => `${count} ${change}`);
+    return counts.length === 0
+        ? "## Requirements signoff: no requirement changes"
+        : `## Requirements signoff: ${counts.join(", ")}`;
+}
+// implements REQ-kibi-signoff-views
+/** The end-of-work summary as Markdown, without the fence. */
+export function renderSummaryMarkdownBody(summary, limit = SIGNOFF_MARKDOWN_LIMIT) {
+    const lines = [headline(summary)];
+    const approvals = approvalNumbers(CHANGE_ORDER.flatMap((change) => summary.requirements.filter((row) => row.change === change)));
+    if (approvals.length > 0)
+        lines.push("", `**${approvalSentence(approvals)}**`);
+    let number = 0;
+    for (const change of CHANGE_ORDER) {
+        const rows = summary.requirements.filter((row) => row.change === change);
+        const shown = rows.slice(0, Math.max(0, limit - number));
+        if (shown.length === 0)
+            continue;
+        lines.push("", `### ${SIGNOFF_CHANGE_LABELS[change]}`);
+        for (const row of shown) {
+            number += 1;
+            lines.push("", ...requirementBlock(row, number));
+        }
+    }
+    const hidden = summary.requirements.length - limit;
+    if (hidden > 0) {
+        lines.push("", `…and ${hidden} more. Run \`kibi signoff --format html --open\` to see them all.`);
+    }
+    if (approvals.length > 0) {
+        lines.push("", 'Reply by number, for example "approve 1" or "1: reword …".');
+    }
+    for (const note of summary.notes)
+        lines.push("", `Note: ${note}`);
+    return lines.join("\n");
+}
+// implements REQ-kibi-signoff-views
+/** The mid-work decision questions as Markdown, without the fence. */
+export function renderQuestionsMarkdownBody(view) {
+    const open = view.questions.filter(questionOpen).length;
+    const answered = view.questions.length - open;
+    const lines = [
+        `## Decisions to confirm: ${open} open${answered > 0 ? `, ${answered} answered` : ""}`,
+    ];
+    for (const question of view.questions) {
+        const title = question.title ?? question.current?.title ?? question.id;
+        const heading = `${question.number}. ${questionKind(question)}${title ? `: ${title}` : ""}`;
+        lines.push("");
+        if (!questionOpen(question)) {
+            lines.push(`~~**${heading}**~~ · answered: ${question.answer}`);
+            continue;
+        }
+        lines.push(`**${heading}**${question.firmness ? ` · would be ${question.firmness}` : ""}`);
+        if (question.current) {
+            lines.push(...rewriteLines(question.current.statement, question.statement, [
+                `Recorded now (${firmnessTag(question.current.firmness)})`,
+                "Proposed",
+            ]));
+        }
+        else {
+            lines.push(quote(question.statement));
+        }
+        if (question.quote)
+            lines.push(`- Your words: "${question.quote}"`);
+        if (question.governs?.length) {
+            lines.push(`- Governs: ${question.governs.join(", ")}`);
+        }
+        for (const conflict of question.conflicts) {
+            lines.push(`- Conflicts with ${conflict.id} (${firmnessTag(conflict.firmness)}): ${conflict.statement}`);
+        }
+        if (question.question)
+            lines.push(`- Question: ${question.question}`);
+    }
+    if (open > 0) {
+        lines.push("", 'Reply by number, for example "1 yes, 2 exploratory, 3 reword: …".');
+    }
+    for (const note of view.notes)
+        lines.push("", `Note: ${note}`);
+    return lines.join("\n");
+}
+// implements REQ-kibi-signoff-views
+/**
+ * A signoff view as plain Markdown for a chat reply or a messaging tool
+ * (headings, quotes and lists that any Markdown surface renders), with no
+ * fence for a host renderer to find.
+ */
+export function renderSignoffChatMarkdown(view) {
+    return view.kind === "summary"
+        ? renderSummaryMarkdownBody(view)
+        : renderQuestionsMarkdownBody(view);
+}
+// implements REQ-kibi-signoff-views
+/**
+ * A signoff view as the fenced block agents paste into chat. Host renderers
+ * (the Claude Code display hook, the OpenCode TUI) key on the fence's info
+ * string; hosts without one show it as a code block, so they get `chat`.
+ */
+export function renderSignoffMarkdown(view) {
+    const fence = SIGNOFF_FENCES[view.kind];
+    const body = renderSignoffChatMarkdown(view);
+    // A body line starting with ``` would close the fence early.
+    const safe = body.replace(/^```/gm, "'''");
+    return `\`\`\`${fence}\n${safe}\n\`\`\`\n`;
+}

package/dist/signoff/model.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Requirement signoff views. A person signs off requirements at two moments:
+ * mid-work, when the agent asks them to confirm rules before recording them
+ * (questions), and at the end of the work, before the commit (summary). Both
+ * views are one JSON document that every host renders: the CLI prints it as a
+ * fenced Markdown block or a self-contained HTML page, and editor plugins read
+ * the copies written to `.kb/briefs/signoff/` (latest.json, latest.md and
+ * latest.html; `.kb/briefs/` is git-ignored and never synced).
+ */
+export declare const SIGNOFF_VERSION = "kibi.signoff.v1";
+/** The fence info strings host renderers key on. */
+export declare const SIGNOFF_FENCES: {
+    readonly summary: "kibi-signoff";
+    readonly questions: "kibi-questions";
+};
+/** Where the latest signoff view is written, relative to the workspace. */
+export declare const SIGNOFF_BRIEF_DIR = ".kb/briefs/signoff";
+export declare const SIGNOFF_LATEST_JSON = ".kb/briefs/signoff/latest.json";
+/** The latest view's Markdown body (no fence), for plain-text host views. */
+export declare const SIGNOFF_LATEST_MARKDOWN = ".kb/briefs/signoff/latest.md";
+/** The latest view as a self-contained page, for browsers and webviews. */
+export declare const SIGNOFF_LATEST_HTML = ".kb/briefs/signoff/latest.html";
+export type SignoffFirmness = "firm" | "default" | "exploratory";
+/** How a requirement entered the change. */
+export type SignoffChange = "new" | "changed" | "affected" | "retired";
+export type SignoffStatementRef = Readonly<{
+    id: string;
+    title: string;
+    statement: string;
+    firmness?: SignoffFirmness;
+}>;
+export type SignoffProof = Readonly<{
+    /** Coverage proof status: proven, missing, unresolved or not_applicable. */
+    status: string;
+    /** The earliest unmet proof gate, or "proven". */
+    gate: string;
+    testCount: number;
+    contradictions: readonly string[];
+}>;
+export type SignoffRequirement = Readonly<{
+    id: string;
+    title: string;
+    change: SignoffChange;
+    status: string;
+    statement: string;
+    /** The statement at the base commit, when the change rewrote it. */
+    previousStatement?: string;
+    firmness?: SignoffFirmness;
+    originKind?: string;
+    originRef?: string;
+    approvedBy?: string;
+    supersedes: readonly SignoffStatementRef[];
+    scenarios: readonly Readonly<{
+        id: string;
+        title: string;
+    }>[];
+    /** Changed code symbols that implement it (affected requirements). */
+    symbols: readonly string[];
+    proof?: SignoffProof;
+    source: string;
+}>;
+export type SignoffSummary = Readonly<{
+    version: typeof SIGNOFF_VERSION;
+    kind: "summary";
+    scope: "staged" | "working";
+    generatedAt: string;
+    branch?: string;
+    requirements: readonly SignoffRequirement[];
+    /** Parts of the view Kibi could not compute, in plain words. */
+    notes: readonly string[];
+}>;
+/** One decision the agent asks the person to confirm. */
+export type SignoffQuestionInput = Readonly<{
+    /** Existing or proposed requirement id. */
+    id?: string;
+    title?: string;
+    /** The rule as it would be recorded. */
+    statement: string;
+    /** The person's words that would go in origin.ref. */
+    quote?: string;
+    firmness?: SignoffFirmness;
+    /** Files or symbols the rule governs. */
+    governs?: readonly string[];
+    /** Recorded requirements the rule conflicts with. */
+    conflictsWith?: readonly string[];
+    /** What the agent asks, when it is more than "record this?". */
+    question?: string;
+    /** The person's answer, once given. */
+    answer?: string;
+}>;
+export type SignoffQuestion = SignoffQuestionInput & Readonly<{
+    number: number;
+    /** The recorded requirement this question would change. */
+    current?: SignoffStatementRef;
+    conflicts: readonly SignoffStatementRef[];
+}>;
+export type SignoffQuestions = Readonly<{
+    version: typeof SIGNOFF_VERSION;
+    kind: "questions";
+    generatedAt: string;
+    questions: readonly SignoffQuestion[];
+    notes: readonly string[];
+}>;
+export type SignoffView = SignoffSummary | SignoffQuestions;
+export declare const SIGNOFF_CHANGE_LABELS: Readonly<Record<SignoffChange, string>>;
+export declare const SIGNOFF_GATE_LABELS: Readonly<Record<string, string>>;
+/** A short proof label for one requirement. */
+export declare function proofLabel(proof: SignoffProof | undefined): string;
+/** Whether a question still waits for the person. */
+export declare function questionOpen(question: SignoffQuestionInput): boolean;
+/** The kind of decision a question asks for. */
+export declare function questionKind(question: SignoffQuestion): string;
+/** One sentence of a rewritten statement and how the rewrite changed it. */
+export type StatementSentence = Readonly<{
+    text: string;
+    change: "kept" | "added" | "removed";
+}>;
+/**
+ * A rewrite of a statement as its sentences in reading order, each kept,
+ * added or removed (a longest-common-subsequence diff), so the person reads
+ * what changed instead of comparing two paragraphs. Undefined when no
+ * sentence survives the rewrite, where before and after reads better.
+ */
+export declare function statementSentenceDiff(previous: string, statement: string): readonly StatementSentence[] | undefined;
+/**
+ * Whether the change asks the person to approve a requirement: the agent
+ * wrote or rewrote it and nobody has approved it.
+ */
+export declare function awaitsApproval(requirement: SignoffRequirement): boolean;
+/** The numbers (in view order) of the requirements awaiting approval. */
+export declare function approvalNumbers(ordered: readonly SignoffRequirement[]): number[];
+/** One sentence naming the requirements that wait for the person. */
+export declare function approvalSentence(numbers: readonly number[]): string;
+//# sourceMappingURL=model.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../../src/signoff/model.ts"],"names":[],"mappings":"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"}

package/dist/signoff/model.js

@@ -0,0 +1,138 @@
+/**
+ * Requirement signoff views. A person signs off requirements at two moments:
+ * mid-work, when the agent asks them to confirm rules before recording them
+ * (questions), and at the end of the work, before the commit (summary). Both
+ * views are one JSON document that every host renders: the CLI prints it as a
+ * fenced Markdown block or a self-contained HTML page, and editor plugins read
+ * the copies written to `.kb/briefs/signoff/` (latest.json, latest.md and
+ * latest.html; `.kb/briefs/` is git-ignored and never synced).
+ */
+export const SIGNOFF_VERSION = "kibi.signoff.v1";
+/** The fence info strings host renderers key on. */
+export const SIGNOFF_FENCES = {
+    summary: "kibi-signoff",
+    questions: "kibi-questions",
+};
+/** Where the latest signoff view is written, relative to the workspace. */
+export const SIGNOFF_BRIEF_DIR = ".kb/briefs/signoff";
+export const SIGNOFF_LATEST_JSON = `${SIGNOFF_BRIEF_DIR}/latest.json`;
+/** The latest view's Markdown body (no fence), for plain-text host views. */
+export const SIGNOFF_LATEST_MARKDOWN = `${SIGNOFF_BRIEF_DIR}/latest.md`;
+/** The latest view as a self-contained page, for browsers and webviews. */
+export const SIGNOFF_LATEST_HTML = `${SIGNOFF_BRIEF_DIR}/latest.html`;
+export const SIGNOFF_CHANGE_LABELS = {
+    new: "New",
+    changed: "Changed",
+    affected: "Affected by the code change (statement unchanged)",
+    retired: "Superseded or retired",
+};
+export const SIGNOFF_GATE_LABELS = {
+    semantic: "semantic model incomplete",
+    scenario: "no scenario yet",
+    implementation: "no owning code yet",
+    e2e: "no end-to-end test yet",
+    evidence: "end-to-end evidence not current",
+    proven: "proven",
+};
+/** A short proof label for one requirement. */
+export function proofLabel(proof) {
+    if (proof === undefined)
+        return "not checked";
+    if (proof.status === "not_applicable")
+        return "not applicable";
+    const gate = SIGNOFF_GATE_LABELS[proof.gate] ?? proof.gate;
+    const tests = `${proof.testCount} ${proof.testCount === 1 ? "test" : "tests"}`;
+    return proof.gate === "proven" ? `proven, ${tests}` : `${gate}, ${tests}`;
+}
+/** Whether a question still waits for the person. */
+export function questionOpen(question) {
+    return (question.answer ?? "").trim() === "";
+}
+/** The kind of decision a question asks for. */
+export function questionKind(question) {
+    if (question.current)
+        return `Change ${question.current.id}`;
+    if (question.conflicts.length > 0)
+        return "Conflict with a recorded rule";
+    return "New rule";
+}
+function sentences(statement) {
+    return statement
+        .replace(/\s+/g, " ")
+        .trim()
+        .split(/(?<=[.!?])\s+(?=[A-Z0-9"'`(])/)
+        .filter((sentence) => sentence.length > 0);
+}
+// implements REQ-kibi-signoff-views
+/**
+ * A rewrite of a statement as its sentences in reading order, each kept,
+ * added or removed (a longest-common-subsequence diff), so the person reads
+ * what changed instead of comparing two paragraphs. Undefined when no
+ * sentence survives the rewrite, where before and after reads better.
+ */
+export function statementSentenceDiff(previous, statement) {
+    const before = sentences(previous);
+    const after = sentences(statement);
+    const table = before.map(() => new Array(after.length + 1).fill(0));
+    table.push(new Array(after.length + 1).fill(0));
+    for (let i = before.length - 1; i >= 0; i -= 1) {
+        for (let j = after.length - 1; j >= 0; j -= 1) {
+            const row = table[i];
+            const next = table[i + 1];
+            row[j] =
+                before[i] === after[j]
+                    ? next[j + 1] + 1
+                    : Math.max(next[j], row[j + 1]);
+        }
+    }
+    if ((table[0]?.[0] ?? 0) === 0)
+        return undefined;
+    const result = [];
+    let i = 0;
+    let j = 0;
+    while (i < before.length || j < after.length) {
+        if (i < before.length && j < after.length && before[i] === after[j]) {
+            result.push({ text: after[j], change: "kept" });
+            i += 1;
+            j += 1;
+        }
+        else if (j < after.length &&
+            (i >= before.length ||
+                table[i]?.[j + 1] >= table[i + 1]?.[j])) {
+            result.push({ text: after[j], change: "added" });
+            j += 1;
+        }
+        else {
+            result.push({ text: before[i], change: "removed" });
+            i += 1;
+        }
+    }
+    return result;
+}
+// implements REQ-kibi-signoff-views
+/**
+ * Whether the change asks the person to approve a requirement: the agent
+ * wrote or rewrote it and nobody has approved it.
+ */
+export function awaitsApproval(requirement) {
+    return ((requirement.change === "new" || requirement.change === "changed") &&
+        requirement.originKind === "agent" &&
+        !requirement.approvedBy);
+}
+// implements REQ-kibi-signoff-views
+/** The numbers (in view order) of the requirements awaiting approval. */
+export function approvalNumbers(ordered) {
+    return ordered.flatMap((requirement, index) => awaitsApproval(requirement) ? [index + 1] : []);
+}
+// implements REQ-kibi-signoff-views
+/** One sentence naming the requirements that wait for the person. */
+export function approvalSentence(numbers) {
+    if (numbers.length === 0)
+        return "";
+    const list = numbers.length === 1
+        ? `${numbers[0]}`
+        : `${numbers.slice(0, -1).join(", ")} and ${numbers.at(-1)}`;
+    return numbers.length === 1
+        ? `Requirement ${list} was written by the agent and waits for your approval.`
+        : `Requirements ${list} were written by the agent and wait for your approval.`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-cli",
-  "version": "2.29.0",
+  "version": "2.30.0",
   "type": "module",
   "description": "Kibi CLI for knowledge base management",
   "engines": {
@@ -235,7 +235,7 @@
     "fast-glob": "^3.2.12",
     "gray-matter": "^4.0.3",
     "js-yaml": "^4.1.0",
-    "kibi-core": "^0.22.4",
+    "kibi-core": "^0.22.5",
     "kibi-plugin-builtin": "^0.5.3",
     "kibi-plugin-sdk": "^0.5.0",
     "kibi-swipl": "^1.0.1",

package/src/public/operations/contracts.ts

@@ -652,6 +652,7 @@ const BASE_DATA_SCHEMAS: Readonly<
     warnings: valueArray,
     semanticAdvisor: nullableJsonSchema(recordValue),
     normalizedPreview: nullableJsonSchema(recordValue),
+    errorCode: stringValue,
     stagedFacts: stringArray,
     whatIf: recordValue,
   }),
@@ -683,6 +684,7 @@ const BASE_DATA_SCHEMAS: Readonly<
           warnings: valueArray,
           semanticAdvisor: nullableJsonSchema(recordValue),
           normalizedPreview: nullableJsonSchema(recordValue),
+          errorCode: stringValue,
           stagedFacts: stringArray,
           whatIf: recordValue,
           dryRun: { const: true },

package/src/public/operations/specs/bootstrap.ts

@@ -20,7 +20,7 @@ export const planBootstrapSpec = {
   name: "kb_plan_bootstrap",
   cliName: "plan-bootstrap",
   description:
-    "Generate a deterministic, snapshot-bound kibi.bootstrap-plan.v1 for repository onboarding. Read-only analysis of the repository plus any declared knowledge sources and cited intent claims returns evidence, bounded context questions, exact dependency-ordered actions, a canonical plan hash, and no mutation side effects.",
+    "Generate a deterministic, snapshot-bound kibi.bootstrap-plan.v1 for repository onboarding. Use it only to onboard a repository whose KB is empty or incomplete (the kibi-bootstrap skill drives it); for a change in an onboarded project use kb_compile_intent. Read-only analysis of the repository plus any declared knowledge sources and cited intent claims returns evidence, bounded context questions, exact dependency-ordered actions, a canonical plan hash, and no mutation side effects.",
   businessInputSchema: {
     type: "object",
     properties: {

package/src/public/operations/specs/composite.ts

@@ -217,7 +217,7 @@ export const modelSpec = {
   name: "kb_model",
   cliName: "model",
   description:
-    "Turn requirement prose into checkable structure without writing the KB. mode:analyze returns the semantic advisor receipt: the clause ledger, what is grounded, what is ambiguous and suggested modeling (pass clauses for compound prose and optional typed kibi.logic.v1 interpretations). mode:requirement converts one claim (subjectKey, propertyKey, operator, value, or typed logic) into a strict-lane write set and applyPlan. mode:predicates ranks ontology predicate schemas and returns an applicable predicate-fact plan only for reviewed bindings, otherwise an ontology-gap observation. With requirementId, mode:predicates also returns a hash-bound plan (fact write plus requires_predicate link) for kb_apply_plan, whose contradictionAnalysis is the what-if over the current KB; other returned plans apply with kb_upsert, and kb_upsert dryRun with plannedFacts previews a requirement before its facts exist.",
+    "Turn requirement prose into checkable structure without writing the KB. Use it for one requirement's prose; to plan a whole change request use kb_compile_intent. mode:analyze returns the semantic advisor receipt: the clause ledger, what is grounded, what is ambiguous and suggested modeling (pass clauses for compound prose and optional typed kibi.logic.v1 interpretations). mode:requirement converts one claim (subjectKey, propertyKey, operator, value, or typed logic) into a strict-lane write set and applyPlan. mode:predicates ranks ontology predicate schemas and returns an applicable predicate-fact plan only for reviewed bindings, otherwise an ontology-gap observation. With requirementId, mode:predicates also returns a hash-bound plan (fact write plus requires_predicate link) for kb_apply_plan, whose contradictionAnalysis is the what-if over the current KB; other returned plans apply with kb_upsert, and kb_upsert dryRun with plannedFacts previews a requirement before its facts exist.",
   businessInputSchema: {
     type: "object",
     required: ["mode", "text"],

package/src/public/operations/specs/discovery.ts

@@ -259,7 +259,7 @@ export const statusSpec = {
   name: "kb_status",
   cliName: "status",
   description:
-    "Report current branch, KB snapshot, freshness metadata, schema status, and a typed kibi.migration-plan.v2 action graph. Read-only status inspection with no mutation side effects; damaged stores are diagnosed without starting the engine.",
+    "Report current branch, KB snapshot, freshness metadata, schema status, and a typed kibi.migration-plan.v2 action graph. Call it first to orient on a branch or after a failed call; use kb_check for validation findings and kb_coverage for proof status. Read-only status inspection with no mutation side effects; damaged stores are diagnosed without starting the engine.",
   businessInputSchema: { type: "object", properties: {} },
   // Status must remain available when the branch store cannot be attached.
   requiresProlog: false,

package/src/public/operations/specs/impact-review-preparation.ts

@@ -5,13 +5,15 @@ export const prepareImpactReviewSpec = {
   name: "kb_prepare_impact_review",
   cliName: "prepare-impact-review",
   description:
-    "Prepare complete content-bound impact-review authoring inputs from the current staged snapshot or explicitly selected immutable Git commits. Returns strict reviewer schemas and an unauthored template; it does not decide, approve, sign, stage, or prove the review.",
+    "Prepare complete content-bound impact-review authoring inputs from the current staged snapshot or explicitly selected immutable Git commits. Use it when kb_check reports that changed files need an impact review; it does not plan KB changes. Returns strict reviewer schemas and an unauthored template; it does not decide, approve, sign, stage, or prove the review.",
   businessInputSchema: {
     type: "object",
     additionalProperties: false,
     required: ["scope"],
     properties: {
       scope: {
+        description:
+          'What to review: {"kind":"staged"} for the staged snapshot, or {"kind":"diff","baseCommit":"<sha>","headCommit":"<sha>"} with full commit hashes.',
         oneOf: [
           {
             type: "object",

package/src/public/operations/specs/planning.ts

@@ -35,7 +35,7 @@ export const compileIntentSpec = {
   name: "kb_compile_intent",
   cliName: "compile-intent",
   description:
-    "Compile complete change intent into a deterministic, snapshot-bound read-only plan. Reuses intent-aware discovery and semantic modeling, accounts for every proposition, reports contradiction witnesses, proposes traceability links, and emits dependency-ordered kb_upsert-style steps only for resolved typed claims. contradictionAnalysis.outcome is no_conflict only when the check could decide: an unmodeled proposition or a related current requirement without logic leaves it unresolved with reasons and reviewCandidates to compare and judge through conflictReviews. No mutation side effects.",
+    "Compile complete change intent into a deterministic, snapshot-bound read-only plan. Use it before editing code for a change request that may touch several requirements; use kb_model for one requirement's prose and kb_plan_bootstrap for first-time onboarding. Reuses intent-aware discovery and semantic modeling, accounts for every proposition, reports contradiction witnesses, proposes traceability links, and emits dependency-ordered kb_upsert-style steps only for resolved typed claims. contradictionAnalysis.outcome is no_conflict only when the check could decide: an unmodeled proposition or a related current requirement without logic leaves it unresolved with reasons and reviewCandidates to compare and judge through conflictReviews. No mutation side effects.",
   businessInputSchema: {
     type: "object",
     required: ["intent", "mode"],