kibi-opencode 0.5.4 → 0.6.1

package/dist/repo-posture.js

@@ -0,0 +1,196 @@
+// implements REQ-opencode-smart-enforcement-v1, REQ-opencode-kibi-plugin-v1
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join, resolve } from "node:path";
+// Default sync paths — must stay in sync with file-filter.ts DEFAULT_SYNC_PATHS
+const DEFAULT_SYNC_PATHS = {
+    requirements: "documentation/requirements/**/*.md",
+    scenarios: "documentation/scenarios/**/*.md",
+    tests: "documentation/tests/**/*.md",
+    adr: "documentation/adr/**/*.md",
+    flags: "documentation/flags/**/*.md",
+    events: "documentation/events/**/*.md",
+    facts: "documentation/facts/**/*.md",
+    symbols: "documentation/symbols.yaml",
+};
+// ── helpers ────────────────────────────────────────────────────────────
+function findVendoredTrees(cwd) {
+    const results = [];
+    const vendoredMarkers = [
+        ["kibi", "opencode.json"],
+        ["kibi", "package.json"],
+        ["kibi", "packages", "mcp"],
+        ["kibi", "documentation"],
+    ];
+    for (const marker of vendoredMarkers) {
+        const markerPath = join(cwd, ...marker);
+        if (existsSync(markerPath)) {
+            results.push(marker.join("/"));
+        }
+    }
+    const nodeModules = join(cwd, "node_modules");
+    if (existsSync(nodeModules)) {
+        for (const entry of readdirSync(nodeModules)) {
+            if (entry === "kibi" || entry.startsWith("kibi-")) {
+                results.push(`node_modules/${entry}`);
+            }
+        }
+    }
+    return [...new Set(results)];
+}
+/** Check if .kb/config.json exists at root. */
+function rootKbConfigExists(cwd) {
+    return existsSync(join(cwd, ".kb", "config.json"));
+}
+/** Read and parse .kb/config.json. Returns null on failure. */
+function readRootConfig(cwd) {
+    try {
+        return (JSON.parse(readFileSync(join(cwd, ".kb", "config.json"), "utf8")) || null);
+    }
+    catch {
+        return null;
+    }
+}
+/** Check if all configured KB targets resolve (directories / files exist). */
+function rootTargetsAllResolve(cwd) {
+    const configPath = join(cwd, ".kb", "config.json");
+    let config = {};
+    try {
+        config = JSON.parse(readFileSync(configPath, "utf8")) || {};
+    }
+    catch {
+        return false;
+    }
+    const paths = config.paths;
+    const defaultKeys = [
+        "requirements",
+        "scenarios",
+        "tests",
+        "adr",
+        "flags",
+        "events",
+        "facts",
+        "symbols",
+    ];
+    for (const key of defaultKeys) {
+        const raw = paths?.[key] ?? DEFAULT_SYNC_PATHS[key];
+        // Normalize: strip trailing slashes and glob patterns to get the root dir/file path
+        const normalized = raw.replace(/\/+$/, "");
+        const isFile = normalized.endsWith(".yaml") || normalized.endsWith(".yml");
+        if (isFile) {
+            if (!existsSync(resolve(cwd, normalized)))
+                return false;
+        }
+        else {
+            // Strip first glob segment
+            const segments = normalized.split("/");
+            const rootSegments = [];
+            for (const seg of segments) {
+                if (seg.includes("*") || seg.includes("?") || seg.includes("["))
+                    break;
+                rootSegments.push(seg);
+            }
+            const dirPath = rootSegments.join("/") || ".";
+            if (!existsSync(resolve(cwd, dirPath)))
+                return false;
+        }
+    }
+    return true;
+}
+/** Detect root-level Kibi intent (plugin config present but no .kb). */
+function hasRootKibiIntent(cwd) {
+    if (existsSync(join(cwd, ".opencode", "kibi.json"))) {
+        return true;
+    }
+    try {
+        const oc = JSON.parse(readFileSync(join(cwd, "opencode.json"), "utf8"));
+        if (oc &&
+            Array.isArray(oc.plugin) &&
+            oc.plugin.some((p) => typeof p === "string" && p.includes("kibi"))) {
+            return true;
+        }
+    }
+    catch { }
+    for (const guidanceFile of [
+        "AGENTS.md",
+        join(".github", "copilot-instructions.md"),
+    ]) {
+        try {
+            const content = readFileSync(join(cwd, guidanceFile), "utf8");
+            if (content.includes("kb_query") || content.includes("kb_search")) {
+                return true;
+            }
+        }
+        catch { }
+    }
+    return false;
+}
+// ── main classifier ────────────────────────────────────────────────────
+export function detectPosture(cwd) {
+    const hasRootConfig = rootKbConfigExists(cwd);
+    const vendoredTrees = findVendoredTrees(cwd);
+    // 1. hybrid_root_plus_vendored — root config AND vendored subtrees
+    if (hasRootConfig && vendoredTrees.length > 0) {
+        return {
+            state: "hybrid_root_plus_vendored",
+            needsBootstrap: false,
+            reason: `Root .kb/config.json exists alongside vendored tree(s): ${vendoredTrees.join(", ")}`,
+            maintenanceDegraded: false,
+        };
+    }
+    // 2-3. root config exists (check maintenance mode and target resolution)
+    if (hasRootConfig) {
+        const config = readRootConfig(cwd);
+        const maint = config?.maintenance;
+        const maintenanceDisabled = maint !== undefined && maint.enabled === false;
+        // maintenance_degraded overlay: maintenance explicitly disabled → root_active
+        if (maintenanceDisabled) {
+            return {
+                state: "root_active",
+                needsBootstrap: false,
+                reason: "Root .kb/config.json exists; maintenance mode explicitly disabled",
+                maintenanceDegraded: true,
+            };
+        }
+        const allResolve = rootTargetsAllResolve(cwd);
+        if (allResolve) {
+            return {
+                state: "root_active",
+                needsBootstrap: false,
+                reason: "Root .kb/config.json exists and all configured KB targets resolve",
+                maintenanceDegraded: false,
+            };
+        }
+        // 3. root_partial — root config exists but targets are missing
+        return {
+            state: "root_partial",
+            needsBootstrap: true,
+            reason: "Root .kb/config.json exists but some configured KB targets are missing",
+            maintenanceDegraded: false,
+        };
+    }
+    // 4. vendored_only — no root config, but vendored markers found
+    if (vendoredTrees.length > 0) {
+        return {
+            state: "vendored_only",
+            needsBootstrap: false,
+            reason: `No root .kb/config.json, but vendored Kibi tree(s) detected: ${vendoredTrees.join(", ")}`,
+            maintenanceDegraded: false,
+        };
+    }
+    // 5. root_uninitialized — no root .kb, no vendored trees, but root declares intent
+    if (hasRootKibiIntent(cwd)) {
+        return {
+            state: "root_uninitialized",
+            needsBootstrap: true,
+            reason: "No root .kb and no vendored trees, but Kibi plugin intent detected at root",
+            maintenanceDegraded: false,
+        };
+    }
+    // Fallback: treat as uninitialized (no kibi presence at all)
+    return {
+        state: "root_uninitialized",
+        needsBootstrap: true,
+        reason: "No Kibi presence detected in workspace",
+        maintenanceDegraded: false,
+    };
+}

