PACT task-completion authority redesign: lead is the acceptance gate for all task completions

[michael-wojcik]

Summary

Establish a new PACT-wide convention: teammates never mark their own tasks as completed. The lead is the authoritative completion signal for all tasks. This reshapes the task-system's authority model and — as a consequence — cleanly replaces the cooperative-halt teachback protocol that was empirically falsified in PR #477 round-8 dogfooding.

Supersedes #489.

---

Central Rule

Teammates never self-complete tasks. When a teammate finishes work, they write their HANDOFF to task metadata and leave the task in in_progress. The lead reads the HANDOFF, judges whether the work is acceptable, and marks the task completed only if so. Otherwise the lead writes corrections/feedback and the teammate revises (task stays in_progress through revision cycles).

This applies to every PACT task, not just teachbacks. It's a convention change to the entire task-system's authority model.

---

How this reshapes teachback specifically

The current failure (empirically documented)

PR #477 cycle-10 shipped a cooperative-halt teachback protocol: teammate sends teachback_submit metadata, then waits passively for lead's teachback_approved metadata/SendMessage reply before starting work. Round-8 dogfooding caught two distinct livelock failure modes (3 teammates stuck):

• Mode 1 (reader-path): Teammate waits for approval in metadata; TaskGet doesn't surface metadata field; approval invisible via documented reader-path.
• Mode 2 (mailbox-refresh): Teammate submits teachback, idles, waits for SendMessage reply. Reply delivered but teammate's working context never refreshes to see it. 100+ TeammateIdle hook fires elapse with no progress.

Both failure modes are consequences of the same root cause: cooperative halt × platform mailbox/context-refresh semantics = livelock. See comment on #489 for the full failure-mode catalog.

The new model under this redesign

Lead dispatches a teammate with two tasks:

• Task A (teachback) — small, scoped for the teachback ritual
• Task B (primary work) — blockedBy=[A]

Flow under the central rule (teammates never self-complete):

1. Teammate claims A, writes teachback content to A's metadata/handoff
2. Teammate does NOT mark A completed — leaves it in_progress
3. Lead reads A's metadata, judges the teachback
4. Lead marks A completed if approved → blockedBy edge unblocks B automatically, B appears in TaskList as claimable
5. OR lead writes corrections to A, leaves it in_progress → teammate revises A, loop
6. Teammate claims B, does the work, writes HANDOFF to B's metadata, leaves B in_progress
7. Lead reads B's HANDOFF, judges the work
8. Lead marks B completed if accepted, OR writes feedback and leaves B in_progress → teammate revises

No passive wait, no mailbox-refresh dependency, no custom reader-path. Task status transitions ARE the authority signal. Directly observable via TaskGet/TaskList.

---

Why this kills both livelock failure modes

Mode 1 obsolete: approval is Task A's status == completed, directly observable via TaskGet. No custom metadata-reader-path.

Mode 2 obsolete: teammate doesn't 'wait for a reply' — they submit content and either claim the next claimable task or idle because they have none. When lead completes A, B becomes claimable via normal TaskList polling. The platform's existing claim-next-task mechanism handles the wake-up; no custom protocol needed.

---

Design questions for plan-mode

1. Who currently self-completes? Audit: which PACT workflows today have teammates self-completing tasks? Secretary consolidation tasks? Reviewer review tasks? Cycle-fixer commits? All of them need to switch to lead-completion.

2. Hook impact: handoff_gate.py (TaskCompleted hook) currently blocks teammate completion without HANDOFF. Under new rule, does this hook fire on the LEAD'S completion instead? Does the lead need a lead-specific version of the hook? Or does handoff_gate get retired because HANDOFF is now authored pre-completion by the teammate, not at completion-time?

3. TaskCompleted hook semantics: fires on any transition to completed. Under new rule, it fires only when lead transitions a task. Does its logic (memory-save prompt, teammate-role learnings) need to change?

4. Teammate idle behavior when no claimable task exists: if teammate has submitted HANDOFF and lead hasn't reviewed yet, teammate idles with no work. Good? Or does the lead need a default queue behavior?

5. Parallel dispatch shape: lead spawns 3 reviewers. Each gets 2 tasks (teachback + review). 6 tasks total upfront, lead reviews each teachback as it lands, completes them in whatever order. Is there a coordination issue if the lead is busy reviewing teachbacks while primary tasks are blocked?

