kibi-opencode 0.7.2 → 0.8.0

package/README.md

@@ -25,6 +25,7 @@ The plugin now uses a posture-aware, low-token smart-enforcement model before em
 - **Repo posture detection**: distinguishes `root_active`, `root_partial`, `root_uninitialized`, `vendored_only`, and `hybrid_root_plus_vendored`
 - **Risk classification**: separates `safe_docs_only`, `safe_test_only`, `kb_doc_structural`, `req_policy_candidate`, `behavior_candidate`, `traceability_candidate`, and `manual_kb_edit`
 - **Source-linked micro-briefs**: risky code edits (`behavior_candidate`, `traceability_candidate`) prepend a concise list of existing Kibi links (e.g., `- Existing Kibi links: REQ-001, REQ-002`) when 1-3 concrete source-linked KB hits are found in `documentation/symbols.yaml`. Skip on cache hit.
+- **Start-task risky cue**: authoritative risky edits also add a compact `/brief-kibi` cue so agents can start with an explicit Kibi briefing before acting, while staying inside the same single prompt block and token budget.
 - **Effective mode gating**: `strict` is only possible for `root_active` and `hybrid_root_plus_vendored` when `requireRootKbForStrict` is enabled; `maintenanceDegraded` overrides everything back to `advisory`
 - **Low-token prompt policy**: docs-only and test-only edits avoid unnecessary discovery prompts; vendored-only repos suppress operational bootstrap nudges; at most one contextual block is injected per prompt (≤120 words, ≤5 bullets)
 - **Completion reminder**: when `completionReminder` is enabled, risky code edits append a single prompt-visible `kb_check` reminder exactly once per cached context
@@ -45,10 +46,10 @@ The plugin provides context-aware prompt guidance based on recent edits and work
 
 After KB-document edits, the plugin queues targeted validation rules to run via background sync operations:
 
-- **Must-priority requirement edits**: elevated validation including coverage checks (`must-priority-coverage`)
+- **Must-priority requirement edits**: elevated validation including coverage checks (`must-priority-coverage`) and `strict-req-fact-pairing`
 - **Traceability candidate code edits**: schedules `symbol-traceability` via reason `smart-enforcement.traceability`
 - **Fact KB doc edits**: includes `strict-fact-shape` validation alongside standard structural checks
-- **Other requirement/scenario/test/ADR/fact edits**: standard validation for `required-fields` and `no-dangling-refs`
+- **Requirement KB doc edits**: includes `strict-req-fact-pairing` validation alongside standard structural checks
 
 The plugin inspects requirement frontmatter to detect `priority: must` and schedules elevated validation for critical requirements. Runs in background after sync completes, non-blocking. Can be disabled via `guidance.targetedChecks.enabled: false`.
 
@@ -87,9 +88,9 @@ When editing code files, the plugin analyzes long comments and docstrings for du
 
 - **Supported languages**: JavaScript/TypeScript (`//`, `/* */`, `/** */`) and Python (`#` blocks, true docstrings)
 - **Smart filtering**: Only analyzes comments above `guidance.commentDetection.minLines` threshold
-- **Classification**: Automatically categorizes as FACT (invariants/limits), ADR (decisions/tradeoffs), REQ (behavior), SCEN (flows), or TEST (verification)
+- **Classification**: Automatically categorizes as FACT (strict domain facts: invariants/limits/cardinalities), ADR (decisions/tradeoffs), REQ (behavior), SCEN (flows), or TEST (verification)
 - **Specific routing guidance**: Injects targeted prompts based on classification:
-  - FACT: "This looks like a domain invariant; route to a FACT via Kibi"
+  - FACT: "This looks like a strict domain fact (invariant/property/limit); route to a FACT via Kibi. Bug/workaround notes use `fact_kind: observation` or `meta`."
   - ADR: "This looks like decision rationale; route to an ADR"
   - REQ: "This looks like behavior intent; route to a REQ"
 - **Deduplication**: Tracks seen comments by fingerprint to avoid repeated guidance
