kibi-opencode 0.5.4 → 0.6.1

package/dist/path-kind.js

@@ -14,7 +14,7 @@ const KIBI_DOC_PATTERNS = [
 ];
 export function analyzePath(
 // implements REQ-opencode-kibi-plugin-v1
-filePath, cwd) {
+filePath, cwd = process.cwd()) {
     const rel = path.isAbsolute(filePath)
         ? path.relative(cwd, filePath).split(path.sep).join("/")
         : filePath.split(path.sep).join("/");
@@ -46,15 +46,23 @@ filePath, cwd) {
                 else if (patternPrefix.includes("facts"))
                     kind = "fact";
                 else if (patternPrefix.includes("events"))
-                    kind = "fact"; // events map to fact for routing
+                    kind = "event";
                 else if (patternPrefix.includes("flags"))
-                    kind = "fact"; // flags map to fact for routing
+                    kind = "flag";
                 else if (patternPrefix.includes("symbols"))
-                    kind = "fact";
+                    kind = "symbol";
             }
             break;
         }
     }
+    if (kind === "unknown") {
+        const isTestPath = normalized.includes("/__tests__/") ||
+            normalized.startsWith("tests/") ||
+            /(?:^|\/)[^/]+\.(test|spec)\.[^.]+$/i.test(normalized);
+        if (isTestPath) {
+            kind = "test";
+        }
+    }
     // Check for code files
     if (kind === "unknown") {
         const ext = path.extname(rel).toLowerCase();

package/dist/prompt.d.ts

@@ -1,6 +1,9 @@
 import type { CommentAnalysisResult } from "./comment-analysis.js";
 import type { KibiConfig } from "./config.js";
+import type { GuidanceCache } from "./guidance-cache.js";
 import type { PathKind } from "./path-kind.js";
+import type { RepoPosture } from "./repo-posture.js";
+import type { RiskClass } from "./risk-classifier.js";
 import type { WorkspaceHealth } from "./workspace-health.js";
 declare const SENTINEL = "<!-- kibi-opencode -->";
 export interface PromptContext {
@@ -11,9 +14,27 @@ export interface PromptContext {
     workspaceHealth?: WorkspaceHealth;
     hasRecentKbEdit?: boolean;
     recentCommentSuggestion?: CommentAnalysisResult | null;
+    /** Posture detected by repo-posture detection */
+    posture?: RepoPosture;
+    /** Risk class from risk-classifier */
+    riskClass?: RiskClass;
+    /** Cache instance for skip-repeated-guidance */
+    cache?: GuidanceCache;
+    /** Workspace root for cache key */
+    workspaceRoot?: string;
+    /** Branch for cache key */
+    branch?: string;
+    /** Whether to append completion reminder for risky classes */
+    completionReminder?: boolean;
+    /** Merged maintenance-degraded state (static + runtime overlay) */
+    maintenanceDegraded?: boolean;
+    /** Degraded-mode logging policy */
+    degradedMode?: "warn-once" | "structured-only";
+    /** Whether to show the degraded advisory block this invocation */
+    showDegradedAdvisory?: boolean;
 }
 /**
- * Build prompt with contextual guidance based on recent edits and workspace state.
+ * Build prompt with contextual guidance based on posture, risk class, and cache state.
  */
 export declare function buildPrompt(context?: PromptContext): string;
 /**

package/dist/prompt.js

@@ -1,163 +1,339 @@
+import * as path from "node:path";
 import { isPluginEnabled } from "./config.js";
+import { getSourceLinkedRequirementIds } from "./source-linked-guidance.js";
 const SENTINEL = "<!-- kibi-opencode -->";
-/**
- * Build prompt guidance block based on path kind.
- */
-// implements REQ-opencode-kibi-plugin-v1, REQ-opencode-agent-mcp-only
-function buildContextualGuidance(context) {
-    const parts = [SENTINEL];
-    if (context.hasRecentKbEdit) {
-        parts.push(`
-⚠️  **WARNING: Do not edit .kb/** files manually.**
+// ── Token budget enforcement ───────────────────────────────────────────
+const MAX_BULLETS = 5;
+const MAX_WORDS = 117; // Reserve 3 words for sentinel so total injected prompt stays ≤ 120
+function countWords(text) {
+    return text.split(/\s+/).filter(Boolean).length;
+}
+function countBullets(lines) {
+    return lines.filter((l) => l.startsWith("-")).length;
+}
+function enforceBudget(block) {
+    const lines = block.split("\n");
+    if (countBullets(lines) > MAX_BULLETS || countWords(block) > MAX_WORDS) {
+        // Trim to budget: keep header + first MAX_BULLETS bullet lines
+        const header = [];
+        const bullets = [];
+        for (const line of lines) {
+            if (line.startsWith("-") && bullets.length < MAX_BULLETS) {
+                bullets.push(line);
+            }
+            else if (!line.startsWith("-")) {
+                if (bullets.length === 0)
+                    header.push(line);
+            }
+        }
+        const trimmed = [...header, ...bullets].join("\n");
+        if (countWords(trimmed) <= MAX_WORDS)
+            return trimmed;
+        // Hard truncate to MAX_WORDS
+        const words = trimmed.split(/\s+/).slice(0, MAX_WORDS);
+        return words.join(" ");
+    }
+    return block;
+}
+// ── File bucket derivation ─────────────────────────────────────────────
+function deriveFileBucket(pathKind) {
+    return pathKind;
+}
+// ── Guidance blocks by risk class ──────────────────────────────────────
+const GUIDANCE_BY_RISK = {
+    safe_docs_only: null,
+    safe_test_only: null,
+    kb_doc_structural: `📚 **Kibi documentation changes detected**
+
+When editing KB documentation:
+- Maintain traceability — link entities using relationships: specified_by, verified_by, etc.
+- Validate — Use kb_check after making changes to catch integrity issues.
+- Follow entity patterns — ensure each entity has proper frontmatter.`,
+    req_policy_candidate: `📋 **Requirement changes detected**
+
+Requirement edits need policy alignment. Run kb_check with required-fields and no-dangling-refs. For priority:must requirements, also run must-priority-coverage.
+- Keep artifacts separate (REQ, SCEN, TEST)
+- Add verification: create or update linked SCEN and TEST entities`,
+    behavior_candidate: `📝 **Code changes detected**
+
+Code changes need traceability. Use kb_search for context. For test/e2e symbols, prefer durable relationships (e.g. via symbols.yaml with covered_by + validates/verified_by); inline // implements REQ-xxx comments remain optional and backward-compatible.`,
+    traceability_candidate: `📝 **Code changes detected**
 
-The Kibi knowledge base is managed through public MCP tools and internal maintenance flows. Direct manual edits to files under .kb/** can cause inconsistencies and should be avoided.
+Code changes need traceability. Use kb_search for context. For test/e2e symbols, prefer durable relationships (e.g. via symbols.yaml with covered_by + validates/verified_by); inline // implements REQ-xxx comments remain optional and backward-compatible.
+- Durable knowledge comment detected — route to KB instead of inline comments
+- Use kb_upsert for FACT, ADR, or REQ entities as appropriate`,
+    manual_kb_edit: `⚠️  **WARNING: Direct .kb/ edits bypass validation**
 
-Instead:
-- Use kb_search to discover relevant entities
+The Kibi knowledge base is managed through public MCP tools. Direct manual edits to .kb/** can cause inconsistencies.
 - Use kb_upsert to create/update entities
-- Use kb_query for exact lookup and source-linked follow-up
-- Use kb_check to validate consistency
-`);
+- Use kb_delete to remove entities
+- Use kb_check to validate consistency`,
+};
+// ── Posture overrides ──────────────────────────────────────────────────
+function postureGuidance(posture) {
+    switch (posture) {
+        case "vendored_only":
+            // Minimal guidance only, no bootstrap nags
+            return null;
+        case "root_uninitialized":
+            return `🔧 **Bootstrap required**
+
+This repository does not appear to have Kibi initialized. Agents should:
+- Use \`/init-kibi\` for retroactive bootstrap of existing repos (preferred MCP command)
+- Ask the user/operator to run setup or repair outside this session if \`/init-kibi\` is insufficient
+
+Do not run \`kibi\` CLI commands directly; use the public MCP tools (kb_search, kb_query, kb_status, kb_find_gaps, kb_coverage, kb_graph, kb_upsert, kb_delete, kb_check).`;
+        case "root_partial":
+            return `⚠️  **Partial KB setup detected**
+
+Root .kb/config.json exists but some configured KB targets are missing. Guidance remains advisory until the user/operator restores the configured KB targets.`;
+        default:
+            return null;
+    }
+}
+// ── Main guidance builder ──────────────────────────────────────────────
+/**
+ * Build prompt guidance block based on posture, risk class, and cache state.
+ */
+function buildContextualGuidance(context) {
+    const posture = context.posture ?? "root_active";
+    const riskClass = context.riskClass;
+    const showDegraded = context.showDegradedAdvisory === true &&
+        context.maintenanceDegraded === true &&
+        context.degradedMode === "warn-once";
+    // ── Single-block priority selection ──
+    // Priority order (highest wins): manual_kb_edit > posture > risk_class > safe/none
+    let selectedBlock = null;
+    // Priority 1: vendored_only → sentinel only (unless degraded advisory forced)
+    if (posture === "vendored_only" && !showDegraded) {
+        return SENTINEL;
+    }
+    // Priority 2: manual_kb_edit — always fires, never cache-suppressed
+    if (context.hasRecentKbEdit || riskClass === "manual_kb_edit") {
+        selectedBlock = GUIDANCE_BY_RISK.manual_kb_edit;
     }
-    if (context.workspaceHealth?.needsBootstrap) {
-        parts.push(`
-🔧 **Bootstrap required**
+    // Priority 3: Posture warnings for non-active states — not cache-suppressed
+    else if (posture === "root_uninitialized" || posture === "root_partial") {
+        const postureBlock = postureGuidance(posture);
+        if (postureBlock)
+            selectedBlock = postureBlock;
+    }
+    // Priority 4: Legacy workspace health bootstrap (only when no posture) — not cache-suppressed
+    else if (!context.posture && context.workspaceHealth?.needsBootstrap) {
+        selectedBlock = `🔧 **Bootstrap required**
 
 This repository does not appear to have Kibi initialized. Agents should:
 - Use \`/init-kibi\` for retroactive bootstrap of existing repos (preferred MCP command)
 - Ask the user/operator to run setup or repair outside this session if \`/init-kibi\` is insufficient
 
-Do not run \`kibi\` CLI commands directly; use the public MCP tools (kb_search, kb_query, kb_status, kb_find_gaps, kb_coverage, kb_graph, kb_upsert, kb_delete, kb_check).
-`);
+Do not run \`kibi\` CLI commands directly; use the public MCP tools (kb_search, kb_query, kb_status, kb_find_gaps, kb_coverage, kb_graph, kb_upsert, kb_delete, kb_check).`;
     }
-    const codeEdits = context.recentEdits.filter((e) => e.kind === "code");
-    const reqEdits = context.recentEdits.filter((e) => e.kind === "requirement");
-    const kbDocEdits = context.recentEdits.filter((e) => ["requirement", "scenario", "test", "adr", "fact"].includes(e.kind));
-    if (codeEdits.length > 0) {
-        const suggestion = context.recentCommentSuggestion;
-        if (suggestion) {
-            let routingMessage = "";
-            switch (suggestion.suggestionType) {
-                case "fact":
-                    routingMessage = `🎯 **Durable knowledge detected: FACT**
+    // Advisory guidance: check cache before selecting, since these blocks can be safely suppressed
+    else {
+        // Cache check: skip repeated advisory guidance — only after critical signals are handled above
+        // Allow degraded advisory to bypass cache so it is always visible
+        if (!showDegraded &&
+            context.cache &&
+            context.workspaceRoot &&
+            context.branch &&
+            riskClass) {
+            const lastEdit = context.recentEdits[context.recentEdits.length - 1];
+            const key = {
+                workspaceRoot: context.workspaceRoot,
+                branch: context.branch,
+                posture,
+                riskClass,
+                fileBucket: deriveFileBucket(lastEdit?.kind ?? "unknown"),
+            };
+            if (context.cache.isSatisfied(key)) {
+                return SENTINEL; // skip guidance — recently satisfied
+            }
+        }
+        // Priority 5: Risk-class-driven guidance (for non-safe classes)
+        if (riskClass &&
+            riskClass !== "safe_docs_only" &&
+            riskClass !== "safe_test_only") {
+            // For behavior/traceability with comment suggestions, use suggestion guidance
+            if ((riskClass === "behavior_candidate" ||
+                riskClass === "traceability_candidate") &&
+                context.recentCommentSuggestion) {
+                selectedBlock = buildCommentSuggestionGuidance(context.recentCommentSuggestion);
+            }
+            else {
+                const block = GUIDANCE_BY_RISK[riskClass];
+                if (block)
+                    selectedBlock = block;
+            }
+        }
+        // Priority 6: Legacy path-kind fallback (when no risk class)
+        else if (!riskClass) {
+            const codeEdits = context.recentEdits.filter((e) => e.kind === "code");
+            const reqEdits = context.recentEdits.filter((e) => e.kind === "requirement");
+            const kbDocEdits = context.recentEdits.filter((e) => [
+                "requirement",
+                "scenario",
+                "test",
+                "adr",
+                "fact",
+                "flag",
+                "event",
+                "symbol",
+            ].includes(e.kind));
+            if (codeEdits.length > 0) {
+                const suggestion = context.recentCommentSuggestion;
+                if (suggestion) {
+                    selectedBlock = buildCommentSuggestionGuidance(suggestion);
+                }
+                else {
+                    selectedBlock = `📝 **Code changes detected**
+
+Before implementing or explaining code:
+1. **Discover first** - Run kb_search to find related requirements, ADRs, tests, facts, and symbols.
+2. **Follow up exactly** - Run kb_query by sourceFile, id, type, or tags once you know what you need.
+3. **Prefer Kibi over comments** - Store durable knowledge in KB entities instead of inline comments.
+4. **Add traceability** - For test/e2e symbols, prefer durable symbol/test/requirement relationships (e.g. via symbols.yaml with covered_by + validates/verified_by); inline // implements REQ-xxx comments remain optional and backward-compatible for quick code-only changes.
+
+If you're adding long explanatory comments, consider routing that knowledge to:
+- \`FACT\` for domain invariants, properties, limits, cardinalities
+- \`ADR\` for technical decisions, tradeoffs, rationale
+- \`REQ\` for system behavior requirements`;
+                }
+            }
+            else if (reqEdits.length > 0) {
+                selectedBlock = GUIDANCE_BY_RISK.req_policy_candidate;
+            }
+            else if (kbDocEdits.length > 0) {
+                selectedBlock = GUIDANCE_BY_RISK.kb_doc_structural;
+            }
+        }
+    }
+    // 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
+    // before the first bullet.
+    if (selectedBlock &&
+        (riskClass === "behavior_candidate" ||
+            riskClass === "traceability_candidate") &&
+        context.workspaceRoot) {
+        try {
+            const lastEdit = context.recentEdits[context.recentEdits.length - 1];
+            if (lastEdit?.path) {
+                const editedPath = lastEdit.path;
+                const absEdited = path.isAbsolute(editedPath)
+                    ? editedPath
+                    : 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)}`;
+                    }
+                    else {
+                        selectedBlock = `${selectedBlock}\n- Existing Kibi links: ${linkedIds.join(", ")}`;
+                    }
+                }
+            }
+        }
+        catch {
+            // Non-fatal: source-linked brief is best-effort
+        }
+    }
+    // Inject degraded advisory block for warn-once mode
+    if (showDegraded) {
+        const advisory = `⚠️  **Maintenance degraded**
+
+The Kibi workspace is in a maintenance-degraded state. Guidance remains advisory.`;
+        if (selectedBlock) {
+            selectedBlock = `${advisory}\n\n${selectedBlock}`;
+        }
+        else {
+            selectedBlock = advisory;
+        }
+    }
+    // Record cache after generating (advisory, non-blocking)
+    // Do not cache degraded-advisory-only emissions
+    if (!showDegraded &&
+        context.cache &&
+        context.workspaceRoot &&
+        context.branch &&
+        riskClass) {
+        const lastEdit = context.recentEdits[context.recentEdits.length - 1];
+        const key = {
+            workspaceRoot: context.workspaceRoot,
+            branch: context.branch,
+            posture,
+            riskClass,
+            fileBucket: deriveFileBucket(lastEdit?.kind ?? "unknown"),
+        };
+        context.cache.recordSatisfied(key, "guidance");
+    }
+    // Append completion reminder for risky classes when enabled
+    const REMINDER_RISK_CLASSES = [
+        "behavior_candidate",
+        "traceability_candidate",
+        "req_policy_candidate",
+    ];
+    if (selectedBlock &&
+        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.`;
+    }
+    // Return: sentinel + one targeted block (or just sentinel if no block)
+    return selectedBlock
+        ? `${SENTINEL}\n\n${enforceBudget(selectedBlock)}`
+        : SENTINEL;
+}
+// ── Comment suggestion guidance (legacy compat) ────────────────────────
+function buildCommentSuggestionGuidance(suggestion) {
+    switch (suggestion.suggestionType) {
+        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).
 
 **Action**: Instead of inline comments, route this to a FACT entity:
 - Create \`documentation/facts/FACT-xxx.md\` with the invariant
-- Link it to relevant requirements using \`constrains\` or \`requires_property\` relationships
-- Reference the FACT in code with a comment (e.g., \`// constrained by FACT-xxx\` in JS/TS or a docstring comment in Python)
+- Link it to relevant requirements
+- Reference the FACT in code with a comment
 
 This keeps domain truths centralized and searchable.`;
-                    break;
-                case "adr":
-                    routingMessage = `🎯 **Durable knowledge detected: ADR**
+        case "adr":
+            return `🎯 **Durable knowledge detected: ADR**
 
 Your recent code edit contains a comment that looks like a **technical decision** (tradeoffs, rationale, or architecture choices).
 
 **Action**: Instead of inline comments, route this to an ADR entity:
 - Create \`documentation/adr/ADR-xxx.md\` documenting the decision
 - Include context, options considered, and the chosen approach
-- Link to constrained code symbols using \`constrained_by\` relationships
+- Link to constrained code symbols
 
 This preserves decision context for future maintainers.`;
-                    break;
-                case "req":
-                    routingMessage = `🎯 **Durable knowledge detected: REQ**
+        case "req":
+            return `🎯 **Durable knowledge detected: REQ**
 
 Your recent code edit contains a comment that looks like **behavior intent** (system capabilities or user-facing requirements).
 
 **Action**: Instead of inline comments, route this to a REQ entity:
 - Create \`documentation/requirements/REQ-xxx.md\` with the behavior description
 - Add SCEN and TEST entities for specification and verification
-- Link code to requirements using traceability comments (e.g., \`// implements REQ-xxx\` in JS/TS or docstring references in Python)
+- Link code to requirements: for test/e2e symbols prefer durable relationships (e.g. via symbols.yaml with covered_by + validates/verified_by); inline // implements REQ-xxx comments remain optional and backward-compatible
 
 This ensures behavior is documented and traceable.`;
-                    break;
-                default:
-                    routingMessage = `📝 **Code changes detected**
-
-Before implementing or explaining code:
-1. **Discover first** - Run kb_search to find related requirements, ADRs, tests, facts, and symbols.
-2. **Follow up exactly** - Run kb_query by sourceFile, id, type, or tags once you know what you need.
-3. **Check freshness when needed** - Run kb_status if you need branch or stale-state confirmation.
-4. **Prefer Kibi over comments** - Store durable knowledge in KB entities instead of inline comments.
-5. **Add traceability** - Add traceability comments to new or modified functions/classes so the pre-commit hook can verify coverage (e.g., \`// implements REQ-xxx\` in JS/TS or docstring references in Python).`;
-            }
-            parts.push(routingMessage);
-        }
-        else {
-            parts.push(`
-📝 **Code changes detected**
+        default:
+            return `📝 **Code changes detected**
 
 Before implementing or explaining code:
 1. **Discover first** - Run kb_search to find related requirements, ADRs, tests, facts, and symbols.
 2. **Follow up exactly** - Run kb_query by sourceFile, id, type, or tags once you know what you need.
-3. **Check freshness when needed** - Run kb_status if you need branch or stale-state confirmation.
-4. **Prefer Kibi over comments** - Store durable knowledge in KB entities instead of inline comments.
-5. **Add traceability** - Add traceability comments to new or modified functions/classes (e.g., \`// implements REQ-xxx\` in JS/TS or docstring references in Python) so the pre-commit hook can verify coverage.
-
-If you're adding long explanatory comments, consider routing that knowledge to:
-- \`FACT\` for domain invariants, properties, limits, cardinalities
-- \`ADR\` for technical decisions, tradeoffs, rationale
-- \`REQ\` for system behavior requirements
-- \`SCEN\` for behavior examples and flows
-- \`TEST\` for verification intent
-`);
-        }
-    }
-    if (reqEdits.length > 0) {
-        parts.push(`
-📋 **Requirement changes detected**
-
-When editing requirements:
-1. **Keep artifacts separate** - Do not embed scenarios or tests inside requirement files.
-2. **Add verification** - Create or update linked \`SCEN\` and \`TEST\` entities.
-3. **Check coverage** - For \`priority: must\` requirements, ensure both scenario and test coverage.
-
-Preferred structure:
-- \`REQ-xxx.md\` contains the requirement statement
-- \`SCEN-xxx.md\` specifies behavior via Given/When/Then
-- \`TEST-xxx.md\` verifies the requirement
-`);
-    }
-    if (kbDocEdits.length > 0 && reqEdits.length === 0) {
-        parts.push(`
-📚 **Kibi documentation changes detected**
-
-When editing KB documentation:
-1. **Maintain traceability** - Link entities using relationships: specified_by (req→scenario), verified_by (req→test), etc.
-2. **Validate** - Use \`kb_check\` after making changes to catch integrity issues.
-3. **Follow entity patterns** - Ensure each entity has proper frontmatter with required fields.
-`);
-    }
-    if (parts.length === 1) {
-        parts.push(`This project uses Kibi (via MCP). Prefer storing durable knowledge in Kibi over code comments.
-
-Before changing behavior: use kb_search for discovery, then kb_query by sourceFile, id, type, or tags for exact follow-up; do not rely on undocumented tools.
-
-Keep changed symbols traceable: add \`// implements REQ-xxx\` to every new or modified function/class so the pre-commit hook can verify coverage.
-
-Run kb_check after KB mutations.
-
-Dogfood note for this repo: OpenCode here uses local built \`kibi-mcp\` and \`kibi-opencode\` artifacts. If you change package versions or local package wiring, run \`bun run build\` before relying on OpenCode in this workspace.
-
-**Kibi-first workflow:**
-1. **Discover**: Run kb_search to find relevant requirements, ADRs, tests, facts, and symbols.
-2. **Confirm**: Run kb_query with sourceFile, id, type, or tags once you know the exact follow-up target.
-3. **Inspect freshness**: Run kb_status when branch or stale-state confidence matters.
-4. **Document intent**: If you are about to explain code, STOP. Route that explanation to kb_upsert instead of inline comments.
-5. **Link during work**: When creating KB entities, include relationship rows: specified_by (req→scenario), verified_by (req→test), implements (symbol→req), covered_by (symbol→test).
-6. **Validate**: Run kb_check after KB mutations to catch violations early.
-
-**Public Kibi tools only:** kb_search, kb_query, kb_status, kb_find_gaps, kb_coverage, kb_graph, kb_upsert, kb_delete, kb_check.
-
-Do not invoke Kibi CLI commands directly from the agent.
-
-Bootstrap existing repos: use \`/init-kibi\` to run the retroactive initialization workflow.`);
+3. **Prefer Kibi over comments** - Store durable knowledge in KB entities instead of inline comments.
+4. **Add traceability** - For test/e2e symbols, prefer durable symbol/test/requirement relationships (e.g. via symbols.yaml with covered_by + validates/verified_by); inline // implements REQ-xxx comments remain optional and backward-compatible for quick code-only changes.`;
     }