package/dist/risk-classifier.d.ts

@@ -0,0 +1,39 @@
+import type { PathKind } from "./path-kind.js";
+/**
+ * Risk classification for file edits.
+ * Ordered from safest to riskiest for consumer convenience.
+ */
+export type RiskClass = "safe_docs_only" | "safe_test_only" | "kb_doc_structural" | "req_policy_candidate" | "behavior_candidate" | "traceability_candidate" | "manual_kb_edit";
+/**
+ * Input parameters for risk classification.
+ * All fields are cheaply computable — no AST parsing or async required.
+ * pathKind already encodes path-based classification from analyzePath().
+ */
+export interface ClassifyRiskParams {
+    pathKind: PathKind;
+    isUnderKb: boolean;
+    hasMustPriority: boolean;
+    hasDurableComment: boolean;
+    fileContent: string;
+}
+/**
+ * Result of risk classification with the determined class and human-readable reasons.
+ */
+export interface RiskClassification {
+    riskClass: RiskClass;
+    reasons: string[];
+}
+/**
+ * Classify a file edit into a deterministic risk class.
+ *
+ * Classification order (first match wins):
+ * 1. manual_kb_edit        — file is under .kb/
+ * 2. safe_test_only        — pathKind is "test"
+ * 3. req_policy_candidate  — pathKind is "requirement"
+ * 4. kb_doc_structural     — pathKind is "scenario", "adr", or "fact"
+ * 5. safe_docs_only        — pathKind is "unknown" (markdown/config/etc.)
+ * 6. traceability_candidate — code with exports AND (hasDurableComment OR missing traceability)
+ * 7. behavior_candidate    — code with exports, already has traceability, no durable comment
+ * 8. safe_docs_only        — code without exports, or fallback
+ */
+export declare function classifyRisk(params: ClassifyRiskParams): RiskClassification;

