From 8e00f117f5d7a6f79b7417986bbe28ce7fbdab02 Mon Sep 17 00:00:00 2001 From: michael-wojcik <5386199+michael-wojcik@users.noreply.github.com> Date: Mon, 20 Apr 2026 11:22:23 -0400 Subject: [PATCH 1/2] =?UTF-8?q?docs(#401):=20cycle-9=20universal=20teachba?= =?UTF-8?q?ck=20imperative=20=E2=80=94=20generative=20content=20at=20every?= =?UTF-8?q?=20dispatch?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add explicit "every dispatch, regardless of variety" imperative to the three protocol documents that describe the teachback ritual, closing the gap where the structured teachback_submit/teachback_approved form was canonical at variety >= 7 but implicit below. - pact-plugin/skills/pact-agent-teams/SKILL.md: teammate-side imperative adjacent to the existing teachback section — teammate produces the structured teachback_submit metadata via TaskUpdate at every dispatch. SendMessage remains the notification channel; the structured metadata carries the substance. - pact-plugin/skills/orchestration/SKILL.md: lead-side mirror imperative in the "Validating Incoming Teachbacks" section — lead produces the structured teachback_approved metadata at every dispatch. Writing the structured form IS the genuine engagement; its substring-inequality, citation-shape, and grounding-reference requirements force actual reading instead of rubber-stamp approval. - pact-plugin/protocols/pact-ct-teachback.md: new top-level "Design principle: shared understanding is constructed, not transmitted" section placed before the existing Conversation-Theory / state-machine sections. Design rationale: (a) Pask's Conversation Theory framing — shared understanding between two agents is CONSTRUCTED through mutual generative exchange, not transmitted. Both sides must generate content grounded in the other's text; the ritual implements that construction at every dispatch. (b) User directive — "I think the instructions should be universally applied to both teammates and the lead. Structured teachbacks at every turn regardless of variety." The protocol applies uniformly; mechanical enforcement is the variety-gated safeguard, not the scope definer. (c) Q2 tightening plan resolution — the variety-7 gate threshold controls mechanical enforcement (teachback_gate.py firing on missing or invalid content). It does NOT gate whether the content should be produced. Below the threshold, the discipline-based layer constructs shared understanding with the same generative shape, just without mechanical fallback. Docs-only change. No source code modifications, no test additions, no behavioral changes to the gate implementation. Pytest: 7292 passed, 3 skipped (no regression from baseline). --- pact-plugin/protocols/pact-ct-teachback.md | 25 ++++++++++++++++++++ pact-plugin/skills/orchestration/SKILL.md | 15 ++++++++++++ pact-plugin/skills/pact-agent-teams/SKILL.md | 17 +++++++++++++ 3 files changed, 57 insertions(+) diff --git a/pact-plugin/protocols/pact-ct-teachback.md b/pact-plugin/protocols/pact-ct-teachback.md index 813ccc03..53e6999d 100644 --- a/pact-plugin/protocols/pact-ct-teachback.md +++ b/pact-plugin/protocols/pact-ct-teachback.md @@ -1,3 +1,28 @@ +## Design principle: shared understanding is constructed, not transmitted + +Per Pask's Conversation Theory, shared understanding between two agents is +CONSTRUCTED through mutual generative exchange — not transmitted from one +to the other. The teachback protocol implements this construction: the +teammate produces self-identified risk plus concrete plan; the lead +produces independent-read verification plus distinct-risk scan. Both sides +generate content grounded in the other's text. + +The ritual applies at every dispatch, regardless of variety. Mechanical +enforcement (the variety-7 gate threshold in `teachback_gate.py`) is a +second-layer safeguard for high-consequence work — it does NOT define the +scope of the ritual itself. Below the threshold, the discipline-based +layer (orchestrator reading the teammate's teachback; teammate receiving +the orchestrator's structured approval) constructs shared understanding +with the same generative shape, just without mechanical fallback. + +**Implication**: `teachback_submit` and `teachback_approved` are produced +at every dispatch in every PACT workflow. The variety threshold gates +whether the tool-use gate fires on missing or invalid content; it does +not gate whether the content should be produced. Both structured objects +are the canonical per-dispatch practice regardless of variety score. + +--- + ## Conversation Theory: Teachback Protocol > **Source**: Gordon Pask's Conversation Theory, applied to LLM multi-agent systems. diff --git a/pact-plugin/skills/orchestration/SKILL.md b/pact-plugin/skills/orchestration/SKILL.md index 6641f4e2..0979b700 100644 --- a/pact-plugin/skills/orchestration/SKILL.md +++ b/pact-plugin/skills/orchestration/SKILL.md @@ -459,6 +459,21 @@ A list of things that include the following: When an agent sends a teachback, **compare it against the task as you dispatched it — check for both misstatements AND omissions of the objective, constraints, or success criteria**. If you spot a misunderstanding, reply with a correction via `SendMessage` before any other action — the agent is already working, so the correction window is short. Prevents **misunderstanding disguised as agreement** from going undetected until TEST phase. +**Structured `teachback_approved` at every dispatch.** Every teachback +approval, regardless of task variety, produces the structured +`teachback_approved` metadata via `TaskUpdate` (with `scanned_candidate`, +`response_to_assumption`, `response_to_least_confident`, `first_action_check`, +and `conditions_met` sub-fields). Writing the structured form is how you +genuinely engage with the teammate's teachback — the substring-inequality, +citation-shape, and grounding-reference requirements force actual reading +rather than rubber-stamp approval. The variety-7 threshold means that below +it, the structured form is not mechanically enforced; at or above it, the +gate adds a second layer. In either regime, the structured form IS the +canonical practice at every dispatch. If a teammate sent a bare-text +teachback without the structured `teachback_submit` metadata, reply via +`SendMessage` asking them to re-submit via `TaskUpdate` — the structured +form is what you respond to. + #### Expected Agent HANDOFF Format Every agent delivers a structured HANDOFF stored in task metadata. Read via `TaskGet(taskId).metadata.handoff` when needed: diff --git a/pact-plugin/skills/pact-agent-teams/SKILL.md b/pact-plugin/skills/pact-agent-teams/SKILL.md index f5e9c87c..79bba7b8 100644 --- a/pact-plugin/skills/pact-agent-teams/SKILL.md +++ b/pact-plugin/skills/pact-agent-teams/SKILL.md @@ -63,6 +63,23 @@ content via `@`-ref. Background: [pact-ct-teachback.md](../../protocols/pact-ct-teachback.md) (optional — protocol rationale and design history). +### Structured `teachback_submit` at every dispatch + +Every teachback, regardless of task variety, produces the structured +`teachback_submit` metadata via `TaskUpdate` (with `understanding`, +`most_likely_wrong`, `least_confident_item`, and `first_action` sub-fields). +The gate's variety-7 threshold controls mechanical enforcement — NOT whether +the structured form applies as a practice. Below the threshold, the +orchestrator validates discipline-based; at or above the threshold, +mechanical enforcement adds a second layer on top of the same ritual. The +structured shape is the canonical practice at every dispatch. + +The `SendMessage` notification described above remains the channel that +alerts the lead a teachback is ready to read. The structured +`teachback_submit` metadata is what the lead reads, validates, and replies +to. Produce both at every dispatch: `SendMessage` carries the notification; +`TaskUpdate(metadata={"teachback_submit": {...}})` carries the substance. + ## Progress Reporting Report progress naturally in your responses. For significant milestones, update your task metadata: From 1247b0c3ebced1189be8708fc1bae7162b9ad9a9 Mon Sep 17 00:00:00 2001 From: michael-wojcik <5386199+michael-wojcik@users.noreply.github.com> Date: Mon, 20 Apr 2026 11:34:41 -0400 Subject: [PATCH 2/2] docs(#401): cycle-9b sharpen teachback imperative to hard-rule mandatory tone MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Cycle-9 introduced the "every dispatch, regardless of variety" scope but framed it as "canonical practice" and exposed the variety-7 threshold and mechanical-enforcement two-layer structure inside the instructional voice. User correction: agent-facing instructional content uses MUST / no-exceptions imperative; the mechanical enforcement layer (hooks, variety thresholds, conditional behavior) is hidden from the instructional voice. From the LLM's perspective reading the instruction, the practice is ALWAYS mandatory. The fact that an additional mechanical safeguard fires at variety >= 7 is a backend implementation detail that does not appear in the voice of the instruction. User's exact words: "from the LLM's perspective it should be mandatory every turn. We are just hiding an additional layer of mechanical enforcement behind the scenes, when the variety score warrants it." Per-file treatment: - pact-plugin/skills/pact-agent-teams/SKILL.md: rewrite the "Structured teachback_submit at every dispatch" first paragraph to MUST imperative ("Every teachback you produce — on every dispatch, no exceptions — MUST include teachback_submit metadata via TaskUpdate with the sub-fields understanding, most_likely_wrong, least_confident_item, first_action. All 4 sub-fields are required on every dispatch. A teachback without these fields is not a teachback."). Strip the "below the threshold / mechanical enforcement adds a second layer" sentence entirely. Preserve the SendMessage + TaskUpdate co-produced trailing paragraph. - pact-plugin/skills/orchestration/SKILL.md: rewrite the "Structured teachback_approved at every dispatch" lead-side paragraph to MUST imperative ("Every teachback you validate — on every dispatch, no exceptions — MUST include a teachback_approved metadata write via TaskUpdate with the sub-fields scanned_candidate, response_to_assumption, response_to_least_confident, first_action_check, conditions_met. All 5 sub-fields are required on every approval."). Strip the variety-7 threshold sentence. Preserve the "bare-text teachback -> ask teammate to re-submit via TaskUpdate" loophole-close at the end. - pact-plugin/protocols/pact-ct-teachback.md: preserve the "## Design principle: shared understanding is constructed, not transmitted" body paragraphs as design-rationale (the mechanism-discussion legitimately belongs here for mechanism auditors). Rewrite ONLY the trailing Implication paragraph to hard-rule form ("teachback_submit and teachback_approved MUST be produced at every dispatch in every PACT workflow. No exceptions. The variety-7 threshold is a hidden mechanical enforcement layer — invisible in agent instructional voice, and does not gate whether the structured form is produced. From the agent's perspective, producing the structured form is always mandatory."). Grep post-conditions (all verified zero-hits against softening/mechanism chatter in the two SKILL files): - grep "canonical practice" across pact-plugin -> 0 hits - grep "below the threshold|at or above the threshold|mechanical enforcement adds a second layer|variety-7|variety 7" in pact-agent-teams/SKILL.md -> 0 hits - grep "below the threshold|at or above the threshold|mechanical enforcement adds a second layer|variety-7|variety 7" in orchestration/SKILL.md -> 0 hits (the pre-existing "variety 7+" mention at line 140 is in the Workflow Selection section and predates this work) - grep "on every dispatch, no exceptions" across pact-plugin -> 2 hits (one each in pact-agent-teams/SKILL.md and orchestration/SKILL.md) Docs-only change. No source code modifications, no test additions, no behavioral changes to the gate implementation. Pytest: 7292 passed, 3 skipped (unchanged from cycle-9 baseline). --- pact-plugin/protocols/pact-ct-teachback.md | 11 +++++---- pact-plugin/skills/orchestration/SKILL.md | 26 +++++++++----------- pact-plugin/skills/pact-agent-teams/SKILL.md | 13 ++++------ 3 files changed, 23 insertions(+), 27 deletions(-) diff --git a/pact-plugin/protocols/pact-ct-teachback.md b/pact-plugin/protocols/pact-ct-teachback.md index 53e6999d..3411e66e 100644 --- a/pact-plugin/protocols/pact-ct-teachback.md +++ b/pact-plugin/protocols/pact-ct-teachback.md @@ -15,11 +15,12 @@ layer (orchestrator reading the teammate's teachback; teammate receiving the orchestrator's structured approval) constructs shared understanding with the same generative shape, just without mechanical fallback. -**Implication**: `teachback_submit` and `teachback_approved` are produced -at every dispatch in every PACT workflow. The variety threshold gates -whether the tool-use gate fires on missing or invalid content; it does -not gate whether the content should be produced. Both structured objects -are the canonical per-dispatch practice regardless of variety score. +**Implication**: `teachback_submit` and `teachback_approved` MUST be +produced at every dispatch in every PACT workflow. No exceptions. The +variety-7 threshold is a hidden mechanical enforcement layer — invisible +in agent instructional voice, and does not gate whether the structured +form is produced. From the agent's perspective, producing the structured +form is always mandatory. --- diff --git a/pact-plugin/skills/orchestration/SKILL.md b/pact-plugin/skills/orchestration/SKILL.md index 0979b700..47ccf089 100644 --- a/pact-plugin/skills/orchestration/SKILL.md +++ b/pact-plugin/skills/orchestration/SKILL.md @@ -459,20 +459,18 @@ A list of things that include the following: When an agent sends a teachback, **compare it against the task as you dispatched it — check for both misstatements AND omissions of the objective, constraints, or success criteria**. If you spot a misunderstanding, reply with a correction via `SendMessage` before any other action — the agent is already working, so the correction window is short. Prevents **misunderstanding disguised as agreement** from going undetected until TEST phase. -**Structured `teachback_approved` at every dispatch.** Every teachback -approval, regardless of task variety, produces the structured -`teachback_approved` metadata via `TaskUpdate` (with `scanned_candidate`, -`response_to_assumption`, `response_to_least_confident`, `first_action_check`, -and `conditions_met` sub-fields). Writing the structured form is how you -genuinely engage with the teammate's teachback — the substring-inequality, -citation-shape, and grounding-reference requirements force actual reading -rather than rubber-stamp approval. The variety-7 threshold means that below -it, the structured form is not mechanically enforced; at or above it, the -gate adds a second layer. In either regime, the structured form IS the -canonical practice at every dispatch. If a teammate sent a bare-text -teachback without the structured `teachback_submit` metadata, reply via -`SendMessage` asking them to re-submit via `TaskUpdate` — the structured -form is what you respond to. +**Structured `teachback_approved` at every dispatch.** Every teachback you +validate — on every dispatch, no exceptions — MUST include a +`teachback_approved` metadata write via `TaskUpdate` with the sub-fields +`scanned_candidate`, `response_to_assumption`, `response_to_least_confident`, +`first_action_check`, and `conditions_met`. All 5 sub-fields are required +on every approval. Writing the structured form is how you genuinely engage +with the teammate's teachback — the substring-inequality, citation-shape, +and grounding-reference requirements force actual reading rather than +rubber-stamp approval. An approval without these fields is not an approval. +If a teammate sent a bare-text teachback without the structured +`teachback_submit` metadata, reply via `SendMessage` asking them to +re-submit via `TaskUpdate` — the structured form is what you respond to. #### Expected Agent HANDOFF Format diff --git a/pact-plugin/skills/pact-agent-teams/SKILL.md b/pact-plugin/skills/pact-agent-teams/SKILL.md index 79bba7b8..695497c7 100644 --- a/pact-plugin/skills/pact-agent-teams/SKILL.md +++ b/pact-plugin/skills/pact-agent-teams/SKILL.md @@ -65,14 +65,11 @@ Background: [pact-ct-teachback.md](../../protocols/pact-ct-teachback.md) (option ### Structured `teachback_submit` at every dispatch -Every teachback, regardless of task variety, produces the structured -`teachback_submit` metadata via `TaskUpdate` (with `understanding`, -`most_likely_wrong`, `least_confident_item`, and `first_action` sub-fields). -The gate's variety-7 threshold controls mechanical enforcement — NOT whether -the structured form applies as a practice. Below the threshold, the -orchestrator validates discipline-based; at or above the threshold, -mechanical enforcement adds a second layer on top of the same ritual. The -structured shape is the canonical practice at every dispatch. +Every teachback you produce — on every dispatch, no exceptions — MUST +include `teachback_submit` metadata via `TaskUpdate` with the sub-fields +`understanding`, `most_likely_wrong`, `least_confident_item`, and +`first_action`. All 4 sub-fields are required on every dispatch. A +teachback without these fields is not a teachback. The `SendMessage` notification described above remains the channel that alerts the lead a teachback is ready to read. The structured