task-transitions

name	task-transitions
description	Pre-transition checklist for closing or reviewing tasks. Covers fresh verification evidence, commits, and memory gates.
category	core
metadata	{"gobby":{"audience":"all","format_overrides":{"autonomous":"full"}}}

Task Transition Checklist

Before closing or changing task status, complete ALL gates below. They fire in order — handle them all at once to avoid bouncing.

---

Gate Summary

#	Gate	Variable	Skipped by
1	Fresh verification evidence ready	verification_evidence	—
2	Clean working tree	—	Non-work closes
3	Commit SHA passed to close_task	—	Non-work closes
4	Memory review completed	memory_review_completed	—

Non-work close reasons (skip commit gates 2-3): duplicate, already_implemented, wont_fix, obsolete, out_of_repo

Fresh evidence and memory review still apply for non-work closures.

---

Gate 1: Fresh Verification Evidence

Run verification after the final file edit. Later file edits clear readiness evidence. Git commits preserve evidence, so the normal sequence is:

1. Finish editing files.
2. Run focused validation.
3. Commit.
4. Review memory.
5. Close or submit for review.

Run the verification commands defined in .gobby/project.json on the files you touched. The verification key contains named commands — run the ones relevant to your changes:

# Read the project's verification config
cat .gobby/project.json | jq '.verification'

# Run relevant checks (examples — use the actual commands from project.json)
# verification.lint → linting
# verification.format → format checking
# verification.type_check → type checking
# verification.unit_tests → tests (scope to relevant files, not the full suite)
# verification.custom.* → project-specific checks (frontend, etc.)

Scope test runs to relevant files — do NOT run the full test suite unless explicitly asked.

Successful validation commands such as uv run pytest ..., uv run ruff check ..., uv run mypy ..., and npm test are recorded automatically as validation_command evidence. A failed validation command blocks readiness until a later validation command succeeds. Manual evidence can satisfy readiness when no failed validation command is pending, but it cannot clear a failed validation command.

For manual review, PR state, or another non-command artifact, record evidence explicitly:

call_tool("gobby-sessions", "record_verification_evidence", {
    "summary": "Read the diff and verified the touched lifecycle gates match the task",
    "evidence_type": "manual_diff_review",
    "supports": "completion readiness for #N"
}, session_id="#2333")

Gate 2: Clean Working Tree

All changes must be committed before status transitions.

git add <specific-files>
git commit -m "[<project_name>-#<task_number>] <type>: <description>"

Prefer staging specific files over git add -A. Include the task reference in the commit message. project_name is a placeholder for the real project name, never a literal prefix. In this repo, use [gobby-#N] type: description.

Gate 3: Close with Commit SHA

Pass commit_sha to close_task — this links the commit and closes in one call:

call_tool("gobby-tasks", "close_task", {
    "task_id": "#N",
    "commit_sha": "abc1234",
    "changes_summary": "What changed and why"
}, session_id="#2333")

session_id is a parameter of call_tool, not the inner tool — pass your Gobby session ref.

Do NOT call link_commit separately — close_task handles linking internally when you pass commit_sha. The link_commit tool exists only for associating commits to tasks still in progress (multi-commit work).

Gate 4: Memory Review

Review your session for memories worth preserving:

• New insights about the codebase, user preferences, or design decisions
• Stale memories that need updating or deleting

If nothing new was learned and no stale memories remain, clear the gate:

set_variable(name="memory_review_completed", value=true, session_id="#2333")

Do NOT create memories for bugs or errors — create tasks instead.

---

Complete Close Sequence (interactive sessions)

1. Run verification commands from .gobby/project.json after the final file edit
2. Fix every error, warning, and failure you encounter
3. git add + git commit (with [<project_name>-#<task_number>] in the message, e.g. [gobby-#N])
4. Review memories → save/delete/clear gate
5. set_variable(memory_review_completed=true)
6. close_task(task_id, commit_sha, changes_summary)  ← one call links + closes

Review Flow (autonomous/pipeline agents)

Autonomous agents must use the review flow — they cannot close tasks directly. The same gates apply. Review tools live on gobby-tasks-ops and require the explicit stage_name being reviewed, such as planning, expansion, development, or holistic_qa.

submit_for_review — submit work for review

call_tool("gobby-tasks-ops", "submit_for_review", {
    "task_id": "#N",
    "stage_name": "development",
    "review_notes": "What was done and what to verify"
}, session_id="#2333")

Commits are auto-linked from your session. All four gates still apply before this call succeeds.

approve_review — approve after review

call_tool("gobby-tasks-ops", "approve_review", {
    "task_id": "#N",
    "stage_name": "development",
    "approval_notes": "Verified: tests pass, changes match spec"
}, session_id="#2333")

Used by QA agents after reviewing work. Same gates apply — if the reviewer made fixes and committed, those commits are auto-linked.

reject_review — send reviewed stage work back to ready

call_tool("gobby-tasks-ops", "reject_review", {
    "task_id": "#N",
    "stage_name": "development",
    "rejection_notes": "Blocking findings that must be addressed before the next review",
    "round_number": 2
}, session_id="#2333")

Used by structured review loops such as plan adversary rounds. The current stage row returns to ready; round_number is optional and scopes the rejection notes for numbered review loops.

Interactive vs Autonomous

Context	Use	Why
Interactive (user present)	close_task	User is the reviewer — no separate review step needed
Autonomous (pipeline/agent)	submit_for_review	Required — autonomous agents cannot close tasks directly
QA review agent	approve_review	Moves reviewed stage work to review_approved

submit_for_review, approve_review, and reject_review are blocked in interactive sessions — use close_task directly. Conversely, autonomous agents must use the review flow.

Closing Without Commits

For tasks that don't require code changes:

call_tool("gobby-tasks", "close_task", {
    "task_id": "#N",
    "reason": "duplicate",  # or obsolete, wont_fix, already_implemented, out_of_repo
    "changes_summary": "Why no changes were needed"
}, session_id="#2333")

Fresh evidence and memory review still apply. changes_summary is still required — explain why no changes were needed.

Common Mistakes

Mistake	Why it fails	Fix
Close without commit_sha	Gate 2 blocks — no commit to validate	Commit first, pass commit_sha to close_task
Separate link_commit then close_task	Unnecessary extra call	Pass commit_sha directly to close_task
git add -A	May stage secrets or binaries	Stage specific files
Skip memory review	Gate 4 blocks — memory_review_completed not set	Review or explicitly clear
Record evidence before final edits	Gate 1 blocks after later file edits clear evidence	Run validation after the final edit
Run validation that fails, then record manual evidence	Gate 1 blocks because failed validation is unresolved	Run a later successful validation command
Omit changes_summary	close_task rejects — required for leaf tasks	Describe what changed and why
Use review tools in interactive session	Blocked by rule	Use close_task — user is the reviewer