---
id: T-325
name: "Actionable human AC handoffs — enforce quality, surface pending reviews"
description: >
  Human ACs have 50% completion rate when vague vs 95% when specific. Two gaps: (1)
  ACs lack
  executable steps, (2) no proactive notification when human action is needed. Explore
  enforcement
  and surfacing mechanisms.

status: work-completed
workflow_type: inception
owner: human
horizon:
tags: [governance, ux, handoff]
components: [agents/task-create/update-task.sh, agents/handover/handover.sh, 
      agents/task-create/create-task.sh]
related_tasks: [T-193, T-285, T-289]
created: 2026-03-04T23:51:59Z
last_update: '2026-06-11T22:24:18Z'
date_finished: 2026-03-08T19:30:13Z
target_blast_radius: 3   # T-2193 migration default (M=small-subsystem floor)
voi_score: 0.5            # T-2193 migration default (medium)
bvp_scores_proposed:
  - ts: '2026-06-11T22:24:18Z'
    estimator: bvp-estimator-v1-heuristic
    scores:
      D1: 2
      D2: 2
      D3: 2
      D4: 2
      F-RECALL: 2
      F-ORCH: 2
      F3: 2
      F1: 2
      F2: 2
    rationale: D1=2 (no-signal); D2=2 (no-signal); D3=2 (no-signal); D4=2 
      (no-signal); F-RECALL=2 (no-signal); F-ORCH=2 (no-signal); F3=2 
      (no-signal); F1=2 (no-signal); F2=2 (no-signal)
    rubric_sha: e4a00f38e801
---

# T-325: Actionable human AC handoffs — enforce quality, surface pending reviews

## Problem Statement

Human acceptance criteria are written as outcome statements ("verify X works") not executable instructions. Evidence from 46 tasks: vague ACs complete at 50%, specific ACs at 95%. Tasks pile up for 72h+ triggering D2 audit failures. The agent-to-human handoff assumes context the human no longer has.

Two gaps:
1. **Actionability** — ACs lack commands, URLs, expected output, failure steps
2. **Discoverability** — No proactive notification; human must visit Watchtower to find pending work

## Assumptions

- A-1: Enforcing a `Steps:` block in human ACs will improve completion rates
- A-2: Surfacing pending human ACs at session start will reduce D2 staleness
- A-3: Confidence signaling (rubber-stamp vs genuine review) will help humans prioritize
- A-4: Watchtower UI is sufficient — CLI/handover/resume are the real gaps

## Exploration Plan

1. **Spike 1: Template + CLAUDE.md rule change** (30 min)
   - Draft new human AC format with required `Steps:` block containing:
     - **Exact commands** to run (copy-pasteable, no placeholders the human must figure out)
     - **Expected output** (what success looks like — exact text, status code, or screenshot description)
     - **Environment prerequisites** (SSH access, URLs, credentials location, required tools)
     - **Failure recovery** (what to do if it doesn't work — specific diagnostic commands)
   - Draft CLAUDE.md rule for writing actionable human ACs
   - Validate against 5 existing tasks: would it have helped?

2. **Spike 2: Enforcement gate prototype** (30 min)
   - Prototype P-010 extension: regex check for commands/URLs in human ACs
   - Test: does it catch vague ACs without false positives on good ones?

3. **Spike 3: Surfacing mechanisms** (30 min)
   - Add `fw task list --needs-human-verification` CLI
   - Add pending human ACs to resume output
   - Add "Human Actions Required" section to handover generation

4. **Spike 4: Confidence signal** (15 min)
   - Define rubber-stamp vs genuine-review markers
   - Draft syntax for task files

## Technical Constraints

- Must not break existing tasks (backward compatible)
- P-010 gate changes must fail open (warn, not block) for existing tasks without Steps blocks
- Handover changes must not bloat the document significantly

## Scope Fence

**IN scope:**
- Human AC format requirements (template, CLAUDE.md)
- P-010 gate extension (quality check)
- CLI/handover/resume surfacing
- Confidence signaling design

**OUT of scope:**
- Email/webhook/external notifications (separate task if needed)
- Watchtower UI changes (already has "Awaiting Verification")
- Retroactive fixing of all existing human ACs

## Acceptance Criteria

- [x] Problem statement validated
- [x] Assumptions tested
- [x] Go/No-Go decision made

## Go/No-Go Criteria

**GO if:**
- Template change demonstrably improves AC actionability on 3+ real examples
- Enforcement gate has <10% false positive rate on existing good ACs
- Surfacing mechanisms can be built in <2h total

**NO-GO if:**
- Format enforcement creates friction without measurable improvement
- Existing human AC patterns are too diverse to standardize
- The real problem is notification (out of scope), not quality

## Verification

# Research artifact exists (C-001)
test -f docs/reports/T-325-human-ac-handoff-quality.md

## Decisions

**Decision**: GO

**Rationale**: All 4 assumptions validated. Scoped to instruction quality: CLAUDE.md rule + template + WARN gate. Surfacing/notification deferred.

### 2026-03-08 — GO decision (detail)
- **Chose:** GO — proceed with implementation (tightened scope)
- **Scope:** Agent must write human ACs with step-by-step instructions (Steps/Expected/If-not). Three deliverables: CLAUDE.md rule, template update, WARN gate in update-task.sh.
- **Deferred:** Surfacing/notification (resume, handover, CLI) — separate task if needed.
- **Why:** All 4 assumptions validated. 4/5 real tasks improved. 0% false positive on gate. Zero breaking changes.
- **Rejected:** Broader scope including notification/surfacing mechanisms (user confirmed: core is instruction quality, not discoverability).

## Updates

### 2026-03-05T00:00:00Z — inception-start
- **Action:** Created inception with 4-agent research phase
- **Findings:** 46 tasks analyzed, clear correlation between AC specificity and completion rate
- **Research artifact:** docs/reports/T-325-human-ac-handoff-quality.md

### 2026-03-08T09:42:47Z — inception-decision [inception-workflow]
- **Action:** Recorded inception decision
- **Decision:** GO
- **Rationale:** All assumptions validated. Scope: agent must write human ACs with step-by-step instructions (Steps/Expected/If-not). CLAUDE.md rule + template update + WARN gate in update-task.sh. Surfacing/notification deferred to separate task.

### 2026-03-08T19:30:13Z — status-update [task-update-agent]
- **Change:** status: started-work → work-completed

## Reviewer Verdict (v1.5)

- **Scan ID:** R-f3e012c5
- **Timestamp:** 2026-06-02T15:02:10Z
- **Catalogue:** v1.3-seed
- **Overall:** PASS
- **Needs Human:** no
- **Findings:** none
