Phase 896/897 HACP Repo Exact Docs/Examples Edit

[joefeser]

Source Approval

This PR applies the exact HACP repo docs/examples edit approved by what-is-the-spec Phase 894/895.

Source gate verified before editing:

• what-is-the-spec origin/dev includes Phase 894/895 PR #565 commit e2e7eb6b.
• Phase 894/895 records decision token hacp_repo_exact_docs_examples_edit_approval_gate_ready.
• Selected decision: approve_future_hacp_repo_exact_docs_examples_edit_phase_from_update_packet.
• Approved future phase type: hacp_repo_exact_docs_examples_edit_only.
• Approved future target repo: joefeser/hacp.
• Approved target path count: 7, exclusive list.
• Phase 892/893 records source packet token hacp_repo_docs_examples_update_packet_from_alignment_scoping_ready with proposed paths, excerpts/source material, non-claims wording, and validation checklist.

Changed Paths

• docs/examples/manual-approved-loop-v0/evidence-chain.md
• docs/examples/manual-approved-loop-v0/human-decision-gate.md
• docs/examples/manual-approved-loop-v0/bounded-action-report.md
• docs/examples/manual-approved-loop-v0/no-retry-no-autonomous-continuation.md
• docs/examples/manual-approved-loop-v0/docs-backed-product-readback.md
• docs/concepts/proof-is-evidence-not-approval.md
• docs/concepts/manual-loop-is-not-runtime-transport-self-running.md

Boundary Summary

• Proof is evidence, not approval.
• Human decision records approve consequential next steps.
• Manual approved-loop evidence is not runtime, transport, self-running, production, compliance, certification, product-completion, loop-completion, or formal-standardization evidence.
• The examples preserve first local manual attempt report count 1, later follow-up action report count 1, retry count 0, second attempt count 0, autonomous continuation count 0, transport/runtime count 0, durable persistence count 0, hosted shell count for bounded action 0, and model/tool-call count for bounded action 0.
• No schema changes, protocol semantics changes, README rewrite, runtime, transport, HTTP hooks, RabbitMQ, watcher/polling, durable persistence, hosted shell, model/tool calls, retry, second attempt, or autonomous continuation are introduced.

Validation

• npm run hacp:doctor: command requires an explicit input path in this repo and exits with Missing path; target-specific doctor checks below were run.
• npm run hacp:doctor -- schemas/examples --manifest schemas/examples/manifest.json: passed, 15 expected-valid and 9 expected-invalid.
• npm run hacp:doctor -- schemas/examples/valid: passed.
• npm run hacp:cli-bridge-examples: passed for 8 files.
• git diff --cached --check: passed before commit.
• Markdown link check over the seven approved files: passed.
• Kiro Opus 4.8 doc review: no blocking findings; one informational clarity note fixed before commit.
• Kiro Sonnet 4.6 implementation/doc review: link/navigation findings resolved before commit.

Note

Add HACP concept and example docs for manual approved-loop evidence boundaries

Adds seven documentation files under docs/concepts/ and docs/examples/manual-approved-loop-v0/ to clarify what manual approved-loop evidence does and does not represent.

• Two concept docs (manual-loop-is-not-runtime-transport-self-running.md and proof-is-evidence-not-approval.md) define approval boundaries and explicitly list non-claims (not production, compliance, certification, or standardization evidence).
• Five example docs cover the full manual-approved-loop v0 chain: bounded action report, evidence chain, human decision gate, readback summary, and a no-retry/no-autonomous-continuation boundary statement.
• All documents emphasize that retry, continuation, runtime, transport, and model/tool call counters remain at zero unless separately approved.

^{Macroscope summarized e106130.}

Summary by CodeRabbit

• Documentation
  • Added comprehensive documentation for the manual approved-loop v0 framework, including concept definitions, workflow examples, and structured decision-gate specifications.
  • Clarified distinctions between proof/evidence and approval requirements.
  • Added bounded action report and product readback documentation with schema examples.
  • Documented evidence-chain definitions and boundary constraints.

[sourcery-ai]

Sorry @joefeser, you have reached your weekly rate limit of 1500000 diff characters.

Please try again later or upgrade to continue using Sourcery

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0) 🎨 UX issues (0) 🔗 Cross-repo conflicts (0)

1. Schema-inconsistent YAML examples ✓ Resolved 🐞 Bug ≡ Correctness

Description

