Epiphany/notes/hands-cultnet-contracts.md

Hands CultNet Contracts

Objective: make Hands the action organ. Commands, patches, and commits are consequences, not thoughts. They enter as bounded action intents and leave receipts that can be verified or admitted into Mind state.

Authority Map

• Owner: Hands owns execution of bounded actions.
• Inputs: typed action intents, Substrate Gate access grants, requested commands or patches, current repo policy, Soul verification requirements, and coordinator authority.
• Outputs: Hands action reviews, command receipts, patch receipts, commit receipts, and action refusal receipts.
• Derived state: diffs, command logs, and commits are action receipts. They are not durable Mind state until Mind admits them.
• Forbidden writers: raw workers, Persona, Eyes, Imagination, Self, compatibility JSON-RPC routes, and bridge tools must not execute repo-affecting commands, edit files, commit, or publish without the Hands path after Body access.
• Shared path: file edits, shell commands, and commits share Hands action intent/review/receipt semantics.
• Deletion line: Substrate Gate grants access; it does not execute. Soul verifies; it does not execute. Mind records durable state; it does not execute.

Contract Families

• epiphany.hands.action_intent: request for bounded action.
• epiphany.hands.action_review: Hands decision and execution plan.
• epiphany.hands.command_receipt: proof of command execution.
• epiphany.hands.patch_receipt: proof of file mutation.
• epiphany.hands.commit_receipt: proof of commit creation.
• epiphany.hands.action_refusal_receipt: proof that Hands refused to act.

Neighboring Gates

Substrate Gate grants substrate access before Hands touches the repo. Hands consumes the adopted plan and exact current route directly. Eyes is requested only when that reasoning needs evidence outside the Body. Soul verifies action results and invariants. Mind admits durable state after the action and verification receipts exist.

Hands is not a permission organ. It is the actuator. The wrench does not bless itself.

Pull-request or other remote publication is not an Epiphany-owned Hands receipt. The remote provider/Bifrost crossing owns its exact publication evidence; Epiphany may consume that provider-owned receipt after the local commit exists.

Executable Slice

The first runtime-spine proof chain now exists:

HandsActionIntent
-> HandsActionReview
-> HandsPatchReceipt
-> HandsCommandReceipt
-> HandsCommitReceipt

epiphany-core::hands_gateway owns the typed document bodies and constructors. epiphany-core::runtime_spine can persist and reread the intent, review, patch, command, and commit receipts from the runtime-spine CultCache store. The launch organ contract's repo-action proof profile now requires the full Hands chain, not only the final patch receipt. epiphany-mvp-coordinator now turns continueImplementation into a persisted Substrate Gate grant plus Hands intent/review gate and exposes the receipt ids in the operator step. epiphany-hands-action is the first native consequence recorder for that gate: record-patch, record-command, and record-commit load the stored intent/review, reject mismatches, require an approved review, enforce allowed operations, and keep patch/commit changed paths inside the requested scope. Focused epiphany-hands-action tests prove that the live packaged recorder refuses wrong authority, scope escape, and substituted consequence cargo. The separate main-only smoke executables were deleted; they were compiled by Cargo but did not participate in the Rust test harness.