---
name: worker-report
description: "Use at the end of every worker task to produce a structured completion report the orchestrator can parse. Trigger when all work on the Sprint Contract is complete OR when aborting due to a blocker. This is the ONLY communication channel back to the orchestrator. Must use atomic tmp+rename write."
---

# Worker Report

Every worker session ends with exactly one report. No exceptions. No prose replies to the user.

## Write path (atomic)

Environment provides `BRAID_ROOT`. Target file: `$BRAID_ROOT/reports/<task-id>.md`.

**Never write the target file directly.** Always:

```bash
TASK_ID="$(grep '^task_id:' .sprint-contract.yaml | head -1 | sed -E 's/.*:\s*"?([^"]+)"?.*/\1/')"
TMP="$BRAID_ROOT/reports/.tmp/$TASK_ID.md"
FINAL="$BRAID_ROOT/reports/$TASK_ID.md"
mkdir -p "$BRAID_ROOT/reports/.tmp"

# ... write the report body to $TMP ...

mv "$TMP" "$FINAL"    # atomic rename on same filesystem
```

The `mv` is the commit. Readers will never see a partial file.

## Report format (exact structure required)

```markdown
# Worker Report: <task-id>

## Status
<one of: COMPLETED | FAILED | BLOCKED>

## Acceptance Criteria Check
<for each criterion in the contract verbatim>
- [x|✗] <criterion text> — <one-line concrete evidence>

## Test Results
\`\`\`
<exact stdout of each test_command, in order>
\`\`\`

## Self-Check Verdict
Status: GREEN | YELLOW | RED
Reasoning: <1-3 sentences comparing actual diff + tests against acceptance criteria>
Flagged Items: none | <short bullets>

## Files Changed
\`\`\`
<output of `git diff --stat <target-branch>` in the worktree>
\`\`\`

## Scope Compliance
- Allowed paths touched: <list>
- Forbidden paths touched: NONE | <list if violated>

## Observed Issues (do not fix)
<bullets of problems noticed outside scope, or "none">

## Blockers (if Status != COMPLETED)
<specific: what stopped you, what would unblock>
```

## Hard rules

- NEVER write prose outside this structure
- NEVER claim COMPLETED if any `test_command` failed — COMPLETED requires every test green
- NEVER hide failures — if something broke, say so with exact error output
- If BLOCKED: be specific — which command failed, which path was needed outside scope, which dependency was missing
- If you modified a forbidden path even once: Status must be FAILED, list it under Scope Compliance
- Self-Check is not a place to excuse failures. Use GREEN only when every acceptance criterion is satisfied, every test_command is green, and scope compliance is clean. Use YELLOW for uncertainty or partial confidence. Use RED for known issues.

## Before writing the report

Run these one last time inside the worktree and paste the actual output:

- Every `test_command` from the contract
- `git diff --stat <target-branch>`
- `git diff <target-branch> --name-only`

Do not paste stale output from earlier runs.