From ca87963a8799cb69e32c60f3e4a8eff4acc7e19a Mon Sep 17 00:00:00 2001 From: Joe Feser Date: Tue, 26 May 2026 09:29:05 -0500 Subject: [PATCH 1/3] docs: apply phase 260 public HACP protocol packet --- README.md | 37 ++++++++++++++++++++++ docs/adapters-and-projections.md | 35 +++++++++++++++++++++ docs/authority-boundaries.md | 29 +++++++++++++++++ docs/event-lifecycle.md | 28 +++++++++++++++++ docs/glossary.md | 34 ++++++++++++++++++++ docs/workflows/owner-controlled-bridge.md | 38 +++++++++++++++++++++++ schemas/README.md | 10 ++++++ schemas/examples/README.md | 5 +++ 8 files changed, 216 insertions(+) create mode 100644 docs/adapters-and-projections.md create mode 100644 docs/authority-boundaries.md create mode 100644 docs/event-lifecycle.md create mode 100644 docs/glossary.md create mode 100644 docs/workflows/owner-controlled-bridge.md diff --git a/README.md b/README.md index 15564af..d909150 100644 --- a/README.md +++ b/README.md @@ -13,6 +13,43 @@ gates, bounded iteration, and audit evidence. The public draft keeps the reusable contracts and leaves product-specific implementation details out of scope. +## Public Protocol Framing + +HACP is a vendor-neutral human-approved coordination protocol. It defines +packet, report, evidence, decision, stop, and audit contracts for accountable +AI-assisted workflows. + +HACP does not execute shell/model/tool work by itself. File transport, CLI +transport, and adapter delivery paths move records, but they do not grant +authority. Report verification confirms custody and integrity checks, not task +completion proof. + +Risky authority transitions remain human-decision gated. + +See: + +- [docs/glossary.md](docs/glossary.md) +- [docs/event-lifecycle.md](docs/event-lifecycle.md) +- [docs/authority-boundaries.md](docs/authority-boundaries.md) +- [docs/adapters-and-projections.md](docs/adapters-and-projections.md) +- [docs/workflows/owner-controlled-bridge.md](docs/workflows/owner-controlled-bridge.md) + +## HACP Is / Is Not + +HACP is: + +- a protocol for human-approved coordination +- a contract for packet/report/evidence/decision custody +- a way to audit gates, authority, and stop outcomes + +HACP is not: + +- an autonomous orchestration runtime +- a hosted shell +- model/tool routing authority +- a RabbitMQ replacement +- completion proof by report presence or verification + ## Why HACP Exists Teams are starting to use agents and automation for real work, but the approval diff --git a/docs/adapters-and-projections.md b/docs/adapters-and-projections.md new file mode 100644 index 0000000..2bf5f7b --- /dev/null +++ b/docs/adapters-and-projections.md @@ -0,0 +1,35 @@ +# HACP Adapters And Projections + +Adapters and projections carry or display protocol records. They are not core +authority and do not grant approval by themselves. + +## Core Rule + +Authority remains in explicit `HumanDecision` checkpoints. Transport and read +models never replace those checkpoints. + +## Adapter Examples (Transport Paths) + +- `npx hacp` CLI commands +- file drop/push transport +- RabbitMQ adapter +- MCP adapter +- webhook adapters + +Each adapter may move packets, reports, evidence, and receipts. None of them +approves risky transitions. + +## Projection Examples (Read Models) + +- OTEL projections +- dashboard/reporting projections +- derived lifecycle summaries + +Projections are derived views. They are useful for observability and audits, but +they are not source authority. + +## Non-Claims + +- HACP does not execute work by itself. +- HACP does not require RabbitMQ. +- HACP does not treat transport success as completion proof. diff --git a/docs/authority-boundaries.md b/docs/authority-boundaries.md new file mode 100644 index 0000000..eddcc25 --- /dev/null +++ b/docs/authority-boundaries.md @@ -0,0 +1,29 @@ +# HACP Authority Boundaries + +HACP keeps authority explicit and human-issued. The protocol records custody and +decisions; it does not replace approval authority. + +## Mandatory Boundary Statements + +- Approval is explicit and human-issued. +- Report verification confirms custody/integrity checks, not completion. +- File and CLI transports move artifacts but do not grant authority. +- Human decision remains required for risky transitions. + +## What Authority Is Not + +- File arrival is not approval. +- Report presence is not completion proof. +- Verification does not replace human decision. +- Adapter usage does not transfer authority. + +## Control-Plane Posture + +HACP is transport-neutral. It can be carried through multiple adapters while +keeping the same authority contracts: + +- `TaskPacket` defines bounded intent and constraints. +- `AgentReport` and `EvidenceSet` provide reviewable claims. +- `HumanDecision` records approval/rejection/defer outcomes. +- `StopReason` records why continuation halted. +- `AuditEvent` and `Receipt` preserve custody traceability. diff --git a/docs/event-lifecycle.md b/docs/event-lifecycle.md new file mode 100644 index 0000000..23817d3 --- /dev/null +++ b/docs/event-lifecycle.md @@ -0,0 +1,28 @@ +# HACP Event Lifecycle + +This page summarizes public draft lifecycle events for packet custody, report +custody, and explicit authority decisions. + +## Packet Lifecycle + +- `packet.received` +- `packet.exported` +- `packet.validated` + +## Report Lifecycle + +- `report.built` +- `report.ready_for_import` +- `report.import_verifier_checked` + +## Decision And Stop Lifecycle + +- `human_decision_required` +- `stopped` +- `rejected` + +## Boundary Notes + +- `report.import_verifier_checked` confirms custody/integrity checks only. +- Verification state is not completion proof. +- Risky transitions require explicit `HumanDecision`. diff --git a/docs/glossary.md b/docs/glossary.md new file mode 100644 index 0000000..b5ef29d --- /dev/null +++ b/docs/glossary.md @@ -0,0 +1,34 @@ +# HACP Glossary + +This glossary is public-safe protocol framing for core HACP contracts and +authority boundaries. + +## Core Contract Objects + +- `TaskPacket`: bounded, human-approved task intent and constraints. +- `AgentReport`: execution/output record returned for review and import. +- `EvidenceSet`: references and artifacts used to justify report claims. +- `HumanDecision`: explicit approve/reject/defer authority checkpoint. +- `StopReason`: typed reason that continuation stopped or was rejected. +- `Receipt`: custody/readback marker for import/verification steps. +- `AuditEvent`: immutable event record for lifecycle and authority traceability. + +## Lifecycle Terms + +- `packet.received`: packet intake acknowledged. +- `packet.exported`: packet handed to external or local workflow path. +- `packet.validated`: packet contract checks passed. +- `report.built`: report artifact assembled. +- `report.ready_for_import`: report prepared for app-side verifier/import. +- `report.import_verifier_checked`: import verification checks passed. +- `human_decision_required`: authority gate is still open and required. +- `stopped`: execution path halted under explicit stop semantics. +- `rejected`: decision or result rejected with typed rationale. + +## Boundary Terms + +- `authority boundary`: rule defining who can approve risky transitions. +- `transport-neutral`: contract does not depend on one transport mechanism. +- `owner-controlled`: execution boundary stays under owner/operator control. +- `adapter`: implementation path carrying records without granting authority. +- `projection`: derived read model (for example OTEL), not source authority. diff --git a/docs/workflows/owner-controlled-bridge.md b/docs/workflows/owner-controlled-bridge.md new file mode 100644 index 0000000..3ff5925 --- /dev/null +++ b/docs/workflows/owner-controlled-bridge.md @@ -0,0 +1,38 @@ +# Owner-Controlled Bridge Workflow + +This workflow describes a public-safe bridge where an owner controls execution +while HACP records packet/report/evidence/decision custody. + +## Flow + +1. Human approves a bounded `TaskPacket`. +2. Packet is exported through CLI or file transport. +3. External/local runner performs bounded work. +4. Runner returns an `AgentReport` with an `EvidenceSet`. +5. Import verifier checks custody/integrity and emits receipt/audit events. +6. Workflow enters `human_decision_required`. +7. Human records a `HumanDecision` or a `StopReason`. + +## Example Bridge Paths + +CLI: + +```bash +npx hacp packet fetch --packet-id pkt_example_001 --out packet.json +npx hacp runner execute --packet packet.json --command "npm run test:unit" --out report.json +npx hacp report submit --packet packet.json --report report.json +``` + +File transport: + +```text +file-drop/incoming/pkt_example_001.task-packet.json +file-drop/outgoing/rpt_example_001.agent-report.json +``` + +## Required Boundaries + +- File/CLI transport moves records but does not grant authority. +- Verification confirms custody/integrity checks, not completion proof. +- Risky transitions require explicit human-issued decision records. +- HACP records and coordinates these steps; it does not execute work by itself. diff --git a/schemas/README.md b/schemas/README.md index 7cb3f65..ad83014 100644 --- a/schemas/README.md +++ b/schemas/README.md @@ -28,6 +28,9 @@ rather than rewriting old identifiers. These schemas validate shape and vocabulary only. They do not execute workflow. +Schema checks are contract-shape checks. They do not grant authority, do not +replace human approval, and do not prove completion. + They do not: - execute tasks, @@ -41,6 +44,13 @@ They do not: - mutate product records, - certify external tool compatibility. +## Authority Boundary + +- Approval is explicit and human-issued through `HumanDecision` records. +- Report verification is custody/integrity evidence, not completion proof. +- File and CLI transport can carry schema-valid artifacts without granting + approval authority. + ## Schema Index - [task-packet.schema.json](task-packet.schema.json) diff --git a/schemas/examples/README.md b/schemas/examples/README.md index 50df7a7..ccb29e0 100644 --- a/schemas/examples/README.md +++ b/schemas/examples/README.md @@ -16,6 +16,7 @@ runtime instructions. - whether expected-valid and expected-invalid outcomes match manifest declarations when manifest-mode checking runs; - whether artifact vocabulary and basic structure are machine-checkable. +- whether custody artifacts can be validated as records. ## What Fixtures Do Not Prove @@ -23,6 +24,7 @@ runtime instructions. - autonomous dispatch or execution authority; - human approval, merge, deploy, or risk acceptance decisions; - cross-vendor interoperability by themselves. +- task completion proof by report presence or verification. ## Validation Flow @@ -42,3 +44,6 @@ Expected exit-code behavior: Validation output is evidence for review. It is not approval and does not grant execution authority. + +File and CLI transport can move these fixtures, but transport success does not +grant authority and does not replace human decision. From 28d6d693a24d1a343b568797553b84b1c6214929 Mon Sep 17 00:00:00 2001 From: Joe Feser Date: Tue, 26 May 2026 09:39:45 -0500 Subject: [PATCH 2/3] docs: align lifecycle framing and bridge examples with repo vocabulary --- README.md | 3 ++- docs/adapters-and-projections.md | 6 +++--- docs/event-lifecycle.md | 9 +++++++++ docs/glossary.md | 12 ++++++++++-- docs/workflows/owner-controlled-bridge.md | 13 ++++++++----- 5 files changed, 32 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index d909150..83685e3 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,8 @@ scope. ## Public Protocol Framing -HACP is a vendor-neutral human-approved coordination protocol. It defines +HACP is a human-approved coordination protocol with a vendor-neutral contract +design goal. It defines packet, report, evidence, decision, stop, and audit contracts for accountable AI-assisted workflows. diff --git a/docs/adapters-and-projections.md b/docs/adapters-and-projections.md index 2bf5f7b..27b0804 100644 --- a/docs/adapters-and-projections.md +++ b/docs/adapters-and-projections.md @@ -10,10 +10,10 @@ models never replace those checkpoints. ## Adapter Examples (Transport Paths) -- `npx hacp` CLI commands +- implementation CLI commands (for example, owner/operator tooling) - file drop/push transport - RabbitMQ adapter -- MCP adapter +- Model Context Protocol (MCP) adapter - webhook adapters Each adapter may move packets, reports, evidence, and receipts. None of them @@ -21,7 +21,7 @@ approves risky transitions. ## Projection Examples (Read Models) -- OTEL projections +- OpenTelemetry (OTel) projections - dashboard/reporting projections - derived lifecycle summaries diff --git a/docs/event-lifecycle.md b/docs/event-lifecycle.md index 23817d3..e587c26 100644 --- a/docs/event-lifecycle.md +++ b/docs/event-lifecycle.md @@ -3,6 +3,10 @@ This page summarizes public draft lifecycle events for packet custody, report custody, and explicit authority decisions. +These lifecycle labels are public-facing projection labels. They are not a +replacement for base RFC audit `event_type` values or base decision-matrix +status values. + ## Packet Lifecycle - `packet.received` @@ -23,6 +27,11 @@ custody, and explicit authority decisions. ## Boundary Notes +- Base audit `event_type` vocabulary remains in + [RFC-0007](../rfcs/0007-audit-trail-and-evidence-set.md). +- Base status vocabulary remains in + [decision-matrix-base-v0.1.yaml](../decision-matrix-base-v0.1.yaml), + including `needs_human_decision`. - `report.import_verifier_checked` confirms custody/integrity checks only. - Verification state is not completion proof. - Risky transitions require explicit `HumanDecision`. diff --git a/docs/glossary.md b/docs/glossary.md index b5ef29d..f44e2aa 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -9,7 +9,8 @@ authority boundaries. - `AgentReport`: execution/output record returned for review and import. - `EvidenceSet`: references and artifacts used to justify report claims. - `HumanDecision`: explicit approve/reject/defer authority checkpoint. -- `StopReason`: typed reason that continuation stopped or was rejected. +- `StopResponse`: typed record indicating why continuation stopped or was + rejected (with `stop_reason` as the typed reason field). - `Receipt`: custody/readback marker for import/verification steps. - `AuditEvent`: immutable event record for lifecycle and authority traceability. @@ -25,10 +26,17 @@ authority boundaries. - `stopped`: execution path halted under explicit stop semantics. - `rejected`: decision or result rejected with typed rationale. +These lifecycle labels are projection-oriented terms for public framing. Base +audit `event_type` vocabulary remains defined in +[RFC-0007](../rfcs/0007-audit-trail-and-evidence-set.md), and base status +vocabulary remains defined in +[decision-matrix-base-v0.1.yaml](../decision-matrix-base-v0.1.yaml). + ## Boundary Terms - `authority boundary`: rule defining who can approve risky transitions. - `transport-neutral`: contract does not depend on one transport mechanism. - `owner-controlled`: execution boundary stays under owner/operator control. - `adapter`: implementation path carrying records without granting authority. -- `projection`: derived read model (for example OTEL), not source authority. +- `projection`: derived read model (for example OpenTelemetry/OTel), not source + authority. diff --git a/docs/workflows/owner-controlled-bridge.md b/docs/workflows/owner-controlled-bridge.md index 3ff5925..a435165 100644 --- a/docs/workflows/owner-controlled-bridge.md +++ b/docs/workflows/owner-controlled-bridge.md @@ -11,16 +11,19 @@ while HACP records packet/report/evidence/decision custody. 4. Runner returns an `AgentReport` with an `EvidenceSet`. 5. Import verifier checks custody/integrity and emits receipt/audit events. 6. Workflow enters `human_decision_required`. -7. Human records a `HumanDecision` or a `StopReason`. +7. Human records a `HumanDecision` or a `StopResponse`. ## Example Bridge Paths -CLI: +Illustrative CLI shape only. This repository does not ship these commands; it +ships `npm run hacp:doctor` for local schema/fixture validation. + +CLI example: ```bash -npx hacp packet fetch --packet-id pkt_example_001 --out packet.json -npx hacp runner execute --packet packet.json --command "npm run test:unit" --out report.json -npx hacp report submit --packet packet.json --report report.json + packet fetch --packet-id pkt_example_001 --out packet.json + runner execute --packet packet.json --command "npm run test:unit" --out report.json + report submit --packet packet.json --report report.json ``` File transport: From cda53d932908c3a920c824659ce8a77da8ccb7c8 Mon Sep 17 00:00:00 2001 From: Joe Feser Date: Tue, 26 May 2026 09:40:20 -0500 Subject: [PATCH 3/3] docs: clarify stop-response and base status mapping --- docs/authority-boundaries.md | 2 +- docs/event-lifecycle.md | 3 ++- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/authority-boundaries.md b/docs/authority-boundaries.md index eddcc25..34bdd7c 100644 --- a/docs/authority-boundaries.md +++ b/docs/authority-boundaries.md @@ -25,5 +25,5 @@ keeping the same authority contracts: - `TaskPacket` defines bounded intent and constraints. - `AgentReport` and `EvidenceSet` provide reviewable claims. - `HumanDecision` records approval/rejection/defer outcomes. -- `StopReason` records why continuation halted. +- `StopResponse` records why continuation halted (with a typed `stop_reason`). - `AuditEvent` and `Receipt` preserve custody traceability. diff --git a/docs/event-lifecycle.md b/docs/event-lifecycle.md index e587c26..74b3126 100644 --- a/docs/event-lifecycle.md +++ b/docs/event-lifecycle.md @@ -21,7 +21,8 @@ status values. ## Decision And Stop Lifecycle -- `human_decision_required` +- `human_decision_required` (projection label; base status is + `needs_human_decision`) - `stopped` - `rejected`