Repository navigation
v0.4.0 — LLM extraction + write path, MCP parity, retrieval quality, analytics, watch mode - #1
Merged
Merged
Conversation
…, ontology + extraction fixes Fixes: - init --ontology is persisted and honored by build/sync (was always 'general'); --ontology flag added to build and sync - engineering pack gains blocked_by/requires/uses/implements/delivers/precedes/ supports/mentions/Topic; depends_on domain opened - headings no longer emit degenerate Document--about-->Topic self-echo triples - IDF-weighted seed scoring; distinct abstain reasons (no_seeds_matched / seeds_disconnected / empty_subgraph) - citations project all provenance sources with line spans (path:line) - linear-time budget trim + path materialization; removed dead answerHttp branch Features: - build/sync --llm [prompt|http]: LLM-assisted extraction — prompt-file mode for host agents (merge via 'prompt apply extract') or live HTTP mode; candidates clamped to INFERRED with llm/* provenance, still ontology/review gated - Anthropic-native /v1/messages adapter (provider: anthropic); ask --llm http now performs live grounded answers - gsd-graph why <a> <b>: shortest path explained as cited prose - gsd-graph export --format mermaid|graphml|cypher|html (self-contained viewer) - review accept/reject --all/--kind/--predicate batch resolve under one lock - alias/acronym suggest-only entity_merge review items - hooks: sync_on_feature_branches opt-in; failed syncs keep logs + stderr_tail
…rst-run error - forward-only graph.v1 migration registry (registerGraphMigration) applied in loadGraphV1; newer-engine stores fail closed - build/mergeCandidates stamp built_at_commit from git HEAD (null outside a repo) - missing store now raises STORE_NOT_FOUND with 'run gsd-graph enable' hint instead of schema_invalid/path_escape - confineUnderRoot no longer misreports first-run lookups under a not-yet-created store root as PATH_ESCAPE
- loadGraphV1Cached keyed on (mtime,size,ino) of graph.v1.json; read pipelines (query/pack/why/status/communities) reuse the parsed doc until republish - buildAdjacencyMap memoized per document via WeakMap — pack path-pairs and long-lived MCP servers stop re-indexing every call - GsdGraph.open() embedding facade: status/query/pack/ask/why/communities from one handle
- extension-keyed extractor registry (registerExtractor); built-ins markdown/jsonl/json-document/yaml; discovery defaults derive from the registry - dependency-free flat-YAML extractor: title/description as Document fields, tags→mentions Topic edges, relational keys (depends_on, blocked_by, requires, …) as ontology-gated Concept edges, other scalars folded into searchable description - markdown frontmatter routed through the YAML mapping; frontmatter no longer leaks junk Concept definitions; body structure attaches to the frontmatter Document
- plural/singular variant matching in seed scoring ('phases' seeds 'phase', 'dependency' seeds 'dependencies') via multi-variant stems on both sides
- no_seeds_matched abstains now carry top-5 near-miss labels (bounded edit distance over label/alias word stems) as pack.seed_suggestions and answer.suggestions
- applyBudget accepts a relevance scorer; pack trims by confidence-dominant score with seed proximity, predicate weight (mentions=noise), and provenance count as tie-breakers — the budget stops evicting the answering triple - PackCitation carries confidence + source_count; answer markdown renders [EXTRACTED ×3]-style trust tags; why citations show tier
- ask/answer now falls back to community detection (mode 'global') when an overview-shaped question packs empty, or --global/global:true forces it - theme sections list key nodes, main relationships, and representative cited triples; citations stay a subset of pack triples
- 'conflict' review kind: reciprocal cycles on directional predicates and supports/contradicts on same endpoints go to the review queue (both triples still written — surfacing, not suppression); accept is record-only - gsd-graph supersede <winner> <loser> records decision reversals; superseded facts rank a full confidence tier lower, citations flag [superseded] - provenance entries stamp first_seen/last_seen at normalize; re-observed evidence bumps last_seen
…ed graph_sync, store resources - default read tools now include graph_why (cited path prose), graph_resolve (term→id with did-you-mean), graph_diff, graph_communities (read-only unless write=true) - graph_sync incremental project sync behind the allow-build gate; graph_answer gains global flag - GRAPH_REPORT.md and community theme reports exposed as MCP resources (gsd-graph://report, gsd-graph://communities)
- gsd-graph assert <s> <p> <o>: resolves/creates endpoints, merges through the normal ontology/review/provenance gates, records to append-only episodes.jsonl; --supersedes records reversals - gsd-graph retract <tripleId>: removes and logs; full rebuilds replay episodes so asserts survive and retractions keep holding (last action per key wins) - MCP graph_assert/graph_retract behind new --allow-assert gate (actor agent/mcp)
- runEval executes a QA case file (evals/gsd-graph.json) against the store: pass/fail per case, seed recall, citation-validity invariant, abstain/mode expectations, why-path checks - CLI 'gsd-graph eval' exits non-zero when cases fail; evals/example.json documents the format
…t_version - extract/answer system prompts now compose from prompts/<stage>.md (store-local prompts/ override wins over shipped default) — the main LLM quality lever is finally user-tunable - template content hash recorded as prompt_version on every LLM-derived provenance entry (schema + types)
- packs may extend one base (collision-error on duplicate predicate ids; node types dedupe; child policies win); base may not itself extend - pack ids resolve project-local ontology-packs/<id>/ first, then the shipped pack - gsd-graph ontology eject materializes active pack + accepted lock extensions into a committable ontology-packs/<id>-local/ pack and repoints store config
- embeddings.v1.json sidecar: node labels/aliases embedded via any OpenAI-compatible endpoint (store config llm.embeddings), incremental by text hash, disposable and offline-default - SeedScorer interface + registry; semantic candidates consulted ONLY when lexical seeding finds nothing — expand/budget/citations stay deterministic - answerSemantic + ask --semantic retry a no_seeds_matched abstain with sidecar candidates; embeddings build/status CLI
- review summary (counts by kind, top proposed predicates, batch-accept hints), review list --kind/--limit, sync wrap-up nudge at 25+ pending items - ask/why/status/query render human text on an interactive TTY (JSON when piped/--json/CI); abstains print did-you-mean suggestions - status prints prescriptive next steps; export --open launches the html viewer
- gsd-graph top: degree + PageRank ranking (pure TS, damped iteration, deterministic tie-breaks); GRAPH_REPORT gains a Central nodes section - why --k <n>: up to k-1 distinct alternative routes via edge-removal re-search, rendered as 'Alternative routes'
- gsd-graph watch: fs.watch over corpus roots, debounced incremental sync under the ordinary build lock — freshness for Cursor/Codex/plain editors - gsd-graph hook install-git [--remove]: guarded marker block in .git/hooks/post-commit running detached sync; append-safe with existing user hooks
- SKILL.md gains a routing table: agents route project questions through graph_answer/graph_why/graph_communities (or CLI ask/why/top) before re-reading planning docs; abstain+suggestions is the fallback signal - mcp install/doctor output names the tools and the graph-first rule
jeremymcs
changed the title
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Ships v0.3.0 (LLM extraction, Anthropic adapter, export/why) plus the full v0.4.0 recommendation set from the team evaluation — 8 high-impact features, 6 foundational items, and the polish list.
High-impact (v0.4.0)
assert/retractCLI + MCPgraph_assert/graph_retract(new--allow-assertgate); facts flow through the normal ontology/review gates into append-onlyepisodes.jsonland survive full rebuildsgraph_why,graph_resolve,graph_diff,graph_communitiesread tools; gatedgraph_sync;gsd-graph://report+gsd-graph://communitiesresourcesglobal) instead of abstainingSeedScorerfallback seam (ask --semantic)[EXTRACTED ×3]citation trust tagsconflictreview kind,gsd-graph supersede, provenancefirst_seen/last_seen)Foundations
Store migration registry +
built_at_commit, mtime-keyed graph cache +GsdGraph.open()facade,gsd-graph evalQA harness, ontology single-levelextends+ project-local packs +ontology eject, prompts/*.md wired into LLM stages withprompt_versionprovenancePolish
Friendly first-run error (STORE_NOT_FOUND instead of path_escape), human TTY output for ask/why/status/query/top, review-queue triage (
review summary),watchmode + plain git post-commit hook,export --open,top(PageRank/degree),why --kalternative routes, graph-first routing in SKILL.mdTest plan
🤖 Generated with Claude Code