diff --git a/CHANGELOG.md b/CHANGELOG.md index 93aa1ced..2eda827c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,7 +10,10 @@ through CLI, MCP, CompassQL, task context, export, and the viewer. Writes and stronger curated masks remain deny-by-default capabilities. Add read-only ingestion preparation so agents can obtain canonical Base references and - source evidence without implementing Compass digest rules themselves. + source evidence without implementing Compass digest rules themselves. Extend + the bundled coding-agent skill with explicit continuous enrichment: bounded + milestone batches, revision pinning, source-change rebase gates, and + session-end receipts. - Replace the predefined flat call-flow architecture model with the native `compass.viewer.architecture/1` projection. Production source scope is fixed diff --git a/COMPATIBILITY.md b/COMPATIBILITY.md index 3d16db63..04b49d21 100644 --- a/COMPATIBILITY.md +++ b/COMPATIBILITY.md @@ -92,6 +92,13 @@ It calculates exact Base record and source-evidence digests for a selected Base Generation; it does not certify, mutate, or publish an assertion. Apply re-verifies prepared evidence against the pinned Base Generation. +The bundled Compass skill also supports an explicit continuous-enrichment mode +for coding sessions. This is an adapter workflow over the existing versioned +overlay commands, not a new graph or history schema: it keeps a bounded +session-local candidate ledger, publishes only milestone batches, pins each +receipt revision, and requires a complete rebase after a Base Generation +change. Read-only navigation remains the default. + Overlay writes require explicit CLI or server enablement. Existing MCP servers without Agent Graph configuration advertise no Agent Graph tools. Configured read-only servers advertise inspection only; HTTP writes additionally require diff --git a/crates/compass-cli/assets/compass-skill/SKILL.md b/crates/compass-cli/assets/compass-skill/SKILL.md index 729ed378..eea355d0 100644 --- a/crates/compass-cli/assets/compass-skill/SKILL.md +++ b/crates/compass-cli/assets/compass-skill/SKILL.md @@ -1,6 +1,6 @@ --- name: compass -description: "Use for graph-first AI coding sessions and repository analysis: session initialization, architecture maps, dependency or call-graph tracing, symbol and repository search, pull-request risk review, change-impact review, historical diffs, CompassQL, graph refreshes, GROUNDED agent-authored graph enhancements, exact overlay queries or rebases, exports, MCP serving, or project artifacts. Also use when the user invokes /compass or asks about Compass." +description: "Use for graph-first AI coding sessions and repository analysis: session initialization, architecture maps, dependency or call-graph tracing, symbol and repository search, pull-request risk review, change-impact review, historical diffs, CompassQL, graph refreshes, GROUNDED agent-authored graph enhancements, continuous overlay enrichment during coding sessions, exact overlay queries or rebases, exports, MCP serving, or project artifacts. Also use when the user invokes /compass or asks about Compass." compatibility: "Requires the Compass CLI; works with Agent Skills-compatible coding agents." metadata: version: "1" @@ -145,6 +145,38 @@ for this or a later coding session. rebase-plan` against the prior revision, and resolve every stale, missing, or ambiguous item explicitly before `rebase-commit`. Never first-match rebind. +## Continuous enrichment mode + +The default session mode is `read_only`. Enter `continuous` mode only after the +user explicitly asks Compass to keep enriching an overlay during this coding +session (or names an equivalent durable outcome). In continuous mode: + +1. Pin the project root, Base Generation, Overlay ID, active Overlay Revision, + composition profile, and write scope in the session context. Re-read + `status` after an interruption instead of trusting stale model memory. +2. Keep a bounded candidate ledger in session context. Each candidate records + a stable assertion key, fact type, exact Base node/edge or source-span + citations, endpoint identities, and a state: `candidate`, `prepared`, + `applied`, `deferred`, or `rebase_required`. Do not put prompts, + chain-of-thought, credentials, or user-private data in the overlay. +3. At useful milestones (orientation, a design decision, before a commit, and + session end), discard transient observations, query the exact overlay to + deduplicate durable facts, and flush a bounded group through `prepare`, a + strict batch, `apply`, `audit`, and `diff`. Never award `GROUNDED` in the + draft; advance the pin only from the verified receipt. +4. If the Base Generation changes, stop writes and enter `rebase_required`. + Refresh the graph, run `rebase-plan` from the pinned revision, resolve every + exact, missing, changed, or ambiguous item, and commit the complete + resolution before collecting new writes. A watch process is a refresh aid, + not permission to skip this gate. +5. At session end, report the exact Base Generation, Overlay ID, final revision, + composition profile, applied receipts, deferred candidates, and unresolved + conflicts. A later session resumes by pinning that receipt, not by replaying + conversational history. + +Load the continuous-enrichment reference when this mode is active; it contains +the state machine, milestone loop, bounded batching, and recovery checklist. + Create, replace, or retract only agent-owned assertions. Challenge a Base fact instead of deleting it. Curated masks are stronger, require `--allow-masks` in addition to write enablement, and need explicit user intent. `GROUNDED` means @@ -275,6 +307,7 @@ Load only the reference needed for the current request: - Complete command inventory and lifecycle: `references/command-reference.md` - Agentic session setup, GROUNDED overlay CRUD, revision pinning, and rebases: `references/agent-graph.md` +- Continuous coding-session enrichment, milestone batching, and rebase gates: `references/continuous-enrichment.md` - Query, CompassQL, paths, explanations, impact: `references/query.md` - Incremental refresh, clustering, output freshness: `references/update.md` - Semantic extraction, providers, caches: `references/semantic-extraction.md` diff --git a/crates/compass-cli/assets/compass-skill/agents/openai.yaml b/crates/compass-cli/assets/compass-skill/agents/openai.yaml index 2d406fc3..20198560 100644 --- a/crates/compass-cli/assets/compass-skill/agents/openai.yaml +++ b/crates/compass-cli/assets/compass-skill/agents/openai.yaml @@ -1,4 +1,4 @@ interface: display_name: "Compass" - short_description: "Graph navigation and GROUNDED agent enhancements" - default_prompt: "Use $compass to initialize this coding session, map the relevant code, and answer with cited graph and source evidence. Keep graph enhancement read-only unless I explicitly ask you to preserve GROUNDED agent knowledge." + short_description: "Graph navigation and continuous GROUNDED enrichment" + default_prompt: "Use $compass to initialize this coding session, map the relevant code, and answer with cited graph and source evidence. Keep graph enhancement read-only unless I explicitly ask you to preserve GROUNDED agent knowledge; when I enable continuous enrichment, pin revisions and flush only verified milestones." diff --git a/crates/compass-cli/assets/compass-skill/references/continuous-enrichment.md b/crates/compass-cli/assets/compass-skill/references/continuous-enrichment.md new file mode 100644 index 00000000..7571a0ff --- /dev/null +++ b/crates/compass-cli/assets/compass-skill/references/continuous-enrichment.md @@ -0,0 +1,93 @@ +# Continuous Agent Graph enrichment + +Load this reference after the user explicitly enables continuous overlay +enrichment for the current coding session. It turns the one-shot Agent Graph +workflow into a bounded loop while keeping ordinary Compass navigation and the +source-derived Base Graph read-only. + +## Contract and state machine + +Use these states in the assistant's session context: + +```text +READ_ONLY + └─ explicit user opt-in ─▶ PINNED +PINNED ─▶ COLLECTING ─▶ READY_TO_FLUSH ─▶ APPLIED ─▶ COLLECTING + │ │ │ + └─ Base change┴─────────────────┴─▶ REBASE_REQUIRED +REBASE_REQUIRED ─▶ REBASE_REVIEW ─▶ PINNED +COLLECTING ─▶ CLOSED (deferred candidates are reported) +``` + +`PINNED` stores the canonical project root, Base Generation, Overlay ID, +active Overlay Revision, composition profile, and write scope. `COLLECTING` +stores only a bounded candidate ledger: stable assertion key, intended CRUD +operation, endpoint identities, source spans or exact Base references, and a +short evidence summary. A conversation claim without a verifiable citation is +not a candidate for durable knowledge. Never store prompts, chain-of-thought, +credentials, or unrelated private data in the overlay audit trail. + +## Milestone loop + +At orientation, after a durable design decision, before a commit, and before +closing the session: + +1. Query the exact pinned Effective Graph and remove candidates already present. + Use the current assertion ID and digest for updates or retractions; never + create a duplicate because a label looks different. +2. Move only source-cited candidates to `READY_TO_FLUSH`. Keep batches bounded + by the active Agent Graph limits; flush before the candidate ledger or + request approaches a limit. Separate unrelated source spans when preparing + evidence. +3. Run `compass agent-graph prepare` for the exact Base nodes, edges, and + repository-relative byte spans. Copy its Base Generation, expected + revision, references, and grounding submission into a strict + `compass.agent-graph.batch/1` request. Do not hand-edit Compass digests or + add a certificate/status field. +4. Apply only with explicit local or MCP write authority. Treat the operation + as all-or-nothing. Record the receipt, audit it, inspect the revision diff, + and replace the pinned revision with the receipt's revision before the next + query or batch. Reusing an idempotency key is safe only for identical + content. + +Use `put_assertion` for agent-owned create/replace, `retract_assertion` for an +agent-owned deletion, and `put_challenge` when the user disputes a Base fact. +Never delete a Base node or edge. A curated mask is a separate, explicitly +authorized choice and is not part of ordinary continuous enrichment. + +## Source-change gate and recovery + +After `compass update .`, a watch refresh, a checkout change, or any command +that reports a new Base Generation, stop collecting writes and enter +`REBASE_REQUIRED`: + +```bash +compass agent-graph status --root . --graph compass-out/graph.json \ + --overlay overlay:review --format json +compass agent-graph rebase-plan --root . --graph compass-out/graph.json \ + --overlay overlay:review --revision OLD_REVISION --format json +``` + +Resolve every plan item. Exact identities may reattach; missing, changed, and +ambiguous targets require a newly grounded replacement, explicit retraction, +or a user decision. Submit the complete +`compass.agent-graph.rebase-commit/1` request, then pin its receipt and return +to `COLLECTING`. Do not first-match rebind, continue writes on the old Base, +or publish a partial rebase. + +For `revision_conflict`, inspect status/history/diff and regenerate against the +intended exact revision. For grounding or digest failures, reread the selected +source and prepare again. For disabled authority, retain the request as a +proposal and tell the user what explicit capability is required. At close, +report the Base Generation, overlay, final revision, profile, receipts, +deferred candidates, and unresolved conflicts so the next session can resume +deterministically. + +## MCP equivalent + +For a local coding session, configure a canonical project allowlist and use the +read-only `inspect_agent_graph` preparation before drafting a batch. Enable +`apply_agent_graph` only for the requested write scope; HTTP additionally needs +distinct read and write credentials. The server chooses principal, scope, +limits, and expiry. Keep the same pinned-revision, milestone, audit, and +rebase gates as the CLI workflow. diff --git a/crates/compass-cli/tests/install_cli.rs b/crates/compass-cli/tests/install_cli.rs index 3f64b9cc..f6878a34 100644 --- a/crates/compass-cli/tests/install_cli.rs +++ b/crates/compass-cli/tests/install_cli.rs @@ -106,6 +106,10 @@ fn project_codex_install_creates_native_compass_skill() -> Result<(), Box Result<(), Box Result<(), Box, _>>()? .len(), - 16 + 17 ); let hooks: serde_json::Value = serde_json::from_slice(&fs::read(fixture.project.join(".codex/hooks.json"))?)?; diff --git a/crates/compass-ocr/src/engine.rs b/crates/compass-ocr/src/engine.rs index e00d0191..d23a9dc1 100644 --- a/crates/compass-ocr/src/engine.rs +++ b/crates/compass-ocr/src/engine.rs @@ -385,10 +385,7 @@ fn sortable_float(value: f32) -> u32 { } } -#[cfg(any( - not(all(target_os = "macos", target_arch = "x86_64")), - test -))] +#[cfg(any(not(all(target_os = "macos", target_arch = "x86_64")), test))] fn quantize_coordinate(value: f32, bound: u32) -> Result { if !value.is_finite() || value < 0.0 || value > bound as f32 || bound == 0 { return Err(OcrError::InvalidOutput( diff --git a/docs/concepts/agent-graph-overlays.md b/docs/concepts/agent-graph-overlays.md index 8ea672e5..a8b218bf 100644 --- a/docs/concepts/agent-graph-overlays.md +++ b/docs/concepts/agent-graph-overlays.md @@ -45,6 +45,35 @@ Every batch binds the Base Generation, expected Overlay Revision, principal, permissions, limits, and idempotency key. Activation uses compare-and-swap, so concurrent writers cannot silently lose an update. +## Continuous coding-session enrichment + +An overlay can be enriched throughout an agentic coding session, but the +session itself is not a second source of truth. The assistant keeps a bounded, +ephemeral candidate ledger and publishes only durable, source-cited candidates +at explicit milestones. A useful loop is: + +```text +pin → inspect → collect → prepare → apply → audit/diff → re-pin + ↑ │ + └──── source change ──────┘ + rebase gate +``` + +The initial `status` response pins the project root, Base Generation, Overlay +ID, and active revision. Each successful receipt replaces the pinned revision. +After a refresh, checkout change, or watcher update, writes stop until +`rebase-plan` has been reviewed and every exact, missing, changed, or ambiguous +target has an explicit grounded replacement, Retraction, or user decision. +This prevents an agent from adding facts to a stale Base or silently rebinding +an assertion to the first similar symbol. + +Continuous mode is opt-in. Read-only navigation remains the default, and a +chat observation without verifiable source evidence stays transient. At +session end, the assistant reports the Base Generation, overlay, final +revision, composition profile, applied receipts, deferred candidates, and +unresolved conflicts. The next session resumes from those immutable selectors, +not from replayed conversation history. + ## Grounding evidence Version 1 accepts closed evidence forms for source spans, exact Base facts, diff --git a/docs/guides/assistant-setup.md b/docs/guides/assistant-setup.md index 3c74ce20..f6bd5cf6 100644 --- a/docs/guides/assistant-setup.md +++ b/docs/guides/assistant-setup.md @@ -73,6 +73,14 @@ enhancements that will help later coding sessions. Show every applied change, pin the resulting revision, and do not mask or delete Base Graph facts. ``` +For enrichment throughout one coding session, opt in explicitly: + +```text +Use Compass in continuous enrichment mode with overlay overlay:auth-review. +Keep navigation read-only, flush only source-cited milestones, pin each +receipt, and stop for a complete rebase after any Base Graph refresh. +``` + Read-only analysis does not authorize overlay writes. “Add,” “update,” “retract,” “challenge,” or “enhance” makes that intent explicit; masking still requires a separate request. The assistant should report the exact Base diff --git a/docs/guides/enhancing-a-graph-with-an-agent.md b/docs/guides/enhancing-a-graph-with-an-agent.md index a7571824..6bba0a5f 100644 --- a/docs/guides/enhancing-a-graph-with-an-agent.md +++ b/docs/guides/enhancing-a-graph-with-an-agent.md @@ -28,6 +28,34 @@ the user explicitly asks to add, update, retract, challenge, or enhance overlay knowledge. `GROUNDED` is awarded by Compass verification, not asserted by the assistant. +## Continuous mode during a coding session + +Use continuous mode when the assistant should preserve several durable +discoveries while it works, rather than waiting for one final batch: + +```text +Use Compass in continuous enrichment mode with overlay overlay:review for this +coding session. Keep navigation read-only by default. At useful milestones, +preserve only source-cited GROUNDED assertions, show each receipt, and pin the +new revision. Stop writes after any Base Graph refresh and resolve the rebase +plan before continuing. Do not mask Base facts. +``` + +The skill keeps a bounded candidate ledger in session context. At orientation, +after a durable design decision, before a commit, and at session end it queries +the exact Effective Graph, removes duplicates, prepares evidence, applies one +bounded strict batch, audits and diffs the receipt, and updates the revision +pin. Transient observations and unsupported chat claims are discarded. The +overlay audit trail contains only bounded attestations and digests, never the +prompt or chain-of-thought. + +If `compass update .`, `compass watch`, a checkout change, or another refresh +produces a new Base Generation, the assistant enters a rebase gate. It must +finish `rebase-plan` and resolve every exact, missing, changed, or ambiguous +target before it can publish another assertion. A later session resumes with +the reported Base Generation and overlay revision; it does not replay the old +conversation. + ## 1. Inspect the selected Base Generation For a Git repository: diff --git a/docs/reference/commands.md b/docs/reference/commands.md index 2886a225..cac8dd60 100644 --- a/docs/reference/commands.md +++ b/docs/reference/commands.md @@ -983,6 +983,14 @@ Export writes a self-describing `compass.agent-graph.effective/1` document and refuses an unsafe or existing destination. Usage errors exit `2`; typed domain, conflict, authorization, verification, storage, and limit errors exit `1`. +For continuous coding-session enrichment, there is no separate long-running +mutation command. The assistant repeats `status` → `prepare` → `apply` → +`audit`/`diff` at explicit milestones and pins the receipt revision after each +successful batch. A changed Base Generation puts the loop behind +`rebase-plan`/`rebase-commit`; writes must stop until every rebase item is +resolved. The bundled Compass skill documents this lifecycle while keeping +ordinary query and watch operations read-only. + ## Output and exit conventions Human text goes to stdout on success. Diagnostics go to stderr.