oacp-cli 0.4.5__tar.gz → 0.4.6__tar.gz

{oacp_cli-0.4.5 → oacp_cli-0.4.6}/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.6] - 2026-09-05
+
+### Added
+
+- Autonomy audits distinguish expected pauses from unplanned pauses ([pause classification](docs/protocol/autonomy.md#pause-classification)).
+- Human outcome records can retain the changes made when approving a modified task ([human outcomes](docs/protocol/autonomy.md#human-approval-and-decline-outcomes)).
+
+### Fixed
+
+- Startup safety and dispatch guidance follow the current exact-file archive lifecycle ([inbox lifecycle](docs/protocol/inbox_outbox.md#lifecycle)).
+- Startup guidance preserves project memory reads and retrieves org memory on demand ([memory context](docs/guides/memory-context.md)).
+
 ## [0.4.5] - 2026-09-02
 
 ### Changed
@@ -831,6 +843,7 @@ The central debrief store is the headline change: every agent's full end-of-sess
 - Checkout step in github-release workflow job (#19)
 - Pre-release audit fixes: SHA-pinned actions, dangling doc refs (#15, #16)
 
+[0.4.6]: https://github.com/kiloloop/oacp/compare/v0.4.5...v0.4.6
 [0.4.5]: https://github.com/kiloloop/oacp/compare/v0.4.4...v0.4.5
 [0.4.4]: https://github.com/kiloloop/oacp/compare/v0.4.3...v0.4.4
 [0.4.3]: https://github.com/kiloloop/oacp/compare/v0.4.2...v0.4.3

{oacp_cli-0.4.5 → oacp_cli-0.4.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: oacp-cli
-Version: 0.4.5
+Version: 0.4.6
 Summary: Open Agent Coordination Protocol CLI for file-based multi-agent workflows
 Project-URL: Homepage, https://github.com/kiloloop/oacp
 Project-URL: Repository, https://github.com/kiloloop/oacp
@@ -115,7 +115,7 @@ $OACP_HOME/projects/my-app/                  ● writing
   workspace.json                      metadata        [json]
 
 $OACP_HOME/org-memory/                org-wide
-  recent.md            auto-loaded    [⌘]
+  recent.md            on demand      [⌘]
   rules.md             12 rules       [⌘]
   decisions.md         org decisions  [⌘]
 ```
@@ -373,12 +373,16 @@ Optionally, `oacp org-memory init` creates org-level shared memory:
 
 ```
 $OACP_HOME/org-memory/
-├── recent.md                # Always-loaded rolling summary
+├── recent.md                # Rolling summary, retrieved on demand
 ├── decisions.md             # Org-wide decisions
 ├── rules.md                 # Standing conventions
 └── events/                  # Timestamped event entries
 ```
 
+Init loads the four active project memory files. Org memory is retrieved on
+demand; syncing it to disk does not load it into context. See
+[project context and org-memory retrieval](docs/guides/memory-context.md).
+
 ## Development
 
 ```bash

{oacp_cli-0.4.5 → oacp_cli-0.4.6}/QUICKSTART.md

@@ -108,6 +108,11 @@ sequentially. If hooks are unavailable, run the manual fallback:
 oacp session-init --pull-memory --project my-first-project
 ```
 
+Memory pull synchronizes files on disk. The init manifest names the protocol
+files and four project memory files to read into context; org memory is
+retrieved on demand. See [memory context](docs/guides/memory-context.md) for
+retrieval and existing-installation guidance.
+
 Runtime setup does not install an automatic memory push. Publish durable memory
 explicitly during wrap-up with `oacp memory push`.
 

{oacp_cli-0.4.5 → oacp_cli-0.4.6}/README.md

@@ -87,7 +87,7 @@ $OACP_HOME/projects/my-app/                  ● writing
   workspace.json                      metadata        [json]
 
 $OACP_HOME/org-memory/                org-wide
-  recent.md            auto-loaded    [⌘]
+  recent.md            on demand      [⌘]
   rules.md             12 rules       [⌘]
   decisions.md         org decisions  [⌘]
 ```
@@ -345,12 +345,16 @@ Optionally, `oacp org-memory init` creates org-level shared memory:
 
 ```
 $OACP_HOME/org-memory/
-├── recent.md                # Always-loaded rolling summary
+├── recent.md                # Rolling summary, retrieved on demand
 ├── decisions.md             # Org-wide decisions
 ├── rules.md                 # Standing conventions
 └── events/                  # Timestamped event entries
 ```
 
+Init loads the four active project memory files. Org memory is retrieved on
+demand; syncing it to disk does not load it into context. See
+[project context and org-memory retrieval](docs/guides/memory-context.md).
+
 ## Development
 
 ```bash

oacp_cli-0.4.6/docs/guides/memory-context.md

@@ -0,0 +1,72 @@
+# Project context and org-memory retrieval
+
+Load the active project memory at init. Retrieve org memory when a task needs
+shared rules, decisions, or recent cross-project context. Org-wide history can
+grow independently of the small project working set.
+
+| Store | Context policy |
+|---|---|
+| `projects/<project>/memory/` | Read `project_facts.md`, `decision_log.md`, `open_threads.md`, and `known_debt.md` in order at init. |
+| `projects/<project>/memory/archive/` | Historical detail; follow a relevant reference when needed. |
+| `org-memory/` | Search relevant topical files and read matching sections on demand. |
+
+## Initialization and synchronization
+
+Step 3 of the session-init protocol requires the four project files. In
+Codex, the init command verifies three
+protocol files and those four project files, then emits a manifest. The agent
+still performs the ordered reads; verification does not inject their contents.
+Missing project files are reported under the existing degraded-init behavior.
+
+`oacp memory pull` synchronizes the memory repository on disk, including org
+memory and its history. A successful pull does not add those files to model
+context. Keep any configured pull before project-memory reads so those reads
+use the refreshed files. Sync selection and context selection are independent;
+there is no need to remove org memory from sync to avoid eager loading.
+
+Hook enablement remains an adopter choice. This retrieval policy works with a
+trusted startup hook or a manual init invocation. It does not require enabling
+a hook that the project has disabled.
+
+## Retrieve org context for a task
+
+1. Resolve the configured OACP root and the org's topical filenames. Common
+   choices are `rules.md`, `decisions.md`, and `recent.md`; adopters can use
+   others. Read applicable standing rules and decisions before the actions
+   they govern, such as release, review authority, or architecture work.
+2. If cross-machine sync is configured, the task needs current shared facts,
+   and local freshness is unknown, run `oacp memory pull`. A failed pull leaves
+   freshness unknown; report that limitation before relying on affected facts.
+3. Search the relevant explicit files with task identifiers and topic terms.
+   For example, after confirming that `rules.md` exists:
+
+   ```bash
+   OACP_ROOT="${OACP_HOME:-$HOME/oacp}"
+   rg -n -- 'release|version' "$OACP_ROOT/org-memory/rules.md"
+   ```
+
+4. Read the full matching sections, including qualifications and provenance.
+   Follow relevant source links when needed; avoid loading unrelated history
+   or recursively reading `events/` and `debriefs/`. Read `recent.md` sections
+   when recent org-wide changes matter to the task.
+5. A search miss does not establish that no rule applies. Inspect relevant
+   headings or linked topic files when needed. Missing or unreadable files
+   are evidence gaps, not permission to bypass a known requirement. Verify
+   stale or conflicting claims against their authoritative sources.
+
+Runtime/project guidance may explicitly opt into a bounded startup summary.
+The `recent.md` curation budget is a storage-maintenance guideline, not a
+startup context budget. Keep required project reads intact even when org
+retrieval is deferred.
+
+## Update an existing installation
+
+Updated scaffolds apply to newly created files. Runtime setup and org-memory
+initialization preserve existing guidance and curated content; upgrading does
+not rewrite an old `Always-loaded` comment or a local mandatory-org-read rule.
+
+Review existing runtime instructions and summary comments explicitly. Keep the
+four project reads, replace blanket org-memory startup reads with the task-based
+policy above, and retain the underlying rules, decisions, history, and sync
+configuration. Avoid rerunning runtime setup solely to change prose: setup can
+register hooks, including ones an adopter intentionally disabled.

{oacp_cli-0.4.5 → oacp_cli-0.4.6}/docs/protocol/agent_safety_defaults.md

@@ -18,7 +18,7 @@ Cross-agent baseline safety rules. All agents (Claude, Codex, Cursor, Gemini) fo
 
 ## Inbox Safety
 
-- **Delete inbox messages immediately after processing.** For messages that require a reply (`task_request`, `question`, `review_request`), "processed" means reply sent. For `notification` messages, "processed" means read and acknowledged — no reply needed, delete right away. Do not let processed messages accumulate in the inbox.
+- **Follow the canonical [inbox lifecycle](inbox_outbox.md#lifecycle).** Complete required replies and terminal audit before atomically archiving the exact processed file without overwriting an archive entry. Changed bytes or failed archival leave input pending; a successful reply alone is not permission to delete it.
 - **Never silently consume a message that expects a response** — `task_request`, `question`, and `review_request` always require a reply. `notification` is no-response by default, but requires ack/reply when it reports findings or issues.
 - **Always reply** using `oacp send` with `--parent-message-id` to maintain threading.
 - **Idempotent sends** — before sending a response message (e.g., `review_feedback`, `review_addressed`, `review_request`), check the recipient's inbox and your own outbox for an already-sent message matching the same PR + round + type. Skip the send if a duplicate exists. This prevents retry storms when an agent crashes after sending a message but before completing the full workflow, and is re-invoked.

{oacp_cli-0.4.5 → oacp_cli-0.4.6}/docs/protocol/autonomy.md

@@ -106,6 +106,10 @@ schema-invalid profile pauses with `task_profile_unparsable`; it is not a fatal
 message-schema error. Message types listed in `allow_without_task_profile`, such
 as `brainstorm_request`, may auto-accept without the block.
 
+| Optional profile field | Meaning |
+| --- | --- |
+| `expected_pauses` | List of pause reason codes the sender expects to fire, for example `[estimated_minutes_exceeds_threshold, merges_pr_pause]`. Advisory only: unknown codes or malformed values produce declaration warnings, not new admission reasons. Existing safety checks still apply to the whole message. See [pause classification](#pause-classification). |
+
 `expected_files_touched` counts distinct deliverable files only: files created
 or modified as part of the requested outcome or a review-required correction.
 Exclude receiver-local inbox, outbox, audit, memory, cache, and scratch writes
@@ -433,6 +437,11 @@ Audit `schema_version: 2` adds thread identity and the structured
 `result.human_outcome` block. Recorders may upgrade a v1 audit to v2 when the
 first human outcome is written; standing grants trust only v2 records.
 
+| Optional audit evidence | Meaning |
+| --- | --- |
+| `pause_classification`, `expected_pause_codes`, `unplanned_pause_codes` | The paused decision's comparison against the sender's expected reasons; see [pause classification](#pause-classification). Older v2 records may omit all three. |
+| `result.human_outcome.modification` | Free-form YAML mapping recording what the human changed, such as `task_profile: {estimated_minutes: 60}` and `note: "Allow the larger task"`. Written by `--modification-file`; evidence only, with no effect on the scope envelope, standing grants, or checkpoint enforcement. |
+
 ### Contract version
 
 `spec_version` names the protocol contract an artifact was produced under.
@@ -510,6 +519,40 @@ deduplicated against `reason_codes`, and empty on auto-accepted decisions.
 Threshold-calibration analytics should read `reason_codes` and
 `co_occurring_reason_codes` together.
 
+### Pause classification
+
+Every new paused evaluation records `pause_classification`,
+`expected_pause_codes`, and `unplanned_pause_codes` as additive audit evidence.
+The fired set contains only pause reasons in that decision's `reason_codes`.
+Evidence codes such as `message_valid` and `schema_valid`, co-occurring reasons,
+and lexical notes never enter this set.
+
+| Declaration and fired reasons | Classification |
+| --- | --- |
+| `expected_pauses` absent | `undeclared` |
+| Every fired pause reason is expected | `designed` |
+| No fired pause reason is expected | `unplanned` |
+| Some, but not all, fired pause reasons are expected | `mixed` |
+
+`expected_pause_codes` preserves declared string entries, including unknown
+codes; unknown codes are ignored for comparison and recorded as declaration
+warnings in `logged_notes`.
+An absent or malformed declaration contributes no expected reasons.
+`unplanned_pause_codes` lists the fired reasons minus the recognized expected
+reasons.
+All message text, including the advisory value, remains subject to existing
+lexical safety checks.
+An unknown declaration adds no admission reason of its own, but a destructive
+token inside it still fires the same hard stop as that token elsewhere.
+The declaration cannot authorize work or suppress a fired pause.
+
+These fields and `human_outcome.modification` are additive and ignorable within
+audit schema v2: existing records validate unchanged, and readers may ignore the
+fields without changing an admission, finalization, doctor, or enforcement
+decision.
+There is no contract change under the [version rule](#contract-version).
+Historical records are not backfilled.
+
 ### Lexical provenance
 
 `matched_patterns` is a source-ordered list of every autonomy lexical match,
@@ -638,6 +681,18 @@ pause moment, and locks the full read-modify-write sequence before an atomic
 replacement. It refuses to overwrite a recorded outcome unless `--replace` is
 explicit. `decision` is `approved`, `modified`, or `declined`.
 
+| Flag | Meaning |
+| --- | --- |
+| `--modification-file <yaml>` | With `--decision modified`, read a free-form YAML mapping into `result.human_outcome.modification`. Without the file, the modified decision still records and prints a one-line `modification unrecorded` warning. |
+
+An empty mapping is valid.
+A missing, unreadable, invalid-YAML, or non-mapping file leaves the audit
+unchanged, as does using the flag with a decision other than `modified`.
+The payload records the human's delta without applying it to the original
+scope envelope or creating a standing grant.
+It cannot replace the earlier outcome when the command routes to a checkpoint
+clear; scoped checkpoint changes still use the re-authorization path below.
+
 The recorder is state-aware about where the pause moment lives:
 
 - **Admission pauses** (`completion_kind: admission_paused`): the record was

{oacp_cli-0.4.5 → oacp_cli-0.4.6}/docs/protocol/cross_runtime_sync.md

@@ -25,13 +25,15 @@ The protocol defines three complementary sync mechanisms, ordered from most dura
 | `open_threads.md` | Unresolved issues, blocked epics, cross-agent coordination | Any agent via the project's durable-memory promotion flow |
 | `known_debt.md` | Verified unresolved debt that should persist across sessions | Any agent via the project's durable-memory promotion flow |
 
-The top-level files in `memory/` are the active working set. Historical memory can be moved into `memory/archive/`, which is not loaded during session init unless an agent explicitly opts in.
+These four files are the active working set. Other project files and
+`memory/archive/` hold context retrieved when the task needs it; their presence
+does not add them to the required init reads. Org memory is also retrieved on demand.
 
-These files are the **source of truth** for stable project knowledge. All runtimes read the active working set at session start. Only verified, stable outcomes should be written here.
+These files are the **source of truth** for stable project knowledge. All runtimes read the four files in the order above at init. Only verified, stable outcomes should be written here.
 
 **Promotion flow**: Merge decisions contain a "Durable Memory Updates" section. Each implementation should provide a promotion mechanism that extracts approved entries from merge artifacts and appends them to the appropriate memory file, deduplicating against existing content.
 
-**Archive flow**: Users or coordinator agents may move non-standard memory files into `memory/archive/` for historical retention, then restore them back into `memory/` when they become active again.
+**Archive flow**: Users or coordinator agents may move non-standard memory files into `memory/archive/` for historical retention, then restore them back into `memory/` when needed again. Restoring a file does not add it to the required init read set.
 
 ### 2. Handoff Messages with Context Keys
 
@@ -72,7 +74,7 @@ Agents synchronize knowledge at well-defined points in the workflow:
 
 ### Claude
 
-- **Reads**: `CLAUDE.md` (project-level instructions, auto-loaded), `memory/` files (read at session start or on demand)
+- **Reads**: `CLAUDE.md` (project-level instructions, auto-loaded), the four active project memory files at init, and other project/org context on demand
 - **Writes**: Memory files via merge decisions + durable-memory promotion, handoff messages, review packets
 - **Context mechanism**: `CLAUDE.md` is injected into every conversation. Memory files are read explicitly.
 - **Tip**: Keep `CLAUDE.md` under 200 lines. Move detailed notes to memory files and reference them.
@@ -101,7 +103,7 @@ Avoid these common mistakes when syncing knowledge across runtimes:
 | Syncing ephemeral state (temp files, debug logs, partial results) | Clutters memory, confuses future agents | Only promote stable, verified outcomes |
 | Assuming shared context | Agent B cannot read Agent A's conversation history | Always include context in handoff messages |
 | Writing to memory too eagerly | Unverified or in-progress work pollutes the knowledge base | Wait until merge decision to promote |
-| Skipping memory reads at session start | Agent makes decisions contradicting prior work | Always read memory files before starting work |
+| Skipping project memory reads at session start | Agent makes decisions contradicting prior work | Read the four active project memory files; retrieve org memory on demand |
 
 ## Integration with durable-memory promotion
 

{oacp_cli-0.4.5 → oacp_cli-0.4.6}/docs/protocol/dispatch_states.yaml

@@ -349,5 +349,5 @@ constraints:
     - "rejected — agent rejected the task"
   inbox_file_lifecycle:
     - "Dispatch state is tracked via message replies (parent_message_id threading), NOT by retaining the original inbox file"
-    - "Agents delete the original task_request from inbox after processing (per inbox_outbox.md Lifecycle step 5)"
-    - "Long-lived states (blocked, in_review) persist in dispatcher tracking (dispatches.md), not as inbox files"
+    - "Agents follow inbox_outbox.md Lifecycle for terminal processing and exact-file, no-overwrite archival; changed bytes or failed archival leave input pending"
+    - "Long-lived states (blocked, in_review) persist in dispatcher tracking (dispatches.md); pending-file retention still follows inbox_outbox.md Lifecycle"

{oacp_cli-0.4.5 → oacp_cli-0.4.6}/docs/protocol/org_memory.md

@@ -8,7 +8,7 @@ Shared, cross-project memory for multi-agent organizations. Agents across projec
 
 ```
 $OACP_HOME/org-memory/
-  recent.md           # always-loaded rolling summary (~60K chars / ~15K tokens)
+  recent.md           # rolling summary (~60K chars / ~15K tokens)
   decisions.md        # topical: org-wide decisions (illustrative default)
   rules.md            # topical: standing conventions (illustrative default)
   events/             # chronological: timestamped entries
@@ -21,11 +21,17 @@ $OACP_HOME/org-memory/
 
 `decisions.md` and `rules.md` are illustrative defaults, not protocol requirements. Adopters choose which topical files to create (e.g., `agents.md`, `architecture.md`).
 
-Keep `recent.md` to approximately 60,000 characters (roughly 15,000 tokens),
-because its context cost is paid at every session start. Approximately 150
-lines remain a secondary readability hint only; when the measures disagree,
-the character budget governs. Collapse older detail into topical files or
-history so the file remains a rolling summary rather than a complete log.
+Org memory is retrieved on demand by default, separately from the four
+project memory files read during init. Runtime or project guidance may opt
+into a bounded startup summary; the directory layout does not require eager
+loading. See the adopter guide for [memory context and retrieval](../guides/memory-context.md).
+
+Keep `recent.md` to approximately 60,000 characters (roughly 15,000 tokens)
+unless adopter guidance sets a smaller budget. Approximately 150 lines remain
+a secondary readability hint only; when the measures disagree, the character
+budget governs. Collapse older detail into topical files or history so the
+file remains a bounded rolling summary when retrieved. This is a curation
+budget, not a requirement or allowance to load that much context at startup.
 
 ## Event File Schema
 
@@ -221,7 +227,7 @@ verified record — never partial bytes.
 Raw debriefs never enter `recent.md` or `events/` — only curated folds do.
 The coordinator reads debriefs and promotes durable outcomes into events and
 topical files; the raw session narrative stays in `debriefs/`. This keeps the
-always-loaded surfaces bounded and the event channel filtered. Debrief files
+curated surfaces bounded and the event channel filtered. Debrief files
 are likewise never auto-loaded at session start.
 
 ### Sync
@@ -276,7 +282,7 @@ Cortex demonstrates the dual-pipeline pattern — same source data, two audience
 1. Format spec (directory structure, frontmatter schema, naming convention)
 2. CLI: `oacp org-memory init` (scaffold directory, including `debriefs/`) and `oacp write-event` (create event files)
 3. Agents write their full session debrief to `org-memory/debriefs/` (via adopter tooling — see Debrief Store) and curated outcome events during debrief
-4. Agents read topical files + `recent.md` for org context
+4. Agents retrieve relevant sections of topical files and `recent.md` for org context on demand
 5. Coordinator maintains topical files during sync
 
 ## v0.3+

{oacp_cli-0.4.5 → oacp_cli-0.4.6}/docs/protocol/runtime_capabilities.md

@@ -177,6 +177,10 @@ registers a `SessionStart` handler that runs memory pull and `oacp session-init`
 sequentially after the user reviews and trusts it with `/hooks`. The manual
 fallback is `oacp session-init --pull-memory --project <project>`.
 
+Memory pull synchronizes disk files. Init names the required protocol and
+project-memory reads; org-memory retrieval is on demand. See
+[memory context](../guides/memory-context.md).
+
 Session telemetry beyond `status.yaml` is a runtime responsibility: the kernel
 neither defines a schema for it nor ships a reference implementation. A runtime
 that keeps its own session or packet telemetry stores it separately from

{oacp_cli-0.4.5 → oacp_cli-0.4.6}/docs/protocol/session_init.md

@@ -19,7 +19,7 @@ The init sequence has 6 steps in a fixed order. Each step is classified as **req
 ┌─────────────────────────────────────────────┐
 │ 1. Load global rules            [required]  │
 │ 2. Load project rules           [required]  │
-│ 3. Load durable memory          [required]  │
+│ 3. Load project memory          [required]  │
 │ 4. Check inbox                  [optional]  │
 │ 5. Load skills / tools          [optional]  │
 │ 6. Report status                [required]  │
@@ -54,13 +54,15 @@ The init sequence has 6 steps in a fixed order. Each step is classified as **req
 
 **Conflict resolution:** When global and project rules conflict, project rules win. Project rules are closer to the work and reflect repo-specific decisions. Exception: safety defaults from `agent_safety_defaults.md` cannot be relaxed by project rules — they can only be made stricter.
 
-### Step 3: Load Durable Memory
+<a id="step-3-load-durable-memory"></a>
+
+### Step 3: Load Project Memory
 
 **Required.** Read the project's shared memory files to restore cross-session and cross-runtime context.
 
 **Location:** `$OACP_HOME/projects/<project>/memory/`
 
-The top-level files in `memory/` are the active working set. `memory/archive/` is historical storage and is not loaded by default at session start.
+The four files below are the active working set. `memory/archive/` is historical storage and is not loaded by default at session start.
 
 **Loading order:**
 
@@ -69,6 +71,11 @@ The top-level files in `memory/` are the active working set. `memory/archive/` i
 3. `open_threads.md` — unresolved issues, blocked epics, cross-agent coordination. Read third because it builds on the context from facts and decisions.
 4. `known_debt.md` — verified unresolved debt, recurring pain points, and cleanup items that future sessions should keep in view.
 
+This required read set is project-scoped. `$OACP_HOME/org-memory/` is a
+separate store, retrieved on demand by default. Its summary, topical files,
+events, and debriefs are not part of Step 3. Read applicable org rules and
+decisions when the task needs them; see [memory context](../guides/memory-context.md).
+
 **Conflict resolution:** If memory files contradict project rules (e.g., `project_facts.md` says "use pytest" but `CLAUDE.md` says "use make test"), project rules win. Memory files may be stale; project rules are maintained alongside the code.
 
 **Runtime-specific memory:** Some runtimes maintain additional memory (e.g., Claude's `~/.claude/projects/<hash>/memory/MEMORY.md`). Runtime-specific memory supplements but does not override shared durable memory. Load runtime-specific memory after shared memory.
@@ -142,7 +149,7 @@ If a **required** step fails:
 |------|-------------|--------|
 | Global rules | File missing or unreadable | Warn user, continue with defaults (safety defaults still apply) |
 | Project rules | File missing or unreadable | Warn user, continue — project may not have agent config |
-| Durable memory | Directory or files missing | Log absence, continue — project may not be initialized |
+| Project memory | Directory or files missing | Log absence, continue — project may not be initialized |
 | Report status | Cannot write status.yaml | Warn user — dispatch routing will be degraded but work can proceed |
 
 No init failure should prevent the agent from starting. All failures are **degraded mode**, not hard blocks. The agent reports what failed and continues.
@@ -156,6 +163,7 @@ This section provides guidance for per-runtime implementations.
 Steps 1-2 are handled automatically by Claude Code (CLAUDE.md loading). Step 3 requires explicit file reads or auto-memory. Step 4 uses `/check-inbox`. Step 5 is automatic (skill discovery). Step 6 requires a startup hook or explicit script call.
 
 `oacp setup claude` registers the marker-gated memory pull at `SessionStart`.
+Pull synchronizes files on disk; it does not load org memory into context.
 It intentionally does not publish memory at `SessionEnd`; wrap-up owns the
 single explicit `oacp memory push` path. Claude status reporting remains an
 explicit runtime responsibility, and so is any session telemetry beyond
@@ -167,12 +175,13 @@ runtime-kept telemetry is never a `status.yaml` writer.
 Steps 1-2 are handled by AGENTS.md loading. Running `oacp setup codex
 --project <project>` installs one repo-local `SessionStart` handler in
 `.codex/hooks.json`. After the user reviews and trusts it with `/hooks`, the
-handler sequentially pulls shared memory and runs `oacp session-init`. No
-Codex `SessionEnd` hook is installed.
+handler sequentially pulls shared memory to disk and runs `oacp session-init`.
+No Codex `SessionEnd` hook is installed.
 
-The init command verifies that protocol and durable-memory files are readable,
-updates `status.yaml`, and emits bounded developer context naming the required
+The init command verifies that protocol and the four project memory files are
+readable, updates `status.yaml`, and emits bounded developer context naming the required
 ordered reads. It does not claim that the full file contents were injected.
+Org-memory content is not read by this verification or included in its manifest.
 Use this manual fallback when the project hook is unavailable or untrusted:
 
 ```bash
@@ -198,7 +207,8 @@ Steps 1-2 are handled by system prompts and `.agent/rules/`. Steps 3-6 can be im
 
 | Anti-Pattern | Why It Fails | Do Instead |
 |--------------|-------------|------------|
-| Skipping memory reads to "save time" | Agent contradicts prior decisions, duplicates work | Always read memory files — they're small and fast |
+| Skipping active project memory to "save time" | Agent contradicts prior project decisions, duplicates work | Read the four project memory files in Step 3 |
+| Loading the entire org-memory store at init | Context grows with org-wide history and unrelated projects | Retrieve relevant org sections on demand |
 | Auto-processing inbox during init | Surprises the user with unseen actions | Summarize inbox count, let user trigger processing |
 | Writing status.yaml only at session close | Dispatch router thinks agent is offline during work | Write at init AND close (and task boundaries) |
 | Loading all skills eagerly | Slows init, wastes resources for unused tools | Load on-demand; only validate critical tools at init |

{oacp_cli-0.4.5 → oacp_cli-0.4.6}/examples/demo-workspace/README.md

@@ -77,8 +77,8 @@ the loop:
    now carries the rule with "promoted from 3 events" provenance pointing back
    at all three.
 5. **The rolling summary reflects it** — [`org-memory/recent.md`](org-memory/recent.md)
-   (the always-loaded file) lists the rule under Standing Rules, so every
-   agent sees it without scanning events.
+   lists the rule under Standing Rules, so an agent can retrieve it when
+   relevant without scanning events.
 
 `decisions.md` shows the same flow for a one-shot architectural call
 (PostgreSQL over DynamoDB) rather than a repeating pattern.
@@ -97,7 +97,7 @@ demo-workspace/                       ← shaped like $OACP_HOME
         archive/
           2026-05-21-csv-export-timeouts.md   closed thread, 3 dated entries
   org-memory/                         org-wide knowledge
-    recent.md                         always-loaded rolling summary
+    recent.md                         rolling summary, retrieved on demand
     rules.md                          standing conventions (curated)
     decisions.md                      architectural calls (curated)
     events/                           raw signal — 6 events, 3 types

{oacp_cli-0.4.5 → oacp_cli-0.4.6}/examples/demo-workspace/org-memory/recent.md

@@ -1,6 +1,7 @@
 # Org Memory — Rolling Summary
 
-<!-- Always-loaded context for agents. Keep under ~150 lines. -->
+<!-- Retrieved on demand; not required startup context. -->
+<!-- Keep near 60,000 characters or the adopter's smaller budget; ~150 lines is a readability hint. -->
 <!-- Updated by coordinator during sync/curation. -->
 <!-- Last curated: 2026-06-02 by nova -->
 

{oacp_cli-0.4.5 → oacp_cli-0.4.6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "oacp-cli"
-version = "0.4.5"
+version = "0.4.6"
 description = "Open Agent Coordination Protocol CLI for file-based multi-agent workflows"
 readme = "README.md"
 license = "Apache-2.0"
@@ -108,6 +108,8 @@ packages = ["oacp"]
 "docs/protocol/message_signing.md" = "oacp/_protocol/message_signing.md"
 "docs/protocol/autonomy.md" = "oacp/_protocol/autonomy.md"
 "docs/protocol/org_memory.md" = "oacp/_protocol/org_memory.md"
+# Preserve ../guides/ links from the shipped protocol documents.
+"docs/guides/memory-context.md" = "oacp/guides/memory-context.md"
 "templates/inbox_message.template.yaml" = "oacp/_templates/inbox_message.template.yaml"
 "templates/runtime_capabilities.yaml" = "oacp/_templates/runtime_capabilities.yaml"
 "templates/org-memory/recent.md" = "oacp/_templates/org-memory/recent.md"

{oacp_cli-0.4.5 → oacp_cli-0.4.6}/scripts/autonomy_gate.py

@@ -248,6 +248,24 @@ PINNED_REASON_CODES = frozenset({
     "threshold_checkpoint_breached",
     "workspace_check_required",
 })
+# Success and advisory evidence belongs in reason_codes but never names a
+# fired pause, even if a caller records that evidence alongside a blocker.
+PAUSE_REASON_CODES = PINNED_REASON_CODES - frozenset({
+    "checkpoint_reauthorized",
+    "continuation_grant_accepted",
+    "hard_stops_clear",
+    "lexical_advisory",
+    "message_hash_recorded",
+    "message_not_expired",
+    "message_valid",
+    "review_continuation_accepted",
+    "review_continuation_head_mismatch",
+    "risk_threshold_passed",
+    "task_profile_not_required",
+    "task_profile_present",
+    "task_type_allowed",
+    "workspace_check_required",
+})
 
 GUARDRAILS_FENCE_RE = re.compile(
     r"(?ms)^[ \t]*```oacp-guardrails[ \t]*\n"
@@ -826,6 +844,53 @@ def extract_task_profile(body: str) -> Tuple[Optional[Dict[str, Any]], Optional[
     return None, None
 
 
+def _expected_pause_declaration(
+    body: str,
+) -> Tuple[bool, List[str], List[Dict[str, str]]]:
+    """Read audit-only declarations without altering the safety-check input."""
+    profile, error = extract_task_profile(body)
+    if error or profile is None or "expected_pauses" not in profile:
+        return False, [], []
+    declared = profile["expected_pauses"]
+    codes: List[str] = []
+    warnings: List[Dict[str, str]] = []
+
+    def warn(detail: str) -> None:
+        warnings.append({"code": "expected_pauses_declaration_warning", "detail": detail})
+
+    if not isinstance(declared, list):
+        warn("task_profile.expected_pauses must be a list; ignored")
+    else:
+        for index, code in enumerate(declared):
+            if not isinstance(code, str):
+                warn(f"task_profile.expected_pauses[{index}] must be a string; ignored")
+                continue
+            codes.append(code)
+            if code not in PAUSE_REASON_CODES:
+                warn(f"task_profile.expected_pauses[{index}] is not a recognized pause reason code; ignored")
+
+    return True, codes, warnings
+
+
+def _classify_pause(
+    reason_codes: Sequence[str], expected_declared: bool, expected_codes: Sequence[str],
+) -> Dict[str, Any]:
+    """Classify fired pause reasons; success/advisory evidence is excluded."""
+    fired = list(dict.fromkeys(code for code in reason_codes if code in PAUSE_REASON_CODES))
+    expected = set(expected_codes) & PAUSE_REASON_CODES
+    unplanned = [code for code in fired if code not in expected]
+    return {
+        "expected_pause_codes": list(expected_codes),
+        "unplanned_pause_codes": unplanned,
+        "pause_classification": (
+            "undeclared" if not expected_declared
+            else "designed" if not unplanned
+            else "unplanned" if len(unplanned) == len(fired)
+            else "mixed"
+        ),
+    }
+
+
 def _bool_value(profile: Dict[str, Any], key: str) -> bool:
     value = profile.get(key, False)
     if isinstance(value, bool):
@@ -3483,7 +3548,9 @@ def evaluate_autonomy(
     policy_hash = canonical_policy_sha256(config)
     body = str(message.get("body") or "")
     msg_type = str(message.get("type") or "")
-    logged_notes: List[Dict[str, str]] = []
+    expected_declared, expected_codes, logged_notes = (
+        _expected_pause_declaration(body)
+    )
     profile_snapshot: Optional[Dict[str, Any]] = None
     envelope_source: Optional[str] = None
     # Resolved below; pre-bound so early pauses (malformed config) can
@@ -3535,6 +3602,11 @@ def evaluate_autonomy(
         )
         decision.setdefault("co_occurring_reason_codes", [])
         decision["admission_axes"] = admission_axes
+        if decision.get("decision") == "paused":
+            # Only the reasons that drove this pause are fired. Ledger,
+            # co-occurring, and lexical evidence never add classification
+            # inputs or alter admission/approval authority.
+            decision.update(_classify_pause(reason_codes, expected_declared, expected_codes))
         decision["matched_patterns"] = _collect_lexical_provenance(
             body,
             profile_snapshot,

{oacp_cli-0.4.5 → oacp_cli-0.4.6}/scripts/codex_session_init.py

@@ -402,8 +402,10 @@ def build_session_start_hook_output(
         *[f"- {name}" for name in PROTOCOL_FILES],
         f"Project memory root: {memory_root}",
         *[f"- {name}" for name in MEMORY_FILES],
-        "Then read org-memory/recent.md when present, plus relevant decisions.md "
-        "and rules.md, as required by the active AGENTS.md.",
+        "Org memory is separate from these required project reads: retrieve it "
+        "on demand by default under the active AGENTS.md policy. Read applicable "
+        "org rules and decisions before work they govern.",
+        "Memory pull synchronizes disk files; it does not load org content into context.",
         "Include the exact SESSION_INIT_ACK line above in the first response after startup.",
     ]
     if report["warnings"]: