Enhance traceability with relationship-based guidance and tests by Looted · Pull Request #137 · Looted/kibi

Looted · 2026-04-06T10:44:08Z

No description provided.

…ip-first traceability

…m prompt refactor

…inks Agent-Logs-Url: https://github.com/Looted/kibi/sessions/500a899d-ebca-4591-84aa-7f23f24f2f22 Co-authored-by: Looted <6255880+Looted@users.noreply.github.com>

fix(cli): update traceability tests to use relationships instead of links

Copilot

Pull request overview

This PR updates Kibi’s staged traceability enforcement and OpenCode guidance to support relationship-based traceability (symbol → test → requirement) as a first-class path, alongside the existing inline // implements REQ-xxx shortcut.

Changes:

Extend core traceability validation to accept transitive requirement links via covered_by + validates/verified_by.
Enhance kibi check --staged pipeline to project staged manifests/markdown entities into the temp KB for “no prior sync” workflows.
Update OpenCode prompt guidance and expand tests/docs to reflect the relationship-first policy and backward compatibility.

Reviewed changes

Copilot reviewed 30 out of 30 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
packages/opencode/tests/test-fixture-helpers.ts	Switch test helper imports to `node:*` and adjust traceability comment placement.
packages/opencode/tests/prompt.test.ts	Add/adjust assertions for relationship-first traceability phrasing and formatting tweaks.
packages/opencode/src/workspace-health.ts	Minor robustness improvement using optional chaining for config parsing.
packages/opencode/src/prompt.ts	Update guidance copy to prefer durable relationships for test/e2e while keeping inline comments optional.
packages/opencode/src/index.ts	Import reorder and minor formatting cleanup in scheduler call.
packages/opencode/package.json	Version bump to 0.6.0.
packages/opencode/CHANGELOG.md	Add 0.6.0 entry describing relationship-first traceability guidance/policy.
packages/mcp/tests/tools/check.test.ts	Expand MCP check tests for relationship-based traceability paths and improved violation copy expectations.
packages/mcp/package.json	Version bump + dependency bumps to newer kibi-cli/kibi-core.
packages/mcp/CHANGELOG.md	Add 0.6.0 entry + dependency update notes.
packages/core/tests/kb.plt	Add PLUnit tests covering validates/verified_by transitive traceability paths.
packages/core/src/checks.pl	Update `check_symbol_traceability/2` to rely on transitive traceability inference and revise suggestions.
packages/core/package.json	Version bump to 0.4.0.
packages/core/CHANGELOG.md	Add 0.4.0 entry describing relationship-based traceability support.
packages/cli/tests/traceability/traceability.test.ts	Update manifest lookup fixtures to use typed relationships instead of `links`.
packages/cli/tests/traceability/temp-kb.test.ts	Add tests for projecting staged entities/relationships into the temp KB and layering overlays.
packages/cli/tests/traceability/symbol-extract.test.ts	Add coverage for staged-manifest relationship preservation and overrides.
packages/cli/tests/extractors/manifest.test.ts	Add tests for extracting typed relationships from manifest strings.
packages/cli/tests/commands/check.test.ts	Expand staged e2e traceability matrix and adjust staging setup for relationship workflows.
packages/cli/src/traceability/temp-kb.ts	Add `projectStagedEntities()` and Prolog serialization helpers for staging entities into the temp KB.
packages/cli/src/traceability/symbol-extract.ts	Add typed relationship support in manifest lookup and refactor symbol id/traceability resolution.
packages/cli/src/extractors/markdown.ts	Add `extractFromMarkdownString()` to support staged-content extraction without filesystem reads.
packages/cli/src/extractors/manifest.ts	Add `extractFromManifestString()` and refactor relationship extraction.
packages/cli/src/commands/check.ts	Rework staged checking to parse staged manifests/markdown and project them into the temp KB.
packages/cli/package.json	Version bump to 0.5.0 and update kibi-core dependency range.
packages/cli/CHANGELOG.md	Add 0.5.0 entry describing relationship-first staged traceability.
documentation/symbols.yaml	Refresh generated symbol coordinates/timestamps for modified code locations.
docs/prompts/llm-rules.md	Document relationship-first workflow and scope note for staged validation.
docs/cli-reference.md	Document staged relationship-based workflow (but currently duplicated section).
AGENTS.md	Update agent workflow guidance to prefer relationship-based traceability for test/e2e.

