docs: test-time-compute design (verify tool + sub-agent reasoning)

[Hmbown]

Adds docs/TTC_DESIGN.md — the approved design for agent-decided test-time compute. Design only, no code, no crates/config changes. Implementation is v0.8.69, behind the green v0.8.68 stopship.

3-way consensus (verify-tool contributor + GLM 5.2 + internal analysis):

• One shared CriticEngine behind three distinct triggers: agent-invoked verify tool (feat(tools): agent-callable verify/critique tool (agent decides to spend test-time compute on self-review) #4196, MVP feat(tools): agent-callable verify/critique tool (#4196) #4199), advisor watcher (v0.8.68 Subagents: add an optional advisor watcher for live turns #3982), post-turn gates (v0.8.68 WhaleFlow: verification gates (compile, test, lint, review as post-agent hooks) #4013). Unify the engine, never the trigger.
• Sub-agent reasoning: replace the Low clamp with a floor (v0.8.68 2.20: let Fleet profiles save provider model and thinking #4137) — resolution Profile → task → session → Low.
• Recursion guarded in the ToolRegistryBuilder, not prose.

Refs #4196 #4137 #3982 #4013

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[claude]

Claude finished @Hmbown's task in 1m 32s —— View job

---

Review: docs/TTC_DESIGN.md

• Gather context (docs-only PR, single file, +75/-0)
• Read the design doc in full
• Cross-check claims against the actual codebase and guardrails
• Post review feedback

Summary: This is a design doc only — no code, no crates/config changes, confirmed by the diff (docs/TTC_DESIGN.md is the sole changed file). I verified the technical claims it makes against the current tree rather than taking them on faith:

• crates/tui/src/auto_reasoning.rs:12,21-33 — is_subagent == true unconditionally returns ReasoningEffort::Low today, confirming the doc's diagnosis that Low currently acts as a hard clamp, and the proposed "floor, not ceiling" fix is a real, scoped change to that function.
• crates/tui/src/tools/review.rs, crates/tui/src/tools/registry.rs, crates/tui/src/tools/spec.rs — the review tool and ToolRegistryBuilder/ToolSpec machinery the doc proposes reusing for verify do exist, so "structurally isomorphic to review" is a grounded claim, not aspirational.
• crates/tui/src/features.rs — Feature gating exists, matching the doc's plan to gate verify behind a Feature flag.
• crates/tui/src/tools/subagent/mod.rs:1340 — SubAgentRuntime exists as the place reasoning_effort would be forwarded.
• AGENTS.md "Where to work right now" explicitly says the model-facing sub-agent surface is agent-only and that capacity/coherence/lifecycle machinery was removed — the doc's anti-pattern Simplify UI and improve footer display (v0.3.14) #2 (no second runtime/policy surface for a critic sub-agent) and its choice of "tool, not sub-agent" for verify align with that constraint rather than reintroducing removed machinery.
• PR feat(tools): agent-callable verify/critique tool (#4196) #4199 ("agent-callable verify/critique tool (feat(tools): agent-callable verify/critique tool (agent decides to spend test-time compute on self-review) #4196)") is open and matches the doc's description of the MVP it's meant to be refactored onto the shared CriticEngine.

Design-level observations (non-blocking, since this is a docs PR):

• The recursion-guarding story (§"Recursion / cost bounding") is good: tools-disabled by construction + registry-level refusal + budget is defense in depth rather than a single prose rule, consistent with the "guard in ToolRegistryBuilder, not prose" principle stated up top.
• Sequencing in "Issue map & sequencing" correctly calls out that v0.8.68 2.20: let Fleet profiles save provider model and thinking #4137 touches crates/config and should be sequenced separately from the crates/tui/src/tools/ work in feat(tools): agent-callable verify/critique tool (agent decides to spend test-time compute on self-review) #4196/feat(tools): agent-callable verify/critique tool (#4196) #4199 — that keeps this doc's "no crates/config changes" promise honest for the next PR too.
• One thing worth double-checking before implementation (not a doc defect): the doc names a prospective flag Feature::CriticProducerOnly (or equivalent) — since it's explicitly hedged as "or equivalent," no action needed now, just flag it so the follow-up PR doesn't treat the name as already decided.

No correctness bugs, provider/model-routing concerns, or security issues — there's no runtime code in this diff to check against the v0.8.65 provider-prefix invariant. Nothing to fix here; good to merge as a design record.