package/dist/risk-classifier.js

@@ -0,0 +1,111 @@
+// implements REQ-opencode-smart-enforcement-v1, REQ-opencode-kibi-plugin-v1
+/**
+ * Regex to detect exportable code constructs (functions, classes, variables).
+ */
+const BEHAVIOR_PATTERN = /(?:export\s+(?:function|class|const|let|var)|\bclass\s+\w+|\bfunction\s+\w+|\bdef\s+\w+)/;
+/**
+ * Regex to detect traceability annotations.
+ */
+const TRACEABILITY_PATTERN = /implements\s+REQ-[A-Za-z0-9_-]+/i;
+/**
+ * Classify a file edit into a deterministic risk class.
+ *
+ * Classification order (first match wins):
+ * 1. manual_kb_edit        — file is under .kb/
+ * 2. safe_test_only        — pathKind is "test"
+ * 3. req_policy_candidate  — pathKind is "requirement"
+ * 4. kb_doc_structural     — pathKind is "scenario", "adr", or "fact"
+ * 5. safe_docs_only        — pathKind is "unknown" (markdown/config/etc.)
+ * 6. traceability_candidate — code with exports AND (hasDurableComment OR missing traceability)
+ * 7. behavior_candidate    — code with exports, already has traceability, no durable comment
+ * 8. safe_docs_only        — code without exports, or fallback
+ */
+export function classifyRisk(params) {
+    const { pathKind, isUnderKb, hasMustPriority, hasDurableComment, fileContent, } = params;
+    // 1. manual_kb_edit — direct KB manipulation is always risky
+    if (isUnderKb) {
+        return {
+            riskClass: "manual_kb_edit",
+            reasons: ["File is under .kb/ — manual edits bypass KB validation"],
+        };
+    }
+    // 2. safe_test_only — test files are low-risk
+    if (pathKind === "test") {
+        return {
+            riskClass: "safe_test_only",
+            reasons: ["File is a test file — edits are low risk"],
+        };
+    }
+    // 3. req_policy_candidate — requirement docs need policy checks
+    if (pathKind === "requirement") {
+        const reasons = [
+            "File is a requirement document — policy checks recommended",
+        ];
+        if (hasMustPriority) {
+            reasons.push("Requirement has priority:must — elevated validation required");
+        }
+        return {
+            riskClass: "req_policy_candidate",
+            reasons,
+        };
+    }
+    // 4. kb_doc_structural — structural KB documentation
+    if (pathKind === "scenario" ||
+        pathKind === "adr" ||
+        pathKind === "fact" ||
+        pathKind === "flag" ||
+        pathKind === "event" ||
+        pathKind === "symbol") {
+        return {
+            riskClass: "kb_doc_structural",
+            reasons: [
+                "File is structural KB documentation — relationship and field validation recommended",
+            ],
+        };
+    }
+    // 5. safe_docs_only — non-code, non-kb-doc files (markdown, config, etc.)
+    if (pathKind === "unknown") {
+        return {
+            riskClass: "safe_docs_only",
+            reasons: ["File is not a code or KB document — low risk"],
+        };
+    }
+    // pathKind === "code" from here on
+    if (pathKind === "code") {
+        const hasBehavior = BEHAVIOR_PATTERN.test(fileContent);
+        const hasTraceability = TRACEABILITY_PATTERN.test(fileContent);
+        if (hasBehavior) {
+            // 6. traceability_candidate — needs traceability attention
+            if (hasDurableComment || !hasTraceability) {
+                const reasons = [];
+                if (!hasTraceability) {
+                    reasons.push("Code file contains exports without // implements REQ-xxx annotation");
+                }
+                if (hasDurableComment) {
+                    reasons.push("Durable knowledge comment detected — traceability review recommended");
+                }
+                return {
+                    riskClass: "traceability_candidate",
+                    reasons,
+                };
+            }
+            // 7. behavior_candidate — has exports and traceability, no durable comment
+            return {
+                riskClass: "behavior_candidate",
+                reasons: [
+                    "Code file contains exportable constructs — discovery guidance applies",
+                ],
+            };
+        }
+        // Code file without export patterns — treat as safe
+        return {
+            riskClass: "safe_docs_only",
+            reasons: ["Code file has no detected export patterns — low risk"],
+        };
+    }
+    // Fallback — should not be reached since all PathKind values are handled
+    return {
+        riskClass: "safe_docs_only",
+        reasons: ["File type is unhandled — defaulting to safe classification"],
+    };
+}

