feat(cli): harden review and execution gates

Make the review pipeline config-driven with ordered built-in passes and Review Artifact v3.\n\nAlso harden acceptance execution with nested result resume handling, per-criterion timeout support, generic pass expectations, refreshed docs, and expanded smoke coverage.

Author: auscaster

.ai/OPERATORS.md

@@ -70,7 +70,7 @@ trellis exec my-task -p phase1    # run criteria for one phase only
 trellis audit my-task             # compare spec files vs git diff
 trellis audit my-task -b main     # audit against specific base ref
 trellis diff my-task              # show git history for spec
-trellis review my-task            # run automated passes + adversarial review prompt
+trellis review my-task            # run configured automated passes + scaffold Review Artifact v3
 trellis complete my-task          # read review, record verdict, archive (requires review)
 trellis complete my-task --human-reviewed --reason "manual audit"  # exceptional audited override when the review gate is blocked
 trellis fail my-task              # active/ -> archive/ (failed)
@@ -108,14 +108,14 @@ After execution, before completing:
 
 ```bash
 trellis review my-task            # runs automated passes, scaffolds adversarial review
-                                  # reviewer fills in findings + review provenance in .ai/reviews/my-task.md
+                                  # reviewer fills in findings + Review Artifact v3 metadata in .ai/reviews/my-task.md
 trellis complete my-task          # reads review, records verdict, archives
                                   # refuses if the latest review round is missing, malformed, incomplete, or failed
 trellis complete my-task --human-reviewed --reason "manual audit"
                                   # exceptional audited override; requires interactive confirmation
 ```
 
-Review rounds accumulate — each `trellis review` appends a numbered section with a fixed metadata block. Prior rounds provide context for subsequent reviewers and make review provenance visible.
+Review rounds accumulate — each `trellis review` appends a numbered Review Artifact v3 section with per-pass `pass_results`. The default five-layer pipeline is `spec_compliance`, `scope_drift`, `regression_hunt`, `convention_check`, and `dark_patterns`, ordered by explicit `order` fields in `.ai/config.yaml`. Prior rounds provide context for subsequent reviewers and make review provenance visible.
 
 ---
 

.ai/README.md

@@ -11,11 +11,13 @@ Trellis is a spec-driven framework for AI agent task planning and execution. Eve
 1. **Plan:** AI generates a task spec in `.ai/specs/drafts/` via conversational ReAct loop
 2. **Approve:** Developer reviews and moves spec to `.ai/specs/approved/`
 3. **Execute:** AI picks up the approved spec, executes phases, validates at each checkpoint
-4. **Review:** Adversarial review finds what execution missed — `trellis review` runs automated passes, scaffolds a machine-validated review artifact, and records review provenance in the latest round
+4. **Review:** Adversarial review finds what execution missed — `trellis review` runs the configured `spec_compliance` and `scope_drift` checks, scaffolds Review Artifact v3, and prepares the adversarial `regression_hunt`, `convention_check`, and `dark_patterns` passes in the latest round
 5. **Archive:** Completed specs move to `.ai/specs/archive/YYYY-MM/` with truthful review results recorded, or a human-reviewed override audited explicitly when the gate is blocked
 
 The approval gate is the human oversight boundary. The review gate is the quality boundary. During execution, the agent operates autonomously through all phases, pausing only when blocked or deviating from the spec. A normal completion path still stays agent-driven; the human-reviewed override is an exceptional audited escape hatch, not the default workflow.
 
+The default review topology lives in `config.yaml` and uses five ordered built-in passes: `spec_compliance`, `scope_drift`, `regression_hunt`, `convention_check`, and `dark_patterns`. Review Artifact v3 stores per-pass `pass_results`, reviewer provenance, and round status for that configured topology.
+
 ---
 
 ## Directory Structure

.ai/config.yaml

@@ -180,25 +180,31 @@ rubric:
 # Every spec gets the same review — no profiles.
 # Recommended: run the agent review in a fresh context/session.
 review:
-  # Automated passes (run by CLI during trellis review)
-  passes:
-    - id: spec_compliance
-      type: command
-      description: "Re-run acceptance criteria to verify code satisfies spec"
-      command: "trellis exec {task_id} --resume"
-
-    - id: scope_drift
-      type: command
-      description: "Compare spec scope vs actual git diff — flag undeclared changes"
-      command: "trellis audit {task_id}"
-
-  # Agent review — single adversarial pass covering three attack vectors:
-  #   1. Regression hunt: check callers/imports of modified files for breakage
-  #   2. Convention check: verify new code follows CONVENTIONS.md and AGENTS.md
-  #   3. Dark patterns: hunt for hardcoded values, off-by-ones, race conditions, copy-paste errors
-  # Prompt template: .ai/prompts/review.md
-  # Findings written to: .ai/reviews/{task-id}.md
-  agent_review: true
+  # Review pipeline is built from named built-in passes only.
+  # Ordering is explicit; Trellis sorts by `order`, not mapping insertion luck.
+  automated_passes:
+    spec_compliance:
+      order: 10
+      title: "Spec Compliance"
+      description: "Re-run acceptance criteria to verify code satisfies the spec"
+    scope_drift:
+      order: 20
+      title: "Scope Drift"
+      description: "Compare spec scope vs actual git diff and flag undeclared changes"
+
+  adversarial_passes:
+    regression_hunt:
+      order: 30
+      title: "Regression Hunt"
+      description: "Trace callers, importers, and downstream consumers for regressions"
+    convention_check:
+      order: 40
+      title: "Convention Check"
+      description: "Check changed code against CONVENTIONS.md and AGENTS.md"
+    dark_patterns:
+      order: 50
+      title: "Dark Patterns"
+      description: "Hunt for subtle bugs, hardcodes, races, and safety gaps"
 
 # =============================================================================
 # REACT PATTERN (reasoning + acting)

