@systemfsoftware/omp-agent-discipline 1.2.0 → 1.4.0

package/skills/task-decomposition/SKILL.md

@@ -0,0 +1,198 @@
+---
+name: task-decomposition
+description: >-
+  Decompose work into bounded, verifiable units before delegating to
+  subagents; refuse monolithic dispatches. Use when fanning out subagents,
+  parallelizing work, sizing loop work units, or when a worker runs too
+  long or its output takes too long to verify. Triggers: 'split into
+  subagents', 'fan out', 'parallelize', 'decompose the task'. Do not use
+  for one-shot single-agent tasks.
+license: MIT
+metadata:
+  version: "1.2.0"
+---
+
+# Task Decomposition
+
+A subagent handed one massive task fails twice: it runs too long, and its output is too large to verify. Both are specification failures, preventable before dispatch — never after. This skill is the pre-dispatch discipline: size the unit, specify it completely, then dispatch or refuse.
+
+Applies to any orchestrator that spawns workers: interactive fan-out, loop work-unit design, multi-agent topology planning.
+
+<!-- BEGIN DOCTRINE KERNEL -->
+
+Refuse monolithic dispatches: size the unit, specify it completely, then dispatch — or do the work inline.
+
+rules:
+
+- GATE: decomposition is mandatory when ANY hold — multi-subsystem; exceeds one focused session for the worker's model class; irreversible side effects; verification longer than the work; incompatible reasoning modes. Dispatching monolithically anyway is an invalid dispatch: split, or do it yourself.
+- SPEC: every dispatched unit carries objective, write_scope, verify_commands, acceptance, size_estimate, context_paths, rollback, dependencies — written before work starts. Missing any field is undispatchable.
+- CHECK: verifier is not the maker. Run each unit's verify commands fresh in your own context; never accept a worker's reported output or completeness claims. A verify failure rejects the unit: record the failure, re-dispatch with the evidence.
+- FENCE: parallel units need disjoint write scopes, confirmed by comparing write_scope declarations literally — never inferred from topic. Overlap forces serialization.
+
+Full doctrine: skill://task-decomposition — sizing calibration, the dispatch contract, rejection rules, repair-retry. Refuse monolithic dispatches: size, specify, then dispatch or refuse.
+
+<!-- END DOCTRINE KERNEL -->
+
+Core rules as a machine-parseable block:
+
+```yaml
+rules:
+  - id: GATE
+    title: Sizing gate mandatory before dispatch
+    do: apply the sizing gate (multi-subsystem, exceeds one session, irreversible side effects, verification longer than work) before every subagent dispatch
+    dont: skip the gate for async or background workers — the same failure modes apply
+    harm: monolithic dispatches run too long, fail more often, and produce unverifiable outputs that waste the orchestrator's verification budget
+    check: every dispatch is preceded by a sizing decision (decomposed vs. single-unit) recorded in the unit spec
+
+  - id: SPEC
+    title: Complete unit spec required for every dispatch
+    do: write every dispatched unit with objective, write_scope, verify_commands, acceptance, size_estimate, context_paths, rollback, dependencies before the worker starts
+    dont: dispatch incomplete or vague specs — "implement auth" is not a dispatch
+    harm: a worker without a bounded scope produces unbounded output; verification becomes impossible
+    check: every dispatch bundle has all eight fields before spawning the worker
+
+  - id: CHECK
+    title: Verifier is not the maker
+    do: run per-unit verification in a fresh context on a different model lineage than the worker
+    dont: accept the worker's own claims about completeness or quality
+    harm: self-verified work compounds errors; the failure the worker missed drives the next unit off a wrong baseline
+    check: every verify command is run in the orchestrator's context (or a dedicated verifier), never by the maker
+
+  - id: FENCE
+    title: Write scopes must be disjoint for parallel units
+    do: verify that parallel units touch no overlapping files before dispatching; overlap forces serialization
+    dont: infer disjointness from topic — confirm it by comparing write_scope declarations
+    harm: parallel writers on overlapping files produce merge conflicts and lost work
+    check: every parallel batch has a cross-write-scope comparison recorded
+```
+
+## When to Activate
+
+- Before spawning a subagent/worker whose task exceeds one focused work session
+- When designing loop work units or delegation policy
+- After observing: worker runtime approaching the whole task budget, verification longer than the work, a wandering worker
+
+Do not activate for: work one agent finishes in one sitting, deterministic pipelines, narrow read-only lookups.
+
+For deep research problems that require comprehensive multi-source analysis with adversarial review, route by capability: a deep-research pipeline that performs tier-adaptive multi-source analysis with adversarial audit (triggers: 'deep research', 'comprehensive analysis', 'literature review'). Decomposition of a research query into atomic items is step 1 of that pipeline; this skill covers the sizing and specification of coding-task units.
+
+## The Sizing Gate
+
+Decomposition is mandatory when ANY hold:
+
+1. **Multi-subsystem** — the task touches more than one architectural layer or package boundary
+2. **Exceeds one session** — it cannot be completed in one focused work session for the assigned worker's model class
+3. **Irreversible side effects** — migrations, deletions, external API writes that cannot be rolled back atomically
+4. **Verification longer than work** — reviewing the whole result would take longer than producing it
+5. **Reasoning-mode conflict** — the task requires multiple incompatible reasoning modes (abductive exploration, counterfactual analysis, meta-inductive rule extraction, corrective debugging) that pull a shared context in conflicting directions
+
+Gate fires and you dispatch monolithically anyway → invalid dispatch. Split, or do the work yourself sequentially. Budgets are model-relative — a cheap small-context worker gets smaller units than a frontier worker.
+
+Model-relative budgets, full criteria, and the calibration procedure: read `references/sizing-gate.md`; if it is not loaded, stop and load it before sizing units.
+
+## The Unit Spec — no dispatch without it
+
+Every dispatched unit carries, written before work starts:
+
+| Field             | Purpose                                                                        |
+| ----------------- | ------------------------------------------------------------------------------ |
+| `objective`       | One sentence: what exists after this unit that did not exist before            |
+| `write_scope`     | Explicit file/glob ownership; worker modifies nothing outside it               |
+| `verify_commands` | Exact runnable checks for this unit, scoped to the increment                   |
+| `acceptance`      | Observable behavior a reviewer can confirm on this increment alone             |
+| `size_estimate`   | Expected files and verify minutes; must fit the assigned worker's class budget |
+| `context_paths`   | The exact files the worker must read first                                     |
+| `rollback`        | Recovery path if the unit leaves a partial state                               |
+| `dependencies`    | Units that must complete first                                                 |
+
+Missing any field → undispatchable. If a field is unfillable, the task is not decomposed enough.
+
+## Surface Classification
+
+Before decomposing, classify what each unit can touch:
+
+| Surface          | Rule                                                | Example                                                      |
+| ---------------- | --------------------------------------------------- | ------------------------------------------------------------ |
+| Locked           | Never modified by a worker; orchestrator-only       | CI configs, deploy manifests, shared schemas, root AGENTS.md |
+| Editable         | Declared in write_scope; worker owns it until merge | A package's source files, a feature's test files             |
+| Append-only      | Workers append but never overwrite                  | Logs, changelogs, durable action records                     |
+| Human-controlled | Worker prepares but never submits                   | PRs, deploys, releases, database migrations, credentials     |
+
+The `write_scope` field in every unit spec declares the editable surfaces the worker may touch. Fence breaches (touching undeclared surfaces) are rejection grounds per the dispatch contract.
+
+## The Dispatch Contract
+
+- Vague delegation ("implement auth", "review this phase") is invalid — decompose further or do it inline.
+- Hand off a file, not a chat message; pass the path.
+- Parallel writers need disjoint write scopes; overlap → serialize.
+- Sequential units verify green before the next starts; never implement-all-then-test.
+- One maker per unit; verifier is not the maker (fresh context, different lineage where affordable).
+
+Rejection rules, acceptance protocol, and repair-retry: read `references/dispatch-contract.md`; if it is not loaded, stop and load it before accepting any worker result.
+
+## Context and Gate Discipline
+
+Two structural innovations from the latest SOTA research that refine how units are dispatched and verified:
+
+### Context window isolation
+
+Each unit operates in a **clean context window**. The orchestrator never passes accumulated history from prior units into a new worker — context coupling degrades edit reliability and inflates cost. On completion, the unit folds its state (summarises what it learned and what changed) for the orchestrator, then the worker's context is evicted entirely.
+
+Implementation: the unit spec's `context_paths` field lists only the files the worker MUST read first. The orchestrator launches each worker with only those files plus the unit spec. No prior unit's conversation, no accumulated tool output, no stale state.
+
+Measured effect (SWE-Edit, 2026): +2.1 pp resolve rate, -17.9% inference cost on SWE-Bench Verified by decomposing Viewer from Editor into isolated contexts.
+
+### Verifiable acceptance gates
+
+A "done" claim from a worker is not evidence. The only valid signal is a **falsifiable gate that the orchestrator itself runs** — a verify command that could fail, checked before accepting the result.
+
+Principle (Goal-Autopilot, 2026): under gate soundness, floor enforcement, and plan coverage, termination implies the goal holds. The structural failure mode is an honest stall (gate didn't pass → don't claim done), never a fabricated success (claim done without running the gate).
+
+Implementation:
+
+- Every unit spec's `verify_commands` MUST be runnable by the orchestrator in its own context, not by the worker.
+- The orchestrator runs the verify commands FRESH — never accepts the worker's reported output.
+- If a verify command fails, the unit is rejected. The correct response is honest-stall: record the failure, re-dispatch with the failure evidence.
+- A unit whose verify commands cannot be run independently of the worker's context is structurally undispatchable — decompose further.
+
+Measured effect (Goal-Autopilot, 2026): 0.67% fabrication on SWE-bench Lite vs 33.7% (StateFlow baseline) — paired difference -33.07 pp [95% CI -36.53, -29.73].
+
+## Examples
+
+**Good unit spec** (single subsystem, bounded verify):
+
+```
+objective: "Add POST /api/checkout endpoint with Stripe session creation"
+write_scope: ["apps/api/src/routes/checkout.ts", "apps/api/src/routes/checkout.test.ts"]
+verify_commands:
+  - "pnpm --filter api test -- tests/routes/checkout.test.ts"
+  - "curl -s -X POST http://localhost:3000/api/checkout -d '{}' | grep -c sessionId"
+acceptance: "POST /api/checkout returns 201 with a Stripe session ID for a valid cart"
+size_estimate: { files: 3, verify_minutes: 2 }
+rollback: "git checkout HEAD -- apps/api/src/routes/checkout.ts"
+dependencies: []
+```
+
+**Bad unit spec** — multi-subsystem, unverifiable, no bounded scope:
+
+```
+"implement Stripe billing"
+```
+
+**Why bad**: no filesystem boundary (UI + API + DB + webhooks), no verify commands, no acceptance criteria, no size estimate. The worker produces output spanning the entire app; verification is impossible. Correct decomposition: split into UI checkout / API session creation / webhook handling / subscription state — four units, each with its own complete spec.
+
+## Integration
+
+- **Loop kits**: the sizing gate lives in the kit's delegation block and requirement inventory, enforced at seal time and at dispatch time. Architect units once; every fresh iteration inherits them pre-sized.
+- **Interactive fan-out**: apply the gate before each spawn; write each unit spec to a scratch file; pass paths.
+- **Topology last**: decide agent count and roles only after the units exist — a swarm sized before the units produces coordinated noise.
+- **Hierarchy placement**: this skill is the how (loaded on trigger); the must (mandatory gate before delegation) lives in the CLAUDE.md or AGENTS.md always-in-context rules. The harness provides the mandate; this skill provides the procedure.
+- **Capability-aligned decomposition**: decompose by capability boundary, not by topic. A "checkout" unit that writes frontend + API + DB touches three capabilities — split further. Each unit aligns with one capability boundary: tool authority, data domain, verification design. Verification design is a first-class dimension of the unit, not a post-hoc addition. Research basis: CEAD reference architecture ([arXiv:2605.08258](https://arxiv.org/abs/2605.08258)).
+
+Research basis for every rule (specification/verification failure taxonomy, front-loaded instruction effects, per-step verification, attention degradation, heterogeneous model routing, context coupling and clean-context decomposition, verifiable anti-fabrication gates, reasoning-mode decomposition, capability-aligned verification design, multi-stage tool-augmented decomposition, verifiable task synthesis at scale): read `references/research-grounding.md` — consult when justifying or calibrating a rule, not for routine dispatches.
+
+## Resources
+
+- `references/sizing-gate.md` — gate criteria, model-relative budgets, calibration, edge cases
+- `references/dispatch-contract.md` — bundle fields, rejection rules, repair-retry, action records
+- `references/research-grounding.md` — peer-reviewed basis and its limits

package/skills/task-decomposition/references/dispatch-contract.md

@@ -0,0 +1,53 @@
+# The Dispatch Contract — bundle completeness, output rejection, repair-retry
+
+Load this when PREPARING a dispatch or ACCEPTING/REJECTING a worker's result.
+
+## The dispatch bundle — all fields required
+
+A dispatch is a file, not a chat message. Write it to disk; pass the path. Required fields:
+
+1. `objective` — one sentence: what exists after this unit that did not exist before
+2. `write_scope` — explicit file/glob ownership; the worker modifies nothing outside it
+3. `verify_commands` — exact runnable checks for this unit (argv, cwd, timeout), scoped to the increment
+4. `acceptance` — observable behavior a reviewer can confirm on this increment alone
+5. `size_estimate` — expected files / verify minutes; must fit the assigned worker's class budget
+6. `context_paths` — the exact files the worker must read first (upstream specs, relevant source)
+7. `rollback` — recovery path if the unit leaves a partial state
+8. `dependencies` — units that must complete first; absent means parallel-eligible ONLY if write scopes are disjoint
+9. `worker_class` — the model class assigned to this unit, derived from `size_estimate.files` against `delegation.unit_budgets`. One of `frontier` | `cheap_agentic` | `small_local`. Operators may override; the runner defaults to the cheapest class that fits.
+
+If any field is unfillable, the task is not decomposed enough. Do NOT dispatch and "let the worker figure it out" — that is the monolithic-dispatch failure wearing a smaller costume.
+
+## Vague dispatch is invalid
+
+These are not dispatches: "implement auth", "review this phase", "fix the tests", "handle the backend". Each lacks verifiable acceptance and a bounded scope. The correct move when you catch yourself writing one: decompose further, or do the work yourself sequentially. An orchestrator doing a small unit inline is cheaper than a worker doing a big unit badly.
+
+## Output rejection rules — reject when ANY hold
+
+- No explicit verdict / completion claim
+- Claims files changed but doesn't list them, or the list doesn't match the actual diff
+- Doesn't cite which spec/context files it read
+- Ran no verify commands, or ran different ones than specified, or can't show output
+- Generic praise of its own work ("everything looks good") with no grounded findings
+- Touched files outside the declared write scope (fence breach — also a severity escalation)
+- Output can't be checked without trusting the worker's reasoning — the check must be against reality (diff, files, command output), never against the worker's narrative
+
+## Acceptance protocol
+
+1. Diff the write scope: every claimed file appears in the actual diff; nothing outside scope changed.
+2. Run the unit's verify commands FRESH — not the worker's reported output, your own run.
+3. Check acceptance behavior on this increment alone.
+4. Only then mark the unit complete and allow dependent units to start.
+
+## Repair-retry protocol
+
+When a unit fails:
+
+1. Record the failure evidence (which verify command, what output).
+2. Re-dispatch the SAME unit to a fresh worker with the exact failure named and the corrected spec. Do not patch worker output yourself and mark it done — that hides the failure rate you need for calibration and breaks maker/checker separation.
+3. A re-dispatch with an IDENTICAL spec after an identical failure is no-progress: change the mechanism (smaller unit, different model class, clarified acceptance) or escalate to the operator.
+4. Three failures of the same unit under materially different mechanisms → park the unit for a human; the spec itself is likely wrong.
+
+## Durable action records
+
+Every dispatched unit leaves a record: bundle path, worker identity/model, claimed changes, verify output paths, verdict, acceptance decision. Chat logs are not records — they compact away. The record is what lets a fresh agent audit the delegation chain later without trusting anyone's summary.

package/skills/task-decomposition/references/research-grounding.md

@@ -0,0 +1,77 @@
+# Research Grounding — why each rule exists
+
+Every rule in this skill traces to peer-reviewed or primary-source evidence. Load this when you need to justify, calibrate, or push back on a rule — not for routine dispatches.
+
+## Decomposition beats monolithic execution
+
+- **Zhou et al., "Least-to-Most Prompting Enables Complex Reasoning in Large Language Models"** (ICLR 2023, [arXiv:2205.10625](https://arxiv.org/abs/2205.10625)). Decompose-then-solve-sequentially beats monolithic chain-of-thought, with the gap WIDENING as problems get harder than anything in the model's context (SCAN length-generalization: ~99% vs ~16%). Implication: the monolithic worker doesn't just run long — it fails more, and retries are what consume wall-clock.
+- **Wang et al., "TDAG: A Multi-Agent Framework based on Dynamic Task Decomposition and Agent Generation"** (2024, [arXiv:2402.10178](https://arxiv.org/abs/2402.10178)). One purpose-built subagent per bounded subtask outperforms fixed agents with sprawling briefs. Basis for "one maker per unit."
+
+## Specification and verification are the dominant failure categories
+
+- **Cemri et al., "Why Do Multi-Agent LLM Systems Fail?" (MAST)** (NeurIPS 2025, [arXiv:2503.13657](https://arxiv.org/abs/2503.13657)). 14 failure modes over 150+ execution traces across 5 frameworks, in three categories: specification failures, inter-agent misalignment, verification/termination failures. The monolithic rammed-in task is a specification failure; the unverifiable giant output is a verification failure. Their demonstrated mitigations — better specification, multi-level verification — are structural, not prompt-level. Also: more agents is NOT inherently better (coordination failures are their own category) — basis for "one maker by default; decompose on evidence."
+
+## Per-unit verification beats end-of-run verification
+
+- **Lightman et al., "Let's Verify Step by Step"** (ICLR 2024, [paper](https://proceedings.iclr.cc/paper_files/paper/2024/file/aca97732e30bcf1303bc22ac3924fd16-Paper-Conference.pdf)). Process supervision significantly outperforms outcome supervision (78.2% vs 72.4% on MATH). End-of-run verification of a giant diff is the hardest and weakest check; per-unit checks are smaller, earlier, more accurate. Caveat: Jia et al., "Do We Need to Verify Step by Step?" (2025, [arXiv:2502.10581](https://arxiv.org/abs/2502.10581)) complicates the RL-supervision story — per-unit verification here earns its keep through SCOPING (bounded diff, fresh context), which their critique doesn't touch.
+
+## Front-loaded, fully-specified instructions
+
+- **Laban et al., "LLMs Get Lost in Multi-Turn Conversation"** (2025, [arXiv:2505.06120](https://arxiv.org/abs/2505.06120)). Average 39% performance drop when instructions unfold over turns vs. one fully-specified prompt; wrong early turns are unrecoverable. Basis for: complete unit spec at dispatch, in a file, never negotiated in chat; fresh agent + complete spec per unit.
+
+## Context growth degrades attention
+
+- **Liu et al., "Lost in the Middle: How Language Models Use Long Contexts"** (TACL 2024, [arXiv:2307.03172](https://arxiv.org/abs/2307.03172)). U-shaped attention: reliable at context edges, substantial degradation mid-context, worsening with length even below nominal limits. A long-running worker's own brief and verify commands rot mid-context. Basis for small units and brief-at-the-edges.
+
+## Structured handoffs beat dialogue
+
+- **Hong et al., "MetaGPT: Meta Programming for a Multi-Agent Collaborative Framework"** (ICLR 2024, [arXiv:2308.00352](https://arxiv.org/abs/2308.00352)). Structured documents instead of dialogue for inter-agent handoff measurably reduce cascading hallucination. Basis for the dispatch-bundle-as-file rule.
+- **Qian et al., "ChatDev: Communicative Agents for Software Development"** (ACL 2024, [paper](https://aclanthology.org/2024.acl-long.810.pdf)). Phase-chain decomposition with explicit per-phase instruction reduces coding hallucination. Basis for sequential unit execution with green-before-next gates.
+
+## Cheap agentic models and heterogeneous assignment
+
+- **Belcak et al. (NVIDIA), "Small Language Models are the Future of Agentic AI"** (2025, [arXiv:2506.02153](https://arxiv.org/abs/2506.02153)). Most agentic sub-invocations are repetitive, scoped, format-bound — small models suffice for the majority; frontier models only for open-ended reasoning. Position paper (vendor interest noted), but directionally corroborated by RouteLLM. Basis for heterogeneous model assignment: frontier orchestrator, cheap workers.
+- **Ong et al., "RouteLLM: Learning to Route LLMs with Preference Data"** (ICLR 2025, [arXiv:2406.18665](https://arxiv.org/abs/2406.18665)). Routing between strong/weak models cuts cost up to 85% at ~95% quality — IF calls are classifiable. A sealed unit spec with bounded scope and fixed verify commands is an "easy call" by construction; monolithic dispatches are unclassifiable. Basis for why decomposition ENABLES cheap-worker routing.
+- **MiniMax M3** (released 2026-06-01; [GitHub](https://github.com/MiniMax-AI/MiniMax-M3), [HF](https://huggingface.co/MiniMaxAI/MiniMax-M3)). 428B MoE, ~23B active, 1M context, open-weight; SWE-Bench Pro ~59 (frontier-adjacent) at roughly 8–15x under frontier pricing. Sparse attention ([arXiv:2606.13392](https://arxiv.org/abs/2606.13392)) improves long-context THROUGHPUT, not attention reliability over reasoning content — cheap workers make the sizing gate more mandatory, not less. Treat vendor-adjacent benchmark numbers as provisional.
+
+## What the literature does NOT tell us
+
+- No published benchmark measures agentic unit-size vs. model class directly — the budgets in `sizing-gate.md` are engineering defaults to calibrate, not literature values.
+- These papers study single-task benchmarks, not multi-day autonomous loops. Effect directions transfer; magnitudes don't.
+
+## Context window isolation per unit — clean context beats shared history
+
+- **Zhang et al., "SWE-Edit: Rethinking Code Editing for Efficient SWE-Agent"** (2026, [arXiv:2604.26102](https://arxiv.org/abs/2604.26102)). Identifies the "context coupling problem": conflating code inspection, modification planning, and edit execution within a single context window forces agents to interleave exploration with formatted generation — irrelevant context accumulates and edit reliability degrades. SWE-Edit decomposes the interface into Viewer + Editor subagents, each with a clean context window. Result: +2.1 pp resolve rate, -17.9% inference cost on SWE-Bench Verified, consistent across multiple reasoning-model families. Implications for this skill: (1) each decomposed unit must operate in its own clean context — never share accumulated history between units; (2) the Viewer/Editor split is a worked example of capability-aligned decomposition.
+- **Diao et al., "HIPIF: Hierarchical Planning and Information Folding for Long-Horizon LLM Agent Learning"** (2026, [arXiv:2606.10507](https://arxiv.org/abs/2606.10507)). Directly addresses long-context interference in multi-turn agentic tasks: continuously growing histories weaken the agent's ability to track global state. HIPIF trains agents to organise execution around explicit subgoals while **folding** completed subgoal histories — summarising and evicting them to maintain constant per-step context cost. Implications: the unit spec must describe what state is folded on completion; the orchestrator must evict the worker's context after each unit, not accumulate it.
+
+## Verifiable gates prevent fabricated success — a structural firewall
+
+- **"Goal-Autopilot: A Verifiable Anti-Fabrication Firewall for Unattended Long-Horizon Agents"** (2026, [arXiv:2606.11688](https://arxiv.org/abs/2606.11688)). The critical finding: long-horizon LLM agents cannot be trusted to self-report success. The paper proves a No-False-Success theorem — under gate soundness, floor enforcement, and plan coverage, termination implies the goal holds. The mechanism: a gated finite-state machine where a hard floor forbids any terminal "done" claim whose falsifiable gate did not actually execute and pass. Worst case degrades to an honest stall, never a fabricated success. Empirical results: 0.67% fabrication on SWE-bench Lite vs 33.7% (StateFlow), paired difference -33.07 pp [95% CI -36.53, -29.73]. Implications: (1) every dispatch unit's verify commands must be runnable by the orchestrator, not the worker; (2) a failed verify is an honest stall, never a reason to mark the unit done.
+
+## Reasoning-mode decomposition — separate reasoning modes need separate context
+
+- **"R-APS: Compositional Reasoning and In-Context Meta-Learning for Constrained Design via Reflective Adversarial Pareto Search"** (2026, [arXiv:2606.04823](https://arxiv.org/abs/2606.04823)). Identifies a root cause of agent failure: abductive, counterfactual, meta-inductive, corrective, and inductive reasoning pull a shared context in incompatible directions. The fix: reasoning-mode decomposition — allocate each reasoning mode its own context, orchestrate across three timescales (staged compositional reasoning, counterfactual stress-testing, meta-inductive rule extraction). Small 4B reasoning-specialised models prove competitive with general-purpose 70B backbones inside the protocol, suggesting structured protocols partially offset model scale. Implications: when a unit requires multiple reasoning modes, decompose further — one mode per unit, clean context per mode.
+
+## Capability-aligned decomposition — decompose by capability boundary, not topic
+
+- **"Designing Intelligent Enterprise Agents: A Capability-Aligned Multi-Agent Architecture (CEAD)"** (2026, [arXiv:2605.08258](https://arxiv.org/abs/2605.08258)). Revises the enterprise architecture thesis: governance cannot be the primary organising abstraction — agent design must be. Specifically: decompose by capability boundaries, autonomy allocation, interaction protocols, tool and data authority, state and memory design, **verification design**, and human interaction design. Verification is a first-class architectural dimension, not a post-hoc check. Implications: the unit spec's `write_scope` defines a capability boundary; each unit aligns with one capability; verification design is part of the unit spec from the start, not after the fact.
+
+## Verifiable task synthesis at scale
+
+- **Lv et al., "SCALECUA: Scaling Computer Use Agents with Verifiable Task Synthesis and Efficient Online RL"** (2026, [arXiv:2607.11185](https://arxiv.org/abs/2607.11185)). VeriGen framework: end-to-end generation of verifiable RL tasks through iterative docker interactions and a multi-agent feedback loop, producing 24K+ verifiable tasks at 100+ concurrent workers. Also introduces Visual Context Segmentation — a sliding window over recent context that yields 2.83x training speedup over step-wise decomposition. Implications: (1) verification can and should be automated at scale — a verify command is a falsifiable test; (2) sliding-window context management is a valid alternative to full context isolation for bounded-horizon units.
+
+## Coordination complexity — a formal measure of when parallel agents conflict
+
+- **"Tensor-Coord: Algebraic Decomposition of Joint Plan Tensors for Conflict-Free Multi-Agent LLM Planning"** (2026, [arXiv:2606.16478](https://arxiv.org/abs/2606.16478)). Represents joint plans as a third-order tensor over agents, timesteps, and actions. Defines a computable coordination complexity measure CC(Pi) = (R* - N) / N where R* is the minimal approximate CP rank. Proves R* = N is necessary and sufficient for plan independence. The residual defines a conflict score over agent pairs, timesteps, and actions — localising coordination failures without domain-specific rules. Implications: parallel dispatch is safe when write scopes are disjoint AND formal plan coordination complexity is minimal. Cross-write-scope comparison is table-stakes; the formal measure catches dynamic (runtime) conflicts that static scope comparison misses — an open problem this skill should flag as active research.
+
+## Multi-stage tool-augmented decomposition
+
+- **Zhang et al., "ReProAgent: Tool-Augmented Multi-Stage Agentic Generation of Bug Reproduction Tests from Issue Reports"** (2026, [arXiv:2607.09123](https://arxiv.org/abs/2607.09123)). Decomposes a complex SE task into four agent stages: bug localization, root cause analysis, test planning, and test generation. Each stage gets task-specific tools for decomposition and reflection — not a one-size-fits-all toolset. Results: 58.43%/70.30% on SWT-bench, exceeding OpenHands by 20.43/7.90 pp at $0.14/instance. Implications: each decomposed unit should be assigned task-specific tools aligned to its reasoning need — a "code search" unit gets different tools than a "test generation" unit. The dispatcher specifies which tools each unit may use.
+
+## What the literature does NOT tell us
+
+- No published benchmark measures agentic unit-size vs. model class directly — the budgets in `sizing-gate.md` are engineering defaults to calibrate, not literature values.
+- These papers study single-task benchmarks, not multi-day autonomous loops. Effect directions transfer; magnitudes don't.
+- The formal coordination complexity measure (Tensor-Coord) is promising but unvalidated outside contrived domains.
+- Goal-Autopilot's gated state machine trades coverage for honesty — the correct characterization for unattended work, but the coverage loss must be tracked.
+- All SOTA results are sensitive to backbone model. The decomposition rules in this skill are model-class-relative, a property the literature does not study directly.

package/skills/task-decomposition/references/sizing-gate.md

@@ -0,0 +1,38 @@
+# The Sizing Gate — when decomposition is mandatory and how small a unit must be
+
+Load this when deciding WHETHER to decompose and HOW SMALL units must be.
+
+## Gate criteria — any one fires, decomposition is mandatory
+
+1. **Multi-subsystem** — the change touches more than one architectural layer (UI + state + persistence + backend). Each subsystem boundary crossed is coordination surface a single worker must hold in context at once.
+2. **Exceeds one focused session** — the work cannot be completed by one worker in a single focused sitting for its model class. This is the primary "takes too long to run" trigger: a worker that must compact its context mid-task starts making decisions on rotted context.
+3. **Irreversible side effects** — migrations, deletions, external API writes. Smaller units bound the blast radius of each irreversible step and put a verification gate between them.
+4. **Verification longer than the work** — if reviewing the whole result would take longer than producing it, the unit is too big by definition. Verification cost scales with the diff surface; outcome-only verification is the weakest signal available.
+
+If NONE fire, decomposing is usually wrong: more units = more coordination, more handoffs, more chances for inter-agent misalignment. One maker by default; decompose on evidence, not on vibes.
+
+## Model-relative budgets
+
+The same task is a different-sized unit for different workers. Attention reliability over long contexts degrades more sharply in smaller models, so a cheap-agentic worker's unit must be smaller than a frontier worker's:
+
+| Worker class  | Examples                                        | max files | max verify minutes | Notes                                           |
+| ------------- | ----------------------------------------------- | --------- | ------------------ | ----------------------------------------------- |
+| frontier      | top-tier proprietary models                     | ~12       | ~15                | still bounded — frontier models rot too         |
+| cheap_agentic | M3-class MoE (~23B active), strong open-weights | ~5        | ~6                 | economics only pay off inside the reliable zone |
+| small_local   | 7–13B local models                              | ~2        | ~3                 | narrow specialists only; keep scopes tiny       |
+
+These are STARTING DEFAULTS, not measured truths — no published benchmark measures agentic unit-size vs. model class directly. Calibrate per host (below) and record the calibrated values where the orchestrator reads them (loop kit delegation block, project config).
+
+## Calibration procedure
+
+1. Pick 5–10 real past tasks and their actual diffs (files touched, verify runtime).
+2. Run them as single units with the target worker class; record where failures correlate with size (typically: instruction drift, scope creep, verify commands skipped).
+3. Set max_files at the point below which failures were NOT size-correlated; set max_verify_minutes so the per-unit check finishes in a fraction of the unit's work time (target ≤ 25%).
+4. Revisit when the worker model changes — class assignment is per-model, not per-run.
+
+## Edge cases
+
+- **The unit that can't shrink**: some changes are atomic (a schema migration touching 40 call sites). Decompose by PHASE instead: one unit writes the migration + adapter, follow-up units migrate call-site clusters. The write scope is still bounded per unit even though the change is logically one.
+- **Unknown size upfront**: when the scope fence can't be drawn until exploration happens, dispatch a read-only scout unit first (tiny scope, report-only), then size the write units from its map. Never convert a scout into a writer mid-task — its context is optimized for breadth, not depth.
+- **Sequential dependency chains**: units with blocking dependencies serialize by definition. State the dependency in the unit spec so the scheduler doesn't fan them out.
+- **Re-dispatch after failure**: a failed unit re-dispatched with a corrected spec is a NEW unit — its spec must name the prior failure and what changed. A re-dispatch with the identical spec is a no-progress signal, not work.