Comments suppressed due to low confidence (2)

docs/cli-reference.md:321

This section now repeats the entire kibi check --staged description (starting again at “The kibi check --staged command…”). Please remove the duplicated block to avoid conflicting guidance and keep a single canonical staged-traceability section.

The `kibi check --staged` command enforces traceability on code before commit.

**Purpose:**
Every new or modified code symbol (function, class, module) must be explicitly linked to at least one requirement before it can be committed. This prevents "orphan" code from being merged.

**How to use:**
```bash
# Check staged files for traceability coverage
kibi check --staged

This command scans only files staged for commit and reports any new or modified symbols that do not have requirement links. If violations are found and this is run as a pre-commit hook, the commit will be blocked.

**docs/prompts/llm-rules.md:134**
* The relationship bullet list is duplicated (the same items appear twice, with and without the new parenthetical notes). Please collapse to a single list to avoid redundancy and keep the “Optional/Preferred” annotations only once.

Create relationships during the same kb_upsert when possible:
- specified_by for requirement -> scenario
- verified_by or validates for requirement/test links
- implements for symbol -> requirement (Optional/Backward-Compatible shortcut)
- covered_by for symbol -> test (Preferred workflow for test/e2e traceability)
- constrains and requires_property for requirement/fact modeling
- specified_by for requirement -> scenario
- verified_by or validates for requirement/test links
- implements for symbol -> requirement
- covered_by for symbol -> test
- constrains and requires_property for requirement/fact modeling

</details>

Copilot · 2026-04-06T10:50:57Z

+function buildManifestLookup(stagedFiles: ReturnType<typeof getStagedFiles>): {
+  manifestLookup: ManifestLookup;
+  manifestResults: ExtractionResult[];
+} {
+  const manifestLookup: ManifestLookup = new Map();
+  const manifestResults: ExtractionResult[] = [];
+  const stagedManifestFiles = stagedFiles.filter(
+    (file) =>
+      file.content !== undefined &&
+      (file.path.endsWith("/symbols.yaml") ||
+        file.path.endsWith("/symbols.yml") ||
+        file.path === "symbols.yaml" ||
+        file.path === "symbols.yml"),
+  );


kibi check --staged now builds manifestLookup only from staged symbols.yaml/symbols.yml content. This means already-existing symbol IDs/relationships from configured manifests on disk (e.g. documentation/symbols.yaml) won’t be used unless that manifest is also staged, so a code-only change can get a hash-fallback symbol id and incorrectly fail traceability even though the symbol is already linked in the KB. Consider merging (1) manifests discovered from config.paths.symbols (working tree) with (2) staged-manifest overrides, instead of using staged manifests exclusively.

Copilot · 2026-04-06T10:50:58Z

+function toPrologString(value: string): string {
+  const escaped = value
+    .replace(/\\/g, "\\\\")
+    .replace(/"/g, '\\"')
+    .replace(/\n/g, "\\n")
+    .replace(/\r/g, "\\r")
+    .replace(/\t/g, "\\t");
+
+  return `"${escaped}"`;
+}


toPrologString() here duplicates escaping logic that already exists in ../prolog/codec (toPrologString). Reusing the shared codec helper would reduce divergence risk (e.g., future escape rules) and keep Prolog serialization consistent across the CLI.

Copilot · 2026-04-06T10:50:58Z

 {
  "name": "kibi-opencode",
-  "version": "0.5.4",
+  "version": "0.6.0",
  "description": "Kibi OpenCode plugin - thin adapter to integrate Kibi with OpenCode sessions",


Package versions are being bumped directly, but this repo’s release process expects a Changeset to drive version/changelog updates (see AGENTS.md “Release Metadata Required”). Please add an appropriate .changeset/*.md entry (and let changeset version generate the bumps), or clarify why manual versioning is intended for this PR.

Copilot · 2026-04-06T10:50:58Z

 {
  "name": "kibi-mcp",
-  "version": "0.5.2",
+  "version": "0.6.0",
  "dependencies": {
    "@modelcontextprotocol/sdk": "^1.26.0",
    "ajv": "^8.18.0",


Package versions are being bumped directly, but this repo’s release process expects a Changeset to drive version/changelog updates (see AGENTS.md “Release Metadata Required”). Please add an appropriate .changeset/*.md entry (and let changeset version generate the bumps), or clarify why manual versioning is intended for this PR.

Copilot · 2026-04-06T10:50:58Z

 {
  "name": "kibi-cli",
-  "version": "0.4.3",
+  "version": "0.5.0",
  "type": "module",
  "description": "Kibi CLI for knowledge base management",
  "engines": {


Package versions are being bumped directly, but this repo’s release process expects a Changeset to drive version/changelog updates (see AGENTS.md “Release Metadata Required”). Please add an appropriate .changeset/*.md entry (and let changeset version generate the bumps), or clarify why manual versioning is intended for this PR.

Copilot · 2026-04-06T10:50:59Z

 {
  "name": "kibi-core",
-  "version": "0.3.0",
+  "version": "0.4.0",
  "private": false,
  "description": "Core Prolog modules and RDF graph logic for Kibi",
  "type": "module",


Package versions are being bumped directly, but this repo’s release process expects a Changeset to drive version/changelog updates (see AGENTS.md “Release Metadata Required”). Please add an appropriate .changeset/*.md entry (and let changeset version generate the bumps), or clarify why manual versioning is intended for this PR.

Looted · 2026-04-06T10:57:11Z

@copilot apply changes based on the comments in this thread in a separate MR to develop directly. I bumped the version manually, so the changeset was deleted, but it's in history - please bring it back if needed and run the appropriate commands.

Looted and others added 14 commits April 5, 2026 22:26

fix(core): align symbol-traceability with test-backed paths

5dcae30

refactor(cli): read staged manifest traceability from staged blobs

544a2ef

fix(opencode): prefer relationship-based traceability guidance

a472dab

fix(cli): project staged traceability relationships into temp kb

92c34e6

test(cli): cover staged e2e traceability without inline comments

d3e36cf

docs(traceability): document comment-free test workflow

0c2c1e7

style(cli): fix import ordering in staged check command

439bbc1

style: apply biome fixes to changed files for final verification

e720b68

fix(opencode): align contextual prompts and llm-rules with relationsh…

7d30bd9

…ip-first traceability

chore: sync symbol coordinates after merge to develop

73d4071

(chore) version bump

30fa6da

Merge branch 'main' into develop: comment-free traceability + upstrea…

0a58c1e

…m prompt refactor

fix(cli): update traceability tests to use relationships instead of l…

faec8bb

…inks Agent-Logs-Url: https://github.com/Looted/kibi/sessions/500a899d-ebca-4591-84aa-7f23f24f2f22 Co-authored-by: Looted <6255880+Looted@users.noreply.github.com>

Merge pull request #136 from Looted/copilot/fix-ci-failure-on-merge

2123f58

fix(cli): update traceability tests to use relationships instead of links

Copilot AI review requested due to automatic review settings April 6, 2026 10:44

Copilot started reviewing on behalf of Looted April 6, 2026 10:44 View session

Copilot AI reviewed Apr 6, 2026

View reviewed changes

Looted merged commit 30c8f46 into master Apr 6, 2026
10 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Enhance traceability with relationship-based guidance and tests#137

Enhance traceability with relationship-based guidance and tests#137
Looted merged 14 commits intomasterfrom
develop

Looted commented Apr 6, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Apr 6, 2026

Uh oh!

Copilot AI Apr 6, 2026

Uh oh!

Copilot AI Apr 6, 2026

Uh oh!

Copilot AI Apr 6, 2026

Uh oh!

Copilot AI Apr 6, 2026

Uh oh!

Copilot AI Apr 6, 2026

Uh oh!

Uh oh!

Looted commented Apr 6, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

Looted commented Apr 6, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Apr 6, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 6, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 6, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 6, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 6, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 6, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Looted commented Apr 6, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants