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

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

@@ -7,6 +7,43 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-09-09
+
+### Added
+
+- Memory-layout conformance fixture pinning the layout grammar and sync allowlist ([fixture](tests/conformance/memory_layout/README.md)).
+- `oacp doctor` reports the installed `agent-memory` version and defers memory-home checks to it ([doctor guide](docs/guides/doctor.md)).
+- Preflight and wheel guards fail when a kernel module or the wheel ships the memory engine ([lean kernel](docs/protocol/org_memory.md#conformance)).
+
+### Changed
+
+- The org-memory doc becomes the three-tier memory layout spec the kernel scaffolds against ([memory layout](docs/protocol/org_memory.md#layout)).
+- `oacp memory` and `oacp org-memory` delegate to the `agent-memory` CLI until their removal in 0.5.2 ([README](README.md#commands)).
+- `oacp setup` no longer installs memory hooks and retires the ones it generated; `agent-memory setup` replaces them ([quickstart](QUICKSTART.md)).
+- `oacp session-init --pull-memory` delegates to `agent-memory`, reporting `disabled` when absent ([codex](docs/protocol/session_init.md#codex)).
+
+### Removed
+
+- `docs/protocol/cross_runtime_sync.md`; its durable-memory half moved to the layout spec ([layout](docs/protocol/org_memory.md#per-project-tier)).
+- The bundled memory engine and org-memory doctor category, shipped as `agent-memory-cli` ([agent-memory](https://github.com/kiloloop/agent-memory)).
+- `oacp doctor --memory`; the memory home is checked by `agent-memory doctor` ([doctor guide](docs/guides/doctor.md)).
+
+### Fixed
+
+- `oacp setup codex` regenerates its managed `SessionStart` hook but never creates one ([codex startup](docs/protocol/session_init.md#codex)).
+
+## [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 +868,8 @@ 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.5.0]: https://github.com/kiloloop/oacp/compare/v0.4.6...v0.5.0
+[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.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: oacp-cli
-Version: 0.4.5
+Version: 0.5.0
 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  [⌘]
 ```
@@ -262,13 +262,13 @@ uv tool install .
 | `oacp inbox` | List pending inbox messages |
 | `oacp watch` | Emit inbox delta events for Monitor-friendly polling |
 | `oacp retention` | Prune project message history by age and count |
-| `oacp memory` | Archive, restore, or sync memory files |
+| `oacp memory` | Run agent-memory (sync, archive, restore); shim until 0.5.2 |
 | `oacp session-init` | Verify Codex startup inputs and emit SessionStart context |
 | `oacp setup` | Generate runtime-specific config files in a repo |
 | `oacp send` | Send a protocol-compliant inbox message |
 | `oacp key` | Generate and inspect message-signing keys |
 | `oacp trust` | Import, inspect, and revoke trust-root entries (catalog + pins) |
-| `oacp org-memory` | Initialize org-level memory at $OACP_HOME/org-memory/ |
+| `oacp org-memory` | Run agent-memory org (init); shim until 0.5.2 |
 | `oacp write-event` | Write an event to org-memory/events/ |
 | `oacp autonomy-outcome` | Record a human approval/decline in an autonomy audit |
 | `oacp autonomy-finalize` | Record checkpoints and terminal states in an autonomy audit |
@@ -287,9 +287,9 @@ uv tool install .
 
 **`oacp watch`**: `--agent`, repeatable `--project`, `--all-projects`, `--json`, `--since` (default `now`), `--state-id <id>` for per-subscriber cursors, `--show-archived`
 
-**`oacp doctor`**: `--fix` (auto-fix safe issues), `--memory`, `--json`, `-o/--output`
+**`oacp doctor`**: `--fix` (auto-fix safe issues), `--json`, `-o/--output`
 
-**`oacp memory`**: `init [--remote URL]`, `clone <URL> [--force]`, `pull`, `push`, `disable`, `archive <project> <file>`, `restore <project> <file>`
+**`oacp memory`** / **`oacp org-memory`**: exec shims for [agent-memory](https://github.com/kiloloop/agent-memory) (`pip install agent-memory-cli`): argv passes through, `--oacp-dir` becomes `--home`, `oacp memory init` runs `agent-memory enable`. Kept through 0.5.1, removed in 0.5.2; call `agent-memory` directly.
 
 </details>
 
@@ -369,15 +369,16 @@ $OACP_HOME/projects/<project>/
 └── workspace.json           # Project metadata
 ```
 
-Optionally, `oacp org-memory init` creates org-level shared memory:
+Org-level shared memory and cross-machine sync are the memory tool's:
+[agent-memory](https://github.com/kiloloop/agent-memory) (`pip install
+agent-memory-cli`) scaffolds `$OACP_HOME/org-memory/` (`agent-memory org init`),
+syncs the home (`enable`, `pull`, `push`), checks it (`agent-memory doctor`), and
+installs the runtime startup hook (`agent-memory setup <runtime>`). The layout it
+implements is the kernel's [memory layout spec](docs/protocol/org_memory.md).
 
-```
-$OACP_HOME/org-memory/
-├── recent.md                # Always-loaded rolling summary
-├── 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
 

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

@@ -89,9 +89,14 @@ This creates or updates:
 
 - `.claude/agents/my-first-project.md`
 - `.claude/skills/`
-- `.claude/hooks/oacp-memory-pull.sh`
 - `.claude/settings.json`
 
+Memory sync and its startup hook are the memory tool's: install
+[agent-memory](https://github.com/kiloloop/agent-memory) (`pip install
+agent-memory-cli`) and run `agent-memory setup claude`. A regeneration of
+`oacp setup` retires the memory hooks earlier kernels wrote, by exact command
+and digest, and leaves anything you edited in place.
+
 For other supported runtimes, use the same shape:
 
 ```bash
@@ -101,15 +106,21 @@ oacp setup gemini --project my-first-project
 ```
 
 Codex setup creates or merges `.codex/hooks.json` with one startup-only hook.
-Review and trust it with `/hooks`; it runs memory pull and startup verification
-sequentially. If hooks are unavailable, run the manual fallback:
+Review and trust it with `/hooks`; it runs the startup verification. If hooks
+are unavailable, run the manual fallback:
 
 ```bash
-oacp session-init --pull-memory --project my-first-project
+oacp session-init --project my-first-project
 ```
 
+The init manifest names the protocol files and four project memory files to
+read into context; org memory is retrieved on demand. Syncing the home is
+`agent-memory pull` (its `setup codex` hook runs it at startup). 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`.
+explicitly during wrap-up with `agent-memory push`.
 
 Cursor support is scaffold-only until Cursor-owned rules land. Cursor sessions
 must set `OACP_RUNTIME=cursor` or pass `--from` explicitly when sending messages.
@@ -221,7 +232,7 @@ checks the project workspace, inboxes, schemas, and agent status files.
 ## What's Next?
 
 - **Review loop** — Set up structured code review between agents. See [docs/protocol/review_loop.md](docs/protocol/review_loop.md).
-- **Durable memory** — Learn how agents share knowledge across sessions. See [docs/protocol/cross_runtime_sync.md](docs/protocol/cross_runtime_sync.md).
+- **Durable memory** — Learn how agents share knowledge across sessions and machines. See [docs/protocol/org_memory.md](docs/protocol/org_memory.md).
 - **Safety defaults** — Understand the baseline safety rules. See [docs/protocol/agent_safety_defaults.md](docs/protocol/agent_safety_defaults.md).
 - **Full protocol** — Read the complete specification in [SPEC.md](SPEC.md).
 - **Adoption guide** — Minimum, recommended, and full adoption paths. See [docs/guides/adoption.md](docs/guides/adoption.md).

{oacp_cli-0.4.5 → oacp_cli-0.5.0}/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  [⌘]
 ```
@@ -234,13 +234,13 @@ uv tool install .
 | `oacp inbox` | List pending inbox messages |
 | `oacp watch` | Emit inbox delta events for Monitor-friendly polling |
 | `oacp retention` | Prune project message history by age and count |
-| `oacp memory` | Archive, restore, or sync memory files |
+| `oacp memory` | Run agent-memory (sync, archive, restore); shim until 0.5.2 |
 | `oacp session-init` | Verify Codex startup inputs and emit SessionStart context |
 | `oacp setup` | Generate runtime-specific config files in a repo |
 | `oacp send` | Send a protocol-compliant inbox message |
 | `oacp key` | Generate and inspect message-signing keys |
 | `oacp trust` | Import, inspect, and revoke trust-root entries (catalog + pins) |
-| `oacp org-memory` | Initialize org-level memory at $OACP_HOME/org-memory/ |
+| `oacp org-memory` | Run agent-memory org (init); shim until 0.5.2 |
 | `oacp write-event` | Write an event to org-memory/events/ |
 | `oacp autonomy-outcome` | Record a human approval/decline in an autonomy audit |
 | `oacp autonomy-finalize` | Record checkpoints and terminal states in an autonomy audit |
@@ -259,9 +259,9 @@ uv tool install .
 
 **`oacp watch`**: `--agent`, repeatable `--project`, `--all-projects`, `--json`, `--since` (default `now`), `--state-id <id>` for per-subscriber cursors, `--show-archived`
 
-**`oacp doctor`**: `--fix` (auto-fix safe issues), `--memory`, `--json`, `-o/--output`
+**`oacp doctor`**: `--fix` (auto-fix safe issues), `--json`, `-o/--output`
 
-**`oacp memory`**: `init [--remote URL]`, `clone <URL> [--force]`, `pull`, `push`, `disable`, `archive <project> <file>`, `restore <project> <file>`
+**`oacp memory`** / **`oacp org-memory`**: exec shims for [agent-memory](https://github.com/kiloloop/agent-memory) (`pip install agent-memory-cli`): argv passes through, `--oacp-dir` becomes `--home`, `oacp memory init` runs `agent-memory enable`. Kept through 0.5.1, removed in 0.5.2; call `agent-memory` directly.
 
 </details>
 
@@ -341,15 +341,16 @@ $OACP_HOME/projects/<project>/
 └── workspace.json           # Project metadata
 ```
 
-Optionally, `oacp org-memory init` creates org-level shared memory:
+Org-level shared memory and cross-machine sync are the memory tool's:
+[agent-memory](https://github.com/kiloloop/agent-memory) (`pip install
+agent-memory-cli`) scaffolds `$OACP_HOME/org-memory/` (`agent-memory org init`),
+syncs the home (`enable`, `pull`, `push`), checks it (`agent-memory doctor`), and
+installs the runtime startup hook (`agent-memory setup <runtime>`). The layout it
+implements is the kernel's [memory layout spec](docs/protocol/org_memory.md).
 
-```
-$OACP_HOME/org-memory/
-├── recent.md                # Always-loaded rolling summary
-├── 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
 

{oacp_cli-0.4.5 → oacp_cli-0.5.0}/SPEC.md

@@ -23,7 +23,7 @@ documents ship inside the `oacp-cli` wheel.
 | [`docs/protocol/inbox_outbox.md`](docs/protocol/inbox_outbox.md) | Wire format including the signed `auth` trailer; directory layout; message types; lifecycle — a processed inbound message is archived to `inbox/archive/` by digest-checked, no-clobber move (never deleted), and an intake rejection is quarantined to `dead_letter/`; threading, broadcast, expiry, retention. |
 | [`docs/protocol/message_signing.md`](docs/protocol/message_signing.md) | Trust root and receiver pins, verify modes (`off` / `warn` / `enforce`), receiver audit stamping, policy-file signing, key management, rotation and revocation, signing conformance. |
 | [`docs/protocol/autonomy.md`](docs/protocol/autonomy.md) | Receiver autonomy: config and task profiles, the four-gate admission evaluator and hard stops, audit records (admission ledger, human outcomes, terminal finalization), threshold checkpoints and re-authorization, scope-envelope enforcement, continuation grants. |
-| [`docs/protocol/org_memory.md`](docs/protocol/org_memory.md) | Org-level memory: directory structure, event file schema, the debrief store, permission model and lifecycle. |
+| [`docs/protocol/org_memory.md`](docs/protocol/org_memory.md) | Memory layout: the per-project, org, and cross-machine tiers — paths, files, who writes what, the event and debrief schemas, the sync marker and allowlist. |
 
 ## Userland documents
 
@@ -36,7 +36,6 @@ receiver must verify.
 | [`docs/protocol/task_negotiation.md`](docs/protocol/task_negotiation.md) | Propose / accept / counter-propose handshake for splitting work between agents. |
 | [`docs/protocol/multi_agent_shared_workspace.md`](docs/protocol/multi_agent_shared_workspace.md) | Shared-folder implementation → QA → deployment handoff with batched findings and signoff. |
 | [`docs/protocol/session_init.md`](docs/protocol/session_init.md) | Runtime-agnostic session-start sequence and failure handling. |
-| [`docs/protocol/cross_runtime_sync.md`](docs/protocol/cross_runtime_sync.md) | Keeping context consistent across runtimes: durable memory, handoff messages, review artifacts. |
 | [`docs/protocol/runtime_capabilities.md`](docs/protocol/runtime_capabilities.md) | Static capability declarations, dynamic `status.yaml`, health-check contract, agent cards. |
 | [`docs/protocol/agent_profiles.md`](docs/protocol/agent_profiles.md) | Two-tier identity: global agent profiles and project-level agent cards. |
 | [`docs/protocol/agent_safety_defaults.md`](docs/protocol/agent_safety_defaults.md) | Baseline git, staging, inbox, credential, and scope rules every agent follows. |
@@ -49,7 +48,7 @@ Guides — [`docs/guides/setup.md`](docs/guides/setup.md),
 [`versioning.md`](docs/guides/versioning.md),
 [`unified_skill_spec.md`](docs/guides/unified_skill_spec.md) — and the
 executable conformance fixtures under [`tests/conformance/`](tests/conformance/)
-(autonomy, signing, intake, envelope) round out the set. Runtime-specific skills
+(autonomy, signing, intake, envelope, memory layout) round out the set. Runtime-specific skills
 that operate the protocol live in the companion
 [oacp-skills](https://github.com/kiloloop/oacp-skills) repository.
 

{oacp_cli-0.4.5 → oacp_cli-0.5.0}/docs/guides/doctor.md

@@ -27,6 +27,7 @@ Verifies that required and optional CLI tools are installed and reachable on `PA
 | `ruff` | No | Python linter (optional, used in preflight) |
 | `shellcheck` | No | Shell script linter (optional) |
 | `pyyaml` | No | PyYAML library (needed for YAML validation) |
+| `agent-memory` | No | Memory tool (`agent-memory-cli`); the row reports its version and hands memory-home checks to `agent-memory doctor` |
 
 ### 2. Workspace
 
@@ -103,6 +104,8 @@ $ oacp doctor
     [+] ruff — ruff 0.8.1
     [-] shellcheck — not installed (optional)
         Install: brew install shellcheck
+    [-] agent-memory — not installed
+        Install: pip install agent-memory-cli
     [+] pyyaml — available
 
 No issues found.
@@ -120,6 +123,7 @@ $ oacp doctor --project my-project
     [+] ruff — ruff 0.8.1
     [-] shellcheck — not installed (optional)
         Install: brew install shellcheck
+    [+] agent-memory — agent-memory 0.1.0 (run agent-memory doctor)
     [+] pyyaml — available
 
 [+] Workspace
@@ -181,6 +185,7 @@ The exit code reflects the overall result:
 | `pyyaml — not importable` | `pip install pyyaml` |
 | `ruff — not installed` | `pip install ruff` (optional, for linting) |
 | `shellcheck — not installed` | `brew install shellcheck` (optional, for shell script linting) |
+| `agent-memory — not installed` | `pip install agent-memory-cli` (optional; `agent-memory doctor` then checks the memory home) |
 
 ### Workspace
 
@@ -220,7 +225,6 @@ oacp doctor --project <name>         # full workspace + agent checks
 oacp doctor --json                   # machine-readable JSON output
 oacp doctor --project <name> --json  # full checks in JSON format
 oacp doctor --project <name> --fix   # auto-fix safe issues (missing inbox dirs, missing/stale status.yaml)
-oacp doctor --memory                 # advisory checks for OACP_HOME memory git sync
 oacp doctor -o report.txt            # save report to file
 ```
 

oacp_cli-0.5.0/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.
+
+`agent-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 `agent-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.5.0}/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.5.0}/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.5.0}/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.5.0}/docs/protocol/message_signing.md

@@ -333,8 +333,8 @@ can never authenticate a message.
 - **Keys are per-machine and never leave `$OACP_HOME/keys/`.** They are
   never synced and never committed. The memory-sync allowlist structurally
   excludes `keys/` on the push side, and the canonical workspace
-  `.gitignore` carries an explicit `keys/` deny line that `oacp memory
-  init` and the doctor `root-gitignore` drift check propagate fleet-wide.
+  `.gitignore` carries an explicit `keys/` deny line that the memory tool
+  (`agent-memory enable`, and its doctor's drift check) propagates fleet-wide.
 - **The 0600 file keystore is the v0.4.0 floor, not the design.** Private
   key files are created `0600` under `0700` directories and loaded only
   after a mode check. The backend is pluggable by design: messages