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

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

@@ -7,6 +7,42 @@ 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
+
+- Protocol contract stamp `spec_version` moves to `0.4.5` under a pinned bump rule ([contract version](docs/protocol/autonomy.md#contract-version)).
+- `task_profile.estimated_minutes` is the declared admission cap, not an expected duration ([message fields](docs/protocol/autonomy.md#message-fields)).
+
+### Removed
+
+- Unsupported MCP coordinator prototype (`mcp_servers/`) and the packaged session-telemetry script; session telemetry is runtime-owned ([session telemetry](docs/protocol/runtime_capabilities.md#runtime-startup-and-session-telemetry)).
+
+### Fixed
+
+- `oacp doctor --fix` creates `status.yaml` from the packaged `agent_status` template on wheel installs ([agent status](docs/guides/doctor.md#7-agent-status)).
+- Autonomy admission prefers an unfenced `task_profile` declaration over fenced examples ([autonomy](docs/protocol/autonomy.md#message-fields)).
+- Claude envelope accounting recognizes dashed and undashed runtime scratchpad roots without exempting sibling paths ([autonomy](docs/protocol/autonomy.md#envelope-compilation-phase-2)).
+- Autonomy finalization requires the receiver's work-start stamp and flags legacy terminal receipts that omit it ([autonomy](docs/protocol/autonomy.md#terminal-finalization-and-audit-integrity)).
+- `oacp autonomy-finalize` resolves the receiver policy from the record, so sender re-authorizations arbitrate under the receiver's verified caps instead of failing closed ([re-authorization channels](docs/protocol/autonomy.md#re-authorization-channels-and-arbitration)).
+- `oacp autonomy-outcome` records a checkpoint clear without overwriting the admission outcome, and refuses writes to records closed by completion evidence ([human outcomes](docs/protocol/autonomy.md#human-approval-and-decline-outcomes)).
+- Codex session initialization preserves configured capabilities across its own rewrites and records an explicit unknown model when hook metadata is unavailable ([runtime capabilities](docs/protocol/runtime_capabilities.md#dynamic-status-schema)).
+- Codex agent setup publishes every message type the Codex inbox workflow handles, leaving other runtime cards unchanged ([agent profiles](docs/protocol/agent_profiles.md#relationship-to-existing-agent-cards)).
+- Claude agent setup publishes every message type the Claude inbox workflow handles, on new and existing project cards ([agent profiles](docs/protocol/agent_profiles.md#relationship-to-existing-agent-cards)).
+- Claude agent scaffolding records an explicit unknown model instead of echoing the runtime name into `status.yaml` ([runtime capabilities](docs/protocol/runtime_capabilities.md#dynamic-status-schema)).
+
 ## [0.4.4] - 2026-08-28
 
 The central debrief store is the headline change: every agent's full end-of-session debrief now lands in the kernel-owned, append-only `org-memory/debriefs/<project>/<YYYY>/<MM>/` layout — one immutable file per session — instead of per-project trees, with `oacp org-memory init` creating the store and `oacp doctor` checking its setup ([org memory](docs/protocol/org_memory.md#debrief-store)).
@@ -807,6 +843,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.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
 [0.4.2]: https://github.com/kiloloop/oacp/compare/v0.4.1...v0.4.2

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: oacp-cli
-Version: 0.4.4
+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
@@ -48,7 +48,7 @@ $ uv tool install oacp-cli
 ## See it in action
 
 <p align="center">
-  <img src="docs/img/oacp-cli-demo.png" alt="oacp send + watch terminal demo" width="584" />
+  <img src="https://raw.githubusercontent.com/kiloloop/oacp/main/docs/img/oacp-cli-demo.png" alt="oacp send + watch terminal demo" width="584" />
 </p>
 
 The CLI ships structured tasks between agents and lets you watch the conversation in real time.
@@ -56,7 +56,7 @@ The CLI ships structured tasks between agents and lets you watch the conversatio
 ## Live agent fleet
 
 <p align="center">
-  <img src="docs/img/oacp-fleet-thread.png" alt="claude / codex / gemini fleet with PR #42 review thread" width="650" />
+  <img src="https://raw.githubusercontent.com/kiloloop/oacp/main/docs/img/oacp-fleet-thread.png" alt="claude / codex / gemini fleet with PR #42 review thread" width="650" />
 </p>
 
 Every multi-agent thread is a sequence of typed messages — `review_request`, `review_feedback`, `review_addressed`, `review_lgtm` — with explicit quality gates.
@@ -84,7 +84,7 @@ PROJECT · my-app                                   ● live
 ## Filesystem as protocol
 
 <p align="center">
-  <img src="docs/img/oacp-filesystem-tree.png" alt="$OACP_HOME directory tree with inbox/outbox/memory/artifacts" width="526" />
+  <img src="https://raw.githubusercontent.com/kiloloop/oacp/main/docs/img/oacp-filesystem-tree.png" alt="$OACP_HOME directory tree with inbox/outbox/memory/artifacts" width="526" />
 </p>
 
 Everything is plain files in `$OACP_HOME`. Agents have `inbox/`, `outbox/`, `dead_letter/`. Projects have shared `memory/` (durable) and per-thread `artifacts/`, `checkpoints/`, `packets/`. Org-wide knowledge lives in `$OACP_HOME/org-memory/`.
@@ -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  [⌘]
 ```
@@ -320,9 +320,6 @@ oacp/
 └── SPEC.md             # Full protocol specification
 ```
 
-[`mcp_servers/`](mcp_servers/) contains experimental, unsupported prototypes;
-it is not part of the OACP product surface.
-
 ## Related
 
 - **[agent-estimate](https://github.com/kiloloop/agent-estimate)** — Estimate how long agent tasks take. Pairs with OACP dispatch for task sizing.
@@ -376,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.4 → 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.4 → oacp_cli-0.4.6}/README.md

@@ -20,7 +20,7 @@ $ uv tool install oacp-cli
 ## See it in action
 
 <p align="center">
-  <img src="docs/img/oacp-cli-demo.png" alt="oacp send + watch terminal demo" width="584" />
+  <img src="https://raw.githubusercontent.com/kiloloop/oacp/main/docs/img/oacp-cli-demo.png" alt="oacp send + watch terminal demo" width="584" />
 </p>
 
 The CLI ships structured tasks between agents and lets you watch the conversation in real time.
@@ -28,7 +28,7 @@ The CLI ships structured tasks between agents and lets you watch the conversatio
 ## Live agent fleet
 
 <p align="center">
-  <img src="docs/img/oacp-fleet-thread.png" alt="claude / codex / gemini fleet with PR #42 review thread" width="650" />
+  <img src="https://raw.githubusercontent.com/kiloloop/oacp/main/docs/img/oacp-fleet-thread.png" alt="claude / codex / gemini fleet with PR #42 review thread" width="650" />
 </p>
 
 Every multi-agent thread is a sequence of typed messages — `review_request`, `review_feedback`, `review_addressed`, `review_lgtm` — with explicit quality gates.
@@ -56,7 +56,7 @@ PROJECT · my-app                                   ● live
 ## Filesystem as protocol
 
 <p align="center">
-  <img src="docs/img/oacp-filesystem-tree.png" alt="$OACP_HOME directory tree with inbox/outbox/memory/artifacts" width="526" />
+  <img src="https://raw.githubusercontent.com/kiloloop/oacp/main/docs/img/oacp-filesystem-tree.png" alt="$OACP_HOME directory tree with inbox/outbox/memory/artifacts" width="526" />
 </p>
 
 Everything is plain files in `$OACP_HOME`. Agents have `inbox/`, `outbox/`, `dead_letter/`. Projects have shared `memory/` (durable) and per-thread `artifacts/`, `checkpoints/`, `packets/`. Org-wide knowledge lives in `$OACP_HOME/org-memory/`.
@@ -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  [⌘]
 ```
@@ -292,9 +292,6 @@ oacp/
 └── SPEC.md             # Full protocol specification
 ```
 
-[`mcp_servers/`](mcp_servers/) contains experimental, unsupported prototypes;
-it is not part of the OACP product surface.
-
 ## Related
 
 - **[agent-estimate](https://github.com/kiloloop/agent-estimate)** — Estimate how long agent tasks take. Pairs with OACP dispatch for task sizing.
@@ -348,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.4 → oacp_cli-0.4.6}/docs/guides/versioning.md

@@ -17,7 +17,11 @@ The `oacp-cli` package follows semantic versioning:
 `__version__` at runtime via `importlib.metadata`, so `oacp --version` always
 reports the installed package version — the version number itself is edited in
 exactly one file (the release-bump PR also adds the matching `CHANGELOG.md`
-section, see below).
+section, see below). The protocol contract carries a separate stamp,
+`SPEC_VERSION` in `scripts/_oacp_constants.py`, which moves only under the
+contract-version rule in
+[`docs/protocol/autonomy.md`](../protocol/autonomy.md#contract-version)
+(step 2 below).
 
 ## Release Pipeline
 
@@ -32,25 +36,35 @@ itself, which triggers the publish workflow.
    then scan for leaks: hardcoded user paths, private repository references,
    secret patterns, and SPDX headers on all tracked Python files. All checks
    must pass before anything is exported.
-2. **Version bump PR** — update the `version` in `pyproject.toml` and add a
+2. **Contract-version check** — diff `docs/protocol/*.md` and the stamp
+   producers (`scripts/autonomy_gate.py`, `scripts/envelope_compiler.py`,
+   `scripts/init_project_workspace.py`) against the last release and apply the
+   contract-version rule in full: a change every receiver must understand to
+   verify or exchange a message, or to produce and finalize an artifact
+   another receiver reads, moves `SPEC_VERSION` together with the spec's
+   `spec_version` literals and a `CHANGELOG.md` line; additive-and-ignorable
+   changes do not, and the release PR then records "no contract change". The
+   package version moves on every release, the contract stamp only when the
+   contract does.
+3. **Version bump PR** — update the `version` in `pyproject.toml` and add a
    `CHANGELOG.md` section in [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
    format. Gather the changes with `git log --oneline <last-tag>..HEAD`.
-3. **Export to staging** — open a staging PR mirroring the development branch.
+4. **Export to staging** — open a staging PR mirroring the development branch.
    The export copies the tracked tree only (`git archive`), so gitignored
    local files never leave the development machine; rerun the leak audit on
    the staged tree before merging. Non-urgent releases soak here before
    promotion; urgent fixes may skip the soak.
-4. **Promote to public** — open a promotion PR into `kiloloop/oacp` under the
+5. **Promote to public** — open a promotion PR into `kiloloop/oacp` under the
    release automation identity; a human reviews and merges it. The squash
    commit message becomes permanent public history — keep it free of internal
    references (the PR description alone is not what gets published).
-5. **Tag and publish** — push an annotated `vX.Y.Z` tag to the public repo
+6. **Tag and publish** — push an annotated `vX.Y.Z` tag to the public repo
    (a direct tag push, not a PR). The tag-triggered release workflow reruns
    the checks, builds the sdist/wheel, publishes `oacp-cli` to PyPI via
    [Trusted Publishing](https://docs.pypi.org/trusted-publishers/) (OIDC — no
    long-lived API tokens), and creates the GitHub Release with notes from the
    CHANGELOG section.
-6. **Verify** — check the version-pinned endpoint
+7. **Verify** — check the version-pinned endpoint
    `https://pypi.org/pypi/oacp-cli/<version>/json` first; the unversioned
    "latest" endpoint and the pip simple index can lag a few minutes behind it.
    Then install and confirm `oacp --version` prints the new version. On a

{oacp_cli-0.4.4 → 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.4 → 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
@@ -115,6 +119,17 @@ receiver also writes an audit record, reply body, and cache entries; a
 reply-only analysis that uses scratch files but produces no file deliverable
 declares `0`.
 
+`estimated_minutes` is the **declared admission cap**, not an expected-duration
+estimate: it is the value Gate 2 compares against `max_estimated_minutes`, and
+the bound the post-accept checkpoint measures `actual_minutes` against. A
+sender that tracks expected duration separately keeps it out of the profile
+(for example as provenance prose in the brief), and any future
+expected-duration field is a distinct key, so an adapter that maps a caller's
+declared cap onto `estimated_minutes` never inverts. For example, a leg
+expected to take 25 minutes that is declared under a two-round review
+multiplier carries `estimated_minutes: 50`: the gate admits against 50, and
+the checkpoint fires past 50, not 25.
+
 ### Default scope envelope (profileless admissions)
 
 `allow_without_task_profile` is an **admission-only exemption**: the sender
@@ -307,7 +322,7 @@ Every autonomy decision writes one YAML file:
 
 ```yaml
 schema_version: 2
-spec_version: "0.4.3"
+spec_version: "0.4.5"
 created_at_utc: "2026-05-12T13:23:25Z"
 receiver: codex
 sender: iris
@@ -418,23 +433,43 @@ signer_kid, reason}` — the policy-file authorization outcome (see
 `policy_sha256` the record commits to an *authorized* policy identity,
 not just which bytes ran. An `invalid` status fails closed with reason
 code `policy_auth_invalid` before any gate consumes the config.
-`spec_version: "0.4.3"` preserves every autonomy field and rule pinned by
-0.4.2 — Gate 1 integrity
-enforcement, the recalibrated Gate 2/3 policy, full task-profile capture, the
-explicit `breached` list, the outcome block shown above, session-scoped
-envelope enforcement, the enforce-mode trust-pin completeness gate, and
-preserved `always_pause` defaults for configs without an `autonomy` block —
-plus intake verification as mechanism (`verify_mode: enforce` rejects at
-the gate), the `policy_auth` authorized-policy block, the default scope
-envelope for profileless admissions (with `scope_envelope_source` and the
-null-on-admitted writer refusal), and the recorded none-by-rule
-enforcement branch for approved public-visibility tasks. The spec version
-advances because 0.4.3 adds the project-wide message-retention policy and the
-processed-inbound archive convention; autonomy semantics are unchanged. 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.
+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.
+The tooling stamps one value — `SPEC_VERSION` in `scripts/_oacp_constants.py`
+— into audit records, compiled envelopes, and `workspace.json` at workspace
+init, and the `spec_version` literals in this document move with it.
+
+The stamp moves by the kernel admission test. A release advances
+`spec_version` when it adds or changes something every receiver must
+understand to verify or exchange a message, or to produce and finalize an
+artifact another receiver reads: a key a receiver must stamp, a changed
+meaning of an existing field, or a block that enforcement or finalization now
+reads. Additive-and-ignorable changes — an advisory, an optional provenance
+key, a value a reader may skip without changing its decision — do not move it,
+and neither do userland or tooling changes. The value is the `oacp-cli`
+version of the release that carries the move, and every release states the
+outcome in its notes: the new stamp, or "no contract change".
+
+History: 0.4.3 preserved every autonomy field and rule pinned by 0.4.2 and
+advanced the stamp for the project-wide message-retention policy and the
+processed-inbound archive convention. 0.4.4 added the receiver-stamped
+`work_started_at_utc` work clock and the checkpoint `reauthorization` block
+that enforcement reads, which moved the contract, but shipped with the stamp
+unchanged; 0.4.5 carries that move and makes the work clock mandatory at
+terminal finalization. Records, envelopes, and workspaces written between the
+0.4.4 release (2026-08-28) and the 0.4.5 release are therefore stamped
+`0.4.3` under a contract that had already moved — readers tolerate that
+stamp on artifacts dated in the window and read them by the 0.4.5 shape.
 
 `evaluator` is **gate-emitted, not receiver-composed**: the evaluator
 self-stamps its provenance into every decision it returns, and receivers
@@ -484,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,
@@ -612,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
@@ -635,6 +716,32 @@ shape must itself carry `checkpoint_paused` (the checkpoint
 re-evaluation is what updated the result block; any other kind there is
 refused as inconsistent).
 
+On a checkpoint pause whose record **already carries a recorded human
+outcome** (typically the admission approval), the new decision is a
+checkpoint clear, and the recorder routes it into
+`result.threshold_checkpoint.reauthorization` as a scope-less
+`receiver_human` answer through the same arbitration the checkpoint
+evaluator uses — a fresh approval lands as `disposition: resumed`, a
+decline as `declined` — while the recorded outcome (timestamp, latency,
+reason codes, and any standing grant resolved from its `grant` block)
+survives untouched. `--replace` is refused in that state: it would
+destroy the admission ledger entry, and can revoke a standing
+continuation grant as a side effect. The recorder mutates only **live**
+records, on both of its routes: a record already closed by completion
+evidence (a terminal `final_state`, or `completed_at_utc`) is
+historical evidence and refuses every human-outcome write — checkpoint
+clear and admission answer alike — byte-identically. A historical
+correction is a deliberate finalizer supersession, never a rewrite. A
+recorder-based clear is
+scope-less by construction; a scoped budget or boundary-action grant
+goes through `oacp autonomy-finalize --checkpoint` with
+`reauthorization.receiver_human.scope`. The validator flags the damage
+signature of the pre-routing overwrite (an admission-paused record whose
+only recorded outcome answers a checkpoint pause) as the advisory
+`admission_outcome_replaced_by_checkpoint_clear` — advisory, not error,
+because records written before this routing existed had no
+non-destructive way to record the clear.
+
 Latency values on checkpoint records written before `paused_at_utc` existed
 measure from admission and are not comparable with post-fix records.
 
@@ -673,7 +780,7 @@ oacp autonomy-finalize <audit.yaml> --checkpoint --actuals <actuals.yaml>
 
 # terminal update
 oacp autonomy-finalize <audit.yaml> --final-state done \
-  --actual-minutes 30 --actual-files-touched 3 \
+  --started-at <YYYY-MM-DDTHH:MM:SSZ> --actual-files-touched 3 \
   --realized creates_or_updates_pr --realized commits_changes \
   --reply-message-id <msg-id>
 ```
@@ -683,6 +790,37 @@ duplicate live evaluations, and terminal records still carrying a paused
 checkpoint action; the finalizer enforces the pinned enums and
 cross-field invariants at write time, under the shared audit lock.
 
+The finalizer resolves the receiver's admission policy for
+re-authorization arbitration from the record's `policy_path` (override
+with `--config`), so sender_reply answers are capped at the receiver's
+thresholds instead of extending nothing. The read goes through the
+authorized policy path (one bounded snapshot: signature, receiver and
+context binding, and enrollment downgrade resistance verified, then
+parsed from those same bytes) — a policy that fails authorization
+grants nothing. When the policy cannot be resolved or authorized and
+the actuals present a sender answer, the degradation is surfaced on
+stderr and the sender channel stays fail-closed (an explicit `--config`
+that fails is a hard error that leaves the record unchanged); the
+receiver_human channel is unaffected either way.
+
+**Work-clock binding and writer provenance.** Canonical checkpoint and
+`done`/`error` writes require `result.work_started_at_utc`. The first write may
+supply it with `--started-at` (or the equivalent actuals field); later writes
+reuse the record stamp automatically. An explicit value that conflicts with
+the existing stamp is refused, and omitting both sources is an error. With a
+stamp present, omitting `actual_minutes` derives it from the active work clock.
+Each successful canonical write stamps `result.finalizer` with
+`name: oacp autonomy-finalize` and `schema_version: 1`; supersession is exempt
+because it transfers authority rather than reporting task execution. The
+marker lets validation enforce the required clock on new receipts without
+rewriting history: an unmarked legacy terminal receipt with no start gets the
+advisory `terminal_missing_work_started_at`, while a marked checkpoint or
+terminal receipt missing it gets the error
+`canonical_writer_missing_work_started_at`. A malformed marker is
+`invalid_finalizer_provenance`. Legacy terminal receipts remain byte-preserved;
+correct one through a linked superseding evaluation rather than rewriting it
+in place with `--replace`.
+
 **Run-state vocabulary.** `result.final_state` splits by lifecycle phase:
 `pending`, `paused`, and `blocked` are live states; `done`, `superseded`,
 and `error` are terminal. Only terminal states can be finalized.
@@ -792,8 +930,10 @@ reports pinned finding codes (`off_enum_completion_kind`,
 `terminal_paused_without_outcome`, `superseded_missing_successor`,
 `breached_empty_fields`, `invalid_human_outcome`,
 `decision_kind_incoherent`, `off_enum_breach_basis`,
-`breach_basis_incoherent`, `record_unparsable`; advisory:
-`noncanonical_checkpoint_axis`, `terminal_missing_actuals`), and
+`breach_basis_incoherent`, `canonical_writer_missing_work_started_at`,
+`invalid_finalizer_provenance`, `record_unparsable`; advisory:
+`noncanonical_checkpoint_axis`, `terminal_missing_actuals`,
+`terminal_missing_work_started_at`), and
 `oacp doctor` sweeps every receiver's audit directory with the same
 checks. Duplicate YAML keys are refused
 outright — plain YAML loading silently keeps the later value. The
@@ -899,7 +1039,10 @@ the hard stop.
 ## Threshold-Exceeded Checkpoint
 
 `result.work_started_at_utc` is the receiver-stamped time of its first action
-on that task. `actual_minutes` is active wall-clock time from that stamp to
+on that task. The canonical finalizer requires that stamp on every checkpoint
+and `done`/`error` write, reuses the record's value when the caller omits
+`--started-at`, and rejects a conflicting replacement. `actual_minutes` is
+active wall-clock time from that stamp to
 completion or the current checkpoint, rounded up to a whole minute, excluding
 each represented re-authorization pause from `paused_at_utc` through
 `cleared_paused_at_utc`. If a terminal outcome leaves that pause uncleared,
@@ -1057,7 +1200,9 @@ Arbitration rules:
   visibility) are receiver-side authority only, on the scoped and
   scope-less paths alike. The party whose under-declaration caused the
   breach cannot self-serve unlimited scope. Without a resolvable receiver
-  policy the sender channel extends nothing (fail closed).
+  policy the sender channel extends nothing (fail closed) — the finalizer
+  resolves the policy from the record's `policy_path`, overridable with
+  `--config`.
 - **GH comments never clear a checkpoint.** They sit outside the protocol's
   identity and verification boundary; any decision they carry is recorded as
   advisory, and a checkpoint answered only by a GH comment stays paused.
@@ -1240,7 +1385,7 @@ The envelope is written to
 ```json
 {
   "envelope_version": 1,
-  "spec_version": "0.4.3",
+  "spec_version": "0.4.5",
   "compiler": "envelope_compiler.py",
   "compiled_at_utc": "2026-07-12T02:00:00Z",
   "project": "my-project",