Docs/claude md - #326
Closed
GQAdonis wants to merge 43 commits into
Closed
Docs/claude md#326GQAdonis wants to merge 43 commits into
GQAdonis wants to merge 43 commits into
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>
AGENTS.md required every compiling Cargo command to set CARGO_TARGET_DIR beneath /Volumes/Workspace/crabbuild-target, and to stop rather than fall back to a local target/ when that volume was absent. That path is a macOS mount point specific to one contributor's machine, not a property of the project. On any checkout without it, an agent or contributor following AGENTS.md correctly concludes that no build, test, lint, or qualification step may be run at all. 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 compass-store release qualification gate unrunnable elsewhere; - both qualification scripts defaulted CARGO_TARGET_DIR to that absolute path, silently writing build output outside the checkout when the variable was unset. skills/compass-release/SKILL.md additionally listed the volume as a hard compatibility requirement and gated the release procedure on `test -d /Volumes/Workspace`. 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, and cargo clean only with an explicit target directory. Scripts now honor CARGO_TARGET_DIR when set and otherwise fall back to the checkout's own target directory. Documentation uses <cargo-target-dir> and <qualification-corpus-root> placeholders. Introduced in dd14b3c ("docs: add AI contributor guidance"). Fixes crabbuild#211 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>
Resolve upstream integration across graph, history, MCP, language, distribution, and qualification contracts. Co-Authored-By: Warp <agent@warp.dev>
Complete Compass scoping and bounds phase
fix: enforce graph size cap on actual canonical bytes
…l-graph-backend # Conflicts: # AGENTS.md # CHANGELOG.md # Cargo.lock # Cargo.toml # PERFORMANCE.md # crates/compass-cli/tests/history_cli.rs # crates/compass-graphdb-surreal/README.md # crates/compass-graphdb-surreal/src/projection.rs # crates/compass-graphdb-surreal/tests/projection.rs # crates/compass-model/src/code_graph.rs # deny.toml # docs/README.md # docs/implementation/surreal-graph-projection.md # scripts/qualify_code_graph_v1.sh # scripts/qualify_compass_store_release.sh # scripts/qualify_react_frontend_graph.sh
Publish generation-pinned projections, native typed queries and CompassQL, configuration, operations, and integration coverage. Preserve graph-digest binding during restore and scope generation GC by repository. Record operator-directed immediate deployment with remaining targeted verification and certification explicitly pending.
Integrate upstream releases 0.3.24 and 0.3.25 while retaining all fork functionality. Upstream additions preserved: - Typed Leiden community detection replacing Louvain, with compass.community-quality/1 evidence sidecars - Immutable-history authoritative limit raised 512 MiB -> 5 GiB - compass ensure worktree-safe graph bootstrap - compass review readability and strict URI node records Fork functionality retained: - compass-graphdb-surreal and compass-partition crates - compass agent list|install|doctor|export|validate|mcp-config namespace - distribution.toml native package generators - Bounded canonical graph-size preflight (enforce_preflight_graph_size) - COMPASS_MAX_GRAPH_BYTES override consistency - MCP 2026-07-28 discovery contract and rmcp 3.1.4 Conflict resolutions: - compass-history/Cargo.toml, compass-mcp/Cargo.toml: union of upstream 0.3.25 version bumps with fork dependencies - pipeline.rs: union of upstream Leiden imports with fork SnapshotError and max_canonical_graph_bytes - artifacts.rs: upstream streamed canonical encoding supersedes the fork sorting fix; removed the resulting dead canonical_trusted_graph_bytes - CHANGELOG.md: fork Unreleased entries above upstream released sections - Bumped remaining 0.3.23 path pins to 0.3.25 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01T4iiLG9sYTVt8tFtZv5iwe
…merge Upstream 0.3.24 edited the canonical umbrella SKILL.md to document the new `compass ensure` session and worktree bootstrap. The fork's build-time guard pins that file's SHA-256 to keep the six focused skills strictly additive, so the merged tree failed `compass-cli`'s build script. Only upstream modified SKILL.md; the fork has never touched it. Every other guard invariant still holds (canonical frontmatter, all eight required core sections, and all six focused skills), so re-pinning the digest is the correct resolution rather than reverting upstream's guidance. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01T4iiLG9sYTVt8tFtZv5iwe
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01T4iiLG9sYTVt8tFtZv5iwe
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Brings in SurrealDB CLI/MCP wiring, standalone server support, credential precedence, legacy query-artifact rejection, and the fork preflight size-gate fix (16a2e20). Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> # Conflicts: # PERFORMANCE.md # crates/compass-cli/Cargo.toml # crates/compass-cli/src/lib.rs # crates/compass-core/Cargo.toml # crates/compass-core/src/cluster_existing.rs # crates/compass-core/src/pipeline.rs # crates/compass-graphdb-surreal/Cargo.toml # crates/compass-query/Cargo.toml
Removes the hardcoded /Volumes/Workspace build-volume requirement from AGENTS.md, advisor plans, and qualification scripts. Docs and scripts only. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> # Conflicts: # AGENTS.md # scripts/qualify_code_graph_v1.sh
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Absorb upstream 0.3.26-0.3.28 (agent-readable query output, path and callers fidelity, Rust receiver recall) while preserving this fork's optional SurrealDB graph projection. Merge resolution: - Adopt upstream's compass.query/1 + agentView MCP contract in place of this fork's compass.code_context.v1 envelope. The four navigation tools no longer declare a raw output schema, matching upstream. - Keep the fork's envelope-level max_response_bytes bound, which upstream does not have: the query engine bounds the semantic result, and the delivered envelope is bounded after the agent view is attached. - Route the Surreal query path through the same envelope builder as the typed path, so both backends report one contract. - Add QueryGraph::degree for upstream's live CompassQL degree property, implemented for both the in-memory graph and the Surreal projection. Native Windows support, no WSL: - Reject an embedded store path containing "://" instead of silently retargeting the store when the address is split on its scheme. - Report restore cleanup that could not complete rather than discarding it. Embedded store owners are retained for the process lifetime, so Windows refuses the removal and used to leave a half-populated directory that the next attempt rejected as non-empty. - Hash the Surreal repository root losslessly so two distinct non-UTF-8 roots cannot collide onto one repository id. - Qualify the SurrealDB surfaces on windows-2025 in CI; building any SurrealDB feature there needs CMake and NASM for the transitive aws-lc-sys dependency, which the default build does not pull in. Also sync distribution.toml and the MCP discovery golden, which were pinned at 0.3.23 against a 0.3.25 workspace before this merge. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
`<[Value]>::is_empty` named a type that is not in scope in this test, so the history_cli target failed to compile. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The MCP navigation tools now return compass.mcp.tool-result/1. The migration guide previously told clients to read structuredContent.data under compass.code_context.v1, which no longer exists; it now maps every field of the withdrawn envelope onto the shipped one. Update the compatibility contract and integration guide to describe the result/agentView/semanticResultDigest shape, the absence of an advertised raw output schema, and the envelope-level max_response_bytes bound. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Two defects that only the SurrealDB feature builds exercise. The default workspace test wave compiles no Surreal engine, so both passed a green 216-suite run before CI caught them. Trail ranking: upstream 0.3.28 replaced the JSON engine's evidence-quality BFS with a Dijkstra weighted by relation kind, so the two backends chose different edges between the same node pair and the native/JSON differential assertion failed. Port that traversal into the Surreal backend: same cost function, admission rule, tie-breakers, and truncation semantics, using ordered maps so no decision depends on hash iteration. `code_relation_weight` is replicated beside the existing `evidence_quality` replica because compass-query is only a dev-dependency here; the copy names its source of truth. Degree: `QueryGraph::degree` reused `cql_adjacent_at`, which resolves every neighbor's ordinal and fails closed when one is absent, reporting "CQL adjacency endpoint identity mismatch". That is right for traversal and wrong for a degree, which counts incident edges whether or not the far endpoint is retained by the current selection. Add `cql_degree_at`, which counts relation rows under the same bound and stops before endpoint resolution. Also drop a `://` rejection added earlier in this merge. The SDK splits an address on its first `://`, which is always the `surrealkv://` prefix this code builds, so a colon inside the path — including a Windows drive letter — is already carried through as the path. The guard rejected valid paths and its test asserted the wrong behavior; replace it with one that asserts the real property. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The test opened a store directory named `store:colon`, which NTFS cannot create because it reserves `:` for alternate data streams. Windows CI reported `create_store_directory: The directory name is invalid. (os error 267)`. The property under test — a colon inside the path stays part of the path rather than being read as an address scheme — is exercised on Windows by every absolute path through its drive letter, which the other tests in this file already cover. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
…is unavailable `open_beneath` fails closed on non-Unix targets: there is no stdlib equivalent of component-by-component `openat` + `O_NOFOLLOW`, so rather than reopen the canonicalize-then-open race it returns `ErrorKind::Unsupported`. That decision is right and is unchanged here. The defect was the call site. `add_verified_files` propagated that error with `?`, so on Windows EVERY evidence-bearing query — explore, node, callers, callees, impact — returned nothing at all, on both x64 and arm64. The graph answer never depended on reading the file; only the inlined source evidence did. It now degrades exactly as a stale digest already does: the file is reported with `source: None` plus a `SourceConfinementUnsupported` diagnostic naming it, and the query succeeds. Only that one code degrades — an unsafe path or a read failure still aborts, because those are real problems rather than an unavailable mechanism. The classification is extracted into `classify_open_error` so it can be tested on every platform. The existing unit test for this path is `#[cfg(all(test, not(unix)))]`, which is why the propagation bug survived: nothing on Unix ever exercised the shape. The new tests run everywhere, and reverting the classification fails them (verified by mutation). Affects upstream too: crabbuild/compass carries the identical `?` at its line 3397, and no issue tracks it. Assisted-by: AGENT:claude-opus-5 [Bash,Edit,Read] Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…grade fix(code-query): degrade instead of aborting when source confinement is unavailable
`cargo package` rewrites every path dependency into a registry requirement and resolves it against crates.io. This workspace is not published there: `compass-graph` and `compass-files` do not exist on crates.io at all, and the `compass-cli` / `compass-core` names there belong to unrelated projects at unrelated versions (2.0.7, 0.1.0-alpha.1). So the step asserted an operation this project never performs, and failed for that reason rather than for any defect in the archives. It took the `quality`, `dependency-policy` and `dependency-audit` jobs down with it. No flag avoids the lookup — `--no-verify`, `--no-metadata`, `--allow-dirty` and `--offline` were each tried and each still resolved against the index. The requirement is structural, not a verification or a network step. Packaging is now checked on the three crates that have no sibling path dependencies, so they archive without a registry: compass-model, compass-files and compass-ir. That still catches a missing file, an unpackageable path or a broken manifest — the defects this step exists to find — on the leaves the rest of the workspace is built from. Each was verified to package successfully before being listed. Restore the workspace-wide form if these crates are ever published. Assisted-by: AGENT:claude-opus-5 [Bash,Edit,Read] Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
`QueryDiagnosticCode::SourceConfinementUnsupported` arrived with upstream 0.3.28 and is emitted by the query engine, but `agent_caveat` never matched it and that match has no catch-all, so compass-output did not compile. Report it as a Warning rather than a Blocker: the graph answer is still valid, only the source excerpt is missing. The wording tells an agent to read the file directly before quoting or editing, which is the behavior this platform limitation requires. Windows takes this path, since race-resistant source confinement is implemented only for Unix. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Absorb ten upstream commits (PR crabbuild#325): source-backed alias/import/export usage evidence in callers/impact/affected, live CompassQL node degree, historical reads that neutralize checkout filters, the bounded `compass architecture` view, and the shared agent output formats. Conflict resolution kept both sides wherever they were disjoint: - compass-model/src/search.rs: our `searchable_node_terms`, which the Surreal projection depends on, alongside upstream's new `RELATIONSHIP_SEARCH_EDGE_KINDS`. Neither side had the other's symbol. - compass-cli/src/install_commands.rs: our focused-skill collection preflight and consumer updates beside upstream's managed-skill probe and state-event journaling. All eight functions have live call sites. - compass-cli/src/help.rs: upstream's newer option text in all seven hunks, with our `--engine ...|surreal` option re-applied to each. One resolution takes upstream over this fork's version. Our `RELATIONSHIP_TERM_INDEX_CAPABILITY_V2` guarded postings that are byte-identical to the ones `_V1` guards: `af0bb1d0` added `_V2` without removing `_V1`, `direct_call_source_identifier_postings` is unchanged from the merge base, and the base already stored the `(source, term, target)` evidence that commit claimed as new. Keeping `_V2` would make this fork report incomplete relationship coverage for every upstream-written snapshot — a false negative on complete, immutable data — so the marker returns to `_V1` and the three remaining references follow it. No migration is required: snapshots from any 0.3.x-lineage builder stay mutually readable. The now-false v2 claims in CHANGELOG.md and COMPATIBILITY.md are corrected. Re-pin the canonical skill digest; upstream documented its new `architecture` command in SKILL.md, which the build-time guard rejects until the digest is refreshed. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
PR #5 makes code queries degrade instead of aborting when race-resistant source confinement is unavailable, which is every non-Unix platform. That is the upstream-side half of the Windows failure this branch was already carrying a consumer arm for: `agent_caveat` now renders the `SourceConfinementUnsupported` diagnostic as a Warning rather than a Blocker, so the graph answer still stands while an agent is told to read the file directly before quoting or editing it. Auto-merged with no conflicts; `clippy --workspace -D warnings` is clean. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
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
1 participant
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
Describe the user-visible or maintainer-visible change.
Motivation
Link the related Issue or Discussion and explain the problem this change addresses.
Verification
List the commands and manual checks you ran. Note any check you couldn't run and explain why.
Compatibility and documentation
Describe changes to commands, output, file formats, performance, or security boundaries. Link documentation or migration updates when applicable.
Checklist
MIT OR Apache-2.0