Align entity guidance and documentation across multiple files by Looted · Pull Request #121 · Looted/kibi

Looted · 2026-03-27T18:39:42Z

No description provided.

- Update AGENTS.md with canonical entity-choice rule - Add entity choice sections to entity-schema.md and inference-rules.md - Update llm-rules.md and retroactive-init.md with flag/fact guidance - All 24 CLI modeling guidance tests pass Tasks completed: 2, 3, 4

- Add modeling bullet to kibi_overview prompt - Add modeling note to examples resource - Add note after tools table in renderToolsDoc - All 38 doc tests now pass

Remove duplicate fact row in AGENTS.md entity table and duplicate 'Symbol manifests' line in cli-reference.md. Apply Biome formatting to test files and MCP source.

kibi-core@0.3.0, kibi-cli@0.4.0, kibi-mcp@0.5.0, kibi-opencode@0.5.2

Copilot

Pull request overview

Aligns and locks canonical entity-modeling guidance (especially flag vs fact for bug/workaround documentation) across MCP runtime docs, repo documentation, and regression tests, alongside coordinated package version/changelog updates.

Changes:

Updated multiple docs/prompts to consistently describe flag as a runtime/config gate and bugs/workarounds as fact (fact_kind: observation|meta).
Added regression tests in CLI and MCP to enforce the canonical wording and prevent “bug/workaround as entity type” language.
Bumped package versions and updated changelogs; removed consumed changeset entries.

Reviewed changes

Copilot reviewed 43 out of 43 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
packages/opencode/package.json	Version bump + formatting normalization for publish metadata.
packages/opencode/CHANGELOG.md	Adds 0.5.2 release notes reflecting internal refactors and guidance changes.
packages/mcp/tests/tools/find-gaps.test.ts	Formatting-only changes in test fixtures for consistency.
packages/mcp/tests/tools/coverage.test.ts	Formatting-only changes in test fixtures for consistency.
packages/mcp/tests/tools/check.test.ts	Import formatting cleanup and removal of stray blank lines.
packages/mcp/tests/docs.test.ts	New MCP docs regression tests that lock canonical modeling wording.
packages/mcp/test/fixtures/flag-example.md	Updates fixture wording to emphasize runtime/config gating.
packages/mcp/src/tools/core-module.ts	Minor string formatting change (trailing comma) in thrown error.
packages/mcp/src/server/docs.ts	Updates MCP self-documentation prompts/resources and tools docs generation.
packages/mcp/package.json	Version bump + dependency bumps to kibi-cli/kibi-core + files formatting.
packages/mcp/CHANGELOG.md	Adds 0.5.0 release notes including the guidance alignment.
packages/core/package.json	Version bump + files formatting.
packages/core/CHANGELOG.md	Adds 0.3.0 release notes.
packages/cli/tests/modeling-guidance.test.ts	New regression tests enforcing canonical entity-choice wording across docs.
packages/cli/tests/documentation-consistency.test.ts	Adds additional regression checks for “bug/workaround entity type” wording and entity-type listing.
packages/cli/package.json	Version bump + files formatting + dependency bump to kibi-core.
packages/cli/CHANGELOG.md	Adds 0.4.0 release notes.
documentation/tests/e2e/packed/discovery-bundle.test.ts	Formatting-only changes in e2e tests.
documentation/symbols.yaml	Regenerates symbol coordinate metadata timestamps/locations.
documentation/flags/FLAG-005.md	Clarifies flag description as runtime/config gate.
documentation/flags/FLAG-004.md	Clarifies flag description as runtime/config gate for federation.
documentation/flags/FLAG-003.md	Clarifies flag description as runtime/config gate for web UI.
documentation/flags/FLAG-002.md	Clarifies flag description as runtime/config gate for SCIP extraction.
documentation/flags/FLAG-001.md	Clarifies flag description as runtime/config gate for VS Code feature set.
documentation/facts/FACT-EXAMPLE-PAIRED-MODEL.md	Adds a paired-model example (bug fact + mitigation flag) demonstrating canonical guidance.
docs/prompts/retroactive-init.md	Adds explicit “Entity Choice for Bugs and Workarounds” guidance.
docs/prompts/llm-rules.md	Adds explicit entity-choice rules and canonical mapping for bug/workaround documentation.
docs/mcp-reference.md	Adds modeling note about `flag` vs `fact` and observation/meta usage.
docs/install.md	Adds link to Entity Schema for entity-type selection guidance.
docs/inference-rules.md	Adds explicit guidance that observation/meta facts are appropriate for bug/workaround notes.
docs/entity-schema.md	Updates entity descriptions and adds an entity-choice decision table + rules.
docs/cli-reference.md	Adds `symbol` to supported entity types and modeling note.
docs/architecture.md	Adds entity modeling note and link to Entity Schema.
README.md	Adjusts “Feature Flag” wording to “runtime/config gate” and adds entity modeling note.
CONTRIBUTING.md	Adds KB modeling note for contributors.
AGENTS.md	Updates entity descriptions and adds a quick-reference + rules for bugs/workarounds modeling.
.opencode/plans/2026-03-26-code-gardening.md	Adds a detailed internal refactor implementation plan.
.opencode/plans/2026-03-25-kb-fact-typing-overhaul.md	Adds a detailed typed-fact migration plan.
.opencode/plans/2026-03-25-fix-graph-multi-rel-and-symbol-sourcefile.md	Adds a detailed bugfix implementation plan for #113/#114.
.changeset/typed-facts-and-discovery.md	Removes consumed changeset entry.
.changeset/issue-118-mcp-discovery-root.md	Removes consumed changeset entry.
.changeset/code-quality-refactors.md	Removes consumed changeset entry.
.changeset/bugfixes-and-compatibility.md	Removes consumed changeset entry.

