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

oacp_cli-0.4.4/.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 }}'

{oacp_cli-0.4.3 → oacp_cli-0.4.4}/.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"

{oacp_cli-0.4.3 → oacp_cli-0.4.4}/.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/

{oacp_cli-0.4.3 → oacp_cli-0.4.4}/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

{oacp_cli-0.4.3 → oacp_cli-0.4.4}/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).

{oacp_cli-0.4.3 → oacp_cli-0.4.4}/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)

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: oacp-cli
-Version: 0.4.3
+Version: 0.4.4
 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
@@ -20,10 +20,10 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Software Development
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Requires-Python: >=3.9
+Requires-Python: >=3.9.2
 Requires-Dist: pyyaml>=6.0
 Provides-Extra: crypto
-Requires-Dist: cryptography>=3.4; extra == 'crypto'
+Requires-Dist: cryptography>=50.0.0; extra == 'crypto'
 Description-Content-Type: text/markdown
 
 # OACP
@@ -253,22 +253,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>
@@ -319,7 +329,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)
 

{oacp_cli-0.4.3 → oacp_cli-0.4.4}/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
 

{oacp_cli-0.4.3 → oacp_cli-0.4.4}/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)
 

oacp_cli-0.4.4/SPEC.md

@@ -0,0 +1,60 @@
+# OACP — Protocol Specification
+
+**License**: Apache-2.0
+
+OACP (Open Agent Coordination Protocol) is a file-based coordination layer for
+multi-agent engineering workflows: agents on different runtimes (Claude, Codex,
+Cursor, Gemini, or any future runtime) collaborate asynchronously through YAML
+messages in a shared filesystem — no server, no daemon. The protocol is a small
+kernel — the message envelope and its lifecycle, message signing and
+verification, receiver autonomy with audit receipts, and the org-memory layout —
+plus userland conventions (review loops, task negotiation, session init, safety
+defaults) that build on it. This file is the index: the normative text lives in
+the documents below and is versioned with the `oacp-cli` package (see
+[`CHANGELOG.md`](CHANGELOG.md)).
+
+## Kernel documents
+
+What every receiver must understand or verify to exchange a message. These four
+documents ship inside the `oacp-cli` wheel.
+
+| Document | Governs |
+|---|---|
+| [`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. |
+
+## Userland documents
+
+Conventions layered on the kernel. Adopt what fits; none of them change what a
+receiver must verify.
+
+| Document | Covers |
+|---|---|
+| [`docs/protocol/review_loop.md`](docs/protocol/review_loop.md) | Inbox-driven code review: stateless reviewer rounds, findings packets, quality gate, round budgets, post-LGTM nits. |
+| [`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. |
+| [`docs/protocol/credential_scoping.md`](docs/protocol/credential_scoping.md) | Per-agent, per-project least-privilege credentials and rotation. |
+| [`docs/protocol/mcp_integration.md`](docs/protocol/mcp_integration.md) | Attaching MCP tool outputs to findings as structured evidence. |
+| [`docs/protocol/dispatch_states.yaml`](docs/protocol/dispatch_states.yaml) · [`packet_states.yaml`](docs/protocol/packet_states.yaml) · [`skills_manifest.yaml`](docs/protocol/skills_manifest.yaml) | Machine-readable dispatch and review-packet state machines, and the skills manifest. |
+
+Guides — [`docs/guides/setup.md`](docs/guides/setup.md),
+[`adoption.md`](docs/guides/adoption.md), [`doctor.md`](docs/guides/doctor.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
+that operate the protocol live in the companion
+[oacp-skills](https://github.com/kiloloop/oacp-skills) repository.
+
+## Getting started
+
+[`QUICKSTART.md`](QUICKSTART.md) sends a first message in five minutes;
+[`README.md`](README.md) carries the command reference (`oacp --help` is
+authoritative).

{oacp_cli-0.4.3 → oacp_cli-0.4.4}/docs/guides/doctor.md

@@ -22,7 +22,7 @@ Verifies that required and optional CLI tools are installed and reachable on `PA
 | Check | Required? | What it looks for |
 |-------|-----------|-------------------|
 | `git` | Yes | Git CLI |
-| `python3` | Yes | Python 3.9+ interpreter |
+| `python3` | Yes | Python 3.9.2+ interpreter |
 | `gh` | Yes | GitHub CLI (for PR and issue workflows) |
 | `ruff` | No | Python linter (optional, used in preflight) |
 | `shellcheck` | No | Shell script linter (optional) |
@@ -176,7 +176,7 @@ The exit code reflects the overall result:
 | Issue | Fix |
 |-------|-----|
 | `git — not found` | Install Git: https://git-scm.com/downloads |
-| `python3 — not found` | Install Python 3.9+: https://www.python.org/downloads/ |
+| `python3 — not found` | Install Python 3.9.2+: https://www.python.org/downloads/ |
 | `gh — not found` | Install GitHub CLI: `brew install gh` or https://cli.github.com/ |
 | `pyyaml — not importable` | `pip install pyyaml` |
 | `ruff — not installed` | `pip install ruff` (optional, for linting) |

oacp_cli-0.4.4/docs/guides/prompt_caching.md

@@ -0,0 +1,3 @@
+# Prompt Caching Patterns
+
+This guide has moved to the public [Kiloloop research repository](https://github.com/kiloloop/research/blob/main/runtime-comparison/prompt-caching-patterns.md).

{oacp_cli-0.4.3 → oacp_cli-0.4.4}/docs/guides/setup.md

@@ -3,7 +3,7 @@
 ## Prerequisites
 
 - `bash` 3.2+ (macOS default) or 4+ (recommended)
-- `python3` 3.9+ (for JSON state management, quality gate scripts, and inbox messaging)
+- `python3` 3.9.2+ (for JSON state management, quality gate scripts, and inbox messaging)
 - `gh` CLI (optional, for GitHub operations — `gh auth login`)
 - Agent runtime CLI: `claude`, `codex`, `cursor`, or `gemini` (depending on your agents)
 

{oacp_cli-0.4.3 → oacp_cli-0.4.4}/docs/protocol/agent_profiles.md

@@ -24,7 +24,9 @@ $OACP_HOME/
             └── outbox/
 ```
 
-- **Global profiles** (`agents/<name>/profile.yaml`) are created once per agent and rarely change.
+- **Global profiles** (`agents/<name>/profile.yaml`) form the instance registry.
+  `oacp add-agent` and `oacp init --agents` create them and append project
+  memberships without replacing existing identity fields.
 - **Project cards** (`projects/<project>/agents/<name>/agent_card.yaml`) carry project-specific overrides — permissions, skills, routing rules — and are the authoritative resolved identity for that project.
 - **Status files** (`status.yaml`) remain separate; they track dynamic session state, not static identity.
 
@@ -80,9 +82,10 @@ Global profiles use `agent_profile.template.yaml`. Fields:
 |-------|------|----------|-------------|
 | `version` | string | yes | Schema version (semver, currently `0.2.0`) |
 | `name` | string | yes | Agent identifier (matches directory name) |
-| `runtime` | string | yes | One of: `claude`, `codex`, `gemini`, `human` |
-| `model` | string | no | Model version identifier |
+| `runtime` | string | yes | One of: `claude`, `codex`, `cursor`, `gemini`, `human`, `unknown` |
+| `model` | string | no | Configured model identifier; a runtime alias may select that runtime's environment default |
 | `description` | string | no | One-line role summary |
+| `projects` | list | yes | Project workspaces where this agent is initialized |
 | `routing_rules` | dict | no | `primary` (preferred targets) and `avoid` (agents to skip) |
 | `trust_level` | string | no | `untrusted`, `standard`, `elevated`, or `admin` |
 | `quota` | dict | no | `max_cost_usd_per_month`, `reset_day`, `warn_threshold` |
@@ -123,17 +126,30 @@ oacp agent show claude --project my-app
 
 ### `oacp agent list`
 
-List known agents with their tier tags.
+List the instance registry with each agent's runtime and project memberships.
+`--project` preserves the merged global/project view for one workspace.
 
 ```bash
 oacp agent list
-#   claude  (global)
-#   codex   (global)
+#   claude  runtime=claude  memberships=my-app,other-app  (global)
+#   codex   runtime=codex  memberships=my-app  (global)
 
 oacp agent list --project my-app
-#   claude  (global, project)
-#   codex   (global)
-#   gemini  (project)
+#   claude  runtime=claude  memberships=my-app,other-app  (global, project)
+#   codex   runtime=codex  memberships=my-app  (global, project)
+```
+
+### `oacp agent sync`
+
+Backfill the instance registry once from existing project agent directories.
+The command infers defaults from agent cards and status files, preserves every
+existing identity value, and only appends missing memberships. It is safe to
+repeat. `oacp doctor` reports missing profiles or memberships and points to
+this command.
+
+```bash
+oacp agent sync
+# Agent registry synchronized: 3 agent(s), 8 project membership(s); ...
 ```
 
 ## Relationship to Existing Agent Cards
@@ -144,7 +160,7 @@ Agent cards predate global profiles and remain the authoritative per-project ide
 |---------|---------------|--------------------|
 | **Location** | `$OACP_HOME/agents/<name>/profile.yaml` | `$OACP_HOME/projects/<project>/agents/<name>/agent_card.yaml` |
 | **Scope** | All projects | Single project |
-| **Updates** | Rarely (identity changes) | Per project as needed |
+| **Updates** | Identity changes plus append-only project membership | Per project as needed |
 | **Authority** | Defaults only | Authoritative for the project |
 | **Extra sections** | None | `permissions`, `availability`, `protocol` |