package/dist/smart-enforcement.d.ts

@@ -0,0 +1,41 @@
+import type { RepoPosture } from "./repo-posture.js";
+/**
+ * The effective enforcement mode after resolving config + posture + maintenance state.
+ * - "advisory": plugin emits guidance, logs, reminders — never blocks
+ * - "strict": plugin may escalate targeted checks, completion reminders, and
+ *   structured logging. Hooks/checks remain the hard enforcement boundary
+ *   regardless of mode.
+ */
+export type EffectiveMode = "advisory" | "strict";
+/**
+ * Inputs required to determine the effective smart-enforcement mode.
+ */
+export interface ModeInputs {
+    /** Configured smart-enforcement mode. */
+    mode: "advisory" | "strict";
+    /** When true, strict mode only activates for authoritative root KB postures. */
+    requireRootKbForStrict: boolean;
+    /** Current repository posture from detectPosture(). */
+    posture: RepoPosture;
+    /** Whether the maintenance subsystem is in a degraded state. */
+    maintenanceDegraded: boolean;
+}
+/**
+ * Determine whether the current posture qualifies for strict enforcement
+ * when `requireRootKbForStrict` is true.
+ *
+ * Only root_active and hybrid_root_plus_vendored are considered authoritative.
+ */
+export declare function isStrictEligible(inputs: ModeInputs): boolean;
+/**
+ * Compute the effective smart-enforcement mode.
+ *
+ * Decision matrix:
+ * - advisory config → always advisory
+ * - strict config + requireRootKbForStrict=true → strict only for root_active
+ *   and hybrid_root_plus_vendored postures
+ * - strict config + requireRootKbForStrict=false → strict may apply to all
+ *   postures (but hooks/checks remain hard gate regardless)
+ * - maintenance-degraded → advisory regardless of config
+ */
+export declare function computeEffectiveMode(inputs: ModeInputs): EffectiveMode;

package/dist/smart-enforcement.js