6. Teachback content shape: cycles 9+9b (PR docs(#401): universal teachback ritual + hard-rule tone (salvage from #477) #490) define the structured content of teachback_submit and teachback_approved. Under this redesign, teachback_submit lives in Task A's metadata (unchanged); teachback_approved becomes Task A's status == completed + whatever resolution content the lead chose to write. The approval content might not need 5 sub-fields anymore — completion-status + optional resolution comment may suffice.

7. Correction flow mechanics: when lead rejects a teachback, how does the correction reach the teammate? Write to Task A's metadata? SendMessage? Both? (This is the same design decision as current protocol, just now applies to lead→teammate rejection rather than cooperative halt.)

8. What happens to teachback_check.py + teachback_gate.py + teachback_scan.py? The mechanical enforcement layer built in cycles 1-8 was designed against cooperative-halt semantics. Under this redesign, much of it may become obsolete, repurposed, or kept as belt-and-suspenders validation ("teammate wrote well-shaped content, even though gate is task-completion-based").

9. What does the Phase 2: flip teachback_gate to blocking mode (follow-up to #401) #481 Phase-2 flip become? Under the new model, there's no 'advisory vs blocking' mode flag at the gate — blocking is inherent in the task-graph. Phase-2 may become a different kind of transition.

---

What survives from cycles 9+9b (PR #490)

The content/tone work is mostly independent of the completion-authority rule:

• Structured sub-fields of teachback_submit (4 fields) — unchanged; still lives on Task A's metadata
• Hard-rule MUST tone for what teammates produce — unchanged; teammate still MUST produce teachback content
• Universal-at-every-dispatch norm — unchanged
• Pask's CT framing in pact-ct-teachback.md — unchanged

Needs review under new model:

• Structured sub-fields of teachback_approved (5 fields) — may compress or change; lead's acceptance is now a task-status transition, not a metadata write. Some of the 5 sub-fields may still be useful as resolution comments; others may be redundant.
• The specific marker phrase "Do NOT begin work until the lead sends teachback_approved" — needs rewording to match new semantics ("Do NOT begin Task B until Task A is completed by the lead" or similar).

PR #490 is currently open but should wait for this redesign's plan-mode output before merge, since the approval-side content may change.

---

Scope implications

This is a bigger redesign than the prior #489 framing. The prior framing treated the redesign as teachback-specific. The central rule 'teammates never self-complete' affects every PACT workflow. Migration is bigger than anticipated. Plan-mode should assess:

• How many PACT skills/commands reference teammate-side TaskUpdate(status='completed')?
• What's the migration story — big-bang convention change or gradual?
• Are there teammate-types that genuinely need to self-complete (e.g., secretary memory-save tasks that are purely internal)?
• What changes at the hook layer?

Variety estimate (plan-mode will refine): 10-12 (High). Higher than the prior #489 framing because scope is now PACT-wide, not teachback-specific.

---

Relation to other open items

• Codify variety-tiered blocking teachback using variety_scorer.py as backbone #401: original teachback gate issue. This redesign provides the mechanism to fulfill Codify variety-tiered blocking teachback using variety_scorer.py as backbone #401's intent.
• feat(#401): variety-tiered teachback gate with generation-shaped content validation #477: parked PR shipping cycles 1-10 of the old model. Cycles 1-8 (mechanical scanner) may mostly survive; cycle-10 (cooperative halt) is replaced by this redesign.
• Phase-2 prerequisite: integration test for blocking-mode submit-only→exit-2 path with real metadata #487 (Phase-2 integration test): still binding; test may reshape under new model.
• Phase-2 prerequisite: validate teachback_approved payload shape (not just key presence) #488 (payload shape validation): still binding; validation surface may shrink under new model (lead's acceptance replaces scanner-based approval validation).
• handoff_gate + teammate_completion_gate should learn teachback_pending/awaiting_approval state #486 (hook state-awareness for awaiting_approval): obsolete under this redesign — no awaiting_approval state exists. Close as obsoleted.
• Phase 2: flip teachback_gate to blocking mode (follow-up to #401) #481 (Phase-2 flip): redefined under new model; no mode flag in the task-graph approach.
• PR docs(#401): universal teachback ritual + hard-rule tone (salvage from #477) #490 (salvage): hold pending this redesign's content-reconciliation decisions.
• Redesign teachback protocol: task-graph-native blocking (replace cooperative halt) #489: superseded by this issue. Closing with pointer here.

---

Approach

Fresh /PACT:plan-mode session for this issue. Full 5-specialist consultation. Plan output saved to docs/plans/<N>-completion-authority-redesign-plan.md. Expect the plan-mode session to be 2-3 hours given the scope.

[michael-wojcik]

Planning principle note from #497 session (2026-04-21)

During PR #501 (the #497 tactical livelock fix, tracker for the redesign this issue supersedes), we surfaced a planning-methodology principle worth applying to #491's design:

For any change that introduces or modifies a protocol primitive (metadata, hook, dispatch convention, workflow phase): explicitly ask "what changes for teammates? what changes for the lead?" Every primitive has at least two operational surfaces; both need instruction coverage. A fix that instruments only one side leaves the other side inferring — an agent-reader failure mode that only surfaces in dogfooding.

Live precedent from PR #501: the original PR shipped teammate-side intentional_wait SET/CLEAR contract (in pact-agent-teams/SKILL.md) without the lead-side "what now?" guidance (silent teammate = waiting not stuck; lead tracks outstanding waits; lead reads metadata via task file since TaskGet doesn't surface it). The gap was caught mid-session and fixed via commit a75c469 adding a parallel Intentional Waiting (orchestrator responsibilities) section to skills/orchestration/SKILL.md.

Relevance to #491: #491 is expected to touch more protocol primitives than #497 did — "teammates never self-complete; lead is authoritative completion signal for every task" is a redesign of the completion-authority surface, which has clear implications for BOTH teammate behavior (no self-complete) and lead behavior (becomes the authoritative completer). If #491's implementation PR only instruments one side, the other side's agent-readers will infer — and likely get it wrong under pressure.

Suggested application to #491 planning:

For each new or modified protocol primitive #491 introduces, the plan should include a table or equivalent coverage check:

Primitive	Teammate-side surface	Lead-side surface
e.g., "lead-authoritative completion"	pact-agent-teams: "do not call TaskUpdate(status=completed) on your own tasks"; agent-side HANDOFF delivery conventions under the new regime	orchestration skill: "you receive completion signals from teammates as X, validate via Y, write the final TaskUpdate"; command-file appendices where the lead's completion-authority action sits

Both surfaces should be explicit in the implementation plan, not inferred post-hoc.

Related durable captures:

• Pinned axiom (project CLAUDE.md): agent-reader-primary design principle + planning corollary
• Audit issue (Audit PACT instruction surface for verbosity: apply rule + one-sentence-rationale design philosophy #503): this planning corollary added as Pattern 7 (teammate/lead surface asymmetry) in the audit scope
• Session calibration: auto-memory entry feedback_pact_plugin_center_ai_agent_reader.md

Not blocking — just a planning-methodology hint for when #491 enters its design phase.