Remove markdown test docs and document tests inline

packages/orch-runtime/internal/cli/orch/command_contracts_core_test.go

@@ -7,6 +7,7 @@ import (
 	"testing"
 )
 
+// TestOrchRunShowReturnsRunSummaryAndTaskCounts verifies orch run show returns run summary and task counts.
 func TestOrchRunShowReturnsRunSummaryAndTaskCounts(t *testing.T) {
 	t.Parallel()
 
@@ -67,6 +68,7 @@ func TestOrchRunShowReturnsRunSummaryAndTaskCounts(t *testing.T) {
 	}
 }
 
+// TestOrchRunShowRejectsMissingRun verifies orch run show rejects missing run.
 func TestOrchRunShowRejectsMissingRun(t *testing.T) {
 	t.Parallel()
 
@@ -84,6 +86,7 @@ func TestOrchRunShowRejectsMissingRun(t *testing.T) {
 	assertErrorJSON(t, stdout, "not_found")
 }
 
+// TestOrchTaskAddRejectsInvalidAcceptanceJSON verifies orch task add rejects invalid acceptance JSON.
 func TestOrchTaskAddRejectsInvalidAcceptanceJSON(t *testing.T) {
 	t.Parallel()
 
@@ -114,6 +117,7 @@ func TestOrchTaskAddRejectsInvalidAcceptanceJSON(t *testing.T) {
 	assertErrorMessageContains(t, stdout, "acceptance-json must be valid JSON")
 }
 
+// TestOrchTaskAddRejectsInvalidPriority verifies orch task add rejects invalid priority.
 func TestOrchTaskAddRejectsInvalidPriority(t *testing.T) {
 	t.Parallel()
 
@@ -144,6 +148,7 @@ func TestOrchTaskAddRejectsInvalidPriority(t *testing.T) {
 	assertErrorMessageContains(t, stdout, "priority must be one of low, normal, high")
 }
 
+// TestOrchTaskAddSnapshotsSpecAndVerificationPolicy verifies orch task add snapshots spec and verification policy.
 func TestOrchTaskAddSnapshotsSpecAndVerificationPolicy(t *testing.T) {
 	t.Parallel()
 
@@ -200,6 +205,7 @@ func TestOrchTaskAddSnapshotsSpecAndVerificationPolicy(t *testing.T) {
 	}
 }
 
+// TestOrchTaskAddRejectsSpecSHAMismatch verifies orch task add rejects spec SHA mismatch.
 func TestOrchTaskAddRejectsSpecSHAMismatch(t *testing.T) {
 	t.Parallel()
 
@@ -236,6 +242,7 @@ func TestOrchTaskAddRejectsSpecSHAMismatch(t *testing.T) {
 	assertErrorMessageContains(t, stdout, "spec-sha does not match spec-file contents")
 }
 
+// TestOrchReadyOrdersByPriorityAndRespectsLimit verifies orch ready orders by priority and respects limit.
 func TestOrchReadyOrdersByPriorityAndRespectsLimit(t *testing.T) {
 	t.Parallel()
 

packages/orch-runtime/internal/cli/orch/command_contracts_edges_test.go

@@ -5,6 +5,7 @@ import (
 	"testing"
 )
 
+// TestOrchAnswerAcceptsPayloadJSONWithoutBody verifies orch answer accepts payload JSON without body.
 func TestOrchAnswerAcceptsPayloadJSONWithoutBody(t *testing.T) {
 	t.Parallel()
 
@@ -71,6 +72,7 @@ func TestOrchAnswerAcceptsPayloadJSONWithoutBody(t *testing.T) {
 	}
 }
 
+// TestOrchAnswerRejectsEmptyBodyAndPayload verifies orch answer rejects empty body and payload.
 func TestOrchAnswerRejectsEmptyBodyAndPayload(t *testing.T) {
 	t.Parallel()
 
@@ -90,6 +92,7 @@ func TestOrchAnswerRejectsEmptyBodyAndPayload(t *testing.T) {
 	assertErrorJSON(t, stdout, "invalid_input")
 }
 
+// TestOrchCleanupRejectsAttemptWithoutTask verifies orch cleanup rejects attempt without task.
 func TestOrchCleanupRejectsAttemptWithoutTask(t *testing.T) {
 	t.Parallel()
 
@@ -117,6 +120,7 @@ func TestOrchCleanupRejectsAttemptWithoutTask(t *testing.T) {
 	assertErrorJSON(t, stdout, "invalid_input")
 }
 
+// TestOrchCleanupReturnsNoMatchingWorkWhenFiltersMiss verifies orch cleanup returns no matching work when filters miss.
 func TestOrchCleanupReturnsNoMatchingWorkWhenFiltersMiss(t *testing.T) {
 	t.Parallel()
 

packages/orch-runtime/internal/cli/orch/command_contracts_remaining_test.go

@@ -6,6 +6,7 @@ import (
 	"testing"
 )
 
+// TestOrchRunInitCreatesNewRun verifies `run init` persists a new run that `run show` can read back.
 func TestOrchRunInitCreatesNewRun(t *testing.T) {
 	t.Parallel()
 
@@ -56,6 +57,7 @@ func TestOrchRunInitCreatesNewRun(t *testing.T) {
 	}
 }
 
+// TestOrchDispatchCreatesAttemptAndThreadForReadyTask verifies `dispatch` creates the first attempt, thread, and task message for a ready task.
 func TestOrchDispatchCreatesAttemptAndThreadForReadyTask(t *testing.T) {
 	t.Parallel()
 
@@ -116,6 +118,7 @@ func TestOrchDispatchCreatesAttemptAndThreadForReadyTask(t *testing.T) {
 	}
 }
 
+// TestOrchBlockedListsLatestQuestionForBlockedTask verifies `blocked` returns the latest blocked question for a task after reconcile.
 func TestOrchBlockedListsLatestQuestionForBlockedTask(t *testing.T) {
 	t.Parallel()
 
@@ -277,6 +280,7 @@ func TestOrchBlockedListsLatestQuestionForBlockedTask(t *testing.T) {
 	}
 }
 
+// TestOrchStatusReturnsRunSummaryAndTaskList verifies `status` returns the run summary together with the current task list.
 func TestOrchStatusReturnsRunSummaryAndTaskList(t *testing.T) {
 	t.Parallel()
 
@@ -393,6 +397,7 @@ func TestOrchStatusReturnsRunSummaryAndTaskList(t *testing.T) {
 	}
 }
 
+// TestOrchStatusAutoReconcilesAndIncludesBlockedContext verifies `status` reconciles inbox state first and includes blocked context.
 func TestOrchStatusAutoReconcilesAndIncludesBlockedContext(t *testing.T) {
 	t.Parallel()
 
@@ -496,6 +501,7 @@ func TestOrchStatusAutoReconcilesAndIncludesBlockedContext(t *testing.T) {
 	}
 }
 
+// TestOrchReconcileMapsFailedThreadToTerminalTaskState verifies `reconcile` maps a failed inbox thread into the terminal task state.
 func TestOrchReconcileMapsFailedThreadToTerminalTaskState(t *testing.T) {
 	t.Parallel()
 
@@ -601,6 +607,7 @@ func TestOrchReconcileMapsFailedThreadToTerminalTaskState(t *testing.T) {
 	}
 }
 
+// TestOrchWorkflowCodeModeDispatchToCleanup verifies the code-mode workflow runs from dispatch through cleanup.
 func TestOrchWorkflowCodeModeDispatchToCleanup(t *testing.T) {
 	t.Parallel()
 
@@ -703,6 +710,7 @@ func TestOrchWorkflowCodeModeDispatchToCleanup(t *testing.T) {
 	}
 }
 
+// TestOrchWorkflowCouncilReviewEndToEnd verifies the council review workflow completes end to end.
 func TestOrchWorkflowCouncilReviewEndToEnd(t *testing.T) {
 	t.Parallel()
 

packages/orch-runtime/internal/cli/orch/council_report_contracts_test.go

@@ -7,6 +7,7 @@ import (
 	"testing"
 )
 
+// TestOrchCouncilReportRejectsBeforeTally verifies orch council report rejects before tally.
 func TestOrchCouncilReportRejectsBeforeTally(t *testing.T) {
 	t.Parallel()
 
@@ -38,6 +39,7 @@ func TestOrchCouncilReportRejectsBeforeTally(t *testing.T) {
 	}
 }
 
+// TestOrchCouncilReportRejectsInvalidShow verifies orch council report rejects invalid show.
 func TestOrchCouncilReportRejectsInvalidShow(t *testing.T) {
 	t.Parallel()
 
@@ -65,6 +67,7 @@ func TestOrchCouncilReportRejectsInvalidShow(t *testing.T) {
 	}
 }
 
+// TestOrchCouncilReportDefaultsToConsensusForOnlyUnanimousRun verifies orch council report defaults to consensus for only unanimous run.
 func TestOrchCouncilReportDefaultsToConsensusForOnlyUnanimousRun(t *testing.T) {
 	t.Parallel()
 

packages/orch-runtime/internal/cli/orch/help_contracts_test.go

@@ -5,6 +5,7 @@ import (
 	"testing"
 )
 
+// TestOrchRootHelpExplainsLeaderWorkflow verifies orch root help explains leader workflow.
 func TestOrchRootHelpExplainsLeaderWorkflow(t *testing.T) {
 	t.Parallel()
 
@@ -25,6 +26,7 @@ func TestOrchRootHelpExplainsLeaderWorkflow(t *testing.T) {
 	}
 }
 
+// TestOrchDispatchHelpExplainsExecutionModes verifies orch dispatch help explains execution modes.
 func TestOrchDispatchHelpExplainsExecutionModes(t *testing.T) {
 	t.Parallel()
 
@@ -45,6 +47,7 @@ func TestOrchDispatchHelpExplainsExecutionModes(t *testing.T) {
 	}
 }
 
+// TestOrchCouncilStartHelpExplainsWorkflow verifies orch council start help explains workflow.
 func TestOrchCouncilStartHelpExplainsWorkflow(t *testing.T) {
 	t.Parallel()
 
@@ -62,6 +65,7 @@ func TestOrchCouncilStartHelpExplainsWorkflow(t *testing.T) {
 	}
 }
 
+// TestOrchStatusHelpExplainsDashboardRole verifies orch status help explains dashboard role.
 func TestOrchStatusHelpExplainsDashboardRole(t *testing.T) {
 	t.Parallel()
 
@@ -79,6 +83,7 @@ func TestOrchStatusHelpExplainsDashboardRole(t *testing.T) {
 	}
 }
 
+// TestOrchCleanupHelpExplainsScopeFlags verifies orch cleanup help explains scope flags.
 func TestOrchCleanupHelpExplainsScopeFlags(t *testing.T) {
 	t.Parallel()
 
@@ -99,6 +104,7 @@ func TestOrchCleanupHelpExplainsScopeFlags(t *testing.T) {
 	}
 }
 
+// TestOrchVerifyHelpExplainsGateWorkflow verifies orch verify help explains gate workflow.
 func TestOrchVerifyHelpExplainsGateWorkflow(t *testing.T) {
 	t.Parallel()
 

packages/orch-runtime/internal/cli/orch/integration_test.go

@@ -10,6 +10,7 @@ import (
 	"time"
 )
 
+// TestOrchRunDispatchReconcileLifecycle verifies a task moves from ready to done through dispatch and reconcile.
 func TestOrchRunDispatchReconcileLifecycle(t *testing.T) {
 	t.Parallel()
 
@@ -183,6 +184,7 @@ func TestOrchRunDispatchReconcileLifecycle(t *testing.T) {
 	}
 }
 
+// TestOrchVerificationGateLifecycle verifies required checks keep a task gated until every required result passes.
 func TestOrchVerificationGateLifecycle(t *testing.T) {
 	t.Parallel()
 
@@ -360,6 +362,7 @@ func TestOrchVerificationGateLifecycle(t *testing.T) {
 	}
 }
 
+// TestOrchDependencyBlockedAndAnswerFlow verifies blocked dependency work resumes after the leader answers the worker question.
 func TestOrchDependencyBlockedAndAnswerFlow(t *testing.T) {
 	t.Parallel()
 
@@ -636,6 +639,7 @@ func TestOrchDependencyBlockedAndAnswerFlow(t *testing.T) {
 	}
 }
 
+// TestOrchDispatchRejectsNonReadyTask verifies `dispatch` refuses tasks that are not ready to run.
 func TestOrchDispatchRejectsNonReadyTask(t *testing.T) {
 	t.Parallel()
 
@@ -691,6 +695,7 @@ func TestOrchDispatchRejectsNonReadyTask(t *testing.T) {
 	assertErrorJSON(t, stdout, "invalid_state")
 }
 
+// TestOrchDispatchCodeModeCreatesWorktree verifies code-mode dispatch allocates and records a worktree for the attempt.
 func TestOrchDispatchCodeModeCreatesWorktree(t *testing.T) {
 	t.Parallel()
 
@@ -810,6 +815,7 @@ func TestOrchDispatchCodeModeCreatesWorktree(t *testing.T) {
 	}
 }
 
+// TestOrchDispatchCodeModeRejectsDirtyRepoWithoutBaseRef verifies code-mode dispatch rejects a dirty repo when no base ref is provided.
 func TestOrchDispatchCodeModeRejectsDirtyRepoWithoutBaseRef(t *testing.T) {
 	t.Parallel()
 
@@ -859,6 +865,7 @@ func TestOrchDispatchCodeModeRejectsDirtyRepoWithoutBaseRef(t *testing.T) {
 	}
 }
 
+// TestOrchDispatchCodeModeAllowsExplicitBaseRefOnDirtyRepo verifies code-mode dispatch accepts a dirty repo when an explicit base ref is set.
 func TestOrchDispatchCodeModeAllowsExplicitBaseRefOnDirtyRepo(t *testing.T) {
 	t.Parallel()
 
@@ -912,6 +919,7 @@ func TestOrchDispatchCodeModeAllowsExplicitBaseRefOnDirtyRepo(t *testing.T) {
 	}
 }
 
+// TestOrchDispatchRequiresExplicitExecutionMode verifies `dispatch` requires an explicit execution mode.
 func TestOrchDispatchRequiresExplicitExecutionMode(t *testing.T) {
 	dbPath := filepath.Join(t.TempDir(), "coord.db")
 
@@ -947,6 +955,7 @@ func TestOrchDispatchRequiresExplicitExecutionMode(t *testing.T) {
 	assertErrorJSON(t, stdout, "invalid_input")
 }
 
+// TestOrchDispatchAnalysisModeSkipsWorktree verifies analysis-mode dispatch skips worktree creation.
 func TestOrchDispatchAnalysisModeSkipsWorktree(t *testing.T) {
 	t.Parallel()
 
@@ -999,6 +1008,7 @@ func TestOrchDispatchAnalysisModeSkipsWorktree(t *testing.T) {
 	}
 }
 
+// TestOrchWaitWakesOnBlockedEvent verifies `wait` wakes when a blocked event is emitted for the run.
 func TestOrchWaitWakesOnBlockedEvent(t *testing.T) {
 	t.Parallel()
 
@@ -1115,6 +1125,7 @@ func TestOrchWaitWakesOnBlockedEvent(t *testing.T) {
 	}
 }
 
+// TestOrchWaitTimesOutWithoutMatchingEvent verifies `wait` times out when no matching run event arrives.
 func TestOrchWaitTimesOutWithoutMatchingEvent(t *testing.T) {
 	t.Parallel()
 
@@ -1152,6 +1163,7 @@ func TestOrchWaitTimesOutWithoutMatchingEvent(t *testing.T) {
 	}
 }
 
+// TestOrchWaitDefaultsWakeOnVerifyingEvent verifies `wait` wakes on verifying events when no explicit event filter is set.
 func TestOrchWaitDefaultsWakeOnVerifyingEvent(t *testing.T) {
 	t.Parallel()
 
@@ -1277,6 +1289,7 @@ func TestOrchWaitDefaultsWakeOnVerifyingEvent(t *testing.T) {
 	}
 }
 
+// TestOrchRetryCreatesNewAttempt verifies `retry` creates a new attempt after a failed task.
 func TestOrchRetryCreatesNewAttempt(t *testing.T) {
 	t.Parallel()
 
@@ -1375,6 +1388,7 @@ func TestOrchRetryCreatesNewAttempt(t *testing.T) {
 	}
 }
 
+// TestOrchReassignCancelsOldThreadAndDispatchesNewAttempt verifies `reassign` cancels the old thread and dispatches a replacement attempt.
 func TestOrchReassignCancelsOldThreadAndDispatchesNewAttempt(t *testing.T) {
 	t.Parallel()
 
@@ -1482,6 +1496,7 @@ func TestOrchReassignCancelsOldThreadAndDispatchesNewAttempt(t *testing.T) {
 	}
 }
 
+// TestOrchCancelTaskAndRun verifies `cancel` can stop both a single task and the whole run.
 func TestOrchCancelTaskAndRun(t *testing.T) {
 	t.Parallel()
 
@@ -1612,6 +1627,7 @@ func TestOrchCancelTaskAndRun(t *testing.T) {
 	}
 }
 
+// TestOrchCleanupRemovesCompletedWorktree verifies `cleanup` removes the worktree for a completed attempt.
 func TestOrchCleanupRemovesCompletedWorktree(t *testing.T) {
 	t.Parallel()
 
@@ -1699,6 +1715,7 @@ func TestOrchCleanupRemovesCompletedWorktree(t *testing.T) {
 	}
 }
 
+// TestOrchCouncilStartDispatchesThreeReviewers verifies `council start` dispatches three reviewer tasks.
 func TestOrchCouncilStartDispatchesThreeReviewers(t *testing.T) {
 	t.Parallel()
 
@@ -1842,6 +1859,7 @@ func TestOrchCouncilStartDispatchesThreeReviewers(t *testing.T) {
 	}
 }
 
+// TestOrchCouncilWaitWakesWhenAllReviewersComplete verifies `council wait` wakes once all reviewers finish.
 func TestOrchCouncilWaitWakesWhenAllReviewersComplete(t *testing.T) {
 	t.Parallel()
 
@@ -1975,6 +1993,7 @@ func TestOrchCouncilWaitWakesWhenAllReviewersComplete(t *testing.T) {
 	}
 }
 
+// TestOrchCouncilWaitTimesOutWhenReviewersIncomplete verifies `council wait` times out while reviewers are still incomplete.
 func TestOrchCouncilWaitTimesOutWhenReviewersIncomplete(t *testing.T) {
 	t.Parallel()
 
@@ -2012,6 +2031,7 @@ func TestOrchCouncilWaitTimesOutWhenReviewersIncomplete(t *testing.T) {
 	}
 }
 
+// TestOrchCouncilTallyGroupsReviewerFindingsNormal verifies normal council tally groups compatible reviewer findings.
 func TestOrchCouncilTallyGroupsReviewerFindingsNormal(t *testing.T) {
 	t.Parallel()
 
@@ -2110,6 +2130,7 @@ func TestOrchCouncilTallyGroupsReviewerFindingsNormal(t *testing.T) {
 	}
 }
 
+// TestOrchCouncilTallyStrictKeepsDistinctProposals verifies strict council tally keeps distinct proposals separate.
 func TestOrchCouncilTallyStrictKeepsDistinctProposals(t *testing.T) {
 	t.Parallel()
 
@@ -2170,6 +2191,7 @@ func TestOrchCouncilTallyStrictKeepsDistinctProposals(t *testing.T) {
 	}
 }
 
+// TestOrchCouncilReportDefaultShowsConsensusAndMajority verifies the default council report shows consensus and majority sections.
 func TestOrchCouncilReportDefaultShowsConsensusAndMajority(t *testing.T) {
 	t.Parallel()
 
@@ -2247,6 +2269,7 @@ func TestOrchCouncilReportDefaultShowsConsensusAndMajority(t *testing.T) {
 	}
 }
 
+// TestOrchCouncilReportShowAllIncludesMinority verifies `council report --show all` includes minority findings.
 func TestOrchCouncilReportShowAllIncludesMinority(t *testing.T) {
 	t.Parallel()
 
@@ -2276,6 +2299,7 @@ func TestOrchCouncilReportShowAllIncludesMinority(t *testing.T) {
 	}
 }
 
+// TestOrchCouncilReportJSONShape verifies `council report` keeps its JSON response shape stable.
 func TestOrchCouncilReportJSONShape(t *testing.T) {
 	t.Parallel()