The new manual-approved-loop docs present YAML blocks that look like copy/paste-able HACP artifacts
but use a different structure/vocabulary (e.g., nested decision_gate: / bounded_action_report:
and non-schema fields), diverging from the repo’s existing schema-aligned examples. This can mislead
implementers into producing artifacts that won’t validate against the published schemas.

Code

docs/examples/manual-approved-loop-v0/human-decision-gate.md[R10-38]

+## Decision Record Shape
+
+```yaml
+decision_gate:
+  decision_id: hdg_manual_loop_v0_example
+  selected_decision: approve_bounded_docs_followup
+  approved_next_step:
+    description: "Apply the approved documentation-only follow-up."
+    scope:
+      - "Use the reviewed evidence chain."
+      - "Edit only the approved documentation paths."
+  denied_authority:
+    - runtime execution
+    - transport dispatch
+    - retry
+    - second attempt
+    - autonomous continuation
+    - production readiness claim
+    - compliance claim
+    - certification claim
+    - formal standardization claim
+  evidence_refs:
+    - bounded_action_report_manual_loop_v0
+    - docs_backed_product_readback_manual_loop_v0
+  requires_separate_future_approval:
+    - any runtime, transport, or self-running implementation
+    - any schema or protocol semantics change
+    - any production, compliance, certification, or standardization claim
+```

Evidence

Existing repo examples and schemas define HACP records as top-level objects with required fields
like hacp_version and record_kind, but the new docs’ YAML blocks use nested wrapper keys and
different field names, creating an inconsistent and potentially misleading example format.

docs/examples/manual-approved-loop-v0/human-decision-gate.md[10-38]
docs/examples/manual-approved-loop-v0/bounded-action-report.md[9-34]
examples/minimal-v0.1/decision-approve.md[3-22]
schemas/human-decision.schema.json[8-33]
schemas/agent-report.schema.json[8-29]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
The new docs/examples YAML snippets are formatted as if they represent real HACP records, but they don’t match the schema-backed record shapes used elsewhere in the repository (missing `hacp_version`, `record_kind`, etc., and introducing nested wrapper keys / different field names). This risks readers copying invalid shapes into schema-validated artifacts.

### Issue Context
The repo already contains schema-aligned YAML examples under `examples/minimal-v0.1/` and JSON Schemas under `schemas/`.

### Fix Focus Areas
- docs/examples/manual-approved-loop-v0/human-decision-gate.md[10-38]
- docs/examples/manual-approved-loop-v0/bounded-action-report.md[9-34]

### Expected fix
Do one of:
1) Update these YAML blocks to match the schema-backed shapes/vocabulary (top-level fields, `hacp_version`, `record_kind`, etc.), OR
2) Add an explicit note immediately above each YAML block that it is illustrative/pseudocode and not schema-valid, and avoid using schema-reserved names like “Human Decision Gate” for a different shape without clarification.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Broken evidence ref IDs ✓ Resolved 🐞 Bug ≡ Correctness

Description

The human decision gate example’s evidence_refs values don’t correspond to IDs defined in the
related bounded action report/readback examples, so a reader cannot resolve the referenced evidence
artifacts. This undermines the “evidence chain” traceability the example set is trying to
demonstrate.

Code

docs/examples/manual-approved-loop-v0/human-decision-gate.md[R31-34]

+  evidence_refs:
+    - bounded_action_report_manual_loop_v0
+    - docs_backed_product_readback_manual_loop_v0
+  requires_separate_future_approval:

Evidence

The decision gate references bounded_action_report_manual_loop_v0 and
docs_backed_product_readback_manual_loop_v0, but the bounded action report uses a different
report_id, and the readback example defines no ID to reference.

docs/examples/manual-approved-loop-v0/human-decision-gate.md[31-34]
docs/examples/manual-approved-loop-v0/bounded-action-report.md[9-13]
docs/examples/manual-approved-loop-v0/docs-backed-product-readback.md[1-18]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
`evidence_refs` in the human decision gate example points to identifiers that are not defined in the linked example files, making the chain non-followable.

### Issue Context
The bounded action report example defines `report_id: bar_manual_loop_v0_example`, while the decision gate references `bounded_action_report_manual_loop_v0`.

### Fix Focus Areas
- docs/examples/manual-approved-loop-v0/human-decision-gate.md[31-37]
- docs/examples/manual-approved-loop-v0/bounded-action-report.md[9-13]
- docs/examples/manual-approved-loop-v0/docs-backed-product-readback.md[1-18]

