Teach verification order in instructions, gate message, and docs

Author: ihorponom

docs/TASK-PASSPORT.md

@@ -200,6 +200,18 @@ historical so they are not mistaken for active instructions.
 
 The normal human-facing sequence is: start the task, keep status/scope/next actions current, record verification with evidence, print a handoff when another agent or chat may continue, then finalize only after verification is final.
 
+The verification order matters: iterate checks while verification is `pending`
+and fix freely; when no edits remain, commit the in-scope changes and confirm
+the commit changed nothing (clean tree, hooks silent) before recording the
+final verdict. From there the task has two endings. With no external wait, end
+with one `task finalize --status passed` call carrying evidence and the commit
+hash, so no `verifying` window opens. With an external wait (review, PR merge,
+re-score), record `passed`, then `task park`; after the external result,
+finalize — or return verification to `pending` if changes are needed. A
+recorded final verdict moves the task to `verifying` and freezes code changes;
+to commit already-verified changes from there, set verification back to
+`pending`, commit, then re-record the verdict.
+
 Temporary work switching uses `task park`, not `task finalize`. Parking keeps a
 passport open and switchable while unrelated work becomes current. Finalization
 means the task is complete, failed, or explicitly accepted as-is.

src/core/gate.ts

@@ -192,7 +192,7 @@ function collectGateFiles(root: string, options: GateOptions): { files: string[]
 
 function taskNotActiveMessage(status: TaskStatus): string {
   if (status === "verifying") {
-    return "Current task is verifying. Finish or record verification before editing code, or park it for unrelated work.";
+    return "Current task is verifying: a final verdict is recorded and code changes are frozen. Finalize the task; to commit already-verified changes, set verification to pending, commit, then re-record the verdict. Park the task for unrelated work.";
   }
   if (status === "parked") {
     return "Current task is parked. Switch to it, or start the task this work belongs to.";

src/integrations/install.ts

@@ -85,7 +85,10 @@ Task lifecycle gate:
 - treat review mode as a scope check, not an automatic new Task Passport: keep reviews that verify the current active/verifying task inside that task as evidence/checkpoint; park, switch, or start a separate review task only for unrelated reviews
 - park deferred work with \`task_park\`/\`task park\`, or switch/close only when appropriate, before starting unrelated work
 - do not finalize a task just to free the current slot; finalization means verification is passed, failed, or explicitly accepted as complete
-- finalize after the task's changes are committed; park a verified task that is still waiting for review or commit instead of closing it
+- verification order: iterate checks with verification pending and fix freely; when no edits remain, commit the in-scope changes and confirm the commit changed nothing (clean tree, hooks silent) before recording the final verdict
+- no external wait: end with one \`task_finalize\` call carrying the final status, evidence, and commit hash, so no verifying window opens
+- external wait (review, PR merge, re-score): record \`passed\` via \`task_update_verification\`, then \`task_park\`; after the external result finalize, or return verification to pending if changes are needed
+- a recorded final verdict moves the task to verifying and freezes code changes; to commit already-verified changes from there, set verification back to pending, commit, then re-record the verdict
 - keep next actions current: clear or replace a stale plan (\`task update --clear-next-actions\`) before finalizing, so closed passports read as history, not as open work
 - if a task still has next actions and must pause for unrelated work, park it instead of using \`task_finalize\`/\`task finalize --status accepted\`; force accepted finalization only when the remaining next actions are intentionally historical
 - do not mutate a review task into implementation work

tests/agentpack.test.ts

@@ -2454,7 +2454,9 @@ test("previews and writes project-local MCP client install files", () => {
   assert.match(readFileSync(path.join(dir, "AGENTS.md"), "utf8"), /checkpoint mode: summarize what was decided/);
   assert.match(readFileSync(path.join(dir, "AGENTS.md"), "utf8"), /Task lifecycle gate/);
   assert.match(readFileSync(path.join(dir, "AGENTS.md"), "utf8"), /declare a write scope when starting a task/);
-  assert.match(readFileSync(path.join(dir, "AGENTS.md"), "utf8"), /finalize after the task's changes are committed/);
+  assert.match(readFileSync(path.join(dir, "AGENTS.md"), "utf8"), /commit the in-scope changes and confirm the commit changed nothing/);
+  assert.match(readFileSync(path.join(dir, "AGENTS.md"), "utf8"), /one `task_finalize` call carrying the final status, evidence, and commit hash/);
+  assert.match(readFileSync(path.join(dir, "AGENTS.md"), "utf8"), /record `passed` via `task_update_verification`, then `task_park`/);
   assert.match(readFileSync(path.join(dir, "AGENTS.md"), "utf8"), /keep next actions current: clear or replace a stale plan/);
   assert.match(readFileSync(path.join(dir, "AGENTS.md"), "utf8"), /verifying, blocked, closed/);
   assert.match(readFileSync(path.join(dir, "AGENTS.md"), "utf8"), /keep reviews that verify the current active\/verifying task inside that task/);
@@ -2696,7 +2698,7 @@ test("pending verification returns lifecycle to active instead of getting stuck
   assert.equal(passedPassport.status, "verifying", "a final verdict moves the lifecycle to verifying");
   const warnOutput = run(dir, ["task", "gate", "--file", "src/a.ts"]);
   assert.match(warnOutput, /Gate: warn \(mode: warn\)/, "the gate warns while a final verdict is under review");
-  assert.match(warnOutput, /Current task is verifying\. Finish or record verification before editing code, or park it for unrelated work\./);
+  assert.match(warnOutput, /Current task is verifying: a final verdict is recorded and code changes are frozen\. Finalize the task; to commit already-verified changes, set verification to pending, commit, then re-record the verdict\./);
 
   assert.match(run(dir, ["task", "verify"]), /Updated verification for task .* \(pending\)/);
   const pendingPassport = JSON.parse(run(dir, ["task", "passport"]));