docs(protocol): enshrine black-box delegation and pre-review summary gate

- Add Section 3.5 to AGENTS.md for agent orchestration and tool autonomy - Add Section E to tasks/GUIDELINES.md with pre-review summary gate - Update tasks/do.md dispatch template with DRY positive acceptance criteria - Align task lifecycle state machine to keep in-flight work in tasks/new/
2026-08-26 10:37:22 -07:00 · 2026-08-26 10:37:22 -07:00 · 42b336173e
commit 42b336173e
parent 9e2cd81e4d
5 changed files with 61 additions and 13 deletions
--- a/AGENTS.md
+++ b/AGENTS.md
@ -53,6 +53,17 @@ Management (IAM) fabric and WebAuthn Passkey authority.
   - Follow the standardized engineering lifecycle: `tasks/plan.md`
     $\rightarrow$ `tasks/audit-1.md` $\rightarrow$ `tasks/do.md` $\rightarrow$
     `tasks/audit-2.md`, with `tasks/debug.md` for hermetic root-cause analysis.
+5. **Agent Orchestration & Black-Box Delegation:**
+   - **Autonomy over Tooling:** When preparing prompts or tasks for external
+     agents (e.g., Jules), NEVER micromanage their internal execution mechanics
+     or tool choices (e.g. do not prohibit or mandate specific scripting
+     languages).
+   - **Positive Final-State Delivery:** Define strict terminal Acceptance
+     Criteria (clean git working tree, formatted with `deno fmt`, all tests
+     passing) rather than negative constraints on in-flight tools.
+   - **DRY Instructions:** Rely on repository guideline documents (`AGENTS.md`,
+     `tasks/GUIDELINES.md`) by reference rather than copy-pasting operational
+     rules into prompts.

 ## 4. History & Context Link

--- a/tasks/GUIDELINES.md
+++ b/tasks/GUIDELINES.md
@ -84,3 +84,22 @@ objective against the existing codebase and document:

 The structured phases, code extraction points, or execution steps required to
 complete the task safely.