-    return parts.join("\n\n").trim();
 }
+// ── Base guidance (no context) ─────────────────────────────────────────
 /**
  * Build the static guidance block (original behavior).
  */
@@ -166,7 +342,7 @@ This project uses Kibi (via MCP). Prefer storing durable knowledge in Kibi over
 
 Before changing behavior: use kb_search for discovery, then kb_query by sourceFile, id, type, or tags for exact follow-up; do not rely on undocumented tools.
 
-Keep changed symbols traceable: add \`// implements REQ-xxx\` to every new or modified function/class so the pre-commit hook can verify coverage.
+Keep changed symbols traceable: for test and e2e code, prefer durable symbol/test/requirement relationships (e.g. via \`symbols.yaml\`); inline \`// implements REQ-xxx\` comments remain optional and backward-compatible for quick code-only changes.
 
 Run kb_check after KB mutations.
 
@@ -186,7 +362,7 @@ Do not invoke Kibi CLI commands directly from the agent.
 
 Bootstrap existing repos: use \`/init-kibi\` to run the retroactive initialization workflow.`;
 /**
- * Build prompt with contextual guidance based on recent edits and workspace state.
+ * Build prompt with contextual guidance based on posture, risk class, and cache state.
  */
 export function buildPrompt(context) {
     if (!context) {

package/dist/repo-posture.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Classification of the repository's Kibi posture — how Kibi is (or isn't)
+ * set up relative to the active workspace root.
+ */
+export type RepoPosture = "root_active" | "root_partial" | "root_uninitialized" | "vendored_only" | "hybrid_root_plus_vendored";
+export interface PostureResult {
+    state: RepoPosture;
+    needsBootstrap: boolean;
+    reason: string;
+    maintenanceDegraded: boolean;
+}
+export declare function detectPosture(cwd: string): PostureResult;