docs(agent-graph): add continuous enrichment skill workflow

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

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

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`

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."

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.

crates/compass-cli/tests/install_cli.rs

@@ -106,6 +106,10 @@ fn project_codex_install_creates_native_compass_skill() -> Result<(), Box<dyn Er
     assert!(body.contains("references/operations.md"));
     assert!(body.contains("references/command-reference.md"));
     assert!(body.contains("references/agent-graph.md"));
+    assert!(body.contains("continuous overlay enrichment during coding sessions"));
+    assert!(body.contains("## Continuous enrichment mode"));
+    assert!(body.contains("rebase_required"));
+    assert!(body.contains("Load the continuous-enrichment reference"));
     assert!(body.contains("references/labeling.md"));
     assert!(body.contains("references/security-and-boundaries.md"));
     assert!(body.contains("run `compass update .`\nonce and continue"));
@@ -118,6 +122,7 @@ fn project_codex_install_creates_native_compass_skill() -> Result<(), Box<dyn Er
     let openai_metadata = fs::read_to_string(openai_metadata)?;
     assert!(openai_metadata.contains("display_name: \"Compass\""));
     assert!(openai_metadata.contains("default_prompt: \"Use $compass"));
+    assert!(openai_metadata.contains("continuous enrichment"));
     assert!(
         skill
             .with_file_name("references")
@@ -141,11 +146,17 @@ fn project_codex_install_creates_native_compass_skill() -> Result<(), Box<dyn Er
     assert!(agent_graph.contains("do not need to compose commands or JSON"));
     assert!(agent_graph.contains("Requests cannot award themselves"));
     assert!(agent_graph.contains("Never translate “delete this relation”"));
+    let continuous = fs::read_to_string(references.join("continuous-enrichment.md"))?;
+    assert!(continuous.contains("READ_ONLY"));
+    assert!(continuous.contains("READY_TO_FLUSH"));
+    assert!(continuous.contains("rebase-plan"));
+    assert!(continuous.contains("revision_conflict"));
+    assert!(continuous.contains("distinct read and write credentials"));
     assert_eq!(
         fs::read_dir(&references)?
             .collect::<Result<Vec<_>, _>>()?
             .len(),
-        16
+        17
     );
     let hooks: serde_json::Value =
         serde_json::from_slice(&fs::read(fixture.project.join(".codex/hooks.json"))?)?;

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<u32, OcrError> {
     if !value.is_finite() || value < 0.0 || value > bound as f32 || bound == 0 {
         return Err(OcrError::InvalidOutput(

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,

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

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:

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.