Repository navigation
Assess the verification architecture for long suites and concurrent cycles #376
Description
Problem. Verification is bounded by a single global constant, CLAUDE_VERIFICATION_TIMEOUT_MS = 600_000 (scripts/stage_permissions.py:121). It is applied twice: the Claude executor exports it as BASH_DEFAULT_TIMEOUT_MS and BASH_MAX_TIMEOUT_MS (scripts/executors.py:2863-2864), and the Bash hook rejects a lower explicit timeout on a configured verification command (scripts/stage_permissions.py:543). Background Bash is rejected (:536) so no run goes untracked. A project whose suite needs 20-60 minutes cannot complete a cycle, and raising the constant to 30 minutes only moves the wall.
Goal. Verification must scale to small and large projects, and to several concurrent cycles, without the duration of a suite deciding whether a cycle can finish, and without losing fail-closed behaviour, traceability, idempotency or the verification guarantees.
Scope (investigation and proposal only; no code or contract changes). Analyse and document, with file and line references:
- Where timeouts for Claude, Bash, stages, dispatches and verification commands are configured and enforced, and how they relate (command vs agent call vs stage deadline vs
DEFAULT_DISPATCH_TIMEOUT_SECONDS). - How checks are planned, executed and recorded during implement, verify, review and rereview.
- How long runs, cancellations, interruptions and resumes are handled today (relation to feat(runtime): cap a cycle's wall-clock time and tokens with a resumable budget stop #262 and Resume a stage's pending operation after a grant instead of rerunning it #323).
- When the same check runs again on the same HEAD and under which conditions its evidence could be reused (code, configuration, environment, command identity).
- Which planning, supervision and concurrency mechanisms already exist and can be reused rather than duplicated.
- How to introduce per-project and per-check configuration without breaking current contracts.
- How to run supervised long executions without bypassing permission policy or losing traceability.
Deliverable. A research document under docs/research/ that ends with the proposal split into independent issues, each with dependencies, acceptance criteria, risks and regression tests, separating immediate improvements from architectural changes. It confirms, adjusts or replaces the four follow-up issues linked below.
Out of scope. Changing code, hooks, configuration keys or contracts; implementing any phase.
Follow-up issues. #377 (configurable timeouts), #378 (redundant verification and evidence reuse), #379 (supervised runner), #380 (concurrency limit). Related: #237 (selective tests), #262 (cycle budget), #323 (resume pending operation), #367 (CI evidence for a required check), #290/#366 (verification plan).
Acceptance criteria.
- The document answers each of the seven questions above with file and line references.
- It states which existing capabilities are reused and which gaps remain, and shows no overlap with cc-verify gating and selective tests (split from #182) #237, feat(runtime): cap a cycle's wall-clock time and tokens with a resumable budget stop #262, Resume a stage's pending operation after a grant instead of rerunning it #323 or Let a CI pass on the final head satisfy a required local unverified check #367 left unresolved.
- It splits the work into independent issues with dependencies, acceptance criteria, risks and regression tests, marking each as immediate or architectural.
- It states that no incomplete check may be considered verified and no obligation may be replaced by other evidence without the contract's authorization.
- It states the compatibility rule: with no new configuration, behaviour matches the current 600 s policy.
Tests. None (documentation only). The document passes the repository's documentation checks.
Activity
docs(roadmap): add #376-#380 to the M2 milestone row (#381)