@@ -111,6 +112,15 @@ The plugin injects guidance into OpenCode sessions to improve agent grounding. U
 ### Bootstrap Command
 
 OpenCode exposes Kibi MCP prompts as slash commands. The \`/init-kibi\` command triggers the \`kb_autopilot_generate\` workflow to assist in retroactive bootstrap using only public MCP tools.
+
+### Start-Task Briefing
+
+Use `/brief-kibi` at the start of authoritative risky edit work when the prompt hints for it.
+
+- The plugin only hints about `/brief-kibi` inside smart-enforcement guidance.
+- The actual briefing content is generated by the registered MCP prompt/tool, not by the prompt hook.
+- Live automatic briefing fetch from `experimental.chat.system.transform` is deferred; the hook remains text-only.
+
 ### Discovery-first MCP guidance
 
 Agent-visible guidance is intentionally limited to the curated public MCP surface:

package/dist/index.js

@@ -143,6 +143,7 @@ const kibiOpencodePlugin = async (input) => {
                     "required-fields",
                     "no-dangling-refs",
                     ...(pathAnalysis.kind === "fact" ? ["strict-fact-shape"] : []),
+                    ...(pathAnalysis.kind === "requirement" ? ["strict-req-fact-pairing"] : []),
                 ]
                 : null;
             const checkRules = traceabilityRules ?? kbStructuralRules;
@@ -260,11 +261,12 @@ const kibiOpencodePlugin = async (input) => {
                             "required-fields",
                             "no-dangling-refs",
                             "must-priority-coverage",
+                            "strict-req-fact-pairing",
                         ];
                         logger.info(`kibi-opencode: must-priority requirement detected, scheduling elevated checks for ${filePath}`);
                     }
                     else {
-                        checkRules = ["required-fields", "no-dangling-refs"];
+                        checkRules = ["required-fields", "no-dangling-refs", "strict-req-fact-pairing"];
                     }
                 }
                 logger.info("smart-enforcement.targeted-checks", {

package/dist/knowledge-classifier.js

@@ -94,7 +94,7 @@ export function classifyKnowledge(text) {
         bestMatch = {
             type: "fact",
             confidence: factScore >= 3 ? "high" : "medium",
-            reasoning: 'Contains domain invariant or property cues like "must be unique", "at most", or "default is"',
+            reasoning: 'Contains strict domain fact cues (invariants, properties, limits, cardinalities) for the strict fact lane',
         };
     }
     if (reqScore > maxMatches) {

package/dist/plugin-startup.js

@@ -9,6 +9,15 @@ import { createSyncScheduler } from "./scheduler.js";
 import { getSessionTracker } from "./session-tracker.js";
 import { computeEffectiveMode, } from "./smart-enforcement.js";
 import { checkWorkspaceHealth } from "./workspace-health.js";
+function isSmartEnforcementSyncReason(reason) {
+    if (!reason) {
+        return false;
+    }
+    const normalizedReason = reason.endsWith(".trailing")
+        ? reason.slice(0, -".trailing".length)
+        : reason;
+    return normalizedReason.startsWith("smart-enforcement.");
+}
 const workspaceCacheState = new Map();
 function resolveCurrentBranch(cwd) {
     try {
@@ -148,7 +157,8 @@ export async function runPluginStartup(input) {
                     worktree: input.worktree,
                     config: cfg,
                     onRunComplete: (meta) => {
-                        if (meta.exitCode !== 0)
+                        if (meta.exitCode !== 0 &&
+                            !isSmartEnforcementSyncReason(meta.reason))
                             latchRuntimeDegraded("scheduler_sync_failed");
                         if (meta.checkExitCode !== undefined &&
                             meta.checkExitCode !== 0) {

package/dist/prompt.js

@@ -5,6 +5,10 @@ const SENTINEL = "<!-- kibi-opencode -->";
 // ── Token budget enforcement ───────────────────────────────────────────
 const MAX_BULLETS = 5;
 const MAX_WORDS = 117; // Reserve 3 words for sentinel so total injected prompt stays ≤ 120
+const AUTHORITATIVE_POSTURES = [
+    "root_active",
+    "hybrid_root_plus_vendored",
+];
 function countWords(text) {
     return text.split(/\s+/).filter(Boolean).length;
 }
@@ -35,6 +39,15 @@ function enforceBudget(block) {
     }
     return block;
 }
+function insertBulletAfterHeader(block, bullet) {
+    const headerEnd = block.indexOf("\n");
+    if (headerEnd === -1)
+        return `${block}\n${bullet}`;
+    return `${block.slice(0, headerEnd + 1)}${bullet}\n${block.slice(headerEnd + 1)}`;
+}
+function isAuthoritativePosture(posture) {
+    return AUTHORITATIVE_POSTURES.includes(posture);
+}
 // ── File bucket derivation ─────────────────────────────────────────────
 function deriveFileBucket(pathKind) {
     return pathKind;
@@ -56,12 +69,15 @@ Requirement edits need policy alignment. Run kb_check with required-fields and n
 - Add verification: create or update linked SCEN and TEST entities`,
     behavior_candidate: `📝 **Code changes detected**
 
-Production code: use \`implements\` (symbol→req) for requirement ownership. Test code: use \`executable_for\` (symbol→test). \`covered_by\` is coverage evidence only. Prefer scenario-first: req→scenario→test when scenarios exist.`,
+Production code: use \`implements\` (symbol→req) for requirement ownership. Test code: use \`executable_for\` (symbol→test).
+- \`covered_by\` is coverage evidence only
+- Prefer scenario-first: req→scenario→test when scenarios exist`,
     traceability_candidate: `📝 **Code changes detected**
 
-Production code: use \`implements\` (symbol→req) for requirement ownership. Test code: use \`executable_for\` (symbol→test). \`covered_by\` is coverage evidence only. Prefer scenario-first: req→scenario→test when scenarios exist.
-- Durable knowledge comment detected — route to KB instead of inline comments
-- Use kb_upsert for FACT, ADR, or REQ entities as appropriate`,
+Production code: use \`implements\` (symbol→req) for requirement ownership. Test code: use \`executable_for\` (symbol→test).
+- \`covered_by\` is coverage evidence only
+- Prefer scenario-first: req→scenario→test when scenarios exist
+- Route durable knowledge comments to KB entities, not inline comments`,
     manual_kb_edit: `⚠️  **WARNING: Direct .kb/ edits bypass validation**
 
 The Kibi knowledge base is managed through public MCP tools. Direct manual edits to .kb/** can cause inconsistencies.
@@ -196,7 +212,7 @@ Before implementing or explaining code:
 4. **Add traceability** - Production code: \`implements\` (symbol→req) for ownership. Test code: \`executable_for\`. \`covered_by\` is coverage evidence only for production symbols.
 
 If you're adding long explanatory comments, consider routing that knowledge to:
-- \`FACT\` for domain invariants, properties, limits, cardinalities
+- \`FACT\` for strict domain facts (invariants, properties, limits, cardinalities); bug/workaround notes use \`fact_kind: observation\` or \`meta\`
 - \`ADR\` for technical decisions, tradeoffs, rationale
 - \`REQ\` for system behavior requirements`;
                 }
