kibi-cli 2.28.1 → 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/dist/traceability/commit-amend.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Whether the commit being made replaces a root commit (`git commit --amend`
+ * on a branch with one commit). Such a commit has no parent either, so the
+ * staged gate treats it as a first commit.
+ */
+export declare function amendsRootCommit(workspaceRoot: string, headCommit: string | null): boolean;
+//# sourceMappingURL=commit-amend.d.ts.map

package/dist/traceability/commit-amend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commit-amend.d.ts","sourceRoot":"","sources":["../../src/traceability/commit-amend.ts"],"names":[],"mappings":"AAsEA;;;;GAIG;AAEH,wBAAgB,gBAAgB,CAC9B,aAAa,EAAE,MAAM,EACrB,UAAU,EAAE,MAAM,GAAG,IAAI,GACxB,OAAO,CAmBT"}

package/dist/traceability/commit-amend.js

@@ -0,0 +1,85 @@
+/*
+ Kibi — repo-local, per-branch, queryable long-term memory for software projects
+ Copyright (C) 2026 Piotr Franczyk
+
+ This program is free software: you can redistribute it and/or modify
+ it under the terms of the GNU Affero General Public License as published by
+ the Free Software Foundation, either version 3 of the License, or
+ (at your option) any later version.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ GNU Affero General Public License for more details.
+
+ You should have received a copy of the GNU Affero General Public License
+ along with this program.  If not, see <https://www.gnu.org/licenses/>.
+*/
+import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { basename } from "node:path";
+/** How far up the process tree to look for the `git commit` running a hook. */
+const MAX_ANCESTORS = 8;
+function processArguments(pid) {
+    try {
+        if (process.platform === "linux") {
+            const stat = readFileSync(`/proc/${pid}/stat`, "utf8");
+            const parent = Number(stat.slice(stat.lastIndexOf(")") + 2).split(" ")[1]);
+            const argv = readFileSync(`/proc/${pid}/cmdline`, "utf8")
+                .split("\0")
+                .filter(Boolean);
+            return { parent, argv };
+        }
+        if (process.platform === "win32")
+            return null;
+        const [parent, ...argv] = execFileSync("ps", ["-o", "ppid=,args=", "-p", String(pid)], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 2000 })
+            .trim()
+            .split(/\s+/);
+        return { parent: Number(parent), argv };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Whether this process runs under `git commit --amend`. Git does not tell a
+ * pre-commit hook that it is amending, so the hook's ancestors are read.
+ */
+function runsUnderCommitAmend() {
+    let pid = process.ppid;
+    for (let depth = 0; depth < MAX_ANCESTORS && pid > 1; depth += 1) {
+        const info = processArguments(pid);
+        if (info === null)
+            return false;
+        const [program, ...rest] = info.argv;
+        if (program !== undefined && /^git(\.exe)?$/.test(basename(program)))
+            return rest.includes("commit") && rest.includes("--amend");
+        pid = info.parent;
+    }
+    return false;
+}
+/**
+ * Whether the commit being made replaces a root commit (`git commit --amend`
+ * on a branch with one commit). Such a commit has no parent either, so the
+ * staged gate treats it as a first commit.
+ */
+// implements REQ-kibi-proposition-complete-ingestion
+export function amendsRootCommit(workspaceRoot, headCommit) {
+    if (headCommit === null)
+        return false;
+    try {
+        const parents = execFileSync("git", ["rev-list", "--parents", "-n", "1", headCommit], {
+            cwd: workspaceRoot,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        })
+            .trim()
+            .split(/\s+/);
+        if (parents.length > 1)
+            return false;
+    }
+    catch {
+        return false;
+    }
+    return runsUnderCommitAmend();
+}

package/dist/traceability/staged-inventory-drift.d.ts

@@ -13,12 +13,22 @@ export type StagedInventoryDriftViolation = Readonly<{
  * or in the base tree) whose inventory no longer matches their prose. The
  * next `kibi sync` refuses them under the proposition-complete boundary;
  * the gate applies the same test, so drift is caught at the commit that
- * introduces it instead of after a later merge. Requirements without a
- * contract are left to sync, which decides from its own baseline.
+ * introduces it instead of after a later merge. A requirement the base tree
+ * does not have yet is judged too, as sync judges a source it has never
+ * imported, unless the commit has no parent (a first commit, which sync
+ * imports as its semantic baseline). So is one whose statement (the prose
+ * its inventory covers) differs from the base tree's, as sync judges a
+ * source whose semantic hash changed. Other requirements without a contract,
+ * such as a Context-only edit, are left to sync's baseline.
  */
 export declare function stagedInventoryDriftViolations(input: {
     stagedPaths: ReadonlySet<string>;
     snapshotEntities: readonly ExtractionResult[];
     readBase: (path: string) => string | null;
+    /**
+     * False for a first commit, or an amend of it: sync grandfathers its sources
+     * as a baseline, so only declared contracts are judged.
+     */
+    judgeNewRequirements?: boolean;
 }): StagedInventoryDriftViolation[];
 //# sourceMappingURL=staged-inventory-drift.d.ts.map

package/dist/traceability/staged-inventory-drift.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"staged-inventory-drift.d.ts","sourceRoot":"","sources":["../../src/traceability/staged-inventory-drift.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAKlE,iFAAiF;AAEjF,eAAO,MAAM,2BAA2B,6BAA6B,CAAC;AAGtE,MAAM,MAAM,6BAA6B,GAAG,QAAQ,CAAC;IACnD,IAAI,EAAE,OAAO,2BAA2B,CAAC;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3B,CAAC,CAAC;AAgCH;;;;;;;GAOG;AAEH,wBAAgB,8BAA8B,CAAC,KAAK,EAAE;IACpD,WAAW,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACjC,gBAAgB,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC9C,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;CAC3C,GAAG,6BAA6B,EAAE,CA8BlC"}
+{"version":3,"file":"staged-inventory-drift.d.ts","sourceRoot":"","sources":["../../src/traceability/staged-inventory-drift.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAKlE,iFAAiF;AAEjF,eAAO,MAAM,2BAA2B,6BAA6B,CAAC;AAGtE,MAAM,MAAM,6BAA6B,GAAG,QAAQ,CAAC;IACnD,IAAI,EAAE,OAAO,2BAA2B,CAAC;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3B,CAAC,CAAC;AA0CH;;;;;;;;;;;;GAYG;AAEH,wBAAgB,8BAA8B,CAAC,KAAK,EAAE;IACpD,WAAW,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACjC,gBAAgB,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC9C,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;IAC1C;;;OAGG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC,GAAG,6BAA6B,EAAE,CAsClC"}

package/dist/traceability/staged-inventory-drift.js

@@ -34,6 +34,11 @@ function payloadOf(result) {
         relationships: result.relationships,
     };
 }
+/** The hash of the prose a requirement's inventory must cover. */
+function semanticSourceHashOf(result) {
+    const payload = payloadOf(result);
+    return validateSemanticInventoryBoundary(payload, result.relationships, analyzeSemanticAdvisorInput({ payload }).receipt).sourceHash;
+}
 function baseResult(path, readBase) {
     const content = readBase(path);
     if (content === null)
@@ -50,8 +55,13 @@ function baseResult(path, readBase) {
  * or in the base tree) whose inventory no longer matches their prose. The
  * next `kibi sync` refuses them under the proposition-complete boundary;
  * the gate applies the same test, so drift is caught at the commit that
- * introduces it instead of after a later merge. Requirements without a
- * contract are left to sync, which decides from its own baseline.
+ * introduces it instead of after a later merge. A requirement the base tree
+ * does not have yet is judged too, as sync judges a source it has never
+ * imported, unless the commit has no parent (a first commit, which sync
+ * imports as its semantic baseline). So is one whose statement (the prose
+ * its inventory covers) differs from the base tree's, as sync judges a
+ * source whose semantic hash changed. Other requirements without a contract,
+ * such as a Context-only edit, are left to sync's baseline.
  */
 // implements REQ-kibi-proposition-complete-ingestion
 export function stagedInventoryDriftViolations(input) {
@@ -68,16 +78,23 @@ export function stagedInventoryDriftViolations(input) {
         if (boundary.errors.length === 0)
             continue;
         const base = baseResult(source, input.readBase);
-        const enforce = advertisesContract(result.entity) ||
+        const contract = advertisesContract(result.entity) ||
             (base !== null && advertisesContract(base.entity));
-        if (!enforce)
+        const judgeUncontracted = input.judgeNewRequirements ?? true;
+        const isNew = input.readBase(source) === null && judgeUncontracted;
+        const restated = judgeUncontracted &&
+            base !== null &&
+            semanticSourceHashOf(base) !== boundary.sourceHash;
+        if (!contract && !isNew && !restated)
             continue;
         violations.push({
             rule: STAGED_INVENTORY_DRIFT_RULE,
             entityId: result.entity.id,
             source,
             errors: boundary.errors,
-            message: `${result.entity.id} (${source}): the semantic inventory does not match the requirement's prose, so the next kibi sync rejects it: ${boundary.errors.join("; ")}. Run 'kibi migrate' to re-derive it, or kb_model mode analyze with the complete prose and keep its inventory contract.`,
+            message: contract
+                ? `${result.entity.id} (${source}): the semantic inventory does not match the requirement's prose, so the next kibi sync rejects it: ${boundary.errors.join("; ")}. Run 'kibi migrate' to re-derive it, or kb_model mode analyze with the complete prose and keep its inventory contract.`
+                : `${result.entity.id} (${source}): ${isNew ? "a new requirement" : "a requirement whose statement changes"} needs a semantic inventory that matches its prose, so the next kibi sync rejects it: ${boundary.errors.join("; ")}. Run kb_model mode analyze (CLI: semantic-advisor) with its id and complete semantic_text, then write the returned inventory contract into it (kb_upsert with semantic_inventory, semantic_inventory_version, semantic_source_field, semantic_source_hash and logic_claims).`,
         });
     }
     return violations.sort((left, right) => left.entityId.localeCompare(right.entityId));