Phase 260: apply public HACP protocol docs packet

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

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.

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.

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`.

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.

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
+<implementation-cli> packet fetch --packet-id pkt_example_001 --out packet.json
+<implementation-cli> runner execute --packet packet.json --command "npm run test:unit" --out report.json
+<implementation-cli> 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.

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)

schemas/examples/README.md

@@ -16,13 +16,15 @@ 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
 
 - production safety certification;
 - 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.