kibi-mcp 0.12.0 → 0.13.0

package/dist/server/docs.js

@@ -62,7 +62,7 @@ export const PROMPTS = [
             "Call `kb_autopilot_generate` with the gathered context to synthesize candidate entities.",
             "",
             "This tool is **read-only**. It returns additive `structuredContent` with:",
-            "- `promptBlock`: preview text for the user-facing approval prompt",
+            "- `promptBlock`: review text that can be surfaced in optional human-facing briefs",
             "- `recommendedActions`: agent-facing next steps, including any REQ/SCEN/TEST authoring routed for manual handling",
             "- `declaredContext`: the user-provided bootstrap context",
             "- `confidence`: confidence summary for the generated output",
@@ -70,19 +70,19 @@ export const PROMPTS = [
             "- `candidates`: synthesized entities grounded in declared context and source evidence",
             "- `discoverySummary`: source-backed discovery notes",
             "",
-            "## Step 3: Preview and Approval",
+            "## Step 3: Optional Human Review",
             "",
-            "Present the `promptBlock` and a summary of `candidates` to the user. **Wait for explicit approval** before proceeding to writes.",
+            "Surface the `promptBlock` and a summary of `candidates` when optional human review is useful. Human review is post-hoc/optional via VS Code briefs and must not block writes.",
             "",
-            "## Step 4: Apply Approved Candidates",
+            "## Step 4: Apply Candidates",
             "",
-            "Apply approved candidates sequentially using `kb_upsert`.",
-            "1. Execute each approved candidate's `applyPlan` in ascending phase order.",
+            "Apply candidates sequentially using `kb_upsert`.",
+            "1. Execute each candidate's `applyPlan` in ascending phase order.",
             "2. Confirm success of each `kb_upsert` before moving to the next.",
             "3. Run `kb_check` after the batch to verify KB integrity.",
             "",
             "## Rules",
-            "- Never apply changes without a user-facing preview and approval.",
+            "- Human review is optional and post-hoc via VS Code briefs; do not gate writes on synchronous sign-off.",
             "- `kb_autopilot_generate` is strictly read-only; synthesis is the backend, not the actor.",
             "- Guidance must stay MCP-only; do not suggest `kibi` CLI commands.",
         ].join("\n"),
@@ -135,7 +135,10 @@ export const PROMPTS = [
             "Core modeling principles:",
             "- Kibi has eight entity types: common authoring (req, scenario, test, fact) and supporting/system (adr, flag, event, symbol).",
             "- Encode requirements as linked facts: `req --constrains--> fact` plus `req --requires_property--> fact`.",
-            "- Only strict domain facts (`fact_kind: subject` + `property_value`) participate in contradiction inference; observation and meta facts are non-blocking notes.",
+            "- High-confidence modeling (>= 0.7) is fully automated; optional human review can happen post-hoc.",
+            "- Low-confidence claims (< 0.7) are downgraded to `observation` facts to prevent false-positive contradictions.",
+            "- Only strict domain facts participate in contradiction inference; observation and meta facts are non-blocking notes.",
+            "- v1 contradictions are limited to exact-value, boolean/enum, numeric range, and polarity conflicts.",
             "- Use `kb_search` first for discovery, then `kb_query` for exact follow-up before any mutation.",
             "- Use `kb_upsert` and `kb_delete` only for intentional, traceable KB changes.",
             "- Run `kb_check` after meaningful mutations to catch integrity issues early.",
@@ -152,9 +155,10 @@ export const PROMPTS = [
             "Follow this sequence for reliable operation:",
             "",
             "1. **Discover first**: Call `kb_search` for exploratory discovery, then `kb_query` to confirm exact current state before mutation.",
-            "2. **Create-before-link**: Create endpoint entities with `kb_upsert` before linking them.",
-            "3. **Validate intent**: If creating links, call `kb_query` for both endpoint IDs first to ensure they exist.",
-            "4. **Model requirements as facts**: For new/updated reqs, create/reuse fact entities first, then express req semantics with `constrains` + `requires_property`.",
+            "2. **Check schema status**: Call `kb_status` to see if a schema migration is required for the branch KB.",
+            "3. **Create-before-link**: Create endpoint entities with `kb_upsert` before linking them.",
+            "4. **Validate intent**: If creating links, call `kb_query` for both endpoint IDs first to ensure they exist.",
+            "5. **Model requirements as facts**: For new/updated reqs, create/reuse fact entities first, then express req semantics with `constrains` + `requires_property` (automated via `kb_model_requirement`).",
             "5. **Mutate**: Call `kb_upsert` for create/update, or `kb_delete` for explicit removals.",
             "6. **Targeted checks**: Run `kb_check` after meaningful mutations; specify only the rules you need.",
             "",

package/dist/server/tools.js

@@ -11,6 +11,7 @@ import { handleKbQuery } from "../tools/query.js";
 import { handleKbSearch } from "../tools/search.js";
 import { handleKbStatus } from "../tools/status.js";
 import { handleKbUpsert } from "../tools/upsert.js";
+import { handleKbModelRequirement, } from "../tools/model-requirement.js";
 import { handleKbAutopilotGenerate, } from "../tools/autopilot-generate.js";
 import { handleKbBriefingGenerate, } from "../tools/briefing-generate.js";
 const defaultToolsServerDeps = {
@@ -59,6 +60,7 @@ const DEFAULT_TOOLS_RUNTIME = {
     handleKbSearch,
     handleKbStatus,
     handleKbUpsert,
+    handleKbModelRequirement,
     handleKbAutopilotGenerate,
     handleKbBriefingGenerate,
 };
@@ -321,6 +323,10 @@ runtime = DEFAULT_TOOLS_RUNTIME) {
         const prolog = await runtime.ensureProlog();
         return runtime.handleKbCheck(prolog, args);
     }, runtime);
+    addTool(server, "kb_model_requirement", toolDef("kb_model_requirement").description, toolDef("kb_model_requirement").inputSchema, async (args) => {
+        const prolog = await runtime.ensureProlog();
+        return runtime.handleKbModelRequirement(prolog, args);
+    }, runtime);
     addTool(server, "kb_autopilot_generate", toolDef("kb_autopilot_generate").description, toolDef("kb_autopilot_generate").inputSchema, async (args) => {
         const prolog = await runtime.ensureProlog();
         return runtime.handleKbAutopilotGenerate(prolog, args);

package/dist/tools/autopilot-candidates.js

@@ -2,8 +2,11 @@
 // Implements candidate assembly from public CLI extractors
 import { extractFromManifest } from "kibi-cli/extractors/manifest";
 import { extractFromMarkdown } from "kibi-cli/extractors/markdown";
+import { buildStrictWriteSet, modelRequirementClaims, } from "kibi-cli/public/check-types";
 import path from "node:path";
 import fs from "node:fs";
+import { createRepoIgnorePolicy } from "kibi-cli/ignore-policy";
+import { estimateNormativeSignalConfidence, extractRequirementClaim, strictWriteSetToApplyPlan, writeSetPrimaryEntityId, } from "./model-requirement.js";
 function slugify(value, maxLength = 80) {
     return value
         .toLowerCase()
@@ -63,10 +66,8 @@ function resolveCandidatePaths(filePath, workspaceRoot) {
         .join("/");
     return { absolutePath, relativePath };
 }
-function isIgnoredGenericMarkdownPath(relativePath) {
-    const normalized = relativePath.replace(/\\/g, "/").replace(/^\.\//, "");
-    return /(^|\/)(documentation|\.kb|\.git|node_modules|vendor|vendors|third_party|third-party|dist|coverage)(\/|$)/.test(normalized);
-}
+// Legacy helper removed in favor of the shared ignore policy from kibi-cli/ignore-policy.
+// Use createRepoIgnorePolicy(workspaceRoot).isIgnored(relativePath) in builders.
 function shouldIncludeGenericMarkdown(relativePath, providerScopedMarkdown) {
     const base = path.basename(relativePath).toLowerCase();
     const inDocsDir = /(^|\/)docs\//.test(relativePath);
@@ -103,6 +104,7 @@ function buildUpsertFromExtraction(er, typeOverride) {
 export function buildTypedMarkdownCandidates(discoveryResult, existingEntities) {
     const candidates = [];
     const workspaceRoot = existingEntities.workspaceRoot ?? process.cwd();
+    const ignorePolicy = createRepoIgnorePolicy(workspaceRoot);
     for (const filePath of getTypedMarkdownFiles(discoveryResult)) {
         try {
             const extraction = extractFromMarkdown(filePath);
@@ -110,6 +112,8 @@ export function buildTypedMarkdownCandidates(discoveryResult, existingEntities)
             if (existingEntities.ids.has(entity.id))
                 continue;
             const { absolutePath, relativePath } = resolveCandidatePaths(filePath, workspaceRoot);
+            if (ignorePolicy.isIgnored(relativePath))
+                continue;
             const candidateId = `md:${relativePath}:${entity.id}`;
             const upsert = buildUpsertFromExtraction({ entity, relationships });
             candidates.push({
@@ -186,13 +190,14 @@ export function buildSymbolManifestCandidates(discoveryResult, existingEntities)
 export function buildGenericMarkdownCandidates(discoveryResult, existingEntities, minConfidence = 0.8) {
     const candidates = [];
     const workspaceRoot = existingEntities.workspaceRoot ?? process.cwd();
+    const ignorePolicy = createRepoIgnorePolicy(workspaceRoot);
     const providerScopedMarkdown = hasGenericMarkdownEvidence(discoveryResult);
     const files = getGenericMarkdownFiles(discoveryResult);
     for (const rawPath of files) {
         try {
             const filePath = String(rawPath);
             const { absolutePath, relativePath } = resolveCandidatePaths(filePath, workspaceRoot);
-            if (isIgnoredGenericMarkdownPath(relativePath))
+            if (ignorePolicy.isIgnored(relativePath))
                 continue;
             // Legacy path-only discovery was conservative. Provider-scoped discovery
             // already filters eligible generic docs, so allow broader repo markdown there.
@@ -287,12 +292,13 @@ export function collectSourceOnlyAuthoringSignals(discoveryResult, existingEntit
     const signals = [];
     const seen = new Set();
     const workspaceRoot = existingEntities.workspaceRoot ?? process.cwd();
+    const ignorePolicy = createRepoIgnorePolicy(workspaceRoot);
     const providerScopedMarkdown = hasGenericMarkdownEvidence(discoveryResult);
     for (const rawPath of getGenericMarkdownFiles(discoveryResult)) {
         try {
             const filePath = String(rawPath);
             const { absolutePath, relativePath } = resolveCandidatePaths(filePath, workspaceRoot);
-            if (isIgnoredGenericMarkdownPath(relativePath))
+            if (ignorePolicy.isIgnored(relativePath))
                 continue;
             if (!shouldIncludeGenericMarkdown(relativePath, providerScopedMarkdown))
                 continue;
@@ -370,6 +376,113 @@ export function collectSourceOnlyAuthoringSignals(discoveryResult, existingEntit
     });
 }
 // implements REQ-mcp-init-kibi-autopilot-v1
+export function buildNormativeRequirementCandidates(discoveryResult, existingEntities, minConfidence = 0.8) {
+    const candidates = [];
+    const seeds = [];
+    const workspaceRoot = existingEntities.workspaceRoot ?? process.cwd();
+    const providerScopedMarkdown = hasGenericMarkdownEvidence(discoveryResult);
+    const ignorePolicy = createRepoIgnorePolicy(workspaceRoot);
+    for (const rawPath of getGenericMarkdownFiles(discoveryResult)) {
+        try {
+            const filePath = String(rawPath);
+            const { absolutePath, relativePath } = resolveCandidatePaths(filePath, workspaceRoot);
+            if (ignorePolicy.isIgnored(relativePath))
+                continue;
+            if (!shouldIncludeGenericMarkdown(relativePath, providerScopedMarkdown))
+                continue;
+            if (!fs.existsSync(absolutePath))
+                continue;
+            const content = fs.readFileSync(absolutePath, "utf8");
+            const lines = content.split(/\r?\n/);
+            let activeHeading;
+            let activeHeadingLine;
+            let inCodeFence = false;
+            for (let i = 0; i < lines.length; i++) {
+                const line = lines[i];
+                if (line === undefined)
+                    continue;
+                if (/^\s*(```|~~~)/.test(line)) {
+                    inCodeFence = !inCodeFence;
+                    continue;
+                }
+                if (inCodeFence)
+                    continue;
+                const headingMatch = line.match(/^\s*#+\s*(.+)$/);
+                if (headingMatch?.[1]) {
+                    activeHeading = headingMatch[1].trim();
+                    activeHeadingLine = i + 1;
+                    continue;
+                }
+                const statement = line
+                    .replace(/^\s*[-*+]\s+/, "")
+                    .replace(/^\s*\d+[.)]\s+/, "")
+                    .trim();
+                if (!statement || !/\b(must|shall|should)\b/i.test(statement))
+                    continue;
+                const confidence = estimateNormativeSignalConfidence(statement, activeHeading);
+                if (confidence < minConfidence)
+                    continue;
+                const extracted = extractRequirementClaim({
+                    text: statement,
+                    source: relativePath,
+                    confidence,
+                    provenance: `${relativePath}#L${i + 1}`,
+                });
+                const writeSet = buildStrictWriteSet({
+                    claim: extracted.claim,
+                    statement: extracted.statement,
+                });
+                if (!writeSet.isStrict)
+                    continue;
+                seeds.push({
+                    input: {
+                        claim: extracted.claim,
+                        statement: extracted.statement,
+                    },
+                    writeSet,
+                    sourcePath: absolutePath,
+                    evidence: [
+                        `normative_statement:${relativePath}#L${i + 1}`,
+                        ...(activeHeading && activeHeadingLine
+                            ? [`generic_heading:${relativePath}#L${activeHeadingLine}`]
+                            : []),
+                    ],
+                });
+            }
+        }
+        catch {
+            // ignore unreadable files when deriving strict requirement candidates
+        }
+    }
+    const modeledIds = new Set(modelRequirementClaims(seeds.map((seed) => seed.input)).map((writeSet) => writeSetPrimaryEntityId(writeSet)));
+    const emittedIds = new Set();
+    for (const seed of seeds) {
+        const entityId = writeSetPrimaryEntityId(seed.writeSet);
+        if (!modeledIds.has(entityId) || emittedIds.has(entityId))
+            continue;
+        if (existingEntities.ids.has(entityId))
+            continue;
+        emittedIds.add(entityId);
+        candidates.push({
+            candidateId: `norm:${entityId.toLowerCase()}`,
+            entityType: "req",
+            title: seed.input.statement,
+            sourceKind: "generic_markdown",
+            sourcePath: seed.sourcePath,
+            confidence: seed.writeSet.confidence,
+            confidenceBand: toConfidenceBand(seed.writeSet.confidence),
+            evidence: seed.evidence,
+            relationships: seed.writeSet.relationships.map((relationship) => ({
+                type: relationship.type,
+                from: relationship.from,
+                to: relationship.to,
+            })),
+            applyPlan: strictWriteSetToApplyPlan(seed.writeSet),
+        });
+    }
+    return candidates;
+}
+// implements REQ-mcp-init-kibi-autopilot-v1
 export function buildProviderEvidenceCandidates(discoveryResult, existingEntities, minConfidence = 0.8) {
     const candidates = [];
     const workspaceRoot = existingEntities.workspaceRoot ?? process.cwd();
@@ -431,5 +544,6 @@ export default {
     buildSymbolManifestCandidates,
     buildGenericMarkdownCandidates,
     collectSourceOnlyAuthoringSignals,
+    buildNormativeRequirementCandidates,
     buildProviderEvidenceCandidates,
 };

package/dist/tools/autopilot-discovery.js

@@ -7,6 +7,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import fg from "fast-glob";
+import { createRepoIgnorePolicy } from "kibi-cli/ignore-policy";
 import * as cliSymbolCoordinator from "kibi-cli/extractors/symbols-coordinator";
 import { runJsonModuleQuery } from "./core-module.js";
 // implements REQ-001
@@ -211,7 +212,7 @@ function normalizeDiscoveryPaths(cwd) {
         symbols: readPath("symbols"),
     };
 }
-function buildIgnoredGlobs(vendoredRoots) {
+function buildIgnoredGlobs(vendoredRoots, workspaceRoot) {
     const ignored = new Set();
     for (const dirName of IGNORED_DIRECTORY_NAMES) {
         ignored.add(`**/${dirName}`);
@@ -226,6 +227,18 @@ function buildIgnoredGlobs(vendoredRoots) {
         ignored.add(`**/${normalized}`);
         ignored.add(`**/${normalized}/**`);
     }
+    // Use shared ignore policy to include .gitignore, nested ignores, and other rules.
+    try {
+        const policy = createRepoIgnorePolicy(workspaceRoot);
+        const globs = policy.getFastGlobIgnoreGlobs();
+        for (const glob of globs) {
+            if (glob)
+                ignored.add(glob);
+        }
+    }
+    catch {
+        // best-effort only
+    }
     return Array.from(ignored);
 }
 function detectLanguagesFromPaths(paths) {
@@ -266,6 +279,7 @@ function runTypedKibiDocsProvider(workspaceRoot) {
         onlyFiles: true,
         unique: true,
         suppressErrors: true,
+        ignore: buildIgnoredGlobs([], workspaceRoot),
     });
     const manifestFiles = discoveryPaths.symbols
         ? fg.sync(discoveryPaths.symbols, {
@@ -274,6 +288,7 @@ function runTypedKibiDocsProvider(workspaceRoot) {
             onlyFiles: true,
             unique: true,
             suppressErrors: true,
+            ignore: buildIgnoredGlobs([], workspaceRoot),
         })
         : [];
     const evidence = [
@@ -292,7 +307,7 @@ function runGenericRepoDocsProvider(workspaceRoot, vendoredRoots, typedFilePaths
         onlyFiles: true,
         unique: true,
         suppressErrors: true,
-        ignore: buildIgnoredGlobs(vendoredRoots),
+        ignore: buildIgnoredGlobs(vendoredRoots, workspaceRoot),
     });
     const evidence = sortUnique(markdownFiles)
         .map((absolutePath) => createFileEvidence("generic_repo_docs", "generic_markdown", workspaceRoot, absolutePath))
@@ -435,7 +450,7 @@ function runRepoLayoutProvider(workspaceRoot, vendoredRoots) {
         onlyFiles: true,
         unique: true,
         suppressErrors: true,
-        ignore: buildIgnoredGlobs(vendoredRoots),
+        ignore: buildIgnoredGlobs(vendoredRoots, workspaceRoot),
     });
     return {
         provider: "repo_layout",
@@ -468,7 +483,7 @@ function runTestTopologyProvider(workspaceRoot, vendoredRoots) {
         onlyFiles: true,
         unique: true,
         suppressErrors: true,
-        ignore: buildIgnoredGlobs(vendoredRoots),
+        ignore: buildIgnoredGlobs(vendoredRoots, workspaceRoot),
     });
     const detectedFrameworks = new Set();
     const detectedLanguages = new Set();
@@ -525,7 +540,7 @@ function runSourceSymbolsProvider(workspaceRoot, vendoredRoots) {
         onlyFiles: true,
         unique: true,
         suppressErrors: true,
-        ignore: buildIgnoredGlobs(vendoredRoots),
+        ignore: buildIgnoredGlobs(vendoredRoots, workspaceRoot),
     });
     const evidence = [];
     const detectedLanguages = new Set();

package/dist/tools/autopilot-generate.js

@@ -1,5 +1,8 @@
 import path from "node:path";
-import { collectSourceOnlyAuthoringSignals, buildGenericMarkdownCandidates, buildProviderEvidenceCandidates, buildTypedMarkdownCandidates, buildSymbolManifestCandidates, } from "./autopilot-candidates.js";
+import fg from "fast-glob";
+import { createRepoIgnorePolicy } from "kibi-cli/ignore-policy";
+import { buildNormativeRequirementCandidates, collectSourceOnlyAuthoringSignals, buildGenericMarkdownCandidates, buildProviderEvidenceCandidates, buildTypedMarkdownCandidates, buildSymbolManifestCandidates, } from "./autopilot-candidates.js";
+import { getWorkspaceMigrationWarning } from "./model-requirement.js";
 import { discoverProviderEvidence, resolveActivationPolicy, } from "./autopilot-discovery.js";
 import { loadEntities } from "./entity-query.js";
 import { resolveWorkspaceRoot } from "../workspace.js";
@@ -373,6 +376,7 @@ _prolog, args) {
     const activation = await resolveActivationPolicy(workspaceRoot, prolog);
     const activationState = activation.activationState;
     const activationDiscovery = discoverProviderEvidence(workspaceRoot, activation);
+    const migrationWarning = await getWorkspaceMigrationWarning(workspaceRoot);
     const declaredContext = normalizeBootstrapContext(bootstrapContext);
     const discoveredCandidatePaths = activationDiscovery.evidence.reduce((acc, item) => {
         const relativePath = item.relativePath;
@@ -405,6 +409,7 @@ _prolog, args) {
     let typedMarkdownCandidates = [];
     let manifestCandidates = [];
     let genericCandidates = [];
+    let normativeRequirementCandidates = [];
     let providerEvidenceCandidates = [];
     let allCandidates = [];
     const seenByKey = new Map();
@@ -427,6 +432,10 @@ _prolog, args) {
                 ids: existingIds,
                 workspaceRoot,
             }, normalizedMinConfidence);
+            normativeRequirementCandidates = buildNormativeRequirementCandidates(candidateDiscovery, {
+                ids: existingIds,
+                workspaceRoot,
+            }, normalizedMinConfidence);
         }
         providerEvidenceCandidates = buildProviderEvidenceCandidates(candidateDiscovery, {
             ids: existingIds,
@@ -436,6 +445,7 @@ _prolog, args) {
             ...typedMarkdownCandidates,
             ...manifestCandidates,
             ...genericCandidates,
+            ...normativeRequirementCandidates,
             ...providerEvidenceCandidates,
         ];
         if (entityTypes && entityTypes.length > 0) {
@@ -516,6 +526,40 @@ _prolog, args) {
             seenByKey.set(titleKey, record);
         }
     }
+    // Detect repository files that would be candidate inputs but are ignored by
+    // the repo ignore policy (e.g. .sisyphus drafts, .gitignore entries). Add
+    // them to suppressedCandidates with reason `ignored_source` so callers see
+    // why those files were omitted from candidate output.
+    try {
+        const repoIgnore = createRepoIgnorePolicy(workspaceRoot);
+        const potentialFiles = fg.sync(["**/*.md", "**/symbols.{yml,yaml}"], {
+            cwd: workspaceRoot,
+            absolute: true,
+            onlyFiles: true,
+            unique: true,
+            dot: true,
+            suppressErrors: true,
+        });
+        for (const absPath of potentialFiles) {
+            const rel = toWorkspaceRelativePath(workspaceRoot, absPath);
+            const explain = repoIgnore.explain(rel);
+            if (explain.ignored) {
+                // avoid duplicating existing suppressed entries for the same source
+                if (!suppressed.some((s) => String(s.sourcePath ?? "") === rel && s.reason === "ignored_source")) {
+                    suppressed.push({
+                        candidateId: String("") /* no candidate id for ignored source */,
+                        reason: "ignored_source",
+                        sourcePath: rel,
+                        entityType: String("") /* unknown at this stage */,
+                        detail: explain.reason,
+                    });
+                }
+            }
+        }
+    }
+    catch {
+        // best-effort only; ignore failures here so generation can continue
+    }
     const candidateRecords = Array.from(seenByKey.values());
     const payoffSummary = buildPayoffSummary(candidateRecords);
     const promptBlock = buildPromptBlock(workspaceRoot, activationState, activation.activationMode, activation.reason, activation.applyBlocked, declaredContext, candidateRecords, sourceOnlySignals, activationDiscovery.summary.scanWarnings);
@@ -533,6 +577,7 @@ _prolog, args) {
         bootstrapMode: activation.activationMode,
         activationReason: activation.reason,
         applyBlocked: effectiveApplyBlocked,
+        migrationWarning,
         ...(activation.handoffMessage
             ? { handoffMessage: activation.handoffMessage }
             : {}),
@@ -554,6 +599,7 @@ _prolog, args) {
             },
         ],
         structuredContent,
+        migrationWarning,
         candidates: candidateRecords,
         suppressedCandidates: suppressed,
         payoffSummary,

package/dist/tools/briefing-generate.js

@@ -7,6 +7,8 @@ import { loadEntities } from "./entity-query.js";
 import { handleKbStatus } from "./status.js";
 import { resolveWorkspaceRoot } from "../workspace.js";
 import { isOperationalArtifactPath } from "kibi-cli/operational-artifacts";
+import { createRepoIgnorePolicy } from "kibi-cli/ignore-policy";
+import { getSchemaVersionStatus } from "kibi-cli/schema-version";
 const ALLOWED_TYPES = [
     "req",
     "adr",
@@ -107,6 +109,7 @@ function normalizeSourceFiles(workspaceRoot, sourceFiles) {
     const normalized = [];
     const seen = new Set();
     const normalizedRoot = path.resolve(workspaceRoot);
+    const policy = createRepoIgnorePolicy(workspaceRoot);
     for (const sourceFile of sourceFiles ?? []) {
         const trimmed = String(sourceFile ?? "").trim();
         if (!trimmed)
@@ -125,6 +128,16 @@ function normalizeSourceFiles(workspaceRoot, sourceFiles) {
             .replace(/^\//, "");
         if (!normalizedPath || seen.has(normalizedPath) || isOperationalArtifactPath(normalizedPath))
             continue;
+        // Skip paths ignored by repository ignore policy (eg .gitignore, .git/info/exclude, nested .gitignore,
+        // and hard denylist such as .kb, .git, node_modules, .sisyphus)
+        try {
+            if (policy.isIgnored(normalizedPath))
+                continue;
+        }
+        catch {
+            // Be conservative on errors and do not let ignore policy break briefing generation;
+            // fall through and allow the path unless other checks exclude it.
+        }
         seen.add(normalizedPath);
         normalized.push(normalizedPath);
     }
@@ -141,13 +154,25 @@ function stripOuterSingleQuotes(value) {
 function candidateKey(entity) {
     return `${String(entity.type ?? "")}::${String(entity.id ?? "")}`;
 }
-function normalizeEntity(entity) {
+function normalizeEntity(entity, workspaceRoot) {
     const type = stripOuterSingleQuotes(String(entity.type ?? "").trim());
     if (!isAllowedType(type))
         return null;
     const source = entity.source ? String(entity.source).trim().split(path.sep).join("/") : undefined;
     if (source && isOperationalArtifactPath(source))
         return null;
+    // Respect repository ignore policy for entity sources. Prefer an explicit workspaceRoot when available.
+    try {
+        if (source) {
+            const policyRoot = workspaceRoot ?? process.cwd();
+            const policy = createRepoIgnorePolicy(policyRoot);
+            if (policy.isIgnored(source))
+                return null;
+        }
+    }
+    catch {
+        // Ignore errors from ignore policy to avoid blocking normalization on policy issues.
+    }
     return {
         ...entity,
         id: String(entity.id ?? "").trim(),
@@ -162,8 +187,8 @@ function normalizeEntity(entity) {
                 : undefined,
     };
 }
-function addCandidate(candidates, entity, scoreDelta, reason) {
-    const normalizedEntity = normalizeEntity(entity);
+function addCandidate(candidates, entity, scoreDelta, reason, workspaceRoot) {
+    const normalizedEntity = normalizeEntity(entity, workspaceRoot);
     if (!normalizedEntity)
         return;
     const key = candidateKey(normalizedEntity);
@@ -328,7 +353,7 @@ function buildPromptBlock(entities) {
     }
     const bullets = allBullets.slice(0, 5);
     let promptBlock = bullets.join("\n");
-    let words = promptBlock.split(/\s+/).filter(Boolean);
+    const words = promptBlock.split(/\s+/).filter(Boolean);
     if (words.length > 120) {
         // Hard-truncate to 120 words, preserving whole bullets where possible
         const truncated = [];
@@ -339,7 +364,7 @@ function buildPromptBlock(entities) {
                 // Take a partial bullet that fits within budget
                 const remaining = 120 - wordCount;
                 if (remaining > 3) {
-                    truncated.push(bulletWords.slice(0, remaining).join(" ") + "\u2026");
+                    truncated.push(`${bulletWords.slice(0, remaining).join(" ")}\u2026`);
                 }
                 break;
             }
@@ -367,6 +392,46 @@ function buildCitations(entities) {
         ...(entity.textRef ? { textRef: entity.textRef } : {}),
     }));
 }
+function buildAutomationReviewEntities(entities, confidenceScore) {
+    const entityConfidence = typeof confidenceScore === "number" && Number.isFinite(confidenceScore)
+        ? roundScore(confidenceScore)
+        : 1;
+    return entities.map((entity) => ({
+        id: entity.id,
+        type: entity.type,
+        title: entity.title,
+        confidence: entityConfidence,
+    }));
+}
+function buildAutomationReview(entities, confidence, migrationWarning, prologNeighbors) {
+    if (entities.length === 0) {
+        return null;
+    }
+    const generatedEntities = buildAutomationReviewEntities(entities, confidence.score);
+    const evidenceCitationIds = entities.map((entity) => entity.id);
+    const strictEntities = entities.filter((entity) => entity.type === "req" || entity.type === "fact");
+    const strictReadinessScore = roundScore(strictEntities.length > 0
+        ? Math.min(1, strictEntities.length / entities.length + 0.5)
+        : 0);
+    const contradictionRisks = [];
+    for (const entity of strictEntities) {
+        if (entity.type === "req" && prologNeighbors.has(entity.id)) {
+            contradictionRisks.push(`${entity.id} may have contradiction overlap with related requirements.`);
+        }
+    }
+    const migrationWarnings = [];
+    if (migrationWarning) {
+        migrationWarnings.push(migrationWarning);
+    }
+    return {
+        generatedEntities,
+        strictReadinessScore,
+        confidence: confidence.score,
+        migrationWarnings,
+        contradictionRisks,
+        evidenceCitationIds,
+    };
+}
 function roundScore(score) {
     return Math.max(0, Math.min(1, Math.round(score * 100) / 100));
 }
@@ -408,7 +473,7 @@ function buildConfidence(activationState, freshness, entities, missingEvidence,
         reasons,
     };
 }
-async function expandGraphNeighbors(prolog, seedIds) {
+async function expandGraphNeighbors(prolog, seedIds, workspaceRoot) {
     if (seedIds.length === 0) {
         return new Map();
     }
@@ -425,7 +490,7 @@ async function expandGraphNeighbors(prolog, seedIds) {
     }
     const neighbors = new Map();
     for (const node of payload.nodes ?? []) {
-        const normalized = normalizeEntity(node);
+        const normalized = normalizeEntity(node, workspaceRoot);
         if (!normalized)
             continue;
         const nodeId = String(normalized.id ?? "");
@@ -487,15 +552,16 @@ prolog, args) {
                 regressionRisks: [],
                 missingEvidence: [],
                 citations: [],
+                automationReview: null,
             },
         };
     }
     const candidates = new Map();
     for (const entity of await loadByIds(prolog, seedIds)) {
-        addCandidate(candidates, entity, 100, "seed hit");
+        addCandidate(candidates, entity, 100, "seed hit", workspaceRoot);
     }
     for (const entity of await loadBySourceFiles(prolog, sourceFiles)) {
-        addCandidate(candidates, entity, 90, "source-file hit");
+        addCandidate(candidates, entity, 90, "source-file hit", workspaceRoot);
     }
     const rankedIds = [];
     if (taskText) {
@@ -503,7 +569,7 @@ prolog, args) {
         const matches = await rankEntities(allEntities, taskText, workspaceRoot);
         matches.forEach((match, index) => {
             rankedIds.push(String(match.entity.id ?? ""));
-            addCandidate(candidates, match.entity, 70 - index, `text-search hit (#${index + 1})`);
+            addCandidate(candidates, match.entity, 70 - index, `text-search hit (#${index + 1})`, workspaceRoot);
         });
     }
     const graphSeeds = Array.from(new Set([
@@ -512,9 +578,9 @@ prolog, args) {
         ...Array.from(candidates.values()).map((candidate) => String(candidate.entity.id ?? "")),
         ...rankedIds,
     ].filter(Boolean)));
-    const graphNeighbors = await expandGraphNeighbors(prolog, graphSeeds);
+    const graphNeighbors = await expandGraphNeighbors(prolog, graphSeeds, workspaceRoot);
     for (const neighbor of graphNeighbors.values()) {
-        addCandidate(candidates, neighbor, 40, "graph neighbor");
+        addCandidate(candidates, neighbor, 40, "graph neighbor", workspaceRoot);
     }
     const entities = sortedEntities(candidates);
     const constraints = buildConstraints(entities);
@@ -524,6 +590,26 @@ prolog, args) {
     const citations = buildCitations(entities);
     const confidence = buildConfidence(activationState, freshness, entities, missingEvidence, promptBlock);
     const briefingState = confidence.score >= 0.55 ? "ready" : "no_briefing";
+    // Compute automation review metadata
+    let migrationWarning = null;
+    try {
+        const configPath = path.join(workspaceRoot, ".kb", "config.json");
+        let rawConfig;
+        try {
+            rawConfig = fs.readFileSync(configPath, "utf8");
+            const parsed = JSON.parse(rawConfig);
+            const schemaStatus = getSchemaVersionStatus(parsed ?? undefined);
+            migrationWarning = schemaStatus.warning;
+        }
+        catch {
+            migrationWarning = null;
+        }
+    }
+    catch {
+        migrationWarning = null;
+    }
+    const graphNeighborIds = new Set(graphNeighbors.keys());
+    const automationReview = buildAutomationReview(entities, confidence, migrationWarning, graphNeighborIds);
     if (briefingState === "no_briefing") {
         return {
             content: [{ type: "text", text: "No briefing is available." }],
@@ -540,6 +626,7 @@ prolog, args) {
                 regressionRisks: [],
                 missingEvidence: [],
                 citations: [],
+                automationReview: null,
             },
         };
     }
@@ -558,6 +645,7 @@ prolog, args) {
             regressionRisks,
             missingEvidence,
             citations,
+            automationReview,
         },
     };
 }

package/dist/tools/model-requirement.js

@@ -0,0 +1,334 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { buildStrictWriteSet, } from "kibi-cli/public/check-types";
+import { getSchemaVersionStatus } from "kibi-cli/schema-version";
+import { resolveWorkspaceRoot } from "../workspace.js";
+const STRICT_FALLBACK_CONFIDENCE = 0.69;
+const NORMATIVE_SECTION_PATTERN = /\b(requirements?|polic(?:y|ies)|rules?)\b/i;
+function normalizeText(text) {
+    const normalized = String(text ?? "").trim();
+    if (!normalized) {
+        throw new Error("Requirement modeling failed: text must be a non-empty string");
+    }
+    return normalized;
+}
+function normalizeOptionalString(value) {
+    const normalized = String(value ?? "").trim();
+    return normalized.length > 0 ? normalized : undefined;
+}
+function normalizeSourceFiles(sourceFiles) {
+    const seen = new Set();
+    const normalized = [];
+    for (const sourceFile of sourceFiles ?? []) {
+        const trimmed = String(sourceFile ?? "").trim();
+        if (!trimmed || seen.has(trimmed))
+            continue;
+        seen.add(trimmed);
+        normalized.push(trimmed);
+    }
+    return normalized;
+}
+function clampConfidence(confidence) {
+    const numeric = typeof confidence === "number" && Number.isFinite(confidence) ? confidence : 0.8;
+    return Math.round(Math.min(1, Math.max(0, numeric)) * 100) / 100;
+}
+function normalizeClaimValue(value) {
+    if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+        if (typeof value === "number" && !Number.isFinite(value)) {
+            throw new Error("Requirement modeling failed: value must be a finite number");
+        }
+        return value;
+    }
+    throw new Error("Requirement modeling failed: value must be a string, number, or boolean");
+}
+function stripListPrefix(value) {
+    return value
+        .replace(/^\s*[-*+]\s+/, "")
+        .replace(/^\s*\d+[.)]\s+/, "")
+        .trim();
+}
+function trimSentenceTail(value) {
+    return value.replace(/[\s.?!:;]+$/g, "").trim();
+}
+function cleanSubject(value) {
+    const cleaned = trimSentenceTail(stripListPrefix(value));
+    return cleaned.replace(/^(?:the|a|an)\s+/i, "").trim() || cleaned;
+}
+function cleanPredicate(value) {
+    return trimSentenceTail(stripListPrefix(value)) || "statement";
+}
+function fallbackSubjectFromSource(source) {
+    const basename = path.basename(source, path.extname(source)).replace(/[-_]+/g, " ").trim();
+    return basename || "Requirement";
+}
+function hasExplicitClaimFields(args) {
+    return (args.subjectKey !== undefined ||
+        args.propertyKey !== undefined ||
+        args.operator !== undefined ||
+        args.value !== undefined);
+}
+function buildFallbackClaim(statement, source, confidence, provenance) {
+    return {
+        claim: {
+            source,
+            subjectKey: fallbackSubjectFromSource(source),
+            propertyKey: "statement",
+            operator: "eq",
+            value: statement,
+            confidence: Math.min(confidence, STRICT_FALLBACK_CONFIDENCE),
+            ...(provenance ? { provenance } : {}),
+        },
+        extractionMode: "fallback",
+        extractionWarnings: [
+            "Deterministic claim extraction could not infer a strict semantic claim; emitted a review artifact instead.",
+        ],
+    };
+}
+function extractHeuristicClaim(statement, source, confidence, provenance) {
+    const normalized = stripListPrefix(statement);
+    const retentionMatch = normalized.match(/^(?<subject>.+?)\s+(?:must|shall|should)\s+be\s+retained\s+for\s+(?<value>\d+)\s+(?<unit>day|days|month|months|year|years)\.?$/i);
+    if (retentionMatch?.groups) {
+        const { unit, subject, value } = retentionMatch.groups;
+        if (!unit || !subject || !value)
+            return null;
+        const normalizedUnit = unit.toLowerCase().startsWith("day")
+            ? "Days"
+            : unit.toLowerCase().startsWith("month")
+                ? "Months"
+                : "Years";
+        return {
+            claim: {
+                source,
+                subjectKey: cleanSubject(subject),
+                propertyKey: `Retention ${normalizedUnit}`,
+                operator: "eq",
+                value: Number(value),
+                confidence,
+                ...(provenance ? { provenance } : {}),
+            },
+            extractionMode: "heuristic",
+            extractionWarnings: [],
+        };
+    }
+    const enabledMatch = normalized.match(/^(?<subject>.+?)\s+(?:must|shall|should)\s+be\s+(?<state>enabled|disabled)\.?$/i);
+    if (enabledMatch?.groups) {
+        const { subject, state } = enabledMatch.groups;
+        if (!subject || !state)
+            return null;
+        return {
+            claim: {
+                source,
+                subjectKey: cleanSubject(subject),
+                propertyKey: "enabled",
+                operator: "bool",
+                value: state.toLowerCase() === "enabled",
+                confidence,
+                ...(provenance ? { provenance } : {}),
+            },
+            extractionMode: "heuristic",
+            extractionWarnings: [],
+        };
+    }
+    const forbiddenMatch = normalized.match(/^(?<subject>.+?)\s+(?:must|shall|should)\s+not\s+(?<predicate>.+?)\.?$/i);
+    if (forbiddenMatch?.groups) {
+        const { subject, predicate } = forbiddenMatch.groups;
+        if (!subject || !predicate)
+            return null;
+        return {
+            claim: {
+                source,
+                subjectKey: cleanSubject(subject),
+                propertyKey: cleanPredicate(predicate),
+                operator: "polarity",
+                value: "forbid",
+                confidence,
+                ...(provenance ? { provenance } : {}),
+            },
+            extractionMode: "heuristic",
+            extractionWarnings: [],
+        };
+    }
+    const requiredMatch = normalized.match(/^(?<subject>.+?)\s+(?:must|shall|should)\s+(?<predicate>.+?)\.?$/i);
+    if (requiredMatch?.groups) {
+        const { subject, predicate } = requiredMatch.groups;
+        if (!subject || !predicate)
+            return null;
+        return {
+            claim: {
+                source,
+                subjectKey: cleanSubject(subject),
+                propertyKey: cleanPredicate(predicate),
+                operator: "polarity",
+                value: "require",
+                confidence,
+                ...(provenance ? { provenance } : {}),
+            },
+            extractionMode: "heuristic",
+            extractionWarnings: [],
+        };
+    }
+    return null;
+}
+export function estimateNormativeSignalConfidence(statement, heading) {
+    const normalizedStatement = stripListPrefix(statement).toLowerCase();
+    if (!/\b(must|shall|should)\b/.test(normalizedStatement)) {
+        return 0;
+    }
+    let confidence = normalizedStatement.includes(" shall ")
+        ? 0.86
+        : normalizedStatement.includes(" must ")
+            ? 0.84
+            : 0.78;
+    if (heading && NORMATIVE_SECTION_PATTERN.test(heading)) {
+        confidence += 0.08;
+    }
+    return Math.round(Math.min(0.95, confidence) * 100) / 100;
+}
+export function extractRequirementClaim(args) {
+    const statement = normalizeText(args.text);
+    const sourceFiles = normalizeSourceFiles(args.sourceFiles);
+    const source = normalizeOptionalString(args.source) ?? sourceFiles[0];
+    if (!source) {
+        throw new Error("Requirement modeling failed: provide source or at least one sourceFiles entry");
+    }
+    const provenance = normalizeOptionalString(args.provenance);
+    const confidence = clampConfidence(args.confidence);
+    if (hasExplicitClaimFields(args)) {
+        if (!normalizeOptionalString(args.subjectKey) ||
+            !normalizeOptionalString(args.propertyKey) ||
+            args.operator === undefined ||
+            args.value === undefined) {
+            throw new Error("Requirement modeling failed: subjectKey, propertyKey, operator, and value must all be provided when any extracted claim field is supplied");
+        }
+        return {
+            statement,
+            source,
+            sourceFiles,
+            claim: {
+                source,
+                subjectKey: normalizeOptionalString(args.subjectKey),
+                propertyKey: normalizeOptionalString(args.propertyKey),
+                operator: args.operator,
+                value: normalizeClaimValue(args.value),
+                confidence,
+                ...(provenance ? { provenance } : {}),
+            },
+            extractionMode: "provided",
+            extractionWarnings: [],
+        };
+    }
+    const heuristic = extractHeuristicClaim(statement, source, confidence, provenance);
+    if (heuristic) {
+        return {
+            statement,
+            source,
+            sourceFiles,
+            ...heuristic,
+        };
+    }
+    return {
+        statement,
+        source,
+        sourceFiles,
+        ...buildFallbackClaim(statement, source, confidence, provenance),
+    };
+}
+function toRelationshipPlanRows(relationships) {
+    return relationships.map((relationship) => ({
+        type: relationship.type,
+        from: relationship.from,
+        to: relationship.to,
+    }));
+}
+export function strictWriteSetToApplyPlan(writeSet) {
+    if (!writeSet.isStrict) {
+        return [
+            {
+                type: writeSet.observationFact.type,
+                id: writeSet.observationFact.id,
+                properties: writeSet.observationFact.properties,
+                relationships: [],
+            },
+        ];
+    }
+    return [
+        {
+            type: writeSet.subjectFact.type,
+            id: writeSet.subjectFact.id,
+            properties: writeSet.subjectFact.properties,
+            relationships: [],
+        },
+        {
+            type: writeSet.propertyFact.type,
+            id: writeSet.propertyFact.id,
+            properties: writeSet.propertyFact.properties,
+            relationships: [],
+        },
+        {
+            type: writeSet.req.type,
+            id: writeSet.req.id,
+            properties: writeSet.req.properties,
+            relationships: toRelationshipPlanRows(writeSet.relationships),
+        },
+    ];
+}
+export function writeSetPrimaryEntityId(writeSet) {
+    return writeSet.isStrict ? writeSet.req.id : writeSet.observationFact.id;
+}
+export async function getWorkspaceMigrationWarning(workspaceRoot = resolveWorkspaceRoot()) {
+    const configPath = path.join(workspaceRoot, ".kb", "config.json");
+    let rawConfig;
+    try {
+        rawConfig = await readFile(configPath, "utf8");
+    }
+    catch {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(rawConfig);
+        const status = getSchemaVersionStatus(parsed ?? undefined);
+        return status.warning;
+    }
+    catch {
+        return "KB config schemaVersion could not be read and should be checked before applying automated modeling.";
+    }
+}
+export async function handleKbModelRequirement(_prolog, args) {
+    const extracted = extractRequirementClaim(args);
+    const writeSet = buildStrictWriteSet({
+        claim: extracted.claim,
+        statement: extracted.statement,
+    });
+    const applyPlan = strictWriteSetToApplyPlan(writeSet);
+    const migrationWarning = await getWorkspaceMigrationWarning();
+    const strictSummary = writeSet.isStrict
+        ? `Modeled strict requirement into ${applyPlan.length} sequential applyPlan step(s).`
+        : "Modeled a non-blocking observation review artifact; deterministic claim extraction stayed below the strict threshold.";
+    const structuredContent = {
+        statement: extracted.statement,
+        source: extracted.source,
+        sourceFiles: extracted.sourceFiles,
+        claim: extracted.claim,
+        writeSet,
+        applyPlan,
+        isStrict: writeSet.isStrict,
+        confidence: writeSet.confidence,
+        extractionMode: extracted.extractionMode,
+        extractionWarnings: extracted.extractionWarnings,
+        migrationWarning,
+    };
+    return {
+        content: [
+            {
+                type: "text",
+                text: migrationWarning
+                    ? `${strictSummary} Migration warning included.`
+                    : strictSummary,
+            },
+        ],
+        structuredContent,
+        applyPlan,
+        writeSet,
+        migrationWarning,
+    };
+}

package/dist/tools-config.js

@@ -385,6 +385,56 @@ const BASE_TOOLS = [
             },
         },
     },
+    {
+        name: "kb_model_requirement",
+        description: "Convert a prose requirement plus optional extracted claim fields into a deterministic strict-lane write set. Read-only modeling returns a sequential applyPlan for later kb_upsert calls. High-confidence claims emit req+fact strict output; lower-confidence claims emit an observation review artifact. Includes migration warnings when legacy schemaVersion metadata is detected.",
+        inputSchema: {
+            type: "object",
+            required: ["text"],
+            properties: {
+                text: {
+                    type: "string",
+                    description: "Required prose requirement text to model. Example: 'Customer data must be retained for 7 years.'",
+                },
+                source: {
+                    type: "string",
+                    description: "Optional primary source path or provenance root used for stable IDs and text refs. Example: 'documentation/requirements/customer-retention.md'.",
+                },
+                sourceFiles: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Optional related source files. The first value is used as the source fallback when source is omitted.",
+                },
+                confidence: {
+                    type: "number",
+                    default: 0.8,
+                    minimum: 0,
+                    maximum: 1,
+                    description: "Confidence score for the extracted claim. >= 0.70 yields strict-lane output; lower confidence yields observation-only review output.",
+                },
+                subjectKey: {
+                    type: "string",
+                    description: "Optional extracted semantic claim subjectKey. Example: 'Customer.Data'.",
+                },
+                propertyKey: {
+                    type: "string",
+                    description: "Optional extracted semantic claim propertyKey. Example: 'Retention Years'.",
+                },
+                operator: {
+                    type: "string",
+                    enum: ["eq", "gte", "lte", "neq", "bool", "polarity"],
+                    description: "Optional extracted semantic claim operator. Example: 'eq'.",
+                },
+                value: {
+                    description: "Optional extracted semantic claim value. Accepts string, number, or boolean.",
+                },
+                provenance: {
+                    type: "string",
+                    description: "Optional extracted text reference. Falls back to source when omitted. Example: 'documentation/requirements/customer-retention.md#L1'.",
+                },
+            },
+        },
+    },
     {
         name: "kb_autopilot_generate",
         description: "Generate agent-centric bootstrap output for KB population. Read-only analysis that returns activation state, bootstrap guidance, candidate entities with evidence, payoff summary, and exact applyPlan payloads for later kb_upsert calls. No mutation side effects.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-mcp",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.26.0",
     "ajv": "^8.18.0",
@@ -9,8 +9,8 @@
     "fast-glob": "^3.2.12",
     "gray-matter": "^4.0.3",
     "js-yaml": "^4.1.0",
-    "kibi-cli": "^0.8.0",
-    "kibi-core": "^0.5.2",
+    "kibi-cli": "^0.10.0",
+    "kibi-core": "^0.5.3",
     "mcpcat": "^0.1.12",
     "ts-morph": "^23.0.0",
     "zod": "^4.3.6"