@@ -209,6 +225,13 @@ If you're adding long explanatory comments, consider routing that knowledge to:
             }
         }
     } // closing brace for Priority 2-4 else block starting at 187
+    if (selectedBlock &&
+        (riskClass === "behavior_candidate" ||
+            riskClass === "traceability_candidate") &&
+        isAuthoritativePosture(posture) &&
+        !context.maintenanceDegraded) {
+        selectedBlock = insertBulletAfterHeader(selectedBlock, "- Authoritative risky edit: run `/brief-kibi` before acting.");
+    }
     // Source-linked micro-brief: insert after header line for code risk classes
     // Inserting after the header (not prepending before it) preserves the header
     // under enforceBudget's trimming logic, which only collects non-bullet lines
@@ -226,10 +249,7 @@ If you're adding long explanatory comments, consider routing that knowledge to:
                     : path.join(context.workspaceRoot, editedPath);
                 const linkedIds = getSourceLinkedRequirementIds(context.workspaceRoot, absEdited);
                 if (linkedIds.length >= 1 && linkedIds.length <= 3) {
-                    const headerEnd = selectedBlock.indexOf("\n");
-                    if (headerEnd !== -1) {
-                        selectedBlock = `${selectedBlock.slice(0, headerEnd + 1)}- Existing Kibi links: ${linkedIds.join(", ")}\n${selectedBlock.slice(headerEnd + 1)}`;
-                    }
+                    selectedBlock = insertBulletAfterHeader(selectedBlock, `- Existing Kibi links: ${linkedIds.join(", ")}`);
                 }
             }
         }
