---
name: ayf:task-done
description: |
  Mark a task complete: unlock, update board, cascade unblocks, log.
allowed-tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
  - Agent
  - AskUserQuestion
---

# /task-done -- Mark Task Complete

Finalize a completed task: clean up locks, update tracking, cascade unblocks, log everything.

## Input

The human specifies which task to mark done by number. If not specified, check for the currently locked task in `.ay/tracking/locks/`. If exactly one lock exists, use that task. If multiple or none, ask.

## Step 1: Validate

1. Read the task file at `.ay/tasks/task-{N}.md`.
2. Confirm the task status in `.ay/tracking/BOARD.md` is IN PROGRESS.
3. Confirm a lock file exists at `.ay/tracking/locks/task-{N}.lock`.

If the task is not IN PROGRESS or not locked, warn the human and ask how to proceed.

## Step 2: Delete Lock

Remove `.ay/tracking/locks/task-{N}.lock`.

## Step 3: Update Board

Edit `.ay/tracking/BOARD.md`:
- Change task {N} status from IN PROGRESS to DONE.
- Add completion timestamp.

## Step 4: Append Event to BOARD.jsonl

Append a `done` event to the machine-readable event log at `.ay/tracking/BOARD.jsonl` (the append-only source of truth for task status). One JSON object per line; never edit existing lines.

```bash
echo '{"ts":"'"$(date -u +%Y-%m-%dT%H:%M:%SZ)"'","task_id":"{N}","title":"{title}","agent":"{agent-name}","status":"done","commit":"'"$(git rev-parse --short HEAD)"'"}' >> .ay/tracking/BOARD.jsonl
```

Schema: `{ts: ISO-8601, task_id: string, title: string, agent: string, status: 'ready|in_progress|done|blocked', commit?: string, blocker?: string}`. If the commit SHA is not applicable, omit the `commit` field.

## Step 5: Cascade Unblocks

Scan `.ay/tracking/BOARD.md` for tasks with status BLOCKED that list task {N} as a dependency.

For each blocked task:
1. Check if ALL of its dependencies are now DONE.
2. If yes, change its status from BLOCKED to READY.
3. Note which tasks were unblocked.

Report any unblocked tasks to the human.

## Step 5: Write HANDOFF (validated)

Compose a HANDOFF entry for the next agents in the canonical schema (required
fields: `To`, `From`, `Task`, `Date`, `Summary`; optional `Detail`):

```
---
To: {target-agent or "all"}
From: {agent-name}
Task: {N}
Date: {YYYY-MM-DD HH:MM}
Summary: {one-line summary of what changed and why it matters}
Detail: {gotchas, API discoveries, what downstream agents must know}
---
```

Before appending it to `.ay/tracking/HANDOFFS.md`, validate it through the gate:

```bash
printf '%s' "$ENTRY" | bin/ayf-validate-handoff.sh -
```

If the validator exits non-zero, it prints the missing/invalid fields. Fix the
entry and re-validate. **Do not write an entry that fails validation.** Only
append to `HANDOFFS.md` once the validator exits 0.

## Step 6: Log to AGENTS-LOG

Append to `.ay/tracking/AGENTS-LOG.md`:

```markdown
## Task {N}: {title}
- Agent: {agent-name or "human"}
- Started: {from lock file timestamp}
- Completed: {current timestamp}
- Files: {count} created, {count} modified, {count} deleted
- Deviations: {count from diff-from-plan.md, or 0}
- Learnings: {count of entries added to HANDOFFS or learnings.jsonl}
```

## Step 7: Log to CHANGELOG

Append to `.ay/tracking/CHANGELOG.md` under the current date heading (create the heading if it does not exist):

```markdown
- Task {N}: {one-line summary of what was delivered}
```

## Step 8: Report

Show the human:
- Task {N} marked DONE
- Tasks unblocked (if any)
- Remaining READY tasks available for next cycle
- Current board summary (counts by status)