.ai/prompts/exec.md

@@ -167,6 +167,8 @@ After all phases complete and before `trellis complete`:
 5. Fix any blocking findings if needed
 6. Run `trellis complete <task-id>` — reads the review, records verdict, archives
 
+The default Review Artifact v3 pipeline is `spec_compliance`, `scope_drift`, `regression_hunt`, `convention_check`, and `dark_patterns`. `trellis review` scaffolds the adversarial sections in configured order and expects the reviewer to update `round_status` plus per-pass `pass_results` before completion.
+
 `trellis complete` will **refuse to archive** if the latest review round is missing, malformed, incomplete, or failed. The only bypass is the exceptional human path: `trellis complete <task-id> --human-reviewed --reason "<why>"`, which requires interactive confirmation and records an audited override.
 
 ---

.ai/prompts/review.md

@@ -8,7 +8,7 @@
 
 ## Mission
 
-Find what's wrong. Not what's right — what's wrong.
+Find what is wrong. Not what is right.
 
 You are reviewing changes made during spec execution. A separate agent built this, or you did in a prior session. Either way, your job is to attack it.
 
@@ -31,14 +31,31 @@ A review that finds zero issues is suspicious. Look harder.
 2. Read the git diff of all changes
 3. Read `CONVENTIONS.md` and `AGENTS.md`
 4. Read `.ai/reviews/{task-id}.md` — if prior review rounds exist, read what was found before. Don't re-report fixed issues. Note if a prior finding persists.
-5. Attack the diff through the three vectors below — **all three are required**
-6. Write findings into the latest review section in `.ai/reviews/{task-id}.md` — each adversarial section must have content or `trellis complete` will reject. Update the review provenance metadata for the reviewer who actually performed the review.
+5. Attack the diff through the configured adversarial passes — by default: `regression_hunt`, `convention_check`, and `dark_patterns`
+6. Write findings into the latest review section in `.ai/reviews/{task-id}.md`
+7. Update the Review Artifact v3 metadata so the latest round is truthful and complete
+
+---
+
+## Default Review Pipeline
+
+The default built-in five-pass pipeline in `.ai/config.yaml` is:
+
+- `spec_compliance`
+- `scope_drift`
+- `regression_hunt`
+- `convention_check`
+- `dark_patterns`
+
+`trellis review` already runs `spec_compliance` and `scope_drift` and scaffolds the adversarial sections in configured order. Your job is to complete the adversarial passes and finalize the metadata for Review Artifact v3.
+
+If the project has changed pass titles in `.ai/config.yaml`, follow the headings already scaffolded by `trellis review`. The built-in pass ids stay the same even if the visible section title changes.
 
 ---
 
 ## Attack Vectors
 
-### 1. Regression Hunt
+### 1. Regression Hunt (`regression_hunt`)
 
 For each modified file, find every caller, importer, and downstream consumer. What assumptions do they make that this change violates?
 
@@ -48,15 +65,15 @@ For each modified file, find every caller, importer, and downstream consumer. Wh
 - Verify event listeners and subscribers still match event shapes
 - Check if removed or renamed exports are still referenced elsewhere
 
-### 2. Convention Violations
+### 2. Convention Check (`convention_check`)
 
 Read `CONVENTIONS.md` and `AGENTS.md`. For each changed file, check whether the new code violates a documented rule.
 
 - Cite the specific convention and the specific violating line
 - Don't flag style preferences — only documented, stated conventions
 - Check naming patterns, layer boundaries, import rules, test patterns
 
-### 3. Defect Scan
+### 3. Dark Patterns (`dark_patterns`)
 
 For each change, actively hunt for:
 
@@ -81,30 +98,36 @@ For each change, actively hunt for:
 
 ## Output
 
