task-completion-loop

Task Completion Loop

Converge existing plan / spec / partial work intoa verifiable end state on the same final code snapshot。

This Skill is thin orchestration: dependent skills own the internal protocols; this Skill only manages the task ledger, invocation order, evidence freshness, authorization boundaries, and stop conditions.

Entry and Authorization

Start only when all of the following are present:

1. A Git repository, and a named plan/spec or a clear scope determinable from the current code.
2. An explicit request for a complete closed-loop implementation. Goal only, review-fix-re-review only, architectural hardening only, ordinary implementation, pure discussion, pure review, or read-only diagnosis → not this Loop.

First parse scope from documents and code. When it still cannot be determined safely, ask exactly one scope question and stop. Defaulting to the entire repository is forbidden.

The implementation request authorizes modifying the working tree within the frozen scope; unless the user explicitly requests read-only or forbids edits. It does not authorize:

• git add, commit, push, merge, rebase, branch/worktree creation;
• PRs, issues, comments, messages, tasks, API data, deployment, production writes;
• Excluded paths or modifications outside the frozen scope.

agentic-review-handoff required for .review-handoff/** and idempotent $GIT_COMMON_DIR/info/exclude entries are local protocol artifacts of this closed loop, not delivery actions; disclose them at preflight and record them in the completion report. When the user explicitly forbids .git/** writes, return before modifying source code HUMAN_GATE。

Capability Preflight

Always required:

Capability	Purpose
goal-gate	Goal decisions and runtime activation
agentic-review-handoff	Independent review-fix-re-review
architecture-hardening-loop	Bounded scan, fix, re-review, re-scan
Real Peer A session	Independent stance and cross-questioning
Real Peer B session	Independent stance and cross-questioning
Real Claude Code session	Blind review

Only when the user explicitly requires grill-with-docs, or preflight finds product/domain decisions still owned by the user, require and invoke grill-with-docs(its frontmatter defaults to disable-model-invocation: true; if the file is readable, load it along the parent session path).

Before discussion, Goal, or source modification:

1. Resolve each skill and its transitive hard dependencies (in particular, architecture-hardening-loop 's scanner,codebase-design, read-only delegation, and a real adapter for non-host Reviewers). For invocation policy and parent-session execution paths, follow the rules in architecture-hardening-loop"Hard Dependencies and Runtime Capabilities": the user naming this Loop authorizes nested invocation of hard dependencies by purpose; if the file is readable, the parent session can execute it; only uninstalled/unreadable, contract-incompatible, or worker/tool cannot execute counts as missing. For details, see decision-and-terminal-gates.md 's Preflight policy.
2. Select Peer A and Peer B (see "Peer Selection" below), and for each Peer use agentic-review-handoff 's review-loop consult --repo <root> --peer <product> [--fallback <未用的产品>] --question-file <md> to complete one real round trip (when the user names an account such as codex002 / cc002 / grok002 , add --peer-command=<名字>), and use review-loop sessions --repo <root> --product=<product> to retrieve the resumable handle; Phase 1 A's first successful round trip can serve as this evidence and does not occupy a separate round. Every Peer must be launchable under the adapter's read-only control; likewise for the Claude used for blind review. A name alone, a catalog entry, or the mere existence of a CLI file does not count as available.
3. Confirm that review protocol artifacts can be written and do not conflict with the user's .git/** restrictions.

Peer Selection: Peer A and Peer B are two products different from the host. According to the Reviewer preference order saved in agentic-review-handoff (review-loop prefs, default claude,codex,grok), remove the host and take the first two: three-way convergence requires three different products, so the host is always skipped here, and skipHost in the preferences does not matter. For example, under the default preferences: Claude host → Codex + Grok; Codex host → Claude + Grok; Grok host → Claude + Codex. Products or accounts named by the user take priority. consult can directly pass --host=<宿主> --skip-host, and the script selects by preference. If a Peer times out, the script switches according to --fallback to an installed product not used by either Peer or the host ( fallbacksin the result); if there is no such product, do not switch, and handle it according to the timeout rules below. Do not substitute the product of the other Peer, otherwise the two positions would no longer be independent.

Missing a capability that is always required, or missing a conditional capability actually needed in this round:

Task Completion Result
- Result: MISSING_DEPENDENCIES
- Missing: <exact skill, dependency chain, or runtime capability>
- Stop point: before discussion, Goal activation, and source changes
- Substitution/install: none; no generic agent impersonation, copied skill logic, or automatic install
- Work started: no

It is forbidden to use a generic subagent to impersonate a Peer or the Claude of a blind review, forge sessions, or copy the logic of a missing skill: the value of three-way convergence comes from genuinely independent model positions, and impersonation would degrade cross-questioning into self-commentary. Installing dependencies on behalf constitutes an external write, see "Entry and Authorization".

State machine

预检与任务账本
  -> 三方交叉质疑
  -> 条件式 grill-with-docs（用户决策）
  -> Goal Gate
  -> 实现全部 PENDING + 验证
  -> agentic-review-handoff
  -> architecture-hardening-loop = NO_ACTIONABLE_FINDINGS
  -> 全新只读 Claude 盲审
       -> Fix：修、验、重跑下游门禁、再盲审
       -> 仅 Backlog / Reject：完成 Goal
  -> COMPLETED

任意阶段的出口：
  缺能力 -> MISSING_DEPENDENCIES
  用户决策 / 权限 / 范围扩张 -> HUMAN_GATE
  证据缺失、过期或外部会话超时 -> UNVERIFIED

Phase 0: Task ledger and evidence

1. Read repository instructions, plan/spec, directly related decisions, current code, and tests.
2. Record the repository root, branch, HEAD, and working tree; preserve existing changes, and do not reset / clean unrelated content.
3. Mark each item of work in the original plan:

Status	Evidence
VERIFIED_DONE	Current code and reproducible verification in this round prove it has been delivered
PENDING	Still must be implemented or fixed in this round
OBSOLETE	Superseded by a valid decision or new contract, with the source cited
EXCLUDED	Explicitly excluded by the user or valid documentation
HUMAN_DECISION	No authoritative answer yet, and the choice would change product behavior, public contracts, data ownership, security, or frozen scope, or require new external authorization

The frozen scope includes all of this round's PENDING and the necessary tests/documentation. It may be split into cohesive batches in dependency order, but it must not claim the plan is complete after finishing only the first easy batch.

The original PENDING must not be surreptitiously replaced by reviewer suggestions with Backlog：Backlog : the latter is the reviewer's classification of new findings; the attribution of items promised by the plan belongs only to the user or valid decisions. It can only be completed, superseded by a valid decision, explicitly excluded, or moved into HUMAN_DECISION。

Reversible, in-scope implementation details and test choices that do not change already-decided behavior still belong to the corresponding PENDING, not HUMAN_DECISION. Decide on your own according to authoritative documentation, current code, repository conventions, minimal changes, and verification quality; disagreement among agent opinions does not itself constitute a gate.

Formal evidence ids use the evidence object returned by agentic-review-handoff , and equality compares only baseSha + pathFilter + digest. Prefer reusing the frozen evidence of dependent skills, but before and after every gate, review-loop evidence must be re-run with the same base/filter to recompute; the same HEAD or the same git status does not equal the same snapshot. Any in-scope code or test modification invalidates the downstream test/review/audit conclusions of the old snapshot.

Phase 1: Three-way convergence and user decision

A. Independent positions

The host, real Peer A, and real Peer B each read the same set of documents, code, and task ledger. Each side writes clearly the scope, attribution, assumptions, risks, exclusions, and falsifiable verification. Use review-loop sessions Record recoverable handles for both Peers; the first successful round trip in this step also completes precheck item 2.

Budget and parallelism

• A's three-party positions are mutually independent: when the host writes its own position, launch Peer A and Peer B in parallel.
• B's two cross-examinations are mutually independent; launch them in parallel. B runs at most two rounds; if disagreements remain after the second round, those that are technical defaults are adjudicated by the host based on evidence, and those that are user decisions move to C.
• Set a deadline for each external call (by default consistent with agentic-review-handoff 's Reviewer timeout, 20 minutes; the host may shorten it and record that). Launch as a background process and wait per the next item, to avoid the host's foreground tool timeout truncating the real session. While the process is alive, do not kill it or resend; on timeout, first have --fallback swap in someone else (see "Peer selection"); only if there is no one to swap in, handle it per DELIVERY_UNKNOWN : retry once with the same parameters only if local evidence proves nothing was submitted; otherwise record UNVERIFIEDfor this stage, keep the handle and the positions already obtained, and continue from the missing side in the next round.
• Wait for a background external call to finish: preferably wait on the PID recorded at launch (e.g. review-loop consult ... > out 2>&1 & echo $! > pid, then while kill -0 "$(cat pid)" 2>/dev/null; do sleep 15; done), or use the host's built-in background task completion notification. Do not use pgrep -f / ps | grep to poll by a string that the wait command itself also contains: it will match the waiting script itself and the loop will never end; if the pattern must be used, write it in bracketed form such as [r]eview-loop so it cannot match itself.
• Fast path: when the ledger has no HUMAN_DECISION, the scope is uniquely determined by the plan/code, and A's three parties have no substantive disagreement on scope/ownership/verification, B runs only one round and converges if there are no new disagreements. The fast path does not reduce participants and does not omit B.

B. Cross-examination

• Give the host + Peer B positions to Peer A; give the host + Peer A positions to Peer B.
• Both sides attack the other's strongest argument and are allowed to change their positions based on evidence.
• The host independently opens the cited paths, verifies current behavior, and then synthesizes the evidence.

Three parallel commentaries do not count as convergence: only arguments that still hold after being attacked by the other side are evidence.

C. User decision

• If authoritative documents and code already give the answer, or only ordinary technical defaults remain: converge on your own, do not ask again.
• Genuine HUMAN_DECISION: even if the user says "don't ask", this does not expand product decisions or external write authorization (see "Entry and authorization"); Agent consensus cannot substitute for the user.
• When a real user decision or an explicit grill-with-docs appears, first read decision-and-terminal-gates.md 's Human decision convergence, then decide whether to return HUMAN_GATE. Ask per grilling's frontier round: the same round may contain all mutually independent questions, and each question comes with a recommended answer, so the user only makes trade-offs without re-investigating.

Record:

Three-party Convergence
- Decision:
- Why:
- Work ledger:
- Frozen scope / exclusions:
- Ownership and dependency direction:
- Verification:
- Peer A (product) session:
- Peer B (product) session:
- Fallbacks: none | <from → to, reason>
- Remaining decisions: none | <list>

Phase 2：Goal Gate

After convergence, call goal-gate, strictly obey its Decision / Next：

• wait for user /goal、ask approval or defer: return HUMAN_GATE and stop. Generating the prompt does not mean the Goal is activated.
• suggest + adopt goal and continue: continue this Loop per the transcript contract, report Goal: not-created；suggest + provide prompt / route elsewhere: return HUMAN_GATE。
• Existing Goal: compare objective, frozen scope, Done condition, and completion owner from native tools, product state, or a verifiable parent contract passed in by the caller; the native getter is not the only source of evidence. For the ownership relationship and completion rights, see decision-and-terminal-gates.md 's Goal ownership; only on conflict or insufficient evidence defer。
• When activatable or adoptable, Goal covers the task ledger, frozen scope, verification, three gates, protocol writes, and external write boundaries.

Done condition requires: the ledger has no PENDING / HUMAN_DECISION; verification and the three gates cover the same final evidence id. Only created-by-loop / exact-same-goal is completed by this Skill;broader-compatible even if this Loop has completed, keeps the parent Goal active and reports Goal: active-checkpoint。

Phase 3: Implementation and verification

Process all in dependency order PENDING：

1. turn into observable success criteria; when a behavior change is feasible, first show a failing reproduction.
2. Make the smallest cohesive change; do not opportunistically do adjacent backlog items or speculative abstraction.
3. Run targeted checks first, then related package/repository checks.
4. For externally visible behavior, use real runtime signals such as browser, CLI, logs, rendering, or request/response.
5. Only after evidence passes, mark VERIFIED_DONE, and sync the plan / current-state documentation.

Required evidence that was not run, failed, or is stale is recorded as UNVERIFIED, and cannot count as passed.

Phase 4: Three gates

Before starting or resuming this phase, read decision-and-terminal-gates.md 's three terminal contracts; the dependencies own the internal state machines, and this Skill only checks the terminal state, evidence id, and parent Goal ownership.

1. agentic-review-handoff: default completion=pass; continue only when the final PASS / NO_FINDINGS covers the current evidence id.BLOCKED、concerns_require_fix, review-only, and exception paths are in the reference.
2. architecture-hardening-loop: run in the same scope, accept only NO_ACTIONABLE_FINDINGS; its HUMAN_GATE / MISSING_DEPENDENCIES / UNVERIFIED is passed through as-is as this Loop's same-named Result. Its modifying files invalidates the old evidence id; if its internal review covers the final evidence id, it can be reused without rerunning the direct review. Fix and ownership paths are in the reference.
3. Fresh Claude blind review: use a new verifiable read-only session to review the final evidence id. In-scope Fix triggers a minimal fix and rerun of all downstream gates; at most 2 rounds.

Unattended continuation

Only for unattended / autonomous operation; human-in-the-loop sessions where a person is present to answer do not apply this.

• A turn that ends with plain text is a progress report, not completion evidence. The task ledger is the checklist, updated every turn; if at the end of a turn there is still PENDING and no blocker is stated, continue, or have the host / parent session send a short message naming the unfinished item. Auto-continue the same task at most 2–3 times, then stop for review (returning UNVERIFIEDper the budget rules below), letting the genuinely stuck run end.
• While background commands, subagents, or Peer / Claude sessions started by this Loop are still running, wait for them to finish and retrieve their output; do not treat the task as complete.
• Premature stops that should not occur: (1) a long summary only announcing the next step with no tool call; (2) proposing "I'll continue unless you have other plans" and waiting for a reply; (3) listing items for user decision, but by your own judgment none of them blocks the remaining work; (4) stopping to report because the turn is too long or a milestone is complete. Put status notes and suggestions in the same message as the next tool call. Should stop: cannot proceed without the user (HUMAN_GATE), or the blocker is something deliberately protected. This section does not replace confirmation for high-risk / destructive actions, nor does it expand "entry and authorization".

Terminal state and reporting

Result	Usage conditions
COMPLETED	The ledger has no open items; required verification passes; the three gates cover the same final evidence id; the final blind review has no in-scope Fix; the owned Goal has completed, or the parent Goal remains at active-checkpoint
HUMAN_GATE	wait for a user-owned product/domain decision, Goal activation/conflict, permissions, credentials, external state, scope expansion, or an explicit review-only decision
MISSING_DEPENDENCIES	the precheck lacks a capability that is always required or actually needed for this round; the source code has not yet been modified
UNVERIFIED	the implementation may exist, but required evidence has not been run, has failed, or has expired; or an external session DELIVERY_UNKNOWN / a timeout caused this round's stance, re-review, or audit evidence to be missing (keep the handle, and continue from the missing party in the next round); the Goal must not be completed

The Phase 1 deadline, the number of B rounds, and the 2 rounds of blind review in Phase 4 are the entire budget of this Skill. Running out of budget is neither a reason for completion nor a user decision: it does not change whether the code is correct, and the user has no substantive trade-off to make. If the host can continue running, continue; when control must be handed back, return UNVERIFIED, keep the Goal active, and continue from the incomplete evidence without requiring the user to re-authorize.

Cross-task experience

Experience directory:${AGENT_LESSONS_DIR:-$HOME/.local/state/agent-lessons}/task-completion-loop/, one per <slug>.md. It is outside the skill directory, so updating the skill will not overwrite it, and it will not enter the repository.

• After reading the repository instructions in Phase 0, list that directory and read-only the entries whose cue matches the shape of this task. Experience is only a hint; when it conflicts with the current code, evidence, or user decisions, the latter prevail.
• Before the final report, write at most one new experience entry; if any of the three items is missing, do not write it:
  • cue: what shape of situation it applies to. Write the shape of the situation, not file names, function names, or business facts from this repository.
  • lesson: what approach or pitfall was learned this time.
  • evidence: which evidence id, gate, or blind review conclusion proves it, and which two approaches are being compared.
• Something is not an experience merely because the result is COMPLETED ; if there is no comparable evidence, do not write it. If it duplicates an existing entry, update that entry instead of adding a new one.
• Experience files must not contain review scores, credentials, or user private data.

Task Completion Result
- Scope / exclusions:
- Work ledger:
- Three-party decision:
- Goal: <completed | active-checkpoint | not-created | deferred-conflict>
- Final evidence id:
- Implemented:
- Verification:
- Agentic review: <packet/session + evidence id>
- Architecture hardening: <result + evidence id>
- Final Claude audit: <fresh session + evidence id>
- Fixed / Backlog / Rejected:
- Protocol, Git, and external actions:
- Lessons: <读取的条目 | 新写或更新的条目 + evidence | none（理由）>
- Result: COMPLETED | HUMAN_GATE | MISSING_DEPENDENCIES | UNVERIFIED