### Expected fix
Either:
- Change `evidence_refs` values to match the actual IDs present in the related examples (e.g., reference `bar_manual_loop_v0_example`), and/or
- Add explicit IDs in the readback example so it can be referenced consistently.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

[coderabbitai]

📝 Walkthrough

Walkthrough

Seven documentation pages were added: two foundational concept pages defining what proof/evidence and manual approved-loop evidence do and do not represent, and five example documentation pages that define the Manual Approved-Loop v0 workflow including the evidence chain, human decision gate schema, bounded action report structure, a complete readback trace, and explicit no-retry continuation constraints.

Changes

Manual Approved-Loop v0 and Authority Boundaries

Layer / File(s)	Summary
Proof-Evidence and Manual-Loop Scope Boundaries docs/concepts/proof-is-evidence-not-approval.md, docs/concepts/manual-loop-is-not-runtime-transport-self-running.md	Two concept pages establish that proof/evidence artifacts do not constitute approval and that manual approved-loop evidence does not demonstrate runtime execution, transport dispatch, HTTP/RabbitMQ hooks, durable persistence, or hosted shell/model/tool calls; both pages specify counter boundaries and cross-reference related examples.
Manual Approved-Loop v0 Evidence Chain docs/examples/manual-approved-loop-v0/evidence-chain.md	Defines the complete v0 workflow from human-approved bounded task packet → bounded action report → human decision gate → optional follow-up report → final gate; clarifies the flow is documentation-only evidence with all retry, autonomous, transport, and persistence counts at 0.
Workflow Artifacts: Human Decision Gate and Bounded Action Report docs/examples/manual-approved-loop-v0/human-decision-gate.md, docs/examples/manual-approved-loop-v0/bounded-action-report.md	Defines the YAML schema for human decision gates (identifier, selected decision, approved next step with constraints, denied authority items, evidence references, and areas requiring separate approval) and bounded action reports (approved scope, completed items, not performed, requested next state); both clarify that evidence does not authorize the next step.
Workflow Scenarios and Continuation Constraints docs/examples/manual-approved-loop-v0/docs-backed-product-readback.md, docs/examples/manual-approved-loop-v0/no-retry-no-autonomous-continuation.md	Documents two manual-loop scenarios: a full readback trace with preserved zero counts and explicit non-claims about broader completion/readiness/compliance, and a no-retry variant specifying that the loop terminates after the bounded action report with required explicit human decision approval for any continuation.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

Possibly related PRs

• joefeser/hacp#28: Documents approval/authority boundaries where profiles and digests do not grant approval or authority.
• joefeser/hacp#26: Establishes evidence/proof and evidence-import boundaries, clarifying that evidence is not authorization or runtime approval.
• joefeser/hacp#23: Introduces authority-boundary and event-lifecycle workflow framing that aligns with the proof/evidence/approval separation added here.

Poem

🐰 A loop approved by humans, not machines,
Reports what happened in the bounded scene,
No runtime tricks, no auto-advance schemes—
Just evidence returned to the decision dream! 🎀

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Title check	❓ Inconclusive	The title 'Phase 896/897 HACP Repo Exact Docs/Examples Edit' is vague and overly generic, using phase numbers and abbreviated terminology that provide minimal insight into what the changeset actually accomplishes.	Replace with a more descriptive title that clearly conveys the main documentation change, such as 'Add HACP manual approved-loop concept docs and examples clarifying evidence boundaries.'