@@ -266,24 +286,28 @@ The Kibi workspace is in a maintenance-degraded state. Guidance remains advisory
         };
         context.cache.recordSatisfied(key, "guidance");
     }
+    // Apply budget enforcement before appending the completion reminder so the
+    // reminder bullet is never silently trimmed when bullet count exceeds MAX_BULLETS.
+    const budgeted = selectedBlock ? enforceBudget(selectedBlock) : null;
     // Append completion reminder for risky classes when enabled
     const REMINDER_RISK_CLASSES = [
         "behavior_candidate",
         "traceability_candidate",
         "req_policy_candidate",
     ];
-    if (selectedBlock &&
+    let finalBlock = budgeted;
+    if (finalBlock &&
         context.completionReminder === true &&
         !context.maintenanceDegraded &&
         riskClass &&
         REMINDER_RISK_CLASSES.includes(riskClass) &&
         posture !== "root_uninitialized" &&
         posture !== "root_partial") {
-        selectedBlock = `${selectedBlock}\n- Run \`kb_check\` before completing this task.`;
+        finalBlock = `${finalBlock}\n- Run \`kb_check\` before completing this task.`;
     }
     // Return: sentinel + one targeted block (or just sentinel if no block)
-    return selectedBlock
-        ? `${SENTINEL}\n\n${enforceBudget(selectedBlock)}`
+    return finalBlock
+        ? `${SENTINEL}\n\n${finalBlock}`
         : SENTINEL;
 }
 // ── Comment suggestion guidance (legacy compat) ────────────────────────
@@ -292,14 +316,14 @@ function buildCommentSuggestionGuidance(suggestion) {
         case "fact":
             return `🎯 **Durable knowledge detected: FACT**
 
-Your recent code edit contains a comment that looks like a **domain invariant** (properties, limits, defaults, or cardinality constraints).
+Your recent code edit contains a comment that looks like a **strict domain fact** (invariants, properties, limits, defaults, or cardinality constraints).
 
-**Action**: Instead of inline comments, route this to a FACT entity:
-- Create \`documentation/facts/FACT-xxx.md\` with the invariant
+**Action**: Route to a FACT entity in the strict fact lane:
+- Create \`documentation/facts/FACT-xxx.md\` with the invariant (use \`constrains\` + \`requires_property\` for contradiction-safe reasoning)
+- Bug/workaround notes: use \`fact_kind: observation\` or \`meta\` instead — these are non-blocking and excluded from contradiction inference
 - Link it to relevant requirements
-- Reference the FACT in code with a comment
 
-This keeps domain truths centralized and searchable.`;
+This keeps domain truths centralized, searchable, and contradiction-safe.`;
         case "adr":
             return `🎯 **Durable knowledge detected: ADR**
 

package/dist/scheduler.js

@@ -151,6 +151,10 @@ class WorktreeSyncScheduler {
     }
     emitCompletion(trigger, startedAt, exitCode, checkExitCode, checkRules) {
         const durationMs = Math.max(0, this.now() - startedAt);
+        const normalizedReason = trigger.reason.endsWith(".trailing")
+            ? trigger.reason.slice(0, -".trailing".length)
+            : trigger.reason;
+        const isSmartEnforcementSync = normalizedReason.startsWith("smart-enforcement.");
         const meta = {
             reason: trigger.reason,
             worktree: this.worktree,
@@ -164,6 +168,9 @@ class WorktreeSyncScheduler {
         if (exitCode === 0) {
             logger.info(`sync.succeeded ${JSON.stringify(meta)}`);
         }
+        else if (isSmartEnforcementSync) {
+            logger.errorStructuredOnly(`sync.failed ${JSON.stringify(meta)}`);
+        }
         else {
             logger.error(`sync.failed ${JSON.stringify(meta)}`);
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-opencode",
-  "version": "0.7.2",
+  "version": "0.8.0",
   "description": "Kibi OpenCode plugin - thin adapter to integrate Kibi with OpenCode sessions",
   "type": "module",
   "main": "dist/index.js",