+
+## E. Multi-Agent Orchestration & Dispatching Standards
+
+When dispatching tasks to autonomous external agents (e.g. Jules, CI workers,
+subagents):
+
+1. **Black-Box Delegation:** Treat the worker agent's execution loop as a black
+   box. Specify architectural invariants and domain rules clearly, but never
+   dictate or forbid specific internal tooling, helper scripts, or workflow
+   mechanics.
+2. **Positive Final-State Delivery:** Never use negative constraints to govern
+   tool use. Instead, formulate unambiguous terminal Acceptance Criteria (clean
+   git tree, passing test suites, formatted code).
+3. **Pre-Review Summary Gate:** Require worker agents to provide a concise
+   verification summary (modified files and test pass evidence) BEFORE
+   requesting code review or opening the PR.
+4. **DRY Prompting:** Always reference repository guidelines (`AGENTS.md`,
+   `tasks/GUIDELINES.md`) instead of copy-pasting operational rules into agent
+   prompts.
--- a/tasks/audit-2.md
+++ b/tasks/audit-2.md
@ -49,7 +49,7 @@ the following block:
 ```text
 **Role:** Act as a Senior Security, Architecture & Quality Assurance Auditor. Do not modify production code or push commits during this audit session. Your sole deliverable is an objective Code Quality & Security Audit Report.

-**The Scope:** [Specify target branch, recent commits, modified files, or completed task in `tasks/wip/TASK_FILENAME.md`].
+**The Scope:** [Specify target branch, recent commits, modified files, or task in `tasks/new/TASK_FILENAME.md` or `tasks/complete/TASK_FILENAME.md`].

 **Your Task:**
 Audit the actual codebase changes against the original task specification and our system guidelines (`AGENTS.md`, `docs/`) using the 5-point implementation rubric in `tasks/audit-2.md`:
--- a/tasks/do.md
+++ b/tasks/do.md
@ -9,8 +9,8 @@ This protocol defines the standard for executing an approved task from

 When commanded to **"tasks/do `[TASK_FILE]`"**:

-1. **Move to WIP:** Move the task file from `tasks/new/` to `tasks/wip/` before
-   starting work.
+1. **Keep in New During Work:** The task file remains in `tasks/new/` while work
+   is in progress.
 2. **Follow the 4-Step State Machine:**
   - **Step 1 (Research):** Inspect the target files and verify architectural
     assumptions.
@ -22,8 +22,10 @@ When commanded to **"tasks/do `[TASK_FILE]`"**:
     - `deno task check`
     - `deno test --allow-all` (Run ONLY hermetic unit tests; NEVER run
       `deno task start` in container sandboxes).
-   - **Step 4 (Review & Move):** Upon all gates passing, move the task file to
-     `tasks/complete/YYYY-MMDD.XX.agent.type.scope.title-HHMM.md`.
+   - **Step 4 (Review & Move):** Upon all gates passing, move the task file
+     directly from `tasks/new/` to
+     `tasks/complete/YYYY-MMDD.XX.agent.type.scope.title-HHMM.md`. (If the
+     session must end without completing the task, park it in `tasks/wip/`).
 3. **Commit & Sync:** Commit with standard conventional commit syntax and push
   to both remotes (`origin` and `gitea`).

@ -39,11 +41,21 @@ and provide the following block:

 **The Task:** Please review and execute the approved task plan in `[tasks/new/TASK_FILENAME.md]`.

-**Directives:**
-1. Follow the strict 4-step state machine (Research -> Implementation -> Quality Gates -> Review).
-2. Move the task file from `tasks/new/` to `tasks/wip/` before starting, and to `tasks/complete/` upon verification.
-3. Apply minimal, pure functional modifications adhering to `AGENTS.md`.
-4. Run all quality gates: `deno fmt`, `deno task lint`, `deno task check`, and `deno test --allow-all`.
-5. Run ONLY unit tests (`deno test --allow-all`). Do NOT run `deno task start` or `deno task dev` (database daemons are not running in container sandboxes).
-6. Provide a concise summary of all modified files and verified test results upon completion.
+**Directives & Guidelines:**
+- Adhere strictly to the repository architecture and operating protocols in `AGENTS.md` and `tasks/GUIDELINES.md`.
+- Keep the task file in `tasks/new/` during execution; only move it to `tasks/complete/` upon successful verification (or park in `tasks/wip/` only if work cannot be finished in this session).
+- Run ONLY hermetic unit tests (`deno test --allow-all`). Do NOT start long-running servers (`deno task start` / `deno task dev`).
+
+**Acceptance Criteria & Delivery Protocol:**
+
+1. **Pre-Review Quality & Summary (Before Requesting Review / Opening PR):**
+   - Run and pass all quality gates: `deno fmt`, `deno task lint`, `deno task check`, and `deno test --allow-all`.
+   - Ensure the git working tree contains only intentional modifications to target deliverables (zero untracked or temporary files).
+   - Present a concise verification summary detailing:
+     * Exact list of modified/created files
+     * Test execution results proving all test suites pass
+
+2. **Final Completion (Upon Approval):**
+   - Move the task file from `tasks/new/` directly to `tasks/complete/YYYY-MMDD.XX.agent.type.scope.title-HHMM.md` (or park in `tasks/wip/` only if work cannot be finished in this session).
+   - Submit the final pull request with a clean git history.
 ```
--- a/tasks/new/2026-0825.01.jul.story.protocol.universal-agent-framework-1945.md
+++ b/tasks/new/2026-0825.01.jul.story.protocol.universal-agent-framework-1945.md
@ -47,8 +47,14 @@ and mechanics of the framework.
    another agent).
  - **Strict Operating Gates:** The mandatory read-only first pass, dual-level
    deliberation, and explicit user approval before code edits.
+  - **Orchestration Axioms:** Black-Box Delegation (decoupling architectural
+    invariants from execution mechanics), Positive Final-State Delivery
+    (mandating clean terminal git states rather than tool restrictions), and DRY
+    Prompting.
  - **Kanban State Machine:** The directory progression for tracking state
-    (`tasks/new/` ──► `tasks/wip/` ──► `tasks/complete/`).
+    (`tasks/new/` ──► `tasks/complete/`, with `tasks/wip/` reserved strictly as
+    an incomplete session parking lot; files are moved only at the end of a
+    session).
  - **Semantic Task Metadata:** The strict naming schema and mandatory
    `# TASK METADATA` header.