kibi-cursor 0.2.0 → 0.2.2

package/.cursor-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "kibi-cursor",
   "displayName": "Kibi",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Optional Cursor adapter for Kibi. Requires SWI-Prolog 9+ and project-local kibi-cli, kibi-mcp, and kibi-core before the bundled MCP server can start.",
   "license": "AGPL-3.0-or-later",
   "author": {

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # kibi-cursor
 
+## 0.2.2
+
+### Patch Changes
+
+- Kibi now gives agents clearer guidance for the diagnostics flow, so the release notes should reflect that the bundled usage text and MCP logging story were tightened together.
+
+  This update also keeps the package mirrors aligned where applicable, which helps downstream plugin consumers stay in sync with the canonical guidance.
+
+  - Hardened bundled skill guidance for kibi usage.
+  - Improved MCP diagnostic logging shape and validation hints.
+  - Synced packaged skill copies where they are shipped with the release.
+
+## 0.2.1
+
+### Patch Changes
+
+- 5d2975a: Cursor stop hooks no longer inject a long multi-line Kibi freshness reminder after every agent response. Follow-ups are now one line, and most sessions stay silent.
+
+  - Track `kb_upsert`, `kb_delete`, and `kb_check` MCP usage during the session.
+  - Emit no stop follow-up when nothing KB-relevant changed, or when `kb_check` already ran after edits.
+  - Emit a short summary (`Kibi KB updated (kb_upsert).`) after KB mutations, or a single-line sync nudge when source files changed without KB activity.
+  - Fix publish workflow to build and pack `kibi-cursor` tarballs before npm publish.
+
+- Cursor sessions now use Cursor's documented workspace root payload when deciding whether Kibi is already configured. This prevents the plugin from telling agents that Kibi needs bootstrapping just because the hook process is running from the plugin install directory instead of the actual workspace. The bootstrap reminder now names the missing `.kb/config.json` condition directly instead of implying MCP is unavailable.
+
+  - Parse `workspace_roots` from Cursor hook payloads and prefer the first workspace root for Kibi config detection.
+  - Add a regression test covering `sessionStart` without `cwd` when `workspace_roots` points at a configured workspace.
+  - Reword the bootstrap reminder to describe a missing workspace config rather than generic initialization failure.
+
 ## 0.2.0
 
 ### Minor Changes

package/dist/.cursor-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "kibi-cursor",
   "displayName": "Kibi",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Optional Cursor adapter for Kibi. Requires SWI-Prolog 9+ and project-local kibi-cli, kibi-mcp, and kibi-core before the bundled MCP server can start.",
   "license": "AGPL-3.0-or-later",
   "author": {

package/dist/hook-input.d.ts

@@ -2,6 +2,7 @@ export type HookEvent = "sessionStart" | "preToolUse" | "postToolUse" | "beforeR
 export type HookInput = {
     event: string;
     cwd?: string;
+    workspaceRoots?: readonly string[];
     toolName?: string;
     toolInput?: unknown;
     conversationId?: string;

package/dist/hook-input.js

@@ -10,6 +10,19 @@ function readString(record, keys) {
     }
     return undefined;
 }
+function readStringArray(record, keys) {
+    for (const key of keys) {
+        const value = record[key];
+        if (!Array.isArray(value)) {
+            continue;
+        }
+        const strings = value.filter((item) => typeof item === "string" && item.length > 0);
+        if (strings.length > 0) {
+            return strings;
+        }
+    }
+    return undefined;
+}
 function normalizeEventName(event) {
     const trimmed = event.trim();
     if (trimmed.length === 0) {
@@ -34,6 +47,10 @@ export function parseHookInput(input) {
         "current_working_directory",
         "workspace",
     ]);
+    const workspaceRoots = readStringArray(input, [
+        "workspace_roots",
+        "workspaceRoots",
+    ]);
     const toolName = readString(input, ["toolName", "tool_name", "tool"]);
     const toolInput = input.toolInput ?? input.tool_input ?? input.input;
     const conversationId = readString(input, [
@@ -45,6 +62,9 @@ export function parseHookInput(input) {
     if (cwd !== undefined) {
         parsed.cwd = cwd;
     }
+    if (workspaceRoots !== undefined) {
+        parsed.workspaceRoots = workspaceRoots;
+    }
     if (toolName !== undefined) {
         parsed.toolName = toolName;
     }

package/dist/hook-runner.js

@@ -5,8 +5,8 @@ import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { readGuidance, writeGuidance } from "./guidance.js";
 import { parseHookInput, parseStdinJson, readStdin } from "./hook-input.js";
-import { extractKbMcpToolName } from "./kb-mcp-tools.js";
 import { addDirtyPaths, clearSessionHookState, hasGuidedPath, loadHookState, recordKbMcpTool, rememberGuidedPath, resolveStateDir, } from "./hook-state.js";
+import { extractKbMcpToolName } from "./kb-mcp-tools.js";
 import { BOOTSTRAP_REMINDER, DIRECT_KB_EDIT_WARNING, stopFollowupMessage, } from "./messages.js";
 import { extractExplicitPathFields, isDirectKbPath, isMeaningfulTrackedPath, toRepoRelativePath, } from "./path-policy.js";
 const editableTools = new Set([
@@ -33,7 +33,7 @@ function isReadLikeTool(toolName) {
     return toolName === undefined || readTools.has(toolName);
 }
 function resolveWorkspaceRoot(input) {
-    return input.cwd ?? process.cwd();
+    return input.workspaceRoots?.[0] ?? input.cwd ?? process.cwd();
 }
 function resolvePrimaryPath(input) {
     if (input.filePath) {

package/dist/hook-state.js

@@ -231,7 +231,9 @@ export function recordKbMcpTool(stateDir, toolName) {
         if (normalized === "kb_upsert" || normalized === "kb_delete") {
             return {
                 ...state,
-                kbMutationTools: mergeStringPaths(state.kbMutationTools, [normalized]).slice(-maxKbMutationTools),
+                kbMutationTools: mergeStringPaths(state.kbMutationTools, [
+                    normalized,
+                ]).slice(-maxKbMutationTools),
             };
         }
         return state;

package/dist/kb-mcp-tools.js

@@ -27,7 +27,11 @@ export function extractKbMcpToolName(toolName, toolInput) {
     }
     const nestedArgs = toolInput.arguments ?? toolInput.args;
     if (isRecord(nestedArgs)) {
-        const nestedTool = readString(nestedArgs, ["toolName", "tool_name", "name"]);
+        const nestedTool = readString(nestedArgs, [
+            "toolName",
+            "tool_name",
+            "name",
+        ]);
         if (nestedTool?.startsWith("kb_")) {
             return nestedTool;
         }

package/dist/messages.d.ts

@@ -1,5 +1,5 @@
 import type { HookState } from "./hook-state.js";
-export declare const BOOTSTRAP_REMINDER = "Kibi is not initialized for this workspace. Use the Kibi MCP workflow to bootstrap project memory before relying on KB lookups; do not edit .kb/ files directly.";
+export declare const BOOTSTRAP_REMINDER = "Kibi config was not found at the Cursor workspace root. Use the Kibi MCP /init-kibi workflow to bootstrap project memory before relying on KB lookups; do not edit .kb/ files directly.";
 export declare const DIRECT_KB_EDIT_WARNING = "Avoid direct edits to .kb/. Use Kibi MCP tools for KB discovery and mutations so project memory stays valid.";
 export declare function stopFollowupMessage(state: HookState): string | undefined;
 /** @deprecated Use stopFollowupMessage */

package/dist/messages.js

@@ -1,5 +1,5 @@
 import { isKbFreshnessRelevantPath } from "./path-policy.js";
-export const BOOTSTRAP_REMINDER = "Kibi is not initialized for this workspace. Use the Kibi MCP workflow to bootstrap project memory before relying on KB lookups; do not edit .kb/ files directly.";
+export const BOOTSTRAP_REMINDER = "Kibi config was not found at the Cursor workspace root. Use the Kibi MCP /init-kibi workflow to bootstrap project memory before relying on KB lookups; do not edit .kb/ files directly.";
 export const DIRECT_KB_EDIT_WARNING = "Avoid direct edits to .kb/. Use Kibi MCP tools for KB discovery and mutations so project memory stays valid.";
 export function stopFollowupMessage(state) {
     if (state.kbMutationTools.length > 0) {

package/dist/skills/kibi-usage/SKILL.md

@@ -1,23 +1,216 @@
 ---
-name: kibi-usage
-description: Use Kibi MCP discovery tools to find relevant requirements and context before editing code.
+id: kibi-usage
+name: Kibi Usage
+description: Guides agents to use Kibi MCP, facts, relationships, and validation correctly
+version: 1.0.0
+kibiCompatibility: ">=0.11.0"
+tags:
+  - kibi
+  - mcp
+  - knowledge-base
+  - traceability
+  - agent-guidance
+resources:
+  - resources/relationship-directions.md
+  - resources/fact-lanes.md
+  - resources/workflows.md
 ---
 
-## Goal
+# Kibi Usage
 
-Help an agent discover existing knowledge in Kibi before making changes.
+Consult this skill before any Kibi knowledge base operation, on first interaction with a Kibi-enabled repo, after detecting stale or dirty KB status, and before performing mutations.
 
-## MCP workflow
+## MCP-Only Rules
 
-- Start with `kb_search` using domain keywords and requirement intent.
-- Move to `kb_query` for exact entity retrieval by `id` or `type`.
-- Use `kb_status` when context is stale or branch linkage is unclear.
-- Use curated reports only when the question needs them: `kb_find_gaps`, `kb_coverage`, or `kb_graph`.
-- Mutate only through `kb_upsert` or `kb_delete`, then validate with `kb_check`.
+Interact with the knowledge base exclusively through MCP tools. Do not read or edit files inside `.kb/` directly. Do not run any `kibi` CLI commands from the agent session. The MCP surface is the only sanctioned interface for agents.
 
-## Guidance
+### Tool Name Prefixes
 
-- Prefer source-linked lookups and traceability-aware retrieval via `kb_query` filters.
-- Never open or patch files under `.kb/` directly.
-- When unsure about scope, re-run `kb_search` with tighter terms, then validate with `kb_query`.
-- Report the KB outcome before completion: updated, no-impact with rationale, or deferred/failed.
+Kibi's canonical MCP names are `kb_search`, `kb_query`, `kb_upsert`, `kb_check`, and related `kb_*` tools. Some hosts add a server prefix when exposing tools to agents. In OpenCode, use the visible `kibi_kb_search`, `kibi_kb_query`, `kibi_kb_upsert`, and `kibi_kb_check` names when exact tool identifiers are required; they map to the same canonical MCP names.
+
+## Discovery-First Workflow
+
+Always discover before you mutate. Start with `kb_search` for exploratory discovery across metadata and markdown body text. Split broad queries into 1-3 focused probes. Review top hits for relevance before concluding the KB lacks knowledge.
+
+Follow up with `kb_query` for exact lookups by `id`, `type`, `tags`, or `sourceFile`. Call `kb_status` to inspect branch attachment and freshness when stale context would affect decisions. Only after discovery and confirmation should you mutate.
+
+## Relationship Directions
+
+Relationship direction is fixed and semantic. Getting it wrong breaks traceability queries and validation.
+
+| Relationship | Direction | Meaning |
+|-------------|-----------|---------|
+| `implements` | symbol -> req | Symbol owns or implements requirement behavior |
+| `specified_by` | req -> scenario | Requirement is specified by a scenario |
+| `verified_by` | req/scenario -> test | Requirement or scenario is verified by a test |
+| `validates` | test -> req/scenario | Test validates a requirement or scenario |
+| `executable_for` | symbol -> test | Symbol is executable test code for a test entity |
+| `constrains` | req -> fact(subject) | Requirement constrains a domain fact |
+| `requires_property` | req -> fact(property_value) | Requirement requires a property value |
+| `supersedes` | old-req -> new-req | Old requirement is replaced by new requirement |
+| `covered_by` | symbol -> test | Production symbol has coverage evidence from a test |
+
+See `resources/relationship-directions.md` for detailed payload examples.
+
+## Symbol-First Traceability
+
+Trace code through `symbol` entities, not inline legacy comments. Do not use legacy `// implements REQ-xxx` comments as the primary marker for new or modified code. If a symbol is new or its requirement ownership changes, create or update the `symbol` entity and add an `implements` relationship from the symbol to the requirement.
+
+Use comments only as a temporary backward-compatibility fallback when the symbol manifest cannot be updated in the same task. Prefer durable symbol coordinates in `documentation/symbols.yaml` and `documentation/symbol-coordinates.yaml`, then link those symbols through MCP relationships.
+
+```yaml
+# Preferred traceability model
+symbol:
+  id: SYM-admin-billing-policy
+  title: Admin billing policy check
+  status: active
+relationships:
+  - type: implements
+    from: SYM-admin-billing-policy
+    to: REQ-ADMIN-BILLING-POLICY
+```
+
+## Strict Fact Lane
+
+Normative requirements that must participate in contradiction blocking use the strict fact lane. Create a `fact_kind: subject` fact and link it from the requirement via `constrains`. Create a `fact_kind: property_value` fact and link it via `requires_property`.
+
+```yaml
+# Fact entity
+id: FACT-USER-ROLE
+title: User Role Assignment
+status: active
+fact_kind: subject
+subject_key: user.role_assignment
+
+# Requirement entity
+id: REQ-019
+title: Users can have up to 3 roles
+status: open
+relationships:
+  - type: constrains
+    from: REQ-019
+    to: FACT-USER-ROLE
+  - type: requires_property
+    from: REQ-019
+    to: FACT-LIMIT-3
+```
+
+See `resources/fact-lanes.md` for the full strict vs observation lane comparison.
+
+### Granular fact examples for coherence checks
+
+Model one semantic claim per strict `property_value` fact. Reusing the same `subject_key` and `property_key` lets `domain-contradictions` compare requirements mechanically.
+
+Incoherent role-set example: `REQ-ROLE-SET-2` says the allowed user roles are exactly `[user, admin]`, while `REQ-ROLE-SET-3` says the same property is exactly `[user, admin, superadmin]`. Both constrain `FACT-USER-ROLES` and require different values for `user.roles.allowed_set`, so they cannot both be current.
+
+```yaml
+subject:
+  id: FACT-USER-ROLES
+  fact_kind: subject
+  subject_key: user.roles
+
+property_values:
+  - id: FACT-USER-ROLES-ALLOWED-2
+    fact_kind: property_value
+    subject_key: user.roles
+    property_key: user.roles.allowed_set
+    operator: eq
+    value_type: list
+    value_json: '["user", "admin"]'
+  - id: FACT-USER-ROLES-ALLOWED-3
+    fact_kind: property_value
+    subject_key: user.roles
+    property_key: user.roles.allowed_set
+    operator: eq
+    value_type: list
+    value_json: '["user", "admin", "superadmin"]'
+
+requirements:
+  - id: REQ-ROLE-SET-2
+    relationships:
+      - { type: constrains, from: REQ-ROLE-SET-2, to: FACT-USER-ROLES }
+      - { type: requires_property, from: REQ-ROLE-SET-2, to: FACT-USER-ROLES-ALLOWED-2 }
+  - id: REQ-ROLE-SET-3
+    relationships:
+      - { type: constrains, from: REQ-ROLE-SET-3, to: FACT-USER-ROLES }
+      - { type: requires_property, from: REQ-ROLE-SET-3, to: FACT-USER-ROLES-ALLOWED-3 }
+```
+
+Incoherent permission example: `REQ-ADMIN-CAN-MANAGE-BILLING` says `admin` can manage billing, while `REQ-ONLY-SUPERADMIN-MANAGES-BILLING` says the only allowed actor is `superadmin`. Model both against `billing.manage.allowed_actor` with `operator: eq` so the conflict is explicit.
+
+```yaml
+property_values:
+  - id: FACT-BILLING-MANAGE-ACTOR-ADMIN
+    fact_kind: property_value
+    subject_key: billing.manage
+    property_key: billing.manage.allowed_actor
+    operator: eq
+    value_type: string
+    value_string: admin
+  - id: FACT-BILLING-MANAGE-ACTOR-SUPERADMIN
+    fact_kind: property_value
+    subject_key: billing.manage
+    property_key: billing.manage.allowed_actor
+    operator: eq
+    value_type: string
+    value_string: superadmin
+```
+
+If a new requirement intentionally changes a value, create a replacement requirement and link the old requirement to the new one with `supersedes` instead of leaving two current contradictory requirements.
+
+## Fact vs Flag
+
+Use `flag` for runtime or config gates only. Feature flags, kill-switches, and deferred capabilities are valid `flag` entities.
+
+Bugs, incidents, and workarounds belong in `fact` entities with `fact_kind: observation` or `meta`. These fact kinds are excluded from contradiction inference, making them appropriate for non-blocking evidence.
+
+Anti-example: do not create a `flag` named `BUG-123` to track a defect. Create a `fact` with `fact_kind: observation` instead.
+
+## Create-Before-Link
+
+Always confirm or create endpoint entities before linking them. Query target IDs with `kb_query` first. If an endpoint does not exist, create it with `kb_upsert` before creating the relationship. Creating relationships to non-existent entities produces dangling references that `kb_check` will flag.
+
+For `kb_upsert`, keep relationship rows anchored to the entity you are upserting: each row's `from` must equal the upserted entity ID. If you need a `SYM -> REQ` link, upsert the symbol endpoint first, then link that symbol to the requirement.
+
+Keep symbol payloads minimal: include only the fields needed to identify the symbol, its status, and its source traceability. Put extra prose, examples, or audit notes in docs or evidence files instead of custom `kb_upsert.properties`; strict `kb_upsert.properties` rejects unknown fields.
+
+When a generic `Query failed` appears, do not keep retrying the same payload. First call `kb_validate_upsert`, query or create the missing endpoints, reduce the payload to the minimum required fields, and retry once. If it still fails, report the blocker instead of looping.
+
+## Sequential Upserts
+
+Never fire `kb_upsert` calls in parallel. Execute them sequentially to avoid lock contention and ensure deterministic ordering. This is especially important when creating chains of related entities.
+
+## Targeted and Final Checks
+
+Run `kb_check` with specific rules during iteration for fast feedback. For example, use `rules: ["required-fields", "no-dangling-refs"]` after small changes. Run a full `kb_check` without rule filters before declaring work complete.
+
+## Domain Contradictions and Evolution
+
+The `domain-contradictions` rule detects conflicts between strict-lane facts linked to requirements. When a contradiction is found, the supported escape hatch is `supersedes`: create a new requirement that supersedes the old one, then link the new requirement to updated facts.
+
+Use `kb_model_requirement` for automated strict-fact modeling. It generates the subject and property_value facts, links them via `constrains` and `requires_property`, and handles low-confidence downgrades to `observation` facts automatically.
+
+## Stale or Dirty KB Handling
+
+Call `kb_status` when you suspect the branch KB is stale or when switching context. Report freshness findings to the user rather than relying on outdated KB context. If `kb_status` indicates a schema migration is needed, ask the user or operator to handle it outside the agent session.
+
+## Anti-Patterns and Remediation
+
+| Anti-Pattern | Problem | Remediation |
+|-------------|---------|-------------|
+| Reversed relationship direction | Traceability queries break | Verify direction against the relationship table above |
+| Legacy implements comments | Comments are not durable queryable symbols | Create or update a `symbol` entity and link it to the requirement |
+| Bug-as-flag | `flag` misused for defect tracking | Use `fact` with `fact_kind: observation` or `meta` |
+| Parallel upserts | Lock contention and nondeterminism | Execute `kb_upsert` calls sequentially |
+| Embedded scenarios in reqs | Violates canonical traceability chain | Create separate `req`, `scen`, and `test` entities |
+| Missing `kb_check` | Undetected dangling refs and violations | Run targeted checks during work, full check at completion |
+| Tags as multi-ID lookup | Tags are metadata, not identifiers | Use `kb_query` with explicit `id` values |
+| `relates_to` for strict modeling | Loses contradiction safety | Use `constrains` and `requires_property` instead |
+| `status: implemented` on requirements | Not a valid lifecycle status | Use a valid status such as `closed`, add an `implemented` tag, and link evidence instead |
+
+Before/after for reversed direction:
+
+- Wrong: `relationships: [{ type: "implements", from: "REQ-001", to: "SYM-001" }]`
+- Right: `relationships: [{ type: "implements", from: "SYM-001", to: "REQ-001" }]`
+
+See `resources/workflows.md` for the golden-path discovery to validation sequence.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-cursor",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Kibi Cursor plugin - thin adapter for Cursor MCP integration and editor hooks",
   "type": "module",
   "main": "dist/index.js",

package/skills/kibi-usage/SKILL.md

@@ -1,23 +1,216 @@
 ---
-name: kibi-usage
-description: Use Kibi MCP discovery tools to find relevant requirements and context before editing code.
+id: kibi-usage
+name: Kibi Usage
+description: Guides agents to use Kibi MCP, facts, relationships, and validation correctly
+version: 1.0.0
+kibiCompatibility: ">=0.11.0"
+tags:
+  - kibi
+  - mcp
+  - knowledge-base
+  - traceability
+  - agent-guidance
+resources:
+  - resources/relationship-directions.md
+  - resources/fact-lanes.md
+  - resources/workflows.md
 ---
 
-## Goal
+# Kibi Usage
 
-Help an agent discover existing knowledge in Kibi before making changes.
+Consult this skill before any Kibi knowledge base operation, on first interaction with a Kibi-enabled repo, after detecting stale or dirty KB status, and before performing mutations.
 
-## MCP workflow
+## MCP-Only Rules
 
-- Start with `kb_search` using domain keywords and requirement intent.
-- Move to `kb_query` for exact entity retrieval by `id` or `type`.
-- Use `kb_status` when context is stale or branch linkage is unclear.
-- Use curated reports only when the question needs them: `kb_find_gaps`, `kb_coverage`, or `kb_graph`.
-- Mutate only through `kb_upsert` or `kb_delete`, then validate with `kb_check`.
+Interact with the knowledge base exclusively through MCP tools. Do not read or edit files inside `.kb/` directly. Do not run any `kibi` CLI commands from the agent session. The MCP surface is the only sanctioned interface for agents.
 
-## Guidance
+### Tool Name Prefixes
 
-- Prefer source-linked lookups and traceability-aware retrieval via `kb_query` filters.
-- Never open or patch files under `.kb/` directly.
-- When unsure about scope, re-run `kb_search` with tighter terms, then validate with `kb_query`.
-- Report the KB outcome before completion: updated, no-impact with rationale, or deferred/failed.
+Kibi's canonical MCP names are `kb_search`, `kb_query`, `kb_upsert`, `kb_check`, and related `kb_*` tools. Some hosts add a server prefix when exposing tools to agents. In OpenCode, use the visible `kibi_kb_search`, `kibi_kb_query`, `kibi_kb_upsert`, and `kibi_kb_check` names when exact tool identifiers are required; they map to the same canonical MCP names.
+
+## Discovery-First Workflow
+
+Always discover before you mutate. Start with `kb_search` for exploratory discovery across metadata and markdown body text. Split broad queries into 1-3 focused probes. Review top hits for relevance before concluding the KB lacks knowledge.
+
+Follow up with `kb_query` for exact lookups by `id`, `type`, `tags`, or `sourceFile`. Call `kb_status` to inspect branch attachment and freshness when stale context would affect decisions. Only after discovery and confirmation should you mutate.
+
+## Relationship Directions
+
+Relationship direction is fixed and semantic. Getting it wrong breaks traceability queries and validation.
+
+| Relationship | Direction | Meaning |
+|-------------|-----------|---------|
+| `implements` | symbol -> req | Symbol owns or implements requirement behavior |
+| `specified_by` | req -> scenario | Requirement is specified by a scenario |
+| `verified_by` | req/scenario -> test | Requirement or scenario is verified by a test |
+| `validates` | test -> req/scenario | Test validates a requirement or scenario |
+| `executable_for` | symbol -> test | Symbol is executable test code for a test entity |
+| `constrains` | req -> fact(subject) | Requirement constrains a domain fact |
+| `requires_property` | req -> fact(property_value) | Requirement requires a property value |
+| `supersedes` | old-req -> new-req | Old requirement is replaced by new requirement |
+| `covered_by` | symbol -> test | Production symbol has coverage evidence from a test |
+
+See `resources/relationship-directions.md` for detailed payload examples.
+
+## Symbol-First Traceability
+
+Trace code through `symbol` entities, not inline legacy comments. Do not use legacy `// implements REQ-xxx` comments as the primary marker for new or modified code. If a symbol is new or its requirement ownership changes, create or update the `symbol` entity and add an `implements` relationship from the symbol to the requirement.
+
+Use comments only as a temporary backward-compatibility fallback when the symbol manifest cannot be updated in the same task. Prefer durable symbol coordinates in `documentation/symbols.yaml` and `documentation/symbol-coordinates.yaml`, then link those symbols through MCP relationships.
+
+```yaml
+# Preferred traceability model
+symbol:
+  id: SYM-admin-billing-policy
+  title: Admin billing policy check
+  status: active
+relationships:
+  - type: implements
+    from: SYM-admin-billing-policy
+    to: REQ-ADMIN-BILLING-POLICY
+```
+
+## Strict Fact Lane
+
+Normative requirements that must participate in contradiction blocking use the strict fact lane. Create a `fact_kind: subject` fact and link it from the requirement via `constrains`. Create a `fact_kind: property_value` fact and link it via `requires_property`.
+
+```yaml
+# Fact entity
+id: FACT-USER-ROLE
+title: User Role Assignment
+status: active
+fact_kind: subject
+subject_key: user.role_assignment
+
+# Requirement entity
+id: REQ-019
+title: Users can have up to 3 roles
+status: open
+relationships:
+  - type: constrains
+    from: REQ-019
+    to: FACT-USER-ROLE
+  - type: requires_property
+    from: REQ-019
+    to: FACT-LIMIT-3
+```
+
+See `resources/fact-lanes.md` for the full strict vs observation lane comparison.
+
+### Granular fact examples for coherence checks
+
+Model one semantic claim per strict `property_value` fact. Reusing the same `subject_key` and `property_key` lets `domain-contradictions` compare requirements mechanically.
+
+Incoherent role-set example: `REQ-ROLE-SET-2` says the allowed user roles are exactly `[user, admin]`, while `REQ-ROLE-SET-3` says the same property is exactly `[user, admin, superadmin]`. Both constrain `FACT-USER-ROLES` and require different values for `user.roles.allowed_set`, so they cannot both be current.
+
+```yaml
+subject:
+  id: FACT-USER-ROLES
+  fact_kind: subject
+  subject_key: user.roles
+
+property_values:
+  - id: FACT-USER-ROLES-ALLOWED-2
+    fact_kind: property_value
+    subject_key: user.roles
+    property_key: user.roles.allowed_set
+    operator: eq
+    value_type: list
+    value_json: '["user", "admin"]'
+  - id: FACT-USER-ROLES-ALLOWED-3
+    fact_kind: property_value
+    subject_key: user.roles
+    property_key: user.roles.allowed_set
+    operator: eq
+    value_type: list
+    value_json: '["user", "admin", "superadmin"]'
+
+requirements:
+  - id: REQ-ROLE-SET-2
+    relationships:
+      - { type: constrains, from: REQ-ROLE-SET-2, to: FACT-USER-ROLES }
+      - { type: requires_property, from: REQ-ROLE-SET-2, to: FACT-USER-ROLES-ALLOWED-2 }
+  - id: REQ-ROLE-SET-3
+    relationships:
+      - { type: constrains, from: REQ-ROLE-SET-3, to: FACT-USER-ROLES }
+      - { type: requires_property, from: REQ-ROLE-SET-3, to: FACT-USER-ROLES-ALLOWED-3 }
+```
+
+Incoherent permission example: `REQ-ADMIN-CAN-MANAGE-BILLING` says `admin` can manage billing, while `REQ-ONLY-SUPERADMIN-MANAGES-BILLING` says the only allowed actor is `superadmin`. Model both against `billing.manage.allowed_actor` with `operator: eq` so the conflict is explicit.
+
+```yaml
+property_values:
+  - id: FACT-BILLING-MANAGE-ACTOR-ADMIN
+    fact_kind: property_value
+    subject_key: billing.manage
+    property_key: billing.manage.allowed_actor
+    operator: eq
+    value_type: string
+    value_string: admin
+  - id: FACT-BILLING-MANAGE-ACTOR-SUPERADMIN
+    fact_kind: property_value
+    subject_key: billing.manage
+    property_key: billing.manage.allowed_actor
+    operator: eq
+    value_type: string
+    value_string: superadmin
+```
+
+If a new requirement intentionally changes a value, create a replacement requirement and link the old requirement to the new one with `supersedes` instead of leaving two current contradictory requirements.
+
+## Fact vs Flag
+
+Use `flag` for runtime or config gates only. Feature flags, kill-switches, and deferred capabilities are valid `flag` entities.
+
+Bugs, incidents, and workarounds belong in `fact` entities with `fact_kind: observation` or `meta`. These fact kinds are excluded from contradiction inference, making them appropriate for non-blocking evidence.
+
+Anti-example: do not create a `flag` named `BUG-123` to track a defect. Create a `fact` with `fact_kind: observation` instead.
+
+## Create-Before-Link
+
+Always confirm or create endpoint entities before linking them. Query target IDs with `kb_query` first. If an endpoint does not exist, create it with `kb_upsert` before creating the relationship. Creating relationships to non-existent entities produces dangling references that `kb_check` will flag.
+
+For `kb_upsert`, keep relationship rows anchored to the entity you are upserting: each row's `from` must equal the upserted entity ID. If you need a `SYM -> REQ` link, upsert the symbol endpoint first, then link that symbol to the requirement.
+
+Keep symbol payloads minimal: include only the fields needed to identify the symbol, its status, and its source traceability. Put extra prose, examples, or audit notes in docs or evidence files instead of custom `kb_upsert.properties`; strict `kb_upsert.properties` rejects unknown fields.
+
+When a generic `Query failed` appears, do not keep retrying the same payload. First call `kb_validate_upsert`, query or create the missing endpoints, reduce the payload to the minimum required fields, and retry once. If it still fails, report the blocker instead of looping.
+
+## Sequential Upserts
+
+Never fire `kb_upsert` calls in parallel. Execute them sequentially to avoid lock contention and ensure deterministic ordering. This is especially important when creating chains of related entities.
+
+## Targeted and Final Checks
+
+Run `kb_check` with specific rules during iteration for fast feedback. For example, use `rules: ["required-fields", "no-dangling-refs"]` after small changes. Run a full `kb_check` without rule filters before declaring work complete.
+
+## Domain Contradictions and Evolution
+
+The `domain-contradictions` rule detects conflicts between strict-lane facts linked to requirements. When a contradiction is found, the supported escape hatch is `supersedes`: create a new requirement that supersedes the old one, then link the new requirement to updated facts.
+
+Use `kb_model_requirement` for automated strict-fact modeling. It generates the subject and property_value facts, links them via `constrains` and `requires_property`, and handles low-confidence downgrades to `observation` facts automatically.
+
+## Stale or Dirty KB Handling
+
+Call `kb_status` when you suspect the branch KB is stale or when switching context. Report freshness findings to the user rather than relying on outdated KB context. If `kb_status` indicates a schema migration is needed, ask the user or operator to handle it outside the agent session.
+
+## Anti-Patterns and Remediation
+
+| Anti-Pattern | Problem | Remediation |
+|-------------|---------|-------------|
+| Reversed relationship direction | Traceability queries break | Verify direction against the relationship table above |
+| Legacy implements comments | Comments are not durable queryable symbols | Create or update a `symbol` entity and link it to the requirement |
+| Bug-as-flag | `flag` misused for defect tracking | Use `fact` with `fact_kind: observation` or `meta` |
+| Parallel upserts | Lock contention and nondeterminism | Execute `kb_upsert` calls sequentially |
+| Embedded scenarios in reqs | Violates canonical traceability chain | Create separate `req`, `scen`, and `test` entities |
+| Missing `kb_check` | Undetected dangling refs and violations | Run targeted checks during work, full check at completion |
+| Tags as multi-ID lookup | Tags are metadata, not identifiers | Use `kb_query` with explicit `id` values |
+| `relates_to` for strict modeling | Loses contradiction safety | Use `constrains` and `requires_property` instead |
+| `status: implemented` on requirements | Not a valid lifecycle status | Use a valid status such as `closed`, add an `implemented` tag, and link evidence instead |
+
+Before/after for reversed direction:
+
+- Wrong: `relationships: [{ type: "implements", from: "REQ-001", to: "SYM-001" }]`
+- Right: `relationships: [{ type: "implements", from: "SYM-001", to: "REQ-001" }]`
+
+See `resources/workflows.md` for the golden-path discovery to validation sequence.