kibi-cli 2.5.2 → 2.6.1

package/dist/cli-operation-metadata.d.ts

@@ -71,7 +71,7 @@ export declare const CLI_OPERATION_METADATA: readonly [{
 }, {
     readonly name: "kb_upsert";
     readonly cliName: "upsert";
-    readonly description: "Create or update one entity and optional relationships. Use for KB mutations after validating intent; prefer a dryRun:true call first because it validates without writing and returns semantic advisor receipts for prose-heavy requirements. Use kb_model (mode requirement) before hand-writing strict property facts from prose, and kb_model (mode predicates) before hand-writing ontology predicate facts. Use the `relationships` array for batch creation of multiple links in a single call (e.g., linking a requirement to multiple tests or facts). Prefer modeling requirements as reusable fact links (`constrains`, `requires_property`, or `requires_predicate`) so consistency and contradiction checks remain queryable. Relationship endpoints must already exist in KB. For requirements, the write will be rejected if it contradicts existing current requirements that constrain the same subject with incompatible properties. To replace a conflicting requirement, include a `supersedes` relationship from the new requirement to the old one in the same request, then upsert the old requirement with status closed (kb_check blocks a superseded requirement that is not closed). Successful writes may return non-blocking semantic advisor warnings; inspect and repair those warnings before treating prose as contradiction-checkable. Do not use for read-only inspection. Side effects: writes KB, may refresh symbol coordinates; dryRun:true writes nothing.";
+    readonly description: "Create or update one entity and optional relationships. Use for KB mutations after validating intent; prefer a dryRun:true call first because it validates without writing and returns semantic advisor receipts for prose-heavy requirements. Use kb_model (mode requirement) before hand-writing strict property facts from prose, and kb_model (mode predicates) before hand-writing ontology predicate facts. Use the `relationships` array for batch creation of multiple links in a single call (e.g., linking a requirement to multiple tests or facts). Prefer modeling requirements as reusable fact links (`constrains`, `requires_property`, or `requires_predicate`) so consistency and contradiction checks remain queryable. Relationship endpoints must already exist in KB. For requirements, the write will be rejected if it contradicts existing current requirements that constrain the same subject with incompatible properties. To replace a conflicting requirement, include a `supersedes` relationship from the new requirement to the old one in the same request, then upsert the old requirement with status closed (kb_check blocks a superseded requirement that is not closed). Successful writes may return non-blocking semantic advisor warnings; inspect and repair those warnings before treating prose as contradiction-checkable. Pass a sectioned `document.body` when creating a requirement (the statement, then `## Context` stating why it exists, who asked and the source, then `## Source` with the verbatim excerpt) and a prose body for scenarios, tests, ADRs and observation facts; a result warning reports an entity whose body lacks context, and kb_check blocks it under entity-context-missing. Never invent a reason the requester did not give: write 'Reason not stated'. Do not use for read-only inspection. Side effects: writes KB, may refresh symbol coordinates; dryRun:true writes nothing.";
 }, {
     readonly name: "kb_delete";
     readonly cliName: "delete";

package/dist/cli-operation-metadata.js

@@ -85,7 +85,7 @@ export const CLI_OPERATION_METADATA = [
     {
         name: "kb_upsert",
         cliName: "upsert",
-        description: "Create or update one entity and optional relationships. Use for KB mutations after validating intent; prefer a dryRun:true call first because it validates without writing and returns semantic advisor receipts for prose-heavy requirements. Use kb_model (mode requirement) before hand-writing strict property facts from prose, and kb_model (mode predicates) before hand-writing ontology predicate facts. Use the `relationships` array for batch creation of multiple links in a single call (e.g., linking a requirement to multiple tests or facts). Prefer modeling requirements as reusable fact links (`constrains`, `requires_property`, or `requires_predicate`) so consistency and contradiction checks remain queryable. Relationship endpoints must already exist in KB. For requirements, the write will be rejected if it contradicts existing current requirements that constrain the same subject with incompatible properties. To replace a conflicting requirement, include a `supersedes` relationship from the new requirement to the old one in the same request, then upsert the old requirement with status closed (kb_check blocks a superseded requirement that is not closed). Successful writes may return non-blocking semantic advisor warnings; inspect and repair those warnings before treating prose as contradiction-checkable. Do not use for read-only inspection. Side effects: writes KB, may refresh symbol coordinates; dryRun:true writes nothing.",
+        description: "Create or update one entity and optional relationships. Use for KB mutations after validating intent; prefer a dryRun:true call first because it validates without writing and returns semantic advisor receipts for prose-heavy requirements. Use kb_model (mode requirement) before hand-writing strict property facts from prose, and kb_model (mode predicates) before hand-writing ontology predicate facts. Use the `relationships` array for batch creation of multiple links in a single call (e.g., linking a requirement to multiple tests or facts). Prefer modeling requirements as reusable fact links (`constrains`, `requires_property`, or `requires_predicate`) so consistency and contradiction checks remain queryable. Relationship endpoints must already exist in KB. For requirements, the write will be rejected if it contradicts existing current requirements that constrain the same subject with incompatible properties. To replace a conflicting requirement, include a `supersedes` relationship from the new requirement to the old one in the same request, then upsert the old requirement with status closed (kb_check blocks a superseded requirement that is not closed). Successful writes may return non-blocking semantic advisor warnings; inspect and repair those warnings before treating prose as contradiction-checkable. Pass a sectioned `document.body` when creating a requirement (the statement, then `## Context` stating why it exists, who asked and the source, then `## Source` with the verbatim excerpt) and a prose body for scenarios, tests, ADRs and observation facts; a result warning reports an entity whose body lacks context, and kb_check blocks it under entity-context-missing. Never invent a reason the requester did not give: write 'Reason not stated'. Do not use for read-only inspection. Side effects: writes KB, may refresh symbol coordinates; dryRun:true writes nothing.",
     },
     {
         name: "kb_delete",

package/dist/commands/check.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../../src/commands/check.ts"],"names":[],"mappings":"AAqCA,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAyE7C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAE3D,YAAY,EAAE,SAAS,EAAE,CAAC;AAE1B,MAAM,WAAW,YAAY;IAC3B,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC3B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CAC1B;AA8gBD,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,CAAC,EACtC,MAAM,EAAE,CAAC,GAAG,IAAI,GAAG,SAAS,EAC5B,MAAM,EAAE,CAAC,GAAG,IAAI,GAAG,SAAS,GAC3B,WAAW,CAAC,CAAC,GAAG,CAAC,CAAC,CAMpB;AAGD,wBAAsB,YAAY,CAChC,OAAO,EAAE,YAAY,GACpB,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAymB/B;AAED,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,SAAS,EAAE,CAAC,CAoDtB;AAID,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,MAAM,EAAE,CAAC,CAgBnB;AAED,wBAAsB,eAAe,CACnC,MAAM,EAAE,aAAa,EACrB,IAAI,CAAC,EAAE,MAAM,GACZ,OAAO,CAAC,MAAM,EAAE,CAAC,CAiBnB;AAED,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,SAAS,EAAE,CAAC,CAkEtB;AAID,wBAAsB,aAAa,CACjC,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,SAAS,EAAE,CAAC,CAmGtB;AAED,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,aAAa,EACrB,YAAY,EAAE,MAAM,EAAE,GACrB,OAAO,CAAC,SAAS,EAAE,CAAC,CAyCtB;AAED,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,SAAS,EAAE,CAAC,CAgDtB;AAED,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,SAAS,EAAE,CAAC,CA0BtB;AAED,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,SAAS,EAAE,CAAC,CAqBtB;AAED,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,SAAS,EAAE,CAAC,CAqBtB;AAED,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,SAAS,EAAE,CAAC,CAqBtB;AAED,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,SAAS,EAAE,CAAC,CA+BtB"}
+{"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../../src/commands/check.ts"],"names":[],"mappings":"AAqCA,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AA8E7C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAE3D,YAAY,EAAE,SAAS,EAAE,CAAC;AAE1B,MAAM,WAAW,YAAY;IAC3B,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC3B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CAC1B;AA8gBD,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,CAAC,EACtC,MAAM,EAAE,CAAC,GAAG,IAAI,GAAG,SAAS,EAC5B,MAAM,EAAE,CAAC,GAAG,IAAI,GAAG,SAAS,GAC3B,WAAW,CAAC,CAAC,GAAG,CAAC,CAAC,CAMpB;AAGD,wBAAsB,YAAY,CAChC,OAAO,EAAE,YAAY,GACpB,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CA0nB/B;AAED,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,SAAS,EAAE,CAAC,CAoDtB;AAID,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,MAAM,EAAE,CAAC,CAgBnB;AAED,wBAAsB,eAAe,CACnC,MAAM,EAAE,aAAa,EACrB,IAAI,CAAC,EAAE,MAAM,GACZ,OAAO,CAAC,MAAM,EAAE,CAAC,CAiBnB;AAED,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,SAAS,EAAE,CAAC,CAkEtB;AAID,wBAAsB,aAAa,CACjC,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,SAAS,EAAE,CAAC,CAmGtB;AAED,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,aAAa,EACrB,YAAY,EAAE,MAAM,EAAE,GACrB,OAAO,CAAC,SAAS,EAAE,CAAC,CAyCtB;AAED,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,SAAS,EAAE,CAAC,CAgDtB;AAED,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,SAAS,EAAE,CAAC,CA0BtB;AAED,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,SAAS,EAAE,CAAC,CAqBtB;AAED,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,SAAS,EAAE,CAAC,CAqBtB;AAED,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,SAAS,EAAE,CAAC,CAqBtB;AAED,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,SAAS,EAAE,CAAC,CA+BtB"}

package/dist/commands/check.js

@@ -33,6 +33,7 @@ import { evaluateImpactReview, fingerprintImpactEvaluator, hasValidBaseImpactPol
 import { IMPACT_REVIEW_PATH } from "../traceability/impact-review.js";
 import { validateStagedMarkdown } from "../traceability/markdown-validate.js";
 import { readSnapshotKnowledge } from "../traceability/snapshot-knowledge.js";
+import { collectIntroducedConsistencyViolations, formatConsistencyViolations, stagesKnowledge, } from "../traceability/staged-consistency.js";
 import { collectStagedKibiDiagnostics, } from "../traceability/staged-diagnostics.js";
 import { createStagedEntityIdStyleDiagnostics } from "../traceability/staged-entity-id-style.js";
 import { analyzeStagedFileCoverage, } from "../traceability/staged-file-coverage.js";
@@ -560,6 +561,20 @@ export async function checkCommand(options) {
                     return { exitCode: 1 };
                 }
                 const snapshotEntities = readSnapshotKnowledge(snapshot.readGit, snapshot.headTree, snapshot.readBlobs);
+                // A commit must not introduce a contradiction or an infeasible
+                // scenario that full `kibi check` would report on the same tree.
+                if (stagesKnowledge(stagedInventory.map((file) => file.path))) {
+                    const consistency = await collectIntroducedConsistencyViolations(snapshot, snapshotEntities);
+                    if (consistency.length > 0) {
+                        printSnapshotResult({
+                            format: options.format,
+                            coverage: stagedCoverage,
+                            violations: consistency,
+                            messages: formatConsistencyViolations(consistency),
+                        });
+                        return { exitCode: options.dryRun ? 0 : 1 };
+                    }
+                }
                 const snapshotRequirementIds = new Set(snapshotEntities
                     .filter((row) => row.entity.type === "req")
                     .map((row) => row.entity.id));

package/dist/commands/init-helpers.js

@@ -15,7 +15,7 @@
  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 { chmodSync, constants, copyFileSync, existsSync, lstatSync, mkdirSync, readFileSync, writeFileSync, } from "node:fs";
+import { constants, chmodSync, copyFileSync, existsSync, lstatSync, mkdirSync, readFileSync, writeFileSync, } from "node:fs";
 import * as path from "node:path";
 import fg from "fast-glob";
 import { getBranchDiagnostic, resolveActiveBranch, } from "../utils/branch-resolver.js";

package/dist/commands/migrate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"migrate.d.ts","sourceRoot":"","sources":["../../src/commands/migrate.ts"],"names":[],"mappings":"AAiEA,UAAU,cAAc;IACtB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAC1B,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC7B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,qFAAqF;IACrF,uBAAuB,CAAC,EAAE,OAAO,CAAC;CACnC;AAgKD,wBAAgB,mBAAmB,CACjC,gBAAgB,EAAE,OAAO,EACzB,UAAU,EAAE,MAAM,GAAG,IAAI,GACxB,MAAM,CAUR;AAsXD,wBAAgB,+BAA+B,IAAI;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAKtE;AAGD,wBAAsB,cAAc,CAClC,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAuS/B"}
+{"version":3,"file":"migrate.d.ts","sourceRoot":"","sources":["../../src/commands/migrate.ts"],"names":[],"mappings":"AAiEA,UAAU,cAAc;IACtB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAC1B,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC7B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,qFAAqF;IACrF,uBAAuB,CAAC,EAAE,OAAO,CAAC;CACnC;AAuKD,wBAAgB,mBAAmB,CACjC,gBAAgB,EAAE,OAAO,EACzB,UAAU,EAAE,MAAM,GAAG,IAAI,GACxB,MAAM,CAUR;AAsXD,wBAAgB,+BAA+B,IAAI;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAKtE;AAGD,wBAAsB,cAAc,CAClC,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAiW/B"}

package/dist/commands/migrate.js

@@ -73,6 +73,12 @@ const SCHEMA_MIGRATION_STEPS = [
         to: 7,
         description: "Encode legacy polarity-only property facts as eq boolean true with require/forbid polarity; strict fact shapes are blocking.",
     },
+    {
+        id: "entity-body-context-v8",
+        from: 7,
+        to: 8,
+        description: "Pin semantic_text on requirements that lack it (computed from the body before context sections stop counting), and tag current entities without body context review:context-missing; front matter only, bodies are preserved.",
+    },
 ];
 function migrationStepsFor(fromVersion) {
     const start = Math.max(0, fromVersion ?? 0);
@@ -496,9 +502,23 @@ export async function migrateCommand(options = {}) {
     const originBackfillStep = migrationSteps.some((step) => step.id === "entity-origin-v6");
     const { planPolarityValueBackfill, applyPolarityValueBackfill } = await import("../operations/migration/polarity-values.js");
     const polarityBackfill = planPolarityValueBackfill(cwd);
+    const bodyContextStep = migrationSteps.some((step) => step.id === "entity-body-context-v8");
+    const { acknowledgedContextIds, applyContextMissingTags, applySemanticTextPins, countByType, planContextMissingTags, planSemanticTextPins, } = await import("../operations/migration/entity-body-context.js");
     if (options.dryRun) {
         if (polarityBackfill.length > 0)
             console.log(`dry run: would encode ${polarityBackfill.length} legacy polarity-only fact(s) as typed booleans.`);
+        if (bodyContextStep) {
+            const pins = planSemanticTextPins(cwd);
+            if (pins.targets.length > 0)
+                console.log(`dry run: would pin semantic_text on ${pins.targets.length} requirement(s) that lack it (front matter only; bodies are preserved).`);
+            const tags = planContextMissingTags(cwd);
+            if (tags.targets.length > 0)
+                console.log(`dry run: would tag ${tags.targets.length} current entit(ies) without body context review:context-missing (${Object.entries(countByType(tags.targets))
+                    .map(([type, count]) => `${count} ${type}`)
+                    .join(", ")}); no prose is written.`);
+            for (const skip of [...pins.skipped, ...tags.skipped])
+                printWarning(`Cannot edit ${skip.path}: ${skip.reason}.`);
+        }
         if (storagePlan.moves.length > 0) {
             console.log(`dry run: would move ${storagePlan.moves.length} legacy knowledge file(s) into .kb/:`);
             for (const move of storagePlan.moves) {
@@ -558,6 +578,19 @@ export async function migrateCommand(options = {}) {
     const polarityValuesRewritten = applyPolarityValueBackfill(cwd);
     if (polarityValuesRewritten > 0)
         console.log(`Encoded ${polarityValuesRewritten} legacy polarity-only fact(s) as typed booleans.`);
+    // Pin before tagging: the pin reads the body as the old derivation did, and
+    // tagging then judges context against the statement-only derivation.
+    const semanticTextPinned = bodyContextStep ? applySemanticTextPins(cwd) : 0;
+    if (semanticTextPinned > 0)
+        console.log(`Pinned semantic_text on ${semanticTextPinned} requirement(s) that lacked it.`);
+    const contextPlan = bodyContextStep ? planContextMissingTags(cwd) : null;
+    const contextTagged = bodyContextStep ? applyContextMissingTags(cwd) : 0;
+    if (contextPlan !== null && contextTagged > 0)
+        console.log(`Tagged ${contextTagged} current entit(ies) without body context review:context-missing (${Object.entries(countByType(contextPlan.targets))
+            .map(([type, count]) => `${count} ${type}`)
+            .join(", ")}); no prose was written.`);
+    for (const skip of contextPlan?.skipped ?? [])
+        printWarning(`Cannot tag ${skip.path}: ${skip.reason}.`);
     // Source rewrites run before the manifest records the new schema, so an
     // interrupted run is retried by the next 'kibi migrate --yes'; both are
     // idempotent.
@@ -571,6 +604,16 @@ export async function migrateCommand(options = {}) {
         ...existingManifest,
         schemaVersion: LATEST_KB_SCHEMA_VERSION,
         semanticAdvisorBackfill,
+        ...(contextPlan !== null
+            ? {
+                contextAcknowledged: [
+                    ...new Set([
+                        ...(existingManifest.contextAcknowledged ?? []),
+                        ...acknowledgedContextIds(contextPlan),
+                    ]),
+                ].sort(),
+            }
+            : {}),
     });
     writeJsonAtomically(auditPath, buildMigrationAuditRecord({
         branch,

package/dist/entity-body-context.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Entity Markdown bodies carry human and agent context next to, not inside,
+ * the checked meaning. This module is the one place that knows which body
+ * text is context, so the extractor, the strict check, compile-intent,
+ * bootstrap, the migration and search all agree.
+ */
+/** Heading words whose sections hold context rather than normative text. */
+export declare const CONTEXT_HEADING_WORDS: readonly ["context", "rationale", "why", "background", "source", "notes", "evidence"];
+/** A context section needs at least this many words of prose. */
+export declare const MIN_CONTEXT_WORDS = 12;
+/** Token-set Jaccard at or above this value counts as a restatement. */
+export declare const RESTATEMENT_JACCARD = 0.8;
+/** Tag that marks legacy entities acknowledged as lacking context. */
+export declare const CONTEXT_MISSING_TAG = "review:context-missing";
+/** One body section; the preamble before the first heading has level 0. */
+export type BodySection = Readonly<{
+    level: number;
+    heading: string;
+    /** Prose lines under the heading, up to the next heading. */
+    text: string;
+    isContext: boolean;
+}>;
+/** True when a heading's text starts with a context heading word. */
+export declare function isContextHeading(heading: string): boolean;
+/** Split a Markdown body (front matter removed) into sections by ATX headings. */
+export declare function parseBodySections(body: string): BodySection[];
+/**
+ * The body with every line of its context sections removed (other lines are
+ * untouched), for deriving the checked meaning.
+ */
+export declare function withoutContextSections(body: string): string;
+/** Text of the context sections of a body, headings excluded. */
+export declare function contextSectionText(body: string): string;
+/** The entity fields the context rules read. */
+export type ContextEntity = Readonly<{
+    title?: unknown;
+    semantic_text?: unknown;
+    fact_kind?: unknown;
+}>;
+/** Types whose entities must carry body context. */
+export declare const CONTEXT_REQUIRED_TYPES: readonly ["req", "scenario", "test", "adr", "fact"];
+/**
+ * True when the type needs no body context: symbols, flags and events, and
+ * facts of any fact_kind other than observation or meta (their front matter
+ * is the content).
+ */
+export declare function isContextExempt(type: string, entity: ContextEntity): boolean;
+/**
+ * The body prose that counts as context. Requirements: only text under
+ * context headings. Scenarios, tests, ADRs and observation or meta facts:
+ * all body prose outside headings.
+ */
+export declare function contextProse(type: string, body: string, _entity?: ContextEntity): string;
+/** Normalized token-set Jaccard similarity of two texts (0 when both empty). */
+export declare function tokenSetJaccard(left: string, right: string): number;
+export type ContextAssessment = Readonly<{
+    ok: boolean;
+    /** Why the context does not count; absent when it does. */
+    reason?: "none" | "too_short" | "restatement";
+    words: number;
+}>;
+/**
+ * Judge an entity's body context: at least MIN_CONTEXT_WORDS words of
+ * context prose that do not restate the title (or, for requirements, the
+ * semantic text). Exempt types always pass.
+ */
+export declare function assessContext(type: string, body: string, entity: ContextEntity): ContextAssessment;
+/** True when the entity's body states context that is not a restatement. */
+export declare function hasContext(type: string, body: string, entity: ContextEntity): boolean;
+export type ContextFinding = Readonly<{
+    type: string;
+    id: string;
+    reason: NonNullable<ContextAssessment["reason"]>;
+    words: number;
+    description: string;
+    suggestion: string;
+}>;
+/**
+ * The finding for an entity whose body lacks context, or null when it has
+ * context, is exempt, or is acknowledged by the schema 8 migration
+ * (`acknowledged`, true only for ids the migration recorded in the manifest;
+ * the tag alone never exempts). The strict check and the kb_upsert warning
+ * share it.
+ */
+export declare function contextFinding(type: string, id: string, body: string, entity: ContextEntity, acknowledged?: boolean): ContextFinding | null;
+/** True when the entity's tags acknowledge missing context as legacy. */
+export declare function isContextAcknowledged(tags: unknown): boolean;
+/** What is missing for a type, in the words the check and warnings use. */
+export declare function missingContextDescription(type: string, reason: ContextAssessment["reason"]): string;
+/** Hint shared by the check finding and the kb_upsert warning. */
+export declare const CONTEXT_MISSING_HINT = "Add a '## Context' section (requirements) or a prose body (scenarios, tests, ADRs, observation facts) stating why this exists, who asked, the source and anything that does not fit the front matter. Never invent a reason the requester did not give: write who asked, the source and 'Reason not stated' in the Context section instead.";
+/** Suggestion for a review:context-missing tag the schema 8 migration did not set. */
+export declare const RESERVED_TAG_HINT = "review:context-missing is reserved for entities acknowledged by the schema 8 migration; add context instead: write who asked, the source and 'Reason not stated' in the Context section, and remove the tag.";
+/** Where an entity's statement came from, for the `## Source` section. */
+export type BodySource = Readonly<{
+    /** Verbatim text from the source; rendered as a blockquote. */
+    excerpt?: string | undefined;
+    /** Human title of the source (a ticket, page or document). */
+    title?: string | undefined;
+    /** Locator of the source (URL, ticket id, path). */
+    reference?: string | undefined;
+}>;
+/**
+ * Render a requirement body: the statement, then `## Context` and
+ * `## Source` when given. The statement stays the first, heading-free block
+ * so it remains the derived meaning when no `semantic_text` is pinned.
+ */
+export declare function renderRequirementBody(input: {
+    statement: string;
+    context?: string | undefined;
+    source?: BodySource | undefined;
+}): string;
+/**
+ * Revise a requirement body for a changed statement. The non-context part is
+ * replaced by the new statement; every context section is kept byte for byte,
+ * except that a supplied `context` replaces the `## Context` section and a
+ * supplied source replaces the `## Source` section (each is appended when the
+ * body had none).
+ */
+export declare function reviseRequirementBody(input: {
+    existingBody: string;
+    statement: string;
+    context?: string | undefined;
+    source?: BodySource | undefined;
+}): string;
+/**
+ * The line a search row shows for a body: the first line of the context
+ * prose when the body has any, else the first non-blank body line. With a
+ * statement-only body the first line would repeat the title.
+ */
+export declare function bodySnippetLine(type: string, body: string, entity?: ContextEntity): string | undefined;
+//# sourceMappingURL=entity-body-context.d.ts.map

package/dist/entity-body-context.d.ts.map

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