oacp-cli 0.1.2__tar.gz → 0.2.0__tar.gz

{oacp_cli-0.1.2 → oacp_cli-0.2.0}/CHANGELOG.md

@@ -5,6 +5,27 @@ 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).
 
+## [0.2.0] - 2026-03-20
+
+### Added
+
+- `oacp inbox` command for listing agent inboxes with table and `--json` output
+- Sender inference for `oacp send` — `--from` is now optional when `OACP_AGENT`, `AGENT_NAME`, or agent card runtime can identify the sender
+
+### Changed
+
+- Consolidated shared script constants into `_oacp_constants.py` — canonical `AGENT_RE`, runtime tuples, timestamp/template helpers
+- Agent name validation now requires an alphanumeric first character (names starting with `_`, `.`, `-` are rejected)
+- Message ID and filename suffixes use `secrets.token_hex` instead of `random.choices`
+
+## [0.1.9] - 2026-03-20
+
+### Added
+
+- Memory archive layer with `oacp archive` CLI command for active/archive split (#62, #11)
+- Declarative agent profiles with YAML schema and `oacp agent init|show|list` CLI commands (#52, #48)
+- `known_debt.md` as standard memory file for tracking technical debt (#53, #32)
+
 ## [0.1.2] - 2026-03-18
 
 ### Added
@@ -65,6 +86,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.1.9]: https://github.com/kiloloop/oacp/compare/v0.1.2...v0.1.9
 [0.1.2]: https://github.com/kiloloop/oacp/compare/v0.1.1...v0.1.2
 [0.1.1]: https://github.com/kiloloop/oacp/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/kiloloop/oacp/releases/tag/v0.1.0

{oacp_cli-0.1.2 → oacp_cli-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: oacp-cli
-Version: 0.1.2
+Version: 0.2.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
@@ -68,7 +68,7 @@ Doctor checks your CLI tools, and with `--project` it audits workspace structure
 
 - **Inbox/outbox messaging** — async YAML-based communication with threading, broadcast, and expiry
 - **Structured review loop** — severity-graded findings, quality gates, and multi-round review
-- **Durable shared memory** — project facts, decisions, and open threads that persist across sessions
+- **Durable shared memory** — project facts, decisions, open threads, and known debt with an explicit active/archive split
 - **Dispatch state machine** — full task lifecycle tracking from assignment to merge
 - **Agent safety defaults** — baseline rules for git, credentials, staging, and scope discipline
 - **Runtime-agnostic** — works with any agent runtime that can read/write files
@@ -151,6 +151,7 @@ uv tool install .
 ## Commands
 
 - `oacp init` creates a project workspace under `$OACP_HOME/projects/`
+- `oacp memory` archives or restores project memory files
 - `oacp send` sends a protocol-compliant inbox message
 - `oacp doctor` checks environment and workspace health
 - `oacp validate` validates an inbox/outbox YAML message
@@ -164,7 +165,7 @@ If `OACP_HOME` is unset, workspace commands default to `~/oacp` (underscore).
 | **Inbox/Outbox** | Async messaging between agents via YAML files in `agents/<name>/inbox/` |
 | **Review Loop** | Structured code review: `review_request` → `review_feedback` → `review_addressed` → `review_lgtm` |
 | **Quality Gate** | Merge-readiness criteria: no unresolved P0/P1 findings, deferred nits tracked |
-| **Durable Memory** | Shared `memory/` directory with project facts, decisions, and open threads |
+| **Durable Memory** | Shared `memory/` directory with an active working set plus `memory/archive/` for historical memory |
 | **Dispatch States** | Task lifecycle: `received` → `accepted` → `working` → `pr_opened` → `in_review` → `done` |
 | **Safety Defaults** | Baseline rules all agents follow: no force push, no secrets in commits, stage hygiene |
 
@@ -175,7 +176,7 @@ oacp/
 ├── docs/
 │   ├── protocol/       # Canonical protocol specifications (13 specs)
 │   └── guides/         # Setup, adoption, versioning
-├── scripts/            # 13 kernel scripts (Python + shell)
+├── scripts/            # 18 kernel scripts (Python + shell)
 ├── templates/          # Packet, role, and guardrail templates (19)
 ├── tests/              # Test suite
 ├── Makefile            # Task runner (make help for all targets)
@@ -214,6 +215,7 @@ OACP ships kernel scripts — the key CLI commands you'll use most:
 
 - **`oacp init`** — create a new project workspace (the first command you run)
 - **`oacp add-agent`** — add an agent to an existing project workspace
+- **`oacp memory`** — archive or restore project memory files
 - **`oacp setup`** — generate runtime-specific config files (Claude, Codex, Gemini)
 - **`oacp send`** — send protocol-compliant messages between agents
 - **`oacp doctor`** — environment and workspace health check
@@ -257,7 +259,9 @@ $OACP_HOME/projects/<project>/
 ├── memory/                  # Shared durable memory
 │   ├── project_facts.md
 │   ├── decision_log.md
-│   └── open_threads.md
+│   ├── open_threads.md
+│   ├── known_debt.md
+│   └── archive/
 ├── packets/                 # Review/findings artifacts
 └── workspace.json           # Project metadata
 ```

{oacp_cli-0.1.2 → oacp_cli-0.2.0}/QUICKSTART.md

@@ -55,7 +55,9 @@ $OACP_HOME/projects/my-first-project/
 ├── memory/
 │   ├── project_facts.md
 │   ├── decision_log.md
-│   └── open_threads.md
+│   ├── open_threads.md
+│   ├── known_debt.md
+│   └── archive/
 ├── packets/
 │   ├── review/
 │   └── findings/
@@ -82,7 +84,7 @@ Check inbox: ls $OACP_HOME/projects/my-first-project/agents/claude/inbox/
 OACP workspace: $OACP_HOME/projects/my-first-project/
 ```
 
-**Other runtimes** — point your agent's system prompt at the workspace path and instruct it to read `memory/project_facts.md` at session start.
+**Other runtimes** — point your agent's system prompt at the workspace path and instruct it to read the standard `memory/` files at session start.
 
 For full runtime setup (role templates, guardrails, skills), see [docs/guides/setup.md](docs/guides/setup.md).
 

{oacp_cli-0.1.2 → oacp_cli-0.2.0}/README.md

@@ -42,7 +42,7 @@ Doctor checks your CLI tools, and with `--project` it audits workspace structure
 
 - **Inbox/outbox messaging** — async YAML-based communication with threading, broadcast, and expiry
 - **Structured review loop** — severity-graded findings, quality gates, and multi-round review
-- **Durable shared memory** — project facts, decisions, and open threads that persist across sessions
+- **Durable shared memory** — project facts, decisions, open threads, and known debt with an explicit active/archive split
 - **Dispatch state machine** — full task lifecycle tracking from assignment to merge
 - **Agent safety defaults** — baseline rules for git, credentials, staging, and scope discipline
 - **Runtime-agnostic** — works with any agent runtime that can read/write files
@@ -125,6 +125,7 @@ uv tool install .
 ## Commands
 
 - `oacp init` creates a project workspace under `$OACP_HOME/projects/`
+- `oacp memory` archives or restores project memory files
 - `oacp send` sends a protocol-compliant inbox message
 - `oacp doctor` checks environment and workspace health
 - `oacp validate` validates an inbox/outbox YAML message
@@ -138,7 +139,7 @@ If `OACP_HOME` is unset, workspace commands default to `~/oacp` (underscore).
 | **Inbox/Outbox** | Async messaging between agents via YAML files in `agents/<name>/inbox/` |
 | **Review Loop** | Structured code review: `review_request` → `review_feedback` → `review_addressed` → `review_lgtm` |
 | **Quality Gate** | Merge-readiness criteria: no unresolved P0/P1 findings, deferred nits tracked |
-| **Durable Memory** | Shared `memory/` directory with project facts, decisions, and open threads |
+| **Durable Memory** | Shared `memory/` directory with an active working set plus `memory/archive/` for historical memory |
 | **Dispatch States** | Task lifecycle: `received` → `accepted` → `working` → `pr_opened` → `in_review` → `done` |
 | **Safety Defaults** | Baseline rules all agents follow: no force push, no secrets in commits, stage hygiene |
 
@@ -149,7 +150,7 @@ oacp/
 ├── docs/
 │   ├── protocol/       # Canonical protocol specifications (13 specs)
 │   └── guides/         # Setup, adoption, versioning
-├── scripts/            # 13 kernel scripts (Python + shell)
+├── scripts/            # 18 kernel scripts (Python + shell)
 ├── templates/          # Packet, role, and guardrail templates (19)
 ├── tests/              # Test suite
 ├── Makefile            # Task runner (make help for all targets)
@@ -188,6 +189,7 @@ OACP ships kernel scripts — the key CLI commands you'll use most:
 
 - **`oacp init`** — create a new project workspace (the first command you run)
 - **`oacp add-agent`** — add an agent to an existing project workspace
+- **`oacp memory`** — archive or restore project memory files
 - **`oacp setup`** — generate runtime-specific config files (Claude, Codex, Gemini)
 - **`oacp send`** — send protocol-compliant messages between agents
 - **`oacp doctor`** — environment and workspace health check
@@ -231,7 +233,9 @@ $OACP_HOME/projects/<project>/
 ├── memory/                  # Shared durable memory
 │   ├── project_facts.md
 │   ├── decision_log.md
-│   └── open_threads.md
+│   ├── open_threads.md
+│   ├── known_debt.md
+│   └── archive/
 ├── packets/                 # Review/findings artifacts
 └── workspace.json           # Project metadata
 ```

{oacp_cli-0.1.2 → oacp_cli-0.2.0}/SPEC.md

@@ -29,28 +29,36 @@ Full specification: [`docs/protocol/inbox_outbox.md`](docs/protocol/inbox_outbox
 Agents communicate through a shared filesystem using YAML messages. Each agent has an inbox and outbox directory within a project workspace:
 
 ```
-$OACP_HOME/projects/<project>/
-├── agents/
+$OACP_HOME/
+├── agents/                          # Global agent profiles
 │   ├── claude/
-│   │   ├── inbox/          # Other agents write here
-│   │   ├── outbox/         # Claude's sent messages (copies)
-│   │   ├── status.yaml     # Dynamic agent state
-│   │   └── agent_card.yaml # Static agent identity
-│   ├── codex/
-│   │   ├── inbox/
-│   │   ├── outbox/
-│   │   └── ...
-│   └── gemini/
-│       └── ...
-├── memory/                  # Shared durable memory
-│   ├── project_facts.md
-│   ├── decision_log.md
-│   └── open_threads.md
-├── packets/                 # Review/findings artifacts
-│   ├── review/
-│   └── findings/
-├── merges/                  # Merge decision records
-└── workspace.json           # Project metadata
+│   │   └── profile.yaml            # Global identity defaults
+│   └── codex/
+│       └── profile.yaml
+└── projects/<project>/
+    ├── agents/
+    │   ├── claude/
+    │   │   ├── inbox/               # Other agents write here
+    │   │   ├── outbox/              # Claude's sent messages (copies)
+    │   │   ├── status.yaml          # Dynamic agent state
+    │   │   └── agent_card.yaml      # Static agent identity (overrides global)
+    │   ├── codex/
+    │   │   ├── inbox/
+    │   │   ├── outbox/
+    │   │   └── ...
+    │   └── gemini/
+    │       └── ...
+    ├── memory/                      # Shared durable memory
+    │   ├── project_facts.md
+    │   ├── decision_log.md
+    │   ├── open_threads.md
+    │   └── known_debt.md
+    │   └── archive/
+    ├── packets/                     # Review/findings artifacts
+    │   ├── review/
+    │   └── findings/
+    ├── merges/                      # Merge decision records
+    └── workspace.json               # Project metadata
 ```
 
 ### Message Format
@@ -315,8 +323,11 @@ Location: `$OACP_HOME/projects/<project>/memory/`
 | `project_facts.md` | Agent roles, repo structure, architecture, conventions |
 | `decision_log.md` | Timestamped decisions with rationale |
 | `open_threads.md` | Unresolved issues, blocked epics, cross-agent coordination |
+| `known_debt.md` | Verified unresolved debt and recurring cleanup items |
 
-All runtimes read these at session start. Only stable, verified outcomes are written here. Promotion flows through merge decisions via a project-defined durable-memory promotion mechanism.
+The top-level `memory/` files are the active working set. Historical memory can be moved into `memory/archive/`, which is not loaded at session start by default.
+
+All runtimes read the active memory files at session start. Only stable, verified outcomes are written here. Promotion flows through merge decisions via a project-defined durable-memory promotion mechanism.
 
 #### 2. Handoff Messages with Context Keys (ephemeral)
 
@@ -330,7 +341,7 @@ Review packets, findings packets, and merge decisions form a structured audit tr
 
 | Sync Point | Direction | Action |
 |------------|-----------|--------|
-| Session start | Memory → Agent | Read all 3 memory files |
+| Session start | Memory → Agent | Read all 4 active memory files (not `memory/archive/`) |
 | Task completion | Agent → Memory | Write stable outcomes via merge decision |
 | Handoff | Agent → Agent | Include `conversation_id` + `context_keys` |
 | Review cycle start | Packets → Agent | Read relevant packet history |
@@ -342,7 +353,7 @@ Agents follow a 6-step init sequence at session start:
 
 1. **Load global rules** (required) — safety defaults, tool preferences
 2. **Load project rules** (required) — repo structure, conventions
-3. **Load durable memory** (required) — project facts, decisions, open threads
+3. **Load durable memory** (required) — project facts, decisions, open threads, known debt
 4. **Check inbox** (optional) — summarize pending messages
 5. **Load skills/tools** (optional) — runtime-specific capabilities
 6. **Report status** (required) — update `status.yaml`
@@ -445,7 +456,7 @@ The kernel boundary was established through a classification audit of all projec
 
 OACP ships a **kernel** — the minimal set of scripts, templates, and docs needed to adopt the protocol. Everything else is internal tooling for advanced orchestration workflows.
 
-### Kernel Scripts (14)
+### Kernel Scripts (18)
 
 These scripts ship with the OSS release. Most are stdlib-only Python or POSIX shell with no external dependencies beyond `python3`, `git`, and `gh`. Exception: `preflight.py` also requires `ruff`, `shellcheck`, and optionally `pyyaml` for YAML validation.
 
@@ -458,9 +469,13 @@ These scripts ship with the OSS release. Most are stdlib-only Python or POSIX sh
 | `init_packet.sh` | Bootstraps review/findings/merge packet directories |
 | `init_project_workspace.py` | Creates a new project workspace — CLI: `oacp init` |
 | `add_agent.py` | Add an agent to an existing project workspace — CLI: `oacp add-agent` |
+| `agent_profile.py` | Two-tier agent profile management — CLI: `oacp agent` |
+| `memory_cli.py` | Archive or restore project memory files — CLI: `oacp memory` |
 | `setup_runtime.py` | Generate runtime-specific config files — CLI: `oacp setup` |
 | `normalize_findings.py` | Converts raw reviewer output to canonical findings YAML |
 | `preflight.py` | Unified quality checks — CI runs this on every PR |
+| `promote_to_archive.py` | Move a non-standard memory file into `memory/archive/` |
+| `restore_from_archive.py` | Restore an archived memory file into the active `memory/` working set |
 | `send_inbox_message.py` | CLI for all inbox messaging — CLI: `oacp send` |
 | `update_workspace.sh` | Idempotent workspace sync across protocol versions |
 | `validate_agent_card.py` | Validates agent card YAML against the schema |

oacp_cli-0.2.0/docs/protocol/agent_profiles.md

@@ -0,0 +1,160 @@
+# Agent Profiles — Two-Tier Identity System
+
+## Purpose
+
+Agent profiles provide a two-tier identity system: **global profiles** declare stable defaults for an agent across all projects, while **project-level agent cards** override those defaults for a specific project context. The merge produces a single resolved view used for routing, discovery, and authorization.
+
+The model mirrors how Claude Code handles instructions: a global `~/.claude/CLAUDE.md` sets baseline behavior, and a project-level `CLAUDE.md` overrides or extends it per repository. Profiles work the same way — define an agent's identity once, specialize per project.
+
+## Directory Layout
+
+```
+$OACP_HOME/
+├── agents/                              # Global agent profiles
+│   ├── claude/
+│   │   └── profile.yaml
+│   └── codex/
+│       └── profile.yaml
+└── projects/<project>/
+    └── agents/
+        └── claude/
+            ├── agent_card.yaml          # Project-level overrides
+            ├── status.yaml
+            ├── inbox/
+            └── outbox/
+```
+
+- **Global profiles** (`agents/<name>/profile.yaml`) are created once per agent and rarely change.
+- **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.
+
+## Merge Rules
+
+When both a global profile and a project card exist, they are merged with the following rules:
+
+### Scalars
+
+Project value wins if non-empty. Empty or null project values fall through to the global default.
+
+```yaml
+# Global profile              # Project card               # Merged result
+model: "claude-opus-4-6"       model: "claude-sonnet-4"     model: "claude-sonnet-4"
+description: "Implementer"    description: ""              description: "Implementer"
+trust_level: standard          trust_level: elevated        trust_level: elevated
+```
+
+### Dict Sections
+
+Key-level merge within the dict. Project keys override matching global keys; global-only keys are preserved.
+
+```yaml
+# Global profile               # Project card              # Merged result
+capabilities:                  capabilities:               capabilities:
+  tools: [Bash, Read]           tools: [Bash, Read, Edit]   tools: [Bash, Read, Edit]
+  languages: [python]           domains: [trading]          languages: [python]
+  domains: [backend]                                        domains: [trading]
+```
+
+Note: `tools`, `languages`, and `domains` within `capabilities` are list sub-fields and follow list replacement (see below). The dict-level merge applies to the `capabilities` section itself — project can add or override keys without erasing global-only keys.
+
+### Lists
+
+Full replacement. If the project card defines a list field, it replaces the global list entirely. This prevents ambiguous merge semantics (append? deduplicate? reorder?).
+
+```yaml
+# Global profile               # Project card              # Merged result
+skills:                        skills:                     skills:
+  - id: code_review              - id: security_audit        - id: security_audit
+    name: Code Review              name: Security Audit        name: Security Audit
+```
+
+### Missing Sections
+
+If the project card omits a section entirely, the global profile's value is used verbatim.
+
+## Profile Schema Reference
+
+Global profiles use `agent_profile.template.yaml`. Fields:
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `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 |
+| `description` | string | no | One-line role summary |
+| `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` |
+| `capabilities` | dict | no | `tools`, `languages`, `domains` lists |
+| `skills` | list | no | Structured skill declarations (A2A-compatible) |
+
+Project-level agent cards extend this schema with additional sections: `permissions`, `availability`, and `protocol`. See `templates/agent_card.template.yaml` for the full card schema.
+
+## CLI Reference
+
+The CLI wraps `scripts/agent_profile.py`. All commands auto-discover `$OACP_HOME`.
+
+### `oacp agent init`
+
+Scaffold a global agent profile from the template.
+
+```bash
+oacp agent init claude --runtime claude
+# Created global profile: $OACP_HOME/agents/claude/profile.yaml
+
+oacp agent init codex --runtime codex
+# Created global profile: $OACP_HOME/agents/codex/profile.yaml
+```
+
+If the profile already exists, the command skips without overwriting.
+
+### `oacp agent show`
+
+Print the resolved profile YAML. Without `--project`, prints the global profile. With `--project`, prints the merged result.
+
+```bash
+oacp agent show claude
+# Prints global profile for claude
+
+oacp agent show claude --project my-app
+# Prints merged profile (global + project card overrides)
+```
+
+### `oacp agent list`
+
+List known agents with their tier tags.
+
+```bash
+oacp agent list
+#   claude  (global)
+#   codex   (global)
+
+oacp agent list --project my-app
+#   claude  (global, project)
+#   codex   (global)
+#   gemini  (project)
+```
+
+## Relationship to Existing Agent Cards
+
+Agent cards predate global profiles and remain the authoritative per-project identity. The profile system adds a global defaults layer underneath:
+
+| Concern | Global Profile | Project Agent Card |
+|---------|---------------|--------------------|
+| **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 |
+| **Authority** | Defaults only | Authoritative for the project |
+| **Extra sections** | None | `permissions`, `availability`, `protocol` |
+
+When both exist, the merged result is what other systems (routing, doctor checks, discovery) should consume. When only a project card exists (no global profile), the card is used as-is. When only a global profile exists (no project card), the profile is used as-is.
+
+## Cross-References
+
+- **Runtime Capabilities**: `docs/protocol/runtime_capabilities.md` — capability keys, status schema, health checks
+- **Inbox Protocol**: `docs/protocol/inbox_outbox.md` — agent messaging format
+- **Profile Script**: `scripts/agent_profile.py` — implementation with merge logic
+- **Profile Template**: `templates/agent_profile.template.yaml` — global profile scaffold
+- **Card Template**: `templates/agent_card.template.yaml` — project card scaffold
+- **Card Validator**: `scripts/validate_agent_card.py` — schema validation

{oacp_cli-0.1.2 → oacp_cli-0.2.0}/docs/protocol/cross_runtime_sync.md

@@ -23,11 +23,16 @@ The protocol defines three complementary sync mechanisms, ordered from most dura
 | `project_facts.md` | Agent roles, repo structure, architecture, conventions | Any agent via the project's durable-memory promotion flow |
 | `decision_log.md` | Timestamped decisions with rationale | Any agent via the project's durable-memory promotion flow |
 | `open_threads.md` | Unresolved issues, blocked epics, cross-agent coordination | Any agent via the project's durable-memory promotion flow |
+| `known_debt.md` | Verified unresolved debt that should persist across sessions | Any agent via the project's durable-memory promotion flow |
 
-These files are the **source of truth** for stable project knowledge. All runtimes read them at session start. Only verified, stable outcomes should be written here.
+The top-level files in `memory/` are the active working set. Historical memory can be moved into `memory/archive/`, which is not loaded during session init unless an agent explicitly opts in.
+
+These files are the **source of truth** for stable project knowledge. All runtimes read the active working set at session start. Only verified, stable outcomes should be written here.
 
 **Promotion flow**: Merge decisions contain a "Durable Memory Updates" section. Each implementation should provide a promotion mechanism that extracts approved entries from merge artifacts and appends them to the appropriate memory file, deduplicating against existing content.
 
+**Archive flow**: Users or coordinator agents may move non-standard memory files into `memory/archive/` for historical retention, then restore them back into `memory/` when they become active again.
+
 ### 2. Handoff Messages with Context Keys
 
 **Location**: `agents/<agent>/inbox/`
@@ -57,7 +62,7 @@ Agents synchronize knowledge at well-defined points in the workflow:
 
 | Sync Point | Action | Direction |
 |------------|--------|-----------|
-| **Session start** | Read `memory/project_facts.md`, `decision_log.md`, `open_threads.md` | Memory -> Agent |
+| **Session start** | Read `memory/project_facts.md`, `decision_log.md`, `open_threads.md`, `known_debt.md` (not `memory/archive/`) | Memory -> Agent |
 | **Task completion** | Write stable outcomes to memory via merge decision + durable-memory promotion flow | Agent -> Memory |
 | **Handoff** | Include `conversation_id` + `context_keys` in handoff message | Agent -> Agent |
 | **Review cycle start** | Read relevant packet history | Packets -> Agent |
@@ -104,7 +109,7 @@ Each project should provide a durable-memory promotion mechanism that:
 
 1. Scans merge decisions or equivalent terminal artifacts
 2. Extracts entries from the "Durable Memory Updates" section
-3. Appends new entries to `decision_log.md`, `open_threads.md`, or `project_facts.md`
+3. Appends new entries to `decision_log.md`, `open_threads.md`, `project_facts.md`, or `known_debt.md`
 4. Deduplicates against existing content
 
 This ensures that knowledge flows from ephemeral review artifacts into durable memory that persists across sessions and runtimes, without requiring a specific helper script name.

{oacp_cli-0.1.2 → oacp_cli-0.2.0}/docs/protocol/runtime_capabilities.md

@@ -269,6 +269,7 @@ The card schema is inspired by Google's A2A Agent Card spec (v0.3.0). Key differ
 
 ## Cross-References
 
+- **Agent Profiles**: `docs/protocol/agent_profiles.md` — two-tier global profile + project card system
 - **Parity Matrix**: `docs/guides/runtime_capability_matrix.md` — detailed per-runtime capability comparison
 - **Inbox Protocol**: `docs/protocol/inbox_outbox.md` — agent messaging format
 - **Session Lifecycle**: `scripts/session_lifecycle_hooks.py` (reference implementation) — session boundary hooks

{oacp_cli-0.1.2 → oacp_cli-0.2.0}/docs/protocol/session_init.md

@@ -60,11 +60,14 @@ The init sequence has 6 steps in a fixed order. Each step is classified as **req
 
 **Location:** `$OACP_HOME/projects/<project>/memory/`
 
+The top-level files in `memory/` are the active working set. `memory/archive/` is historical storage and is not loaded by default at session start.
+
 **Loading order:**
 
 1. `project_facts.md` — agent roles, repo structure, architecture, conventions. Read first because it provides the mental model for everything else.
 2. `decision_log.md` — timestamped decisions with rationale. Read second to understand what has been decided and why.
-3. `open_threads.md` — unresolved issues, blocked epics, cross-agent coordination. Read last because it builds on the context from facts and decisions.
+3. `open_threads.md` — unresolved issues, blocked epics, cross-agent coordination. Read third because it builds on the context from facts and decisions.
+4. `known_debt.md` — verified unresolved debt, recurring pain points, and cleanup items that future sessions should keep in view.
 
 **Conflict resolution:** If memory files contradict project rules (e.g., `project_facts.md` says "use pytest" but `CLAUDE.md` says "use make test"), project rules win. Memory files may be stale; project rules are maintained alongside the code.
 

{oacp_cli-0.1.2 → oacp_cli-0.2.0}/oacp/cli.py

@@ -21,6 +21,9 @@ Installable Open Agent Coordination Protocol (OACP) CLI.
 Commands:
   init           Create a project workspace under $OACP_HOME/projects/
   add-agent      Add an agent to an existing project workspace
+  agent          Manage global agent profiles (init, show, list)
+  inbox          List pending inbox messages
+  memory         Archive or restore project memory files
   setup          Generate runtime-specific config files in a repo
   send           Send a protocol-compliant inbox message
   org-memory     Initialize org-level memory at $OACP_HOME/org-memory/
@@ -32,8 +35,10 @@ Examples:
   oacp init my-project --repo /path/to/repo
   oacp init my-project --agents claude,codex
   oacp add-agent my-project alice --runtime claude
+  oacp inbox my-project --agent claude
+  oacp memory archive my-project research_notes.md
   oacp setup claude --project my-project
-  oacp send my-project --from codex --to iris --type notification --subject "Done" --body "Completed"
+  oacp send my-project --to iris --type notification --subject "Done" --body "Completed"
   oacp org-memory init
   oacp write-event --agent claude --project my-project --type decision --slug api-convention --body "Use REST for public APIs"
   oacp doctor
@@ -43,6 +48,9 @@ Examples:
 SCRIPT_NAMES = {
     "init": "init_project_workspace.py",
     "add-agent": "add_agent.py",
+    "agent": "agent_profile.py",
+    "inbox": "oacp_inbox.py",
+    "memory": "memory_cli.py",
     "setup": "setup_runtime.py",
     "send": "send_inbox_message.py",
     "org-memory": "init_org_memory.py",

{oacp_cli-0.1.2 → oacp_cli-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "oacp-cli"
-version = "0.1.2"
+version = "0.2.0"
 description = "Open Agent Coordination Protocol CLI for file-based multi-agent workflows"
 readme = "README.md"
 license = "Apache-2.0"
@@ -50,6 +50,7 @@ packages = ["oacp"]
 
 [tool.hatch.build.targets.wheel.force-include]
 "scripts/codex_session_init.py" = "oacp/_scripts/codex_session_init.py"
+"scripts/_oacp_constants.py" = "oacp/_scripts/_oacp_constants.py"
 "scripts/_oacp_env.py" = "oacp/_scripts/_oacp_env.py"
 "scripts/handoff_schema.py" = "oacp/_scripts/handoff_schema.py"
 "scripts/oacp_doctor.py" = "oacp/_scripts/oacp_doctor.py"
@@ -58,6 +59,12 @@ packages = ["oacp"]
 "scripts/session_lifecycle_hooks.py" = "oacp/_scripts/session_lifecycle_hooks.py"
 "scripts/validate_message.py" = "oacp/_scripts/validate_message.py"
 "scripts/add_agent.py" = "oacp/_scripts/add_agent.py"
+"scripts/agent_profile.py" = "oacp/_scripts/agent_profile.py"
+"scripts/oacp_inbox.py" = "oacp/_scripts/oacp_inbox.py"
+"scripts/memory_cli.py" = "oacp/_scripts/memory_cli.py"
+"scripts/memory_archive_common.py" = "oacp/_scripts/memory_archive_common.py"
+"scripts/promote_to_archive.py" = "oacp/_scripts/promote_to_archive.py"
+"scripts/restore_from_archive.py" = "oacp/_scripts/restore_from_archive.py"
 "scripts/setup_runtime.py" = "oacp/_scripts/setup_runtime.py"
 "scripts/init_org_memory.py" = "oacp/_scripts/init_org_memory.py"
 "scripts/write_event.py" = "oacp/_scripts/write_event.py"
@@ -66,6 +73,7 @@ packages = ["oacp"]
 "templates/org-memory/decisions.md" = "oacp/_templates/org-memory/decisions.md"
 "templates/org-memory/rules.md" = "oacp/_templates/org-memory/rules.md"
 "templates/agent_card.template.yaml" = "oacp/_templates/agent_card.template.yaml"
+"templates/agent_profile.template.yaml" = "oacp/_templates/agent_profile.template.yaml"
 "templates/claude/agents/role_agent.template.md" = "oacp/_templates/claude/agents/role_agent.template.md"
 
 [tool.ruff]

oacp_cli-0.2.0/scripts/_oacp_constants.py

@@ -0,0 +1,58 @@
+# SPDX-FileCopyrightText: 2026 Kiloloop
+# SPDX-License-Identifier: Apache-2.0
+"""Shared constants and helpers for OACP scripts."""
+
+from __future__ import annotations
+
+import datetime as dt
+import re
+from contextlib import nullcontext
+from importlib import resources
+from pathlib import Path
+
+AGENT_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$")
+CREATABLE_RUNTIMES = ("claude", "codex", "gemini")
+ALL_RUNTIMES = ("claude", "codex", "gemini", "human", "unknown")
+CANONICAL_CAPABILITIES = {
+    "headless",
+    "mcp_tools",
+    "shell_access",
+    "git_ops",
+    "github_cli",
+    "subagents",
+    "parallel_teams",
+    "web_search",
+    "browser",
+    "session_memory",
+    "notifications",
+    "async_tasks",
+    "image_generation",
+}
+
+
+def utc_now_iso(now: dt.datetime | None = None) -> str:
+    """Return a UTC RFC3339 timestamp with seconds precision."""
+    base = now or dt.datetime.now(dt.timezone.utc)
+    if base.tzinfo is None:
+        base = base.replace(tzinfo=dt.timezone.utc)
+    else:
+        base = base.astimezone(dt.timezone.utc)
+    return base.strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def _write_if_missing(path: Path, content: str) -> bool:
+    """Write content to *path* only if it does not already exist."""
+    if path.exists():
+        return False
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content, encoding="utf-8")
+    return True
+
+
+def _template_path(relative: str):
+    """Resolve a template file from the repo tree or installed package."""
+    repo_template = Path(__file__).resolve().parent.parent / "templates" / relative
+    if repo_template.is_file():
+        return nullcontext(repo_template)
+    resource = resources.files("oacp").joinpath("_templates", relative)
+    return resources.as_file(resource)