-`trellis review` scaffolds the review file at `.ai/reviews/{task-id}.md` with numbered review sections. Fill in the latest section using the fixed Review Artifact v2 contract:
+`trellis review` scaffolds the review file at `.ai/reviews/{task-id}.md` with numbered review sections. Fill in the latest section using the Review Artifact v3 contract:
 
 ````markdown
 ## Review N — {timestamp}
 
 ### Metadata
 ```json
 {
-  "schema_version": 2,
+  "schema_version": 3,
   "round_status": "completed",
   "reviewer_mode": "fresh_agent",
   "reviewer_session": "session-id-or-empty-string",
   "reviewed_at": "{timestamp}",
   "override_reason": null,
-  "automated_passes": {
+  "pass_results": {
     "spec_compliance": "pass",
-    "scope_drift": "pass"
+    "scope_drift": "pass",
+    "regression_hunt": "pass",
+    "convention_check": "pass",
+    "dark_patterns": "pass"
   }
 }
 ```
 
-### Automated Passes
+### Pass Results
 - spec_compliance: PASS
 - scope_drift: PASS
+- regression_hunt: PASS
+- convention_check: PASS
+- dark_patterns: PASS
 
 ### Regression Hunt
 {For each modified file, trace callers/importers. What assumptions break?
@@ -114,9 +137,9 @@ List findings or "No issues found — checked [what you checked]".}
 {Read CONVENTIONS.md and AGENTS.md. Does new code violate any documented rule?
 List findings or "No issues found — checked [what you checked]".}
 
-### Defect Scan
-{Hunt for hardcoded values, off-by-one, missing null checks, race conditions,
-copy-paste errors, unhandled error paths, security issues.
+### Dark Patterns
+{Hunt for hardcoded values, off-by-one issues, missing null checks, race conditions,
+copy-paste errors, unhandled error paths, and security issues.
 List findings or "No issues found — checked [what you checked]".}
 
 ### Blocking
@@ -129,9 +152,17 @@ List findings or "No issues found — checked [what you checked]".}
 {pass | fail | pass_with_issues}
 ````
 
-Set `reviewer_mode` to `fresh_agent`, `auto`, or `executor` to match the real reviewer. Leave `override_reason` as `null` for normal reviews. Prior review rounds remain in the file as context. Don't modify them — only fill in the latest section.
+Update these metadata fields explicitly:
+
+- Set `round_status` to `completed` when the review is actually done
+- Set `reviewer_mode` to `fresh_agent`, `auto`, or `executor` to match the real reviewer
+- Set `reviewer_session` to the real session identifier or `""`
+- Keep the automated pass results for `spec_compliance` and `scope_drift`
+- Set adversarial `pass_results` for `regression_hunt`, `convention_check`, and `dark_patterns` to `pass`, `pass_with_issues`, or `fail`
+
+Prior review rounds remain in the file as context. Do not rewrite them.
 
-**All three adversarial sections (Regression Hunt, Convention Check, Defect Scan) must contain content.** Each must have at least one finding or an explicit "No issues found" with a brief note of what was checked. `trellis complete` will reject reviews with empty adversarial sections.
+**All configured adversarial sections must contain content.** Each must have at least one finding or an explicit "No issues found" with a brief note of what was checked. `trellis complete` will reject reviews with empty configured sections or with `round_status` left at `in_progress`.
 
 **Verdict rules:** Any blocking finding → `fail`. Non-blocking only → `pass_with_issues`. Clean → `pass`.
 

.ai/schemas/spec.json

@@ -223,7 +223,12 @@
                   "description": {"type": "string"},
                   "command": {"type": "string"},
                   "expected": {"type": "string"},
-                  "cwd": {"type": "string", "description": "Working directory relative to workspace root"}
+                  "cwd": {"type": "string", "description": "Working directory relative to workspace root"},
+                  "timeout_seconds": {
+                    "type": "integer",
+                    "minimum": 1,
+                    "description": "Command timeout in seconds. Defaults to 600 when omitted."
+                  }
                 }
               }
             }
@@ -327,10 +332,38 @@
                   "type": "string",
                   "description": "Working directory for the command, relative to workspace root. Useful in monorepo/workspace setups where different criteria target different submodules."
                 },
+                "timeout_seconds": {
+                  "type": "integer",
+                  "minimum": 1,
+                  "description": "Command timeout in seconds. Defaults to 600 when omitted."
+                },
                 "result": {
-                  "type": "string",
-                  "enum": ["pass", "fail"],
-                  "description": "Result recorded by trellis exec"
+                  "oneOf": [
+                    {
+                      "type": "string",
+                      "enum": ["pass", "fail"],
+                      "description": "Flat result recorded by trellis exec"
+                    },
+                    {
+                      "type": "object",
+                      "required": ["status"],
+                      "properties": {
+                        "status": {
+                          "type": "string",
+                          "enum": ["pass", "fail"]
+                        },
+                        "timestamp": {
+                          "type": "string",
+                          "format": "date-time"
+                        },
+                        "output": {
+                          "type": "string"
+                        }
+                      },
+                      "additionalProperties": false,
+                      "description": "Nested result block supported for execution records"
+                    }
+                  ]
                 },
                 "executed_at": {
                   "type": "string",