@@ -0,0 +1,48 @@
+/** Postures considered authoritative for strict enforcement. */
+const STRICT_ELIGIBLE_POSTURES = new Set([
+    "root_active",
+    "hybrid_root_plus_vendored",
+]);
+/**
+ * Determine whether the current posture qualifies for strict enforcement
+ * when `requireRootKbForStrict` is true.
+ *
+ * Only root_active and hybrid_root_plus_vendored are considered authoritative.
+ */
+export function isStrictEligible(inputs) {
+    if (inputs.maintenanceDegraded)
+        return false;
+    if (inputs.requireRootKbForStrict) {
+        return STRICT_ELIGIBLE_POSTURES.has(inputs.posture);
+    }
+    // When requireRootKbForStrict is false, strict may apply to all postures
+    // (but still subject to maintenance-degraded override in computeEffectiveMode).
+    return true;
+}
+/**
+ * Compute the effective smart-enforcement mode.
+ *
+ * Decision matrix:
+ * - advisory config → always advisory
+ * - strict config + requireRootKbForStrict=true → strict only for root_active
+ *   and hybrid_root_plus_vendored postures
+ * - strict config + requireRootKbForStrict=false → strict may apply to all
+ *   postures (but hooks/checks remain hard gate regardless)
+ * - maintenance-degraded → advisory regardless of config
+ */
+export function computeEffectiveMode(inputs) {
+    // Maintenance-degraded always forces advisory
+    if (inputs.maintenanceDegraded) {
+        return "advisory";
+    }
+    // Advisory config always produces advisory behavior
+    if (inputs.mode === "advisory") {
+        return "advisory";
+    }
+    // Strict config: check posture eligibility
+    if (isStrictEligible(inputs)) {
+        return "strict";
+    }
+    // Strict config but not eligible → fall back to advisory
+    return "advisory";
+}

package/dist/source-linked-guidance.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Resolve the configured symbols manifest path using loadKbSyncPaths(worktree),
+ * read the YAML synchronously, and return up to 3 deduped REQ IDs linked to
+ * the edited file path. Preference is given to relationships[type=implements].target
+ * (in file order) then static links as a fallback, preserving file order.
+ *
+ * Supports both YAML formats: top-level array and { symbols: [...] } object.
+ * This function is purely synchronous and makes no runtime KB queries.
+ */
+export declare function getSourceLinkedRequirementIds(worktree: string, editedAbsolutePath: string): string[];

package/dist/source-linked-guidance.js

