kiloloop · spbkgw-beep · Aug 28, 2026 · Aug 28, 2026
diff --git a/.github/workflows/auto-estimate.yml b/.github/workflows/auto-estimate.yml
@@ -0,0 +1,24 @@
+name: Auto-estimate
+
+# Label an issue `estimate` and agent-estimate posts an estimate comment
+# on it. Recipe from kiloloop/agent-estimate README ("Auto-estimate on
+# label") — consumes the published Action via the v0 tag.
+
+on:
+  issues:
+    types: [labeled]
+
+permissions:
+  contents: read
+  issues: write
+
+jobs:
+  estimate:
+    if: github.event.label.name == 'estimate'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: kiloloop/agent-estimate@7b30943bac5648cf183f3d050baa6fea5485b8a9 # v0.7.4
+        with:
+          issues: ${{ github.event.issue.number }}
+          output-mode: issue-comment
+          title: 'Agent Estimate — issue #${{ github.event.issue.number }}'
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -14,10 +14,10 @@ jobs:
 
     steps:
       - name: Check out repository
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Set up Python
-        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
           python-version: "3.12"
           cache: pip
@@ -30,7 +30,7 @@ jobs:
       - name: Install Python dependencies
         run: |
           python -m pip install --upgrade pip
-          python -m pip install -e ".[crypto]" build pytest ruff
+          python -m pip install --group dev -e ".[crypto]"
 
       - name: Run quality gate
         run: make preflight ARGS="--full"

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -16,10 +16,10 @@ jobs:
 
     steps:
       - name: Check out repository
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Set up Python
-        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
           python-version: "3.12"
           cache: pip
@@ -32,7 +32,7 @@ jobs:
       - name: Install Python dependencies
         run: |
           python -m pip install --upgrade pip
-          python -m pip install -e ".[crypto]" build pytest ruff
+          python -m pip install --group dev -e ".[crypto]"
 
       - name: Run quality gate
         run: make preflight ARGS="--full"
@@ -42,7 +42,7 @@ jobs:
 
       # upload-artifact is still on v6; download-artifact moved to v7 for Node 24.
       - name: Upload release artifacts
-        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6
+        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
         with:
           name: python-package-distributions
           path: dist/
@@ -59,7 +59,7 @@ jobs:
 
     steps:
       - name: Download release artifacts
-        uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131 # v7
+        uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131 # v7.0.0
         with:
           name: python-package-distributions
           path: dist/
@@ -116,11 +116,11 @@ jobs:
 
     steps:
       - name: Check out repository
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       # download-artifact v7 is the current Node 24-compatible major.
       - name: Download release artifacts
