Complete Compass scoping and bounds phase - #306
Conversation
Add a repository-level CLAUDE.md for Claude Code that defers to AGENTS.md as the authoritative operating guide and covers the mechanics it leaves implicit: - the mandatory per-invocation CARGO_TARGET_DIR requirement, including the Makefile targets that resolve binaries through a literal target/ path; - narrow-loop and baseline Rust commands, surface-specific gates, and the npm workspace commands for the viewer and VS Code extension; - the one-directional build pipeline across compass-files, -languages, -resolve, -graph, and -model, with the extractor/resolver evidence boundary and the compass-cypher/compass-query syntax-vs-execution split; - enforced workspace constraints (lint set, determinism, boundedness) and the compatibility-sensitive surfaces. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Track the .prometheus/knowledge/wiki/ session records so the knowledge content lives with the repository. Initialize OpenSpec (schema: spec-driven) with generated configuration for Claude Code, Codex, Kimi CLI, and OpenCode. Zed was requested but is not a supported `openspec init` target, so it has no generated configuration. Kimi receives skills only; OpenSpec reports no command adapter for it. The local .claude/settings.local.json permission allowlist is intentionally left untracked. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Add the KBD orchestrator state for the compass-scoping-and-bounds phase and track the accumulated Prometheus session knowledge. .kbd-orchestrator/: - project.json and constraints.md generated by /kbd-init, with the AGENTS.md CARGO_TARGET_DIR requirement applied to every compiling command; - phase artifacts for compass-scoping-and-bounds — assessment, analysis, spec, plan, goals, decision log, stage handoffs, and the library-candidates and tasks machine contracts; - current-waypoint at plan_ready with 6 registered changes. The phase investigates a 2 GiB canonical graph publication failure. It establishes that scoping already ships and works, that PartitionedGraph already exists in compass-history, and that the operative defect is read_snapshot materializing a payload no production caller reads. .prometheus/: - session wiki transcripts and update log; - events.jsonl and prompt snapshots. AGENTS.md gains a Prometheus state ownership rule classifying .prometheus/knowledge/wiki/** as repository-owned tracked content and every other .prometheus/** path as local runtime state. The local .claude/settings.local.json permission allowlist remains untracked. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
AGENTS.md mandated that every compiling Cargo command set CARGO_TARGET_DIR beneath /Volumes/Workspace/crabbuild-target, and stop rather than fall back to a local target/ when that volume was absent. The path describes one contributor's machine; it is not a property of the project. On any checkout without that volume the rule blocks all verification. Introduced in dd14b3c ("docs: add AI contributor guidance"). Still present upstream on crabbuild/compass at merge time. Two of the references were executable, not advisory: - scripts/qualify_compass_store_release.sh hard-failed with exit 1 unless /Volumes/Workspace was mounted and writable, making the store qualification gate unrunnable elsewhere; - both qualification scripts defaulted CARGO_TARGET_DIR to that path, silently writing outside the checkout. Replace the mandate with environment-neutral guidance that keeps the useful parts — per-checkout target directories, CARGO_TARGET_DIR not persisting between invocations, external qualification repositories treated as read-only. Scripts now honor CARGO_TARGET_DIR when set and fall back to the checkout's own target directory. Documentation uses <cargo-target-dir> and <qualification-corpus-root> placeholders. Regenerates the KBD orchestrator commands and clears the phase artifacts' environment blocker, which derived from the removed rule. Historical .prometheus session transcripts are left unmodified; they record what was true when written. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Implement the full phase across bounded graph storage and query contracts, latest MCP conformance, native agent distribution, installed harness qualification, and phase-first build policy. Co-Authored-By: Warp <agent@warp.dev>
Resolve mainline integration across discovery, storage, MCP, and agent distribution contracts. Co-Authored-By: Warp <agent@warp.dev>
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: dc8e034a41
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| if self.node_count > GRAPH_SNAPSHOT_MAX_ITEMS as u64 | ||
| || self.edge_count > GRAPH_SNAPSHOT_MAX_ITEMS as u64 |
There was a problem hiding this comment.
Remove this aggregate record-count check from the publication/open path. When a graph has more than 5,000,000 nodes or edges, finish_content, activation, and open_active now reject it, even though GRAPH_SNAPSHOT_MAX_ITEMS is explicitly documented as a per-materialized-read limit and current graph-index snapshots are documented as having no aggregate record-count cap. This regresses large graph publication and also makes previously valid snapshots unreadable; enforce the cap only on operations that materialize a whole response.
Useful? React with 👍 / 👎.
| pub fn open_selector_for_maintenance( | ||
| store: &'a S, | ||
| selector: SnapshotSelector, | ||
| ) -> Result<Self, SnapshotError> { | ||
| Self::open_selector_with_policy(store, selector, false) |
There was a problem hiding this comment.
Use this maintenance path from garbage_collect_graph_snapshots. If a retained snapshot was published with a higher COMPASS_MAX_GRAPH_BYTES value and a later process runs under the default/lower bound, GC still calls open_selector at line 1590, which applies the current materialization ceiling and aborts the otherwise bounded reachability pass. The new opener bypasses precisely that irrelevant whole-graph limit, but currently only store validation uses it.
Useful? React with 👍 / 👎.
| installs.push(install_skill_package_at_scoped( | ||
| focused_destination, | ||
| consumers.clone(), | ||
| scope, | ||
| root, |
There was a problem hiding this comment.
Stage or roll back the whole sibling collection rather than committing each package inside this loop. If any later focused package fails to stage or rename—for example because of an I/O error after the umbrella or earlier focused skills were activated—the ? returns an installation failure while leaving a partially upgraded collection on disk. A retry may observe mixed manifests and doctor can report checksum failures; capture and restore all prior directories or atomically swap one staged collection.
AGENTS.md reference: AGENTS.md:L143-L145
Useful? React with 👍 / 👎.
| if existing.complete { | ||
| validate_candidate(database, plan).await?; | ||
| upsert_pointer(database, plan).await?; |
There was a problem hiding this comment.
Validate the stored records, not just their identity lists, before moving the active pointer. If a completed generation's payloadJson or projected fields are altered while its Compass node/edge IDs remain unchanged, validate_candidate succeeds because it compares only ID vectors, and this branch reactivates the generation; native queries then decode those altered payloads without recomputing the projection fingerprint. Compare the bounded stored records or per-record digests against the supplied plan before upsert_pointer.
AGENTS.md reference: AGENTS.md:L141-L145
Useful? React with 👍 / 👎.
Resolve upstream integration across graph, history, MCP, language, distribution, and qualification contracts. Co-Authored-By: Warp <agent@warp.dev>
|
Closing because this branch is intended to merge into the fork's main branch. The correct PR is GQAdonis#1: GQAdonis#1 |
1 participant
Summary
Completes the Compass scoping-and-bounds phase and integrates the current release line. The change delivers bounded discovery and query contracts, segmented snapshot publication, PR intelligence and task-context workflows, expanded agent distribution support, low-inference graph normalization, viewer workbench updates, and current MCP 2026-07-28 behavior.
It also establishes the immutable phase-first development doctrine in
AGENTS.mdandCLAUDE.md: complete implementation before compilation/testing, full integration tests as correctness evidence, serialized Cargo ownership, and smaller development profiles/artifacts.Motivation
This phase closes the planned scoping, bounded-work, storage, query, MCP, and agent-harness contracts while preserving deterministic publication and compatibility boundaries. C-011 was accepted for the Surreal dual-engine licensing decision. C-010 uses the latest MCP stack (
rmcp3.1.4 and protocol 2026-07-28).Verification
npm run test:jswas intentionally not run because the repository's phase doctrine accepts full integration suites—not unit-test harnesses—as correctness evidence. Browser integration changes remain covered by the checked-in integration specifications and deterministic asset/type gates.Compatibility and documentation
Public command, MCP, query, snapshot, history, viewer, security, performance, and migration documentation is updated. Unknown MCP resources now return
-32602with the requested URI in error data. The latest MCP conformance baseline passes; its remaining diagnostic probes are the repository's explicitly documented expected failures.Checklist
MIT OR Apache-2.0Co-Authored-By: Warp agent@warp.dev