Add spec-aware orch tasks and verification gates

docs/orch-cli.md

@@ -2,7 +2,7 @@
 
 ## Purpose
 
-`orch` is the leader-facing scheduler and control plane. It owns the run, task graph, dependencies, ready queue, dispatch decisions, retries, and reassignment logic.
+`orch` is the leader-facing scheduler and control plane. It owns the run, task graph, task specs, dependencies, verification gates, ready queue, dispatch decisions, retries, and reassignment logic.
 
 `orch` does not replace `inbox`. It uses `inbox` as the durable transport and execution record.
 
@@ -20,10 +20,12 @@ In normal operation:
 
 - creating a run for one user request or project
 - defining tasks and dependencies
+- snapshotting task specs and per-task verification policy
 - calculating which tasks are ready
 - dispatching ready tasks to workers
 - tracking attempts and mapping them to inbox threads
 - allocating attempt worktrees for code tasks
+- aggregating post-implementation check results into a task verification gate
 - surfacing blocked tasks to the leader
 - sending answers back into the active inbox thread
 - reconciling thread state into task state
@@ -71,6 +73,7 @@ See [worktree-execution.md](/home/kurihada/project/ai-workflow-skill/docs/worktr
 - `dispatched`: an inbox thread exists but the worker has not started yet
 - `running`: the task has been claimed and is actively executing
 - `blocked`: the active attempt needs clarification or an external dependency
+- `verifying`: the worker reported completion, but required verification checks have not all passed yet
 - `done`: task completed and passed its current acceptance gate
 - `failed`: task completed unsuccessfully
 - `cancelled`: task was cancelled and should not continue
@@ -82,7 +85,10 @@ Suggested transitions:
 - `dispatched -> running`
 - `running -> blocked`
 - `blocked -> running`
-- `running -> done`
+- `running -> verifying` when the worker reports `done` and the task has required checks
+- `running -> done` when the worker reports `done` and the task has no required checks
+- `verifying -> done`
+- `verifying -> failed`
 - `running -> failed`
 - `failed -> ready` through explicit retry
 - `* -> cancelled` by leader action
@@ -97,12 +103,13 @@ The normal leader loop is:
 4. inspect `ready`
 5. `dispatch` tasks
 6. arrange or launch a separate worker runtime that consumes the assigned inbox threads
-7. use `status` for the current operational view; it reconciles first and includes latest attempt and message context
-8. inspect `blocked`
-9. answer blocked questions
-10. if nothing is actionable, call `wait`
-11. retry or reassign failures when needed
-12. finish when all required tasks are `done`
+7. use `status` for the current operational view; it reconciles first and includes latest attempt, message, and gate context
+8. if a task enters `verifying`, record check results with `verify record` and inspect gate state with `verify status`
+9. inspect `blocked`
+10. answer blocked questions
+11. if nothing is actionable, call `wait`
+12. retry or reassign failures when needed
+13. finish when all required tasks are `done`
 
 The leader should block on `orch wait`, not on ad hoc `sleep`.
 
@@ -162,6 +169,13 @@ Suggested flags:
 - `--default-to AGENT`
 - `--acceptance-json STRING`
 - `--priority low|normal|high`
+- `--spec-file PATH`
+- `--spec-sha SHA256`
+- `--check-profile NAME`
+- `--required-check NAME` repeatable
+- `--allowed-path PATH` repeatable
+- `--blocked-path PATH` repeatable
+- `--metadata-json STRING`
 
 ### `orch dep add`
 
@@ -207,7 +221,7 @@ Behavior:
 - in `code` mode, resolves a committed base revision
 - in `code` mode, creates a branch and worktree for the attempt
 - creates or links an `inbox` thread
-- writes `execution_mode` into the inbox task payload and writes workspace metadata for code tasks into attempt storage and task payload
+- writes `execution_mode` into the inbox task payload, includes the task spec snapshot and verification policy in the dispatch payload, and writes workspace metadata for code tasks into attempt storage and task payload
 - moves the task to `dispatched`
 - does not start a worker runtime on its own
 
@@ -235,7 +249,8 @@ Behavior:
 
 - maps inbox `claimed` or `in_progress` to `running`
 - maps inbox `blocked` to `blocked`
-- maps inbox `done` to `done`
+- maps inbox `done` to `verifying` when the task has required checks
+- maps inbox `done` to `done` when the task has no required checks
 - maps inbox `failed` to `failed`
 
 ### `orch blocked`
@@ -246,6 +261,47 @@ Suggested flags:
 
 - `--run RUN_ID`
 
+### `orch verify record`
+
+Record or update one verification check result for the latest task attempt.
+
+Suggested flags:
+
+- `--run RUN_ID`
+- `--task TASK_ID`
+- `--attempt N` optional; defaults to latest
+- `--check NAME`
+- `--status passed|failed|skipped`
+- `--summary TEXT`
+- `--body TEXT`
+- `--body-file PATH`
+- `--metadata-json STRING`
+- `--recorded-by NAME`
+
+Behavior:
+
+- upserts one named check result for the selected attempt
+- emits a verification-recorded event
+- recomputes the gate for the task
+- keeps the task in `verifying` while required checks are still pending
+- moves the task to `done` when all required checks pass
+- moves the task to `failed` when one or more required checks fail
+
+### `orch verify status`
+
+Show the current verification state for one task.
+
+Suggested flags:
+
+- `--run RUN_ID`
+- `--task TASK_ID`
+- `--attempt N` optional; defaults to latest
+
+Behavior:
+
+- returns the task, selected attempt, task spec snapshot, and current gate state
+- helps the leader inspect which required checks are still pending or failed
+
 ### `orch wait`
 
 Block until one or more run-scoped events become available.