-        uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131 # v7
+        uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131 # v7.0.0
         with:
           name: python-package-distributions
           path: dist/

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,6 +5,51 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [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)).
+
+### Added
+
+- Central session-debrief store under org-memory `debriefs/`, created by `oacp org-memory init` and setup-checked by `oacp doctor` ([org memory](docs/protocol/org_memory.md#debrief-store)).
+- `oacp add-agent` and `oacp init --agents` populate the instance agent registry; `oacp agent sync` backfills existing workspaces ([agent profiles](docs/protocol/agent_profiles.md)).
+- `oacp autonomy-finalize` writes and validates checkpoint and terminal autonomy audit updates under lock; `oacp doctor` sweeps audit directories with the same checks ([autonomy](docs/protocol/autonomy.md#terminal-finalization-and-audit-integrity)).
+- Every persisted autonomy evaluation carries an `evaluation_id`; re-evaluations supersede the prior record through a locked transaction ([autonomy](docs/protocol/autonomy.md#terminal-finalization-and-audit-integrity)).
+- The wheel ships the four kernel protocol docs, the wire message template, and five previously unpackaged scripts under `oacp/_protocol/`, `oacp/_templates/`, and `oacp/_scripts/`.
+- Preflight and CI fail when `scripts/` and the wheel's force-include table drift apart.
+- `waiting_on_peer` checkpoint sub-basis separates peer-reply latency from working time in a realized time breach ([threshold checkpoint](docs/protocol/autonomy.md#threshold-exceeded-checkpoint)).
+- Conformance fixture pinning the default scope envelope stamped on profileless admits.
+
+### Removed
+
+- Zero-consumer scripts `normalize_findings.py`, `create_handoff_packet.py`, and `init_project_workspace.sh` with their Makefile targets; `oacp init` replaces `make init`.
+
+### Changed
+
+- `actual_minutes` is active wall-clock from receiver-stamped `work_started_at_utc`, excluding admission idle and re-authorization pauses ([threshold checkpoint](docs/protocol/autonomy.md#threshold-exceeded-checkpoint)).
+- `expected_files_touched` counts distinct deliverable files only, not receiver bookkeeping, memory, cache, or scratch writes ([autonomy policy](docs/protocol/autonomy.md#message-fields)).
+- Parent-less `oacp send` messages get an automatic thread identifier ([conversation threading](docs/protocol/inbox_outbox.md#conversation-threading)).
+- The README `## Commands` table is generated from `oacp --help` via `make docs`, with a drift test.
+- Moved the runtime capability matrix to the public [Kiloloop research repository](https://github.com/kiloloop/research/blob/main/runtime-comparison/runtime_capability_matrix.md).
+- Moved the prompt-caching guide to the public [Kiloloop research repository](https://github.com/kiloloop/research/blob/main/runtime-comparison/prompt-caching-patterns.md), leaving a redirect at its former path.
+- Raised the optional `cryptography` floor to 50.0.0 and the Python floor to 3.9.2 to exclude known-vulnerable crypto releases.
+- Pinned the development and release toolchain through a shared dependency group and refreshed workflow actions to immutable commits.
+- Folded [`SPEC.md`](SPEC.md) into a thin index over `docs/protocol/`; the package `Documentation` URL is unchanged.
+- Pricing/commercial content sensitivity is an advisory instead of a hard stop for reply-only task profiles ([autonomy](docs/protocol/autonomy.md#four-gate-evaluator)).
+- Enveloped sessions can no longer write the receiver's `audit/autonomy_decisions/` directly; only the canonical `oacp` audit writers can ([autonomy](docs/protocol/autonomy.md#envelope-compilation-phase-2)).
+
+### Fixed
+
+- Autonomy lexical classification records every match with its source span and demotion basis ([autonomy](docs/protocol/autonomy.md#lexical-provenance)).
+- Negated or descriptive public-repository, dependency-install, and merge-method language no longer trips lexical hard stops; stacked negations and later unaccounted occurrences still cannot demote an affirmative match ([autonomy](docs/protocol/autonomy.md#lexical-provenance)).
+- `SPEC.md` describes the archive-never-delete inbox lifecycle instead of saying recipients delete processed messages ([inbox/outbox](docs/protocol/inbox_outbox.md)).
+- The envelope hook no longer counts phantom `files_touched` from heredoc bodies or unexpanded shell variables; variable-spelled write targets escalate to `ask` ([autonomy](docs/protocol/autonomy.md#envelope-compilation-phase-2)).
+- Autonomy audit records carry a complete admission ledger (`admission_axes`), so a hard stop no longer masks the threshold, side-effect, or declaration axes ([autonomy](docs/protocol/autonomy.md#admission-ledger)).
+- `declaration_error` pauses record which profile field failed and why.
+- A granted checkpoint re-authorization widens the live file budget, so extra files no longer stay blocked after a valid grant ([autonomy](docs/protocol/autonomy.md#envelope-drift)).
+
 ## [0.4.3] - 2026-08-12
 
 ### Added
@@ -762,6 +807,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Checkout step in github-release workflow job (#19)
 - Pre-release audit fixes: SHA-pinned actions, dangling doc refs (#15, #16)
 
+[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
 [0.4.1]: https://github.com/kiloloop/oacp/compare/v0.4.0...v0.4.1

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -34,13 +34,16 @@ Please read and follow our [Code of Conduct](https://github.com/kiloloop/.github
 
 ## Development Setup
 
+Development and test tooling requires Python 3.10 or newer. The installed CLI
+continues to support Python 3.9.2 and newer.
+
 ```bash
 # Clone
 git clone https://github.com/kiloloop/oacp.git
 cd oacp
 
-# Install dependencies
-pip install pyyaml pytest
+# Install the package, crypto extra, and pinned development tools
+python -m pip install --group dev -e ".[crypto]"
 
 # Verify setup
 make preflight
@@ -81,6 +84,16 @@ make preflight ARGS="--full"
 - Keep the first line under 72 characters
 - Reference issue numbers where applicable: "Fix message validation (#42)"
 
+## Changelog Entries
+
+Entries in `CHANGELOG.md` follow [Common Changelog](https://common-changelog.org) discipline: a changelog answers "does this affect me, and how", not "how does it work".
+
+- One line, one change — split a multi-facet feature into two or three scoped bullets rather than one long bullet.
+- State the user-visible delta, not the implementation path.
+- Do not inline flag enums or sub-mechanism walkthroughs — link the protocol spec or doc section that carries the detail.
+- One link per bullet, pointing at the best entry point.
+- Each bullet must read as self-describing without its `### Added`/`### Changed` heading.
+
 ## License
 
 By contributing, you agree that your contributions will be licensed under the [Apache 2.0 License](LICENSE).
diff --git a/Makefile b/Makefile
@@ -16,7 +16,7 @@ endif
 
 # ── Targets ──────────────────────────────────────────────────────────────
 
-.PHONY: help init update test validate validate-msg validate-card send quality packet handoff normalize preflight doctor
+.PHONY: help update test docs validate validate-msg validate-card send quality packet preflight doctor
 
 help: ## Show available targets (default)
 	@echo "OACP — task runner"
@@ -26,15 +26,15 @@ help: ## Show available targets (default)
 	@grep -E '^[a-z][-a-z]+:.*## ' $(MAKEFILE_LIST) | \
 		awk -F ':.*## ' '{ printf "  %-14s %s\n", $$1, $$2 }'
 
-init: _require-project ## Create a new project workspace
-	bash $(SCRIPTS_DIR)/init_project_workspace.sh $(PROJECT) $(ARGS)
-
 update: _require-project ## Sync existing workspace with latest structure
 	bash $(SCRIPTS_DIR)/update_workspace.sh $(PROJECT) $(ARGS)
 
 test: ## Run all tests
 	python3 -m pytest $(SCRIPTS_DIR)/../tests -v $(ARGS)
 
+docs: ## Regenerate the README command table from oacp --help
+	python3 $(SCRIPTS_DIR)/gen_readme_commands.py --write
+
 validate-msg: ## Validate inbox messages
 	python3 $(SCRIPTS_DIR)/validate_message.py $(ARGS)
 
@@ -57,9 +57,3 @@ quality: ## Run quality gate check
 
 packet: _require-project ## Create a review/findings/merge packet
 	bash $(SCRIPTS_DIR)/init_packet.sh $(PROJECT) $(ARGS)
-
-handoff: _require-project ## Create a structured handoff packet
-	python3 $(SCRIPTS_DIR)/create_handoff_packet.py $(PROJECT) $(ARGS)
-
-normalize: ## Normalize raw findings into canonical YAML
-	python3 $(SCRIPTS_DIR)/normalize_findings.py $(ARGS)
diff --git a/QUICKSTART.md b/QUICKSTART.md
@@ -4,7 +4,7 @@ Get from zero to your first agent-to-agent message in 5 minutes.
 
 ## Prerequisites
 
-- Python 3.9+ and Bash 3.2+
+- Python 3.9.2+ and Bash 3.2+
 
 ## 1. Set Up OACP Home
 

diff --git a/README.md b/README.md
@@ -225,22 +225,32 @@ uv tool install .
 
 ## Commands
 
+<!-- BEGIN GENERATED: oacp commands — do not edit by hand; run `make docs` -->
 | Command | Description |
 |---------|-------------|
-| `oacp init` | Create a project workspace under `$OACP_HOME/projects/` |
+| `oacp init` | Create a project workspace under $OACP_HOME/projects/ |
 | `oacp add-agent` | Add an agent to an existing project workspace |
-| `oacp setup` | Generate runtime-specific config files (Claude, Codex, Cursor, Gemini) |
-| `oacp send` | Send a protocol-compliant inbox message (`--from` auto-inferred) |
-| `oacp inbox` | List pending messages across agents (table or `--json`) |
-| `oacp watch` | Emit inbox delta events for one agent across selected projects |
-| `oacp memory` | Archive, restore, or git-sync project/org memory files |
-| `oacp session-init` | Verify Codex startup inputs, optionally pull memory, and update status |
-| `oacp agent` | Manage global agent profiles (`init`, `show`, `list`) |
-| `oacp org-memory` | Initialize org-level memory at `$OACP_HOME/org-memory/` |
-| `oacp write-event` | Write an event to `org-memory/events/` |
+| `oacp agent` | Manage global agent profiles (init, sync, show, list) |
+| `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 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 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 |
+| `oacp envelope` | Compile, show, or clear the runtime envelope for a task |
 | `oacp doctor` | Check environment and workspace health |
 | `oacp validate` | Validate an inbox/outbox YAML message |
-| `oacp --version` | Print the installed version |
+| `oacp verify` | Verify a message's auth trailer against receiver-local pins |
+<!-- END GENERATED: oacp commands -->
+
+`oacp --version` prints the installed version.
 
 <details>
 <summary>Key flags</summary>
@@ -291,7 +301,7 @@ it is not part of the OACP product surface.
 
 ## Prerequisites
 
-- Python 3.9+
+- Python 3.9.2+
 - Bash 3.2+ (macOS default is fine)
 - `gh` CLI (optional, for GitHub operations)