Copilot · 2026-03-27T18:43:51Z

packages/mcp/src/server/docs.ts

    name: "kibi_overview",
    description: "High-level model for using kibi-mcp safely and effectively.",
    text: [
      "# kibi-mcp Overview",
      "",
      "Treat this server as a branch-aware knowledge graph interface for software traceability.",
      "",
      "The server exposes a curated public tool surface for KB operations:",
      "- `kb_search`: Discovery across metadata and markdown body text",
      "- `kb_query`: Exact lookup of entities by type, ID, tags, or source file",
      "- `kb_status`: Branch, snapshot, and freshness inspection",
      "- `kb_find_gaps`: Bulk missing/present relationship analysis",
      "- `kb_coverage`: Curated coverage reporting",
      "- `kb_graph`: Bounded graph traversal from seed IDs",
      "- `kb_upsert`: Create or update entities and their relationships",
      "- `kb_delete`: Remove entities by ID (with dependency safety checks)",
      "- `kb_check`: Validate KB integrity against configurable rules",
      "",
      "Core modeling principles:",
      "- Encode requirements as linked facts: `req --constrains--> fact` plus `req --requires_property--> fact`.",
      "- Reuse canonical fact IDs across requirements; shared constrained facts make contradictions detectable.",
      "- Use `kb_search` first for discovery, then `kb_query` for exact follow-up before any mutation.",
      "- Use `kb_upsert` and `kb_delete` only for intentional, traceable KB changes.",
      "- Run `kb_check` after meaningful mutations to catch integrity issues early.",
      "- Prefer explicit IDs and enum values to avoid invalid parameters.",
      "- Assume every write can affect downstream traceability queries.",
+      "- Model requirements by first creating/reusing fact entities, then express req semantics with `constrains` + `requires_property` relationships (create-before-link).",
+      "- flag gates runtime/config behavior; use `fact` with `fact_kind: observation` or `meta` for bug and workaround notes.",
    ].join("\n"),


kibi_overview prompt text doesn’t include any Modeling: line, but the newly added MCP docs regression tests look specifically for a terse Modeling: section (and enforce a length limit) containing the canonical wording (flags gate runtime/config behavior; bug/workaround notes use observation/meta facts). Add a short single-line Modeling: ... sentence that includes the schema terms (flag, fact, observation, meta) so the prompt matches the locked wording.

Copilot · 2026-03-27T18:43:51Z

packages/mcp/src/server/docs.ts

+    "## Find missing coverage",
+    '1. `kb_find_gaps` with `{ "type": "req", "missingRelationships": ["specified_by", "verified_by"] }` to find under-linked requirements',
+    "",
+    "## Find missing coverage",
+    "",
    "## Find missing coverage",
    '1. `kb_find_gaps` with `{ "type": "req", "missingRelationships": ["specified_by", "verified_by"] }` to find under-linked requirements',
    '2. `kb_coverage` with `{ "by": "req", "includePassing": false }` to review evaluated coverage rows',


The examples doc resource contains three repeated ## Find missing coverage headings (one empty section) which makes the built-in docs noisy and confusing. Remove the duplicate headings/blank section and keep a single coherent “Find missing coverage” section with the intended steps.

Copilot · 2026-03-27T18:43:52Z

docs/entity-schema.md

+| MQ|       | flag     | Runtime or config gate (feature flag, kill-switch, deferred capability) |
+| HX|       | event    | Domain or system event published/consumed by components            |
+| MN|       | symbol   | Abstract code symbol (function, class, module) - language-agnostic |
+| JZ|       | fact     | Atomic domain fact; use observation/meta for bug and workaround notes |


Copilot · 2026-03-27T18:43:52Z

packages/cli/tests/documentation-consistency.test.ts

