Review AFlow Checkpoint

Use this skill only for checkpoint-scoped review of work produced under an aflow plan that includes Git Tracking. It is meant to be installed as a static skill and driven by prompt context from the workflow engine.

Test and command completion

• Prefer foreground commands and the execution tool's process/session handle.
  Read the command's actual exit status and bounded output before deciding to
  wait, retry, or report success. A launcher exit or a successful tail is not
  the test result; preserve the tested command's status when piping output.
• If background execution is necessary, retain the exact child handle/PID and
  collect its exit status (wait "$child_pid" only from its owning shell).
  Across tool calls, use a supported persistent session or an owned completion
  receipt tied to that invocation; a vanished PID alone does not prove success.
• Never use broad pgrep -f command-text matching to decide whether your test
  finished: it can match the polling shell itself or another run. Do not use
  fixed long sleeps or detached nohup polling in place of child completion.
• Use only timeout options supported by the installed runner. A usage error
  means the command already failed; diagnose it immediately. Prefer an existing
  execution-tool timeout or a verified platform timeout wrapper when needed.
• Once required checks have finished, record the result and continue the
  handoff. Do not rerun matching successful checks merely to fill a wait.
  A whole-harness exclusive resource remains occupied during shell/test waits;
  never manually release its lease while the harness can still issue requests.

Storage and evidence hygiene

• Assess storage and evidence hygiene as concrete acceptance where it is material: owned disposable scratch cleaned after successful evidence extraction, failed and unique artifacts retained, verbose output bounded at production.
• Reuse worker evidence only when its primary log is inspectable and the relevant state is unchanged; do not rerun an unchanged worker check without a reason and do not demand per-review evidence copies.
• Fix permitted environment prerequisites within review authority, or route one bounded recoverable action; do not repeat unchanged rejection loops for recoverable storage conditions.
• Never approve missing acceptance to avoid disk failures; a failed, interrupted, or missing required check blocks approval.
• Keep the cumulative required final verification intact; do not move broad suites into this checkpoint review.
• Do not invent speculative platform requirements (quotas, dashboards, cloud storage) that the plan does not ask for.

Behavior

• Load the active plan before reviewing code or history.
• Review one checkpoint at a time, not the whole accumulated handoff.
• Treat checkpoint/version commit prefixes such as cp4 v01, cp4 v02, and cp5 v01 as commit-boundary labels when they identify the pending target. Use exact SHAs as supporting evidence, not as the only way to understand state.
• Treat Git Tracking as lightweight support metadata. In worktree-first plans, Plan Branch and Pre-Handoff Base HEAD may have been auto-populated by the engine, while Last Reviewed HEAD and Review Log may be absent.
• If the latest checkpoint commit boundary is missing or ambiguous, review the current worktree state and say that the fallback was used.
• Treat files under plans/ as architect or reviewer-owned artifacts. If an implementation commit modifies plan files unexpectedly, reject that work unless the user explicitly asked for plan-file commits from the implementer.
• Treat prompt-supplied concrete review context as authoritative when it is present. Use repo discovery only when the prompt leaves a target ambiguous.
• When the controller supplies a ## Checkpoint under review section, treat its
  original checkpoint identity, active overlay, and worker artifact reference as
  the pending implementation evidence. A direct operator target still takes
  precedence over that context.
• If that section marks the target unresolved, report the ambiguity and use an
  explicit operator target before approving; do not invent a numeric fallback.
• If the original plan is already effectively complete, do not repurpose this skill for whole-plan review.
• If the checkpoint looks correct, approve that checkpoint and advance the original plan's review state.
• If the checkpoint is not acceptable, do not approve it. Create a focused non-checkpoint fix plan for the failed checkpoint or behaviors instead of a whole-plan redo.
• If the checkpoint implementation is correct, this review turn owns the checkpoint commit and any reviewer-owned plan bookkeeping needed to approve it.
• Treat a top-level ## User Acceptance Pending section after the checkpoints as a separate owner handoff. Pending items alone are not grounds to reject a checkpoint or request another worker pass; reject for implementation defects, failed required automated gates, or explicit release or approval gates. Report implementation and acceptance separately and never claim full acceptance without user evidence.
• Treat aflow as the canonical spelling.

Core Rule

The original plan file is the source of truth for long-lived review state. Fix plans are temporary non-checkpoint overlays for rejected checkpoint work, not replacements for the original plan.

Required Inputs

Following plan paths should be provided by the prompt;

ORIGINAL_PLAN: This is the original implementation plan.
ACTIVE_PLAN: This maybe same as the original plan file, or could be a transient follow-up plan focused on fixing of review findings.
NEW_PLAN_PATH: This is the path for a possible follow-up plan for the findings of your review.
If you need to create a follow-up fix plan, write it exactly to NEW_PLAN_PATH. Do not invent a different filename.

Before reviewing, identify the active original aflow plan under plans/in-progress/.

Selection rules:

1. If the user names a plan file, use it.
2. Otherwise search plans/in-progress/ for original plan files containing Pre-Handoff Base HEAD.
3. Filter candidates to the current branch recorded in Plan Branch.
4. Ignore temporary fix plans when choosing the original long-lived plan.
5. If exactly one original plan remains, use it.
6. If multiple original plans remain, stop and ask the user which plan to use.

Review Workflow

1. Read the original plan's Git Tracking section and checkpoint state.
2. Confirm the current branch matches Plan Branch.
3. Confirm the checkpoint under review is the pending implementation target or
   that the user explicitly asked for a non-standard review.