@@ -0,0 +1,164 @@
+// implements REQ-opencode-smart-enforcement-v1
+import { existsSync, readFileSync } from "node:fs";
+import * as path from "node:path";
+import { loadKbSyncPaths } from "./file-filter.js";
+/**
+ * Resolve the configured symbols manifest path using loadKbSyncPaths(worktree),
+ * read the YAML synchronously, and return up to 3 deduped REQ IDs linked to
+ * the edited file path. Preference is given to relationships[type=implements].target
+ * (in file order) then static links as a fallback, preserving file order.
+ *
+ * Supports both YAML formats: top-level array and { symbols: [...] } object.
+ * This function is purely synchronous and makes no runtime KB queries.
+ */
+// implements REQ-opencode-smart-enforcement-v1
+export function getSourceLinkedRequirementIds(worktree, editedAbsolutePath) {
+    try {
+        const paths = loadKbSyncPaths(worktree);
+        const symbolsPathRaw = paths.symbols;
+        if (!symbolsPathRaw)
+            return [];
+        const symbolsPath = path.isAbsolute(symbolsPathRaw)
+            ? symbolsPathRaw
+            : path.join(worktree, symbolsPathRaw);
+        if (!existsSync(symbolsPath))
+            return [];
+        const content = readFileSync(symbolsPath, "utf8");
+        const symbols = parseSymbolsYaml(content);
+        const relEdited = path
+            .relative(worktree, editedAbsolutePath)
+            .split(path.sep)
+            .join("/");
+        const matchedRows = symbols.filter((s) => s.sourceFile === relEdited);
+        if (matchedRows.length === 0)
+            return [];
+        const seen = new Set();
+        const orderedIds = [];
+        // First pass: collect implements relationships in file order
+        for (const row of matchedRows) {
+            for (const r of row.relationships ?? []) {
+                if (r.type === "implements") {
+                    const id = r.target;
+                    if (!seen.has(id)) {
+                        seen.add(id);
+                        orderedIds.push(id);
+                        if (orderedIds.length >= 3)
+                            return orderedIds.slice(0, 3);
+                    }
+                }
+            }
+        }
+        // Second pass: fall back to static links, preserving file order
+        for (const row of matchedRows) {
+            for (const l of row.links ?? []) {
+                if (!seen.has(l)) {
+                    seen.add(l);
+                    orderedIds.push(l);
+                    if (orderedIds.length >= 3)
+                        return orderedIds.slice(0, 3);
+                }
+            }
+        }
+        return orderedIds.slice(0, 3);
+    }
+    catch {
+        return [];
+    }
+}
+// ── Lightweight YAML parser (symbols.yaml subset) ────────────────────
+//
+// Handles:
+//   symbols:
+//     - id: SYM-xxx
+//       sourceFile: path/to/file
+//       links:
+//         - REQ-xxx
+//       relationships:
+//         - type: implements
+//           target: REQ-xxx
+//
+// And bare array format (no wrapping `symbols:` key):
+//     - id: SYM-xxx
+//       ...
+function parseSymbolsYaml(content) {
+    const entries = [];
+    const lines = content.split("\n");
+    let current = null;
+    let section = "none";
+    let pendingRel = null;
+    function flushRel() {
+        if (pendingRel?.type && pendingRel.target && current) {
+            current.relationships.push({
+                type: pendingRel.type,
+                target: pendingRel.target,
+            });
+        }
+        pendingRel = null;
+    }
+    function flushEntry() {
+        flushRel();
+        if (current?.id && current?.sourceFile) {
+            entries.push(current);
+        }
+        current = null;
+        section = "none";
+    }
+    for (const raw of lines) {
+        if (raw.trim().startsWith("#"))
+            continue;
+        // New entry: "  - id: ..."
+        const entryMatch = raw.match(/^\s+-\s+id:\s*(.+)$/);
+        if (entryMatch) {
+            flushEntry();
+            current = { id: entryMatch[1].trim(), links: [], relationships: [] };
+            section = "none";
+            continue;
+        }
+        if (!current)
+            continue;
+        // sourceFile
+        const srcMatch = raw.match(/^\s+sourceFile:\s*(.+)$/);
+        if (srcMatch) {
+            current.sourceFile = srcMatch[1].trim();
+            section = "none";
+            continue;
+        }
+        // links section header
+        if (/^\s+links:\s*$/.test(raw)) {
+            flushRel();
+            section = "links";
+            continue;
+        }
+        // relationships section header
+        if (/^\s+relationships:\s*$/.test(raw)) {
+            flushRel();
+            section = "relationships";
+            continue;
+        }
+        // Link item: "      - REQ-xxx"
+        if (section === "links") {
+            const linkMatch = raw.match(/^\s+-\s+(REQ-[A-Za-z0-9_-]+)\s*$/);
+            if (linkMatch) {
+                current.links.push(linkMatch[1]);
+                continue;
+            }
+        }
+        // Relationship type: "      - type: implements"
+        if (section === "relationships") {
+            const relTypeMatch = raw.match(/^\s+-\s+type:\s*(.+)$/);
+            if (relTypeMatch) {
+                flushRel();
+                pendingRel = { type: relTypeMatch[1].trim() };
+                continue;
+            }
+            // Relationship target: "        target: REQ-..."
+            const relTargetMatch = raw.match(/^\s+target:\s*(.+)$/);
+            if (relTargetMatch && pendingRel) {
+                pendingRel.target = relTargetMatch[1].trim();
+                continue;
+            }
+        }
+    }
+    flushEntry();
+    return entries;
+}

package/dist/workspace-health.d.ts

@@ -6,5 +6,7 @@ export interface WorkspaceHealth {
 }
 /**
  * Analyze workspace health for Kibi bootstrap and initialization.
+ * Uses detectPosture() for root-scoped classification and delegates
+ * bootstrap-needs to the posture result.
  */
 export declare function checkWorkspaceHealth(cwd: string): WorkspaceHealth;