docs: define structured execution note contract

.config/opencode/AGENTS.md

@@ -82,10 +82,96 @@ Memory uses one persistent system: **basic-memory**.
 - `project/workflows` - local dev, build, test, release commands
 - `project/testing` - verification entrypoints and expectations
 - `plans/<slug>` - canonical specs with `Status: draft|approved|blocked|done`
-- `executions/<slug>` - execution log with `Status: in_progress|blocked|done`
+- `executions/<slug>` - structured execution log with `Status: in_progress|blocked|done` (see template below)
 - `decisions/<slug>` - durable project-specific decisions
 - `findings/<slug>` - open findings ledger with evidence and owner
 
+### Execution note template (`executions/<slug>`)
+
+Every execution note must use these literal section names:
+
+```
+## Plan
+- **Source:** plans/<slug>
+- **Status:** approved
+
+## Execution State
+- **Objective:** <one-line goal from the plan>
+- **Current Phase:** <planning|implementing|integrating|verifying|blocked|done>
+- **Next Checkpoint:** <next concrete step>
+- **Blockers:** <none|bullet-friendly summary>
+- **Last Updated By:** <builder|coder|tester|reviewer|librarian>
+- **Legacy Note Normalized:** <yes|no>
+
+## Lane Claims
+Repeated per lane:
+
+### Lane: <lane-name>
+- **Owner:** <builder|coder|tester|reviewer|librarian|unassigned>
+- **Status:** planned | active | released | blocked | done
+- **Claimed Files/Areas:** <paths or named workflow surfaces>
+- **Depends On:** <none|lane names>
+- **Exit Condition:** <what must be true to release or complete this lane>
+
+## Last Verified State
+- **Mode:** none | smoke | full
+- **Summary:** <one-sentence status>
+- **Outstanding Risk:** <none|brief risk>
+- **Related Ledger Entry:** <entry label|none>
+
+## Verification Ledger
+Append-only log. Each entry:
+
+### Entry: <checkpoint-or-step-label>
+- **Goal:** <what is being verified>
+- **Mode:** smoke | full
+- **Command/Check:** <exact command or manual check performed>
+- **Result:** pass | fail | blocked | not_run
+- **Key Evidence:** <concise proof: output snippet, hash, assertion count>
+- **Artifacts:** <paths to logs/screenshots, or `none`>
+- **Residual Risk:** <known gaps, or `none`>
+```
+
+#### Verification summary shape
+
+Each verification entry (in Last Verified State or Verification Ledger) uses these fields:
+
+- **Goal** - what is being verified
+- **Mode** - `smoke` or `full` (see mode rules)
+- **Command/Check** - exact command or manual check performed
+- **Result** - `pass`, `fail`, `blocked`, or `not_run`
+- **Key Evidence** - concise proof (output snippet, hash, assertion count)
+- **Artifacts** - paths to logs/screenshots if any, or `none`
+- **Residual Risk** - known gaps, or `none`
+
+#### Verification mode rules
+
+- Default to **`smoke`** for intermediate checkpoint proof and isolated lane verification.
+- Default to **`full`** before any final completion claim or setting execution status to `done`.
+- If there is only one meaningful verification step, record it as `full` and note there is no separate smoke check.
+
+#### Compact verification summary behavior
+
+- The verification ledger shape is the default evidence format for builder/tester/coder handoffs.
+- Raw logs should stay out of primary context unless a check fails or the user explicitly requests full output.
+- When raw output is necessary, summarize the failure first and then point to the raw evidence.
+
+#### Lane-claim lifecycle
+
+- **Planner** defines intended lanes and claimed files/areas in the approved plan when parallelization is expected.
+- **Builder** creates or updates lane-claim entries in the execution note before fan-out and marks them `active`, `released`, `done`, or `blocked`.
+- Overlapping claimed files/areas or sequential verification dependencies **forbid** parallel fan-out.
+- Claims are advisory markdown metadata, not hard runtime locks.
+
+#### Reviewer and execution-note ownership
+
+- `reviewer` is read-only on execution notes; it reports findings via its response message.
+- `builder` owns all execution-note writes and status transitions.
+
+#### Legacy execution notes
+
+Legacy execution notes may be freeform and lack structured sections. `/continue` must degrade gracefully — read what exists, do not invent conflicts or synthesize missing sections without evidence.
+
 ### Per-repo project setup (required)
 
 Every code repository must have its own dedicated basic-memory project.