+// --- Flag / Fact canonical wording regression tests ---
+
+const ROOT = path.resolve(import.meta.dir, "../../..");
+const DOCS = path.resolve(ROOT, "docs");


DOCS is declared but never used, and the repo has Biome linting enabled (which will typically flag unused locals). Remove the unused constant or use it where intended.

Suggested change

const DOCS = path.resolve(ROOT, "docs");

Copilot · 2026-03-27T18:43:52Z

packages/mcp/src/server/docs.ts

  for (const tool of ACTIVE_TOOLS) {
    const required = Array.isArray(tool.inputSchema?.required)
      ? tool.inputSchema.required.join(", ")
      : "none";
-    lines.push(`| ${tool.name} | ${tool.description} | ${required} |`);
  }
-
+  lines.push("");
+  lines.push(
+    "Modeling note: Prefer query-first discovery; create `fact` entities before `req` entities and express semantics via `constrains` + `requires_property`.",
+  );


In renderToolsDoc(), the loop computes required but never appends a table row for each tool. As a result, the generated kibi://docs/tools resource will contain only the header and no tool entries. Add back the lines.push that emits a row per tool (using tool.name, tool.description, and the computed required).

Looted · 2026-03-27T18:46:10Z

@copilot apply changes based on the comments in this thread

Copilot · 2026-03-27T19:00:47Z

@copilot apply changes based on the comments in this thread

All 5 issues from the review have been addressed in commit 729951f:

renderToolsDoc() missing rows (docs.ts:48-56) — Added lines.push(\| ${tool.name} | ${tool.description} | ${required} |`)` inside the loop so the tools table is populated correctly.
kibi_overview missing Modeling: line (docs.ts:124-152) — Replaced the final modeling bullet with a standalone Modeling: sentence: "Modeling: flag gates runtime/config behavior; bug and workaround notes use \observation`/`meta` facts." — satisfies all schema-term checks (flag, fact, observation, meta`) and fits under 250 characters.
Duplicate ## Find missing coverage headings (docs.ts:239-246) — Removed the two empty/duplicate headings, keeping a single coherent section with all three steps.
Malformed table in docs/entity-schema.md:17-20 — Removed the stray MQ|, HX|, MN|, JZ| prefixes so the rows follow the standard | type | description | format.
Unused DOCS constant (documentation-consistency.test.ts:52) — Removed the unused const DOCS declaration.

All 19 relevant tests (MCP docs + CLI documentation-consistency) pass after the changes. Note: the push is being blocked by branch protection rules on develop; a repository admin may need to allow the push or merge via a PR.

Looted added 11 commits March 27, 2026 16:15

test(cli,mcp): lock entity guidance wording

c862194

docs(mcp): align runtime self-documentation with entity guidance

a1f870b

- Add modeling bullet to kibi_overview prompt - Add modeling note to examples resource - Add note after tools table in renderToolsDoc - All 38 doc tests now pass

docs(cli,mcp): align reference guidance

fbce647

docs: align public entity guidance

6b69aaa

docs(examples): align flag teaching examples

0bf9087

chore(release): add changeset for entity guidance docs

30e5f68

docs(schema): remove unsupported affects relationship

40a2a6a

fix(docs): remove duplicate lines and apply formatting

4c92764

Remove duplicate fact row in AGENTS.md entity table and duplicate 'Symbol manifests' line in cli-reference.md. Apply Biome formatting to test files and MCP source.

chore(release): version packages

eb886de

kibi-core@0.3.0, kibi-cli@0.4.0, kibi-mcp@0.5.0, kibi-opencode@0.5.2

Merge branch 'develop' of https://github.com/Looted/kibi into develop

f314fec

Copilot AI review requested due to automatic review settings March 27, 2026 18:39

Copilot started reviewing on behalf of Looted March 27, 2026 18:40 View session

Copilot AI reviewed Mar 27, 2026

View reviewed changes

Copilot started work on behalf of Looted March 27, 2026 18:46 View session

Looted merged commit ebcbbca into master Mar 27, 2026
10 of 11 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Align entity guidance and documentation across multiple files#121

Align entity guidance and documentation across multiple files#121
Looted merged 11 commits intomasterfrom
develop

Looted commented Mar 27, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Mar 27, 2026

Uh oh!

Copilot AI Mar 27, 2026

Uh oh!

Copilot AI Mar 27, 2026

Uh oh!

Copilot AI Mar 27, 2026

Uh oh!

Copilot AI Mar 27, 2026

Uh oh!

Looted commented Mar 27, 2026

Uh oh!

Uh oh!

Copilot AI commented Mar 27, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

Looted commented Mar 27, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Mar 27, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 27, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 27, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 27, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 27, 2026

Choose a reason for hiding this comment

Uh oh!

Looted commented Mar 27, 2026

Uh oh!

Uh oh!

Copilot AI commented Mar 27, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants