Taskforge run

taskforge-run

Implement the active Specification, then submit the work to an independent reviewer in a fresh context. Run finishes a task or escalates it — it never quietly lowers the bar and never expands scope.

Bundled vs split (docs/ADR-0001 Phase 6). This skill bundles implement + review + done in one pass — the manual, human-driven path. Orchestrated flows use the split capabilities taskforge-implement and taskforge-review (one responsibility each; the kernel routes on the review verdict). Run remains fully supported; the split is the preferred path for autonomy.

Prerequisites: read taskforge/CONTRACTS.md this session; resolve $SCRIPT; guard on readiness (run required).

1. The spec is the whole contract

python3 $SCRIPT show <id>. The active specification — not the description, not your memory of the conversation — is what you implement and what the reviewer judges. Spec vs description conflict? The spec wins; note the conflict in your report. Record the spec's version; you cite it in artifacts. Check python3 $SCRIPT budget <id> if resuming a task with prior rejections.

2. Implement

Plan briefly, then work on the right line (git repo):

• A standalone task owns its delivery — branch taskforge/<task-id>, recorded so provenance isn't prose: $SCRIPT link <id> --branch taskforge/<task-id>.
• A child of a decomposed feature runs on the feature branch and does not link its own — delivery is inherited from the nearest owning ancestor (DESIGN §10.19), so the whole feature ships as one branch/PR. Only link <id> --branch … a child when it genuinely ships on its own line (break-out). If the feature isn't linked yet, link the parent's branch once.

Run the tests.

Scope discipline is binding. Adjacent problems you notice — flaky tests, dead code, missing validation elsewhere — become follow_up entries in your result, described to stand alone. Never extra diff: the reviewer should see nothing the spec didn't ask for.

Upstream discoveries end the attempt immediately — don't push through a broken contract:

• spec ambiguous/contradictory/unimplementable → signal: escalate_refine, the defect named precisely;
• the spec's factual premise is provably false and you have a reproduction → signal: spec_invalidated, signal_reason the claim, plus an invalidation object {reproduction, observed} (a command and the output it should produce). The kernel verifies the reproduction before routing to refine — an unverified claim bounces back, and repeated crying-wolf parks the task (docs/ADR-0001 §9 Phase 5). Use this over escalate_refine when the problem is a fact you can demonstrate, not a judgement;
• the approach itself cannot work → signal: escalate_explore;
• blocked on something only a human can resolve → signal: block_on_human.

Include artifacts already produced and all follow_ups in the escalation result — partial evidence is still evidence.

3. Independent review — recorded, isolated, non-negotiable

Follow taskforge/references/reviewer-prompt.md exactly: write the diff and the test results to two files, then let the engine assemble and record the prompt — build-review-prompt <id> --diff <diff-file> --results <results-file> (it renders the active spec verbatim, so you never hand-serialize it and escaping can never desync the prompt from what audit-review checks). Spawn a fresh-context subagent (Task tool) with the built prompt from the returned file; one re-ask on malformed output, then block_on_human — never guess a verdict, never self-review. audit-review will later verify your recorded prompts deterministically; a review without a recorded prompt is flagged as an isolation failure. Record the verdict verbatim as the review artifact, including rejections you disagree with (disagree in the report, not the record).

4. Route on the verdict

• approved → template run-approved.json, signal: done.
• rejected / implementation → fix and retry: feed back the reviewer's findings list only; re-test; new fresh-context reviewer (new recorded prompt, next version number). Budget: max_review_retries from $SCRIPT config (default 2 retries, 3 attempts). All attempts' implementation + review artifacts go in the final result, in order. The engine enforces the budget — a rejection beyond it parks the task automatically; your signal: block_on_human on exhaustion states the unresolved findings.
• rejected / specification → emit the review artifact with root_cause: specification (template run-rejected-escalate.json), signal: none. The kernel supersedes the specification and routes to refine — the routing is derived from the review verdict, not a signal you emit (Gap B, docs/ADR-0001 §8).
• rejected / architecture → emit the review artifact with root_cause: architecture, signal: none. The kernel sets the explore escalation and, for a child task, escalates its parent. Do not emit an escalate signal; the verdict carries the route.

5. Emit, apply, sync, report

Fresh result_id; validate then apply with --actor run. If you opened a PR, record it on the delivery owner (the feature for a child, else this task): $SCRIPT link <owner-id> --pr <ref>. Terminal + external source → sync per taskforge/references/sync.md (with its honesty rule) — note that done comments, it does not close the issue. Report per reporting.md: attempts, verdicts, root causes, follow_ups, final readiness. No merging/deploying beyond the spec's own criteria; no starting generated tasks. done is not merged: the issue closes only when the code lands (link <owner> --landed, which the engine refuses until every descendant is closed), after the PR merges — often a later session, not here.

Quality bar

• Recorded reviewer prompts pass audit-review (criteria present verbatim; implementation summary absent).
• Every acceptance criterion appears in criteria_results with explicit pass/fail.
• Retries change the code, not the reviewer's standards; never retry specification or architecture rejections.
• The diff contains nothing the spec didn't ask for.