✅ Passed checks (4 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description check	✅ Passed	The pull request description comprehensively covers all required sections with specific source approval details, boundary summary, changed paths, and validation results.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/phase-896-897-hacp-repo-exact-docs-examples-edit

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[joefeser]

@codex review

[qodo-code-review]

PR Summary by Qodo

Add manual approved-loop docs clarifying evidence vs approval boundaries
📝 Documentation 🕐 10-20 Minutes

Walkthroughs

Description

• Add manual approved-loop v0 example docs describing human approval boundaries.
• Clarify non-claims: no runtime/transport/self-running, retries, persistence, or tooling.
• Cross-link concept pages and examples for consistent navigation and framing.

Diagram

graph TD
  P["Proof != approval"] --> EC["Evidence chain"] --> BAR["Bounded action report"] --> HDG["Human decision gate"]
  EC --> DR["Docs-backed readback"] --> HDG
  EC --> NR["No retry/continuation"]
  ML["Manual loop not runtime"] --> EC
  ML --> NR

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Consolidate into a single “manual approved-loop v0” page

• ➕ Fewer files to navigate and maintain
• ➕ Readers get a single canonical narrative with embedded artifacts
• ➖ Harder to deep-link specific concepts (proof vs approval, decision gate shape, counters)
• ➖ Larger page can reduce scannability and reuse across future versions

2. Define these artifacts as formal schemas first (then generate docs)

• ➕ Enforces structure/validation for decision records and reports
• ➕ Reduces ambiguity by making fields and constraints explicit
• ➖ Higher scope/risk and likely needs governance/compatibility decisions
• ➖ Not aligned with a docs-only change boundary

Recommendation: Keep the PR’s current approach (separate concept pages + example artifacts) because it cleanly separates normative boundary language from illustrative examples and supports precise cross-linking. Consolidation could be revisited later, but would be a structural rewrite beyond a tightly-scoped, docs-only edit.

File Changes

Documentation (7)

manual-loop-is-not-runtime-transport-self-running.md Add concept page clarifying manual loop is not runtime/transport evidence +44/-0

Add concept page clarifying manual loop is not runtime/transport evidence

• Introduces a concept page defining what the manual approved-loop example can and cannot demonstrate. Enumerates explicit non-claims (runtime, transport, retries, persistence, tooling) and links to related example artifacts.

docs/concepts/manual-loop-is-not-runtime-transport-self-running.md

---

proof-is-evidence-not-approval.md Add concept page distinguishing proof/evidence from approval authority +29/-0

Add concept page distinguishing proof/evidence from approval authority

• Adds a concise statement that proof is evidence and does not authorize expanded scope or new work lanes. Documents an approval boundary list, non-claims, and links into the manual-loop example set.

docs/concepts/proof-is-evidence-not-approval.md

---

bounded-action-report.md Add bounded action report example artifact and non-performed actions +45/-0

Add bounded action report example artifact and non-performed actions

• Adds a YAML example for a bounded action report including approved scope, completed items, and a detailed not-performed list (runtime/transport/hooks/retries/etc.). Reinforces that reports support review but do not approve next actions.

docs/examples/manual-approved-loop-v0/bounded-action-report.md

---

docs-backed-product-readback.md Add docs-backed readback summarizing chain and preserved counts +38/-0

Add docs-backed readback summarizing chain and preserved counts

• Introduces a narrative readback describing the chain’s start, approvals, produced artifacts, and explicit non-claims. Includes a table of preserved counters (attempts, retries, runtime/transport, persistence, hosted shell, tool calls).

docs/examples/manual-approved-loop-v0/docs-backed-product-readback.md

---

evidence-chain.md Add manual approved-loop v0 evidence chain and counter boundaries +42/-0

Add manual approved-loop v0 evidence chain and counter boundaries

• Adds an end-to-end chain description from human-approved task packet through bounded action reporting and return to a decision gate. Provides a preserved counter table and cross-links to the related artifacts and concepts.

docs/examples/manual-approved-loop-v0/evidence-chain.md

---

human-decision-gate.md Add decision gate record shape and denied authority list +50/-0

Add decision gate record shape and denied authority list

• Introduces a YAML decision record shape capturing the selected decision, approved next step, denied authority, and evidence references. Explicitly states that only the human decision record approves consequential next steps.

docs/examples/manual-approved-loop-v0/human-decision-gate.md

---

no-retry-no-autonomous-continuation.md Add stop rule and boundary counters preventing retries/continuations +35/-0

Add stop rule and boundary counters preventing retries/continuations

• Documents boundary counters (retry/second attempt/autonomous continuation/transport-runtime/etc.) remaining at zero absent explicit human approval. States the stop rule after creating a bounded action report and enumerates excluded behaviors (hooks, messaging, polling, persistence, hosted shell, tool calls).

docs/examples/manual-approved-loop-v0/no-retry-no-autonomous-continuation.md

---

[gemini-code-assist]

Code Review

This pull request introduces documentation and examples for the 'Manual Approved-Loop v0' concept, establishing clear boundaries between manual loop evidence and actual runtime or transport execution. The feedback focuses on aligning the example YAML configurations with standard HACP/RFC-0005 vocabulary and ensuring internal identifier consistency, such as correcting mismatched report IDs, decision types, and state fields.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Another round soon, please!

Reviewed commit: f57a1383c8

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".