4. Determine the review target in this order:
   • honor an explicit operator checkpoint target
   • otherwise use the controller-supplied pending target, including its
     original heading and worker artifact reference
   • otherwise use the next implemented-but-unapproved checkpoint identified
     by the original plan's review markers/log and finalized worker evidence
   • otherwise use a checkpoint commit boundary only when it represents that
     pending checkpoint; an already-approved cpN vNN commit is review base
     context, not the default target
   • otherwise review the current worktree state and say that the fallback was used
5. Review the checkpoint scope from that target through the current code state.
6. Report:
   • the checkpoint/version reviewed
   • whether the review used a commit boundary or worktree fallback
   • the checkpoints and behaviors covered by the reviewed slice
7. Review the actual code state, not just commit messages.
8. When reporting or updating review state, prefer checkpoint/version labels such as "reviewed through cp5 v01". Include exact SHAs only when they materially help disambiguate the history.

Checkpoint Verification

• Independently inspect the changed code, assertions, and coverage against the checkpoint's acceptance criteria. Follow every explicit checkpoint command and observable check in the current plan; a skill or prompt cannot waive one.
• Reuse worker test evidence only when the primary log is inspectable and records the exact command, working directory, tested revision and dirty state, result, and elapsed time. Confirm the relevant source, tests, dependencies, configuration, and environment are unchanged. A summary or claimed pass alone is insufficient.
• Run missing or invalidated focused checks and explain each additional invocation, including why valid worker evidence did not suffice. Do not routinely rerun an unchanged worker check or add a broad suite assigned to cumulative final review. Preserve focused browser and visual coverage required by the checkpoint.
• A failed, interrupted, or missing required check blocks approval. After a fix, rerun affected checks; report any explicit broad checkpoint command that seems misplaced instead of silently weakening or skipping it.

Approval Path

If the checkpoint looks correct:

1. Create the checkpoint approval commit for the reviewed work in this review turn. The first line must use cpN vNN <branch-name>: <meaningful summary>.
2. Advance the original plan's review state for that checkpoint.
3. Update the original plan's lightweight review metadata only when it materially helps later reviewers. Prefer the checkpoint/version commit label as the primary durable marker.
4. Do not squash the whole handoff.
5. Leave the checkpoint commit structure intact unless a later workflow explicitly asks for a different history action.
6. If later checkpoints remain unchecked, keep the original plan in progress for the next checkpoint review or execution pass.
7. Treat dirty changes in plan files that are intentionally part of checkpoint bookkeeping as part of finalization, not as unrelated worktree noise. Still stop if truly unrelated dirty changes remain and make the checkpoint review ambiguous.

Rejection Path

If the checkpoint is not acceptable:

1. Do not approve it.
2. Create a new aflow fix plan that covers only the failed checkpoint or behaviors against the current HEAD.
3. Ensure plans/in-progress/ exists before writing the fix plan. Create it if it does not exist.
4. Write the fix plan exactly to NEW_PLAN_PATH. Keep the content focused on the rejected checkpoint or behavior range.
5. The fix plan must be self-contained, non-checkpoint, and must not require the implementer to read prior chat context.
6. When creating a new fix plan, delete older superseded fix plans for the same checkpoint by default unless the user explicitly asks to keep them.
7. After creating the new fix plan, plans/in-progress/ should contain only the original handoff plan plus that newest fix plan for the same checkpoint.
8. Update the original plan:
   • append a Review Log entry only when it materially helps later review or ambiguity resolution
   • update Last Reviewed HEAD only when it clearly helps and does not create brittle bookkeeping pressure
9. Keep Pre-Handoff Base HEAD unchanged.
10. Do not compact DEVLOG.md and do not squash the whole handoff.

Structural Scope Pressure

If the checkpoint's accepted meaning is clear but review evidence proves the
scope cannot converge as one reviewable execution unit, preserve the work,
leave the checkpoint unapproved, do not rewrite its plan, and emit:

AFLOW_SCOPE_PRESSURE: <concise structural reason>

Use this only for structural indivisibility or oversize, never ordinary
incompleteness, a bounded defect suitable for a fix plan, elapsed time, or a
numeric file/line threshold. The marker advises Full manager evaluation and
does not authorize the reviewer to choose or apply a split.

Use AFLOW_STOP instead for semantic ambiguity, conflicting requirements,
safety or ownership boundaries, destructive handling of user changes, or
another hard blocker requiring human intervention. A real AFLOW_STOP is
terminal and takes precedence over scope pressure.

Stop And Escalate If

• no original aflow plan with Git Tracking can be found
• the current branch does not match the plan's Plan Branch
• Pre-Handoff Base HEAD is missing or no longer reachable
• the worktree has unrelated dirty changes that make the checkpoint review ambiguous
• multiple original plan files are plausible and the active one cannot be determined safely

Verification

Before finishing, verify:

• the reviewed range is correct relative to the original plan's checkpoint/version review history and any helpful support metadata such as Last Reviewed HEAD or Pre-Handoff Base HEAD
• the reviewed target was the latest checkpoint commit when that boundary was available
• the fallback to current worktree state was only used when the checkpoint commit boundary was missing or ambiguous
• the reported commit counts match git history when a commit boundary is available
• after approval, the original plan's review state advances only for the reviewed checkpoint
• after approval, the checkpoint commit was created by the reviewer in the same turn and its first line includes the branch name plus a meaningful summary
• after rejection, no history rewrite occurred
• after rejection, plans/in-progress/ contains only the original handoff plan plus the newest focused fix plan for that checkpoint
• after rejection, superseded older fix plans were deleted unless the user asked to keep them
• DEVLOG.md was not compacted by this workflow