fix(kb): align populate-kb.ts seed entries with canonical documentation#157
fix(kb): align populate-kb.ts seed entries with canonical documentation#157
Conversation
- SCEN-001: align title/status/source/tags with documentation/scenarios/SCEN-001.md - ADR-002: align title/source/tags with documentation/adr/ADR-002.md - FLAG-001: fix status inactive→active to match documentation/flags/FLAG-001.md Ensures KB state is deterministic regardless of script vs doc sync order. Agent-Logs-Url: https://github.com/Looted/kibi/sessions/60eb6884-c2bc-4d26-ac93-22118435c2dc Co-authored-by: Looted <6255880+Looted@users.noreply.github.com>
There was a problem hiding this comment.
Pull request overview
Aligns a few scripts/populate-kb.ts seed entities with their canonical markdown documentation to reduce nondeterministic KB state when seeding vs doc-sync run in different orders.
Changes:
- Updated
ADR-002seed title/source/tags to matchdocumentation/adr/ADR-002.md - Updated
FLAG-001seed status to matchdocumentation/flags/FLAG-001.md - Updated
SCEN-001seed title/status/source/tags to matchdocumentation/scenarios/SCEN-001.md
| type: "scenario", | ||
| id: "SCEN-001", | ||
| properties: { | ||
| title: "Agent queries requirements from KB via MCP kb_query tool", | ||
| status: "passing", | ||
| source: "scripts/populate-kb.ts", | ||
| tags: ["mcp", "query", "agent"], | ||
| title: "Critical Feature Scenario", | ||
| status: "active", | ||
| source: "documentation/scenarios/SCEN-001.md", | ||
| tags: ["critical"], | ||
| }, |
There was a problem hiding this comment.
documentation/scenarios/SCEN-001.md includes created_at/updated_at and multiple links (which become relationships). This seed upsert does not include timestamps or relationships, and entity upsert retracts all triples for the entity URI; if populate-kb.ts runs after doc-sync it can wipe SCEN-001’s outgoing relationships and replace canonical timestamps with new defaults. To make execution order truly idempotent, seed the canonical timestamps and the relationships derived from links (or change the upsert flow to preserve existing timestamps/relationships when updating).
| status: "inactive", | ||
| status: "active", | ||
| source: "documentation/flags/FLAG-001.md", | ||
| tags: ["vscode", "deferred", "post-v0"], |
There was a problem hiding this comment.
FLAG-001 still doesn’t mirror the canonical markdown: documentation/flags/FLAG-001.md uses tags [vscode, deferred, graph], but this seed uses [vscode, deferred, post-v0]. Since entity upsert retracts and rewrites all properties, running this script after doc-sync will overwrite the doc-derived tags and keep KB state order-dependent. Align the tags (and any other canonical fields you intend to preserve) with the markdown source.
| tags: ["vscode", "deferred", "post-v0"], | |
| tags: ["vscode", "deferred", "graph"], |
| type: "adr", | ||
| id: "ADR-002", | ||
| properties: { | ||
| title: "Use Bun/Node.js as CLI wrapper around SWI-Prolog subprocess", | ||
| title: "Public API exports via re-export modules", | ||
| status: "accepted", | ||
| source: "scripts/populate-kb.ts", | ||
| tags: ["cli", "bun", "nodejs"], | ||
| source: "documentation/adr/ADR-002.md", | ||
| tags: ["architecture", "publishing", "exports"], | ||
| }, |
There was a problem hiding this comment.
Even with the title/source/tags aligned, this seed entry will still overwrite canonical metadata from documentation/adr/ADR-002.md (e.g., created_at/updated_at) because handleKbUpsert fills missing timestamps and the Prolog upsert retracts all existing triples for the entity before re-asserting. If the goal is execution-order idempotence vs doc-sync, include the canonical timestamps (and any other fields you want preserved) in the seeded properties, or adjust the upsert path to preserve existing created_at on updates.
Three seed entries in
scripts/populate-kb.tsconflicted with their canonical documentation counterparts, making KB state nondeterministic depending on whether the script or the doc-sync ran last.Changes
documentation/scenarios/SCEN-001.md; aligned to the doc file ("Critical Feature Scenario",active,["critical"])documentation/adr/ADR-002.mdstatus: "inactive"whiledocumentation/flags/FLAG-001.mddeclaresstatus: active; corrected to"active"All three seed entries now mirror their canonical markdown sources, so the upsert is idempotent regardless of execution order.