diff --git a/README.md b/README.md index 15564af..83685e3 100644 --- a/README.md +++ b/README.md @@ -13,6 +13,44 @@ 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 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. + +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..27b0804 --- /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) + +- implementation CLI commands (for example, owner/operator tooling) +- file drop/push transport +- RabbitMQ adapter +- Model Context Protocol (MCP) adapter +- webhook adapters + +Each adapter may move packets, reports, evidence, and receipts. None of them +approves risky transitions. + +## Projection Examples (Read Models) + +- OpenTelemetry (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..34bdd7c --- /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. +- `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 new file mode 100644 index 0000000..74b3126 --- /dev/null +++ b/docs/event-lifecycle.md @@ -0,0 +1,38 @@ +# HACP Event Lifecycle + +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` +- `packet.exported` +- `packet.validated` + +## Report Lifecycle + +- `report.built` +- `report.ready_for_import` +- `report.import_verifier_checked` + +## Decision And Stop Lifecycle + +- `human_decision_required` (projection label; base status is + `needs_human_decision`) +- `stopped` +- `rejected` + +## 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 new file mode 100644 index 0000000..f44e2aa --- /dev/null +++ b/docs/glossary.md @@ -0,0 +1,42 @@ +# 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. +- `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. + +## 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. + +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 OpenTelemetry/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..a435165 --- /dev/null +++ b/docs/workflows/owner-controlled-bridge.md @@ -0,0 +1,41 @@ +# 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 `StopResponse`. + +## Example Bridge Paths + +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 + 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: + +```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.