config: add canonical execution-model.md and update references

Author: cowwoc

.cat/issues/v2/v2.1/canonicalize-wave-hierarchy-doc/index.json

@@ -1,5 +1,6 @@
 {
-  "status": "open",
-  "dependencies": [],
-  "blocks": []
-}
+  "status" : "in-progress",
+  "dependencies" : [ ],
+  "blocks" : [ ],
+  "target_branch" : "v2.1"
+}

plugin/concepts/execution-model.md

@@ -0,0 +1,126 @@
+<!--
+Copyright (c) 2026 Gili Tzabari. All rights reserved.
+Licensed under the CAT Commercial License.
+See LICENSE.md in the project root for license terms.
+-->
+# CAT Execution Model
+
+This document is the canonical reference for CAT's execution hierarchy and wave-based parallelism model.
+
+## Hierarchy
+
+CAT organizes work in a five-level hierarchy:
+
+```
+version
+  └── issue
+        └── sub-issue          (decomposed from a parent issue when context is too large)
+              └── wave          (a batch of work items executed by one subagent)
+                    └── subagent  (executes one wave in an isolated worktree)
+```
+
+| Level | Description |
+|-------|-------------|
+| **version** | A major or minor release (e.g., `v2.1`). See `plugin/concepts/hierarchy.md`. |
+| **issue** | An atomic unit of work within a version. |
+| **sub-issue** | A child issue created by decomposing a parent issue that exceeds the context-size threshold. |
+| **wave** | A batch of work items assigned to one subagent. Items within a wave run in parallel; waves run sequentially only when a dependency exists between them. |
+| **subagent** | An isolated Claude instance that executes one wave inside a dedicated git worktree. |
+
+## Waves
+
+A **wave** is defined by a `### Wave N` subsection under `## Execution Waves` (or `## Sub-Agent Waves`) in plan.md.
+Each wave contains one or more top-level bullet items (`- `) listing the work to be done. Sub-items
+(indented bullets with `  - `) are informational and do not spawn additional subagents.
+
+```markdown
+## Execution Waves
+
+### Wave 1
+- Implement parser module
+- Add parser tests
+
+### Wave 2
+- Implement formatter module
+- Add formatter tests
+- Run full test suite
+```
+
+### Wave Parallelism
+
+**All waves spawn simultaneously in a single API response.** There is no sequential waiting between
+waves unless an explicit dependency between them is declared. Within each wave, all items also run in
+parallel (each item is handled by the same subagent).
+
+Ordering is sequential **only when a dependency exists** between waves (e.g., Wave 2 requires output
+produced by Wave 1). When no dependency exists, treat all waves as launching at the same time.
+
+### When to Use Multiple Waves
+
+Use multiple waves **only** when:
+
+- Work items are genuinely independent (no data or file dependencies between waves)
+- Items in different waves modify **different files** (overlapping files cause merge conflicts)
+- The parallelism benefit justifies the added complexity
+
+**Do NOT use multiple waves when:**
+
+- Items must run in sequence (later items consume output from earlier ones)
+- Items modify the same files
+- The issue is small enough that parallelism adds no benefit
+
+Plans with only 1 wave (or no waves at all) use single-subagent mode, spawning one implementation
+subagent with all items. Only plans with 2 or more distinct waves spawn parallel subagents.
+
+## Sub-Issue Decomposition
+
+A **sub-issue** is created when an issue's context size exceeds the safe threshold (approximately 80 K tokens
+or when compaction events occur). Decomposition splits the parent issue into smaller, focused child issues
+that each fit within a single subagent's context window.
+
+Triggers for decomposition:
+- Token report shows issue approaching 40% threshold (80 K tokens)
+- Subagent has experienced compaction events
+- Pre-emptive analysis reveals the issue is too large before execution begins
+
+After decomposition, the sub-issues are organized into waves following the same dependency analysis rules
+described above. See `plugin/skills/decompose-issue-agent/first-use.md` for the full decomposition workflow.
+
+## Worktree Sharing and Push Coordination
+
+All wave subagents share the same worktree (`WORKTREE_PATH`). They commit and push to the same issue branch.
+Each subagent must `git pull --rebase` before pushing to incorporate commits from other waves that completed
+first.
+
+When pushing encounters a non-fast-forward rejection, the subagent retries up to 3 times, rebasing before
+each retry. See `plugin/concepts/parallel-execution.md` for the full push coordination protocol.
+
+## index.json Ownership
+
+`index.json` must be updated exactly once per issue run. The last wave alphabetically owns the index.json
+update:
+
+- All waves except the last: do NOT update `index.json`
+- Last wave: updates `index.json` to `"status": "closed"` in its final commit
+
+## Architecture Summary
+
+```
+work-with-issue (main agent)
+    |
+    +---> Read plan.md directly
+    |     Detect ## Execution Waves / ### Wave N sections
+    |     Count top-level bullet items per wave
+    |
+    +---> [if 2+ waves] Spawn all wave subagents simultaneously
+    |         Wave 1: subagent handles all items in Wave 1 (parallel)
+    |         Wave 2: subagent handles all items in Wave 2 (parallel)
+    |         Worktree: shared
+    |         index.json: NO (all waves except last) / YES (last wave)
+    |
+    +---> Collect commits from all waves
+    |
+    +---> stakeholder-review (single review of combined work)
+    |
+    +---> work-merge (squashes all commits, single merge)
+```

plugin/concepts/hierarchy.md

@@ -6,6 +6,7 @@ See LICENSE.md in the project root for license terms.
 # CAT Hierarchy: MAJOR > MINOR > ISSUE
 
 > **See also:** [version-paths.md](version-paths.md) for path construction functions and patterns.
+> **See also:** `plugin/concepts/execution-model.md` for the full execution hierarchy including waves and subagents.
 
 ## Structure
 

plugin/concepts/parallel-execution.md

@@ -5,6 +5,8 @@ See LICENSE.md in the project root for license terms.
 -->
 # Parallel Subagent Execution
 
+> See `plugin/concepts/execution-model.md` for the full execution model, hierarchy, and wave parallelism rules.
+
 CAT supports running independent work items in parallel by spawning multiple implementation subagents, each working on
 its own assigned wave of items. Parallelism is opt-in: it only activates when plan.md contains a `## Execution Waves`
 section with multiple `### Wave N` subsections.
@@ -18,10 +20,9 @@ When the work skill starts executing an issue:
 3. **Parallel mode requires 2+ waves:** Plans with only 1 wave (or no waves at all) use single-subagent mode, spawning
    one implementation subagent with all items (default behavior). Only plans with 2 or more distinct waves spawn
    parallel subagents.
-4. **Parallel execution (2+ waves):** For each wave (in order), spawn one subagent per wave simultaneously.
-5. Wait for all subagents in the wave to complete before proceeding to the next wave.
-6. All subagents commit to the same issue branch (`v2.1-issue-name`).
-7. After all waves complete, `work-with-issue` merges their commit lists and proceeds to review and merge.
+4. **Parallel execution (2+ waves):** All wave subagents spawn simultaneously in a single API response.
+5. All subagents commit to the same issue branch (`v2.1-issue-name`).
+6. After all waves complete, `work-with-issue` merges their commit lists and proceeds to review and merge.
 
 ## Wave Section Syntax
 
@@ -42,11 +43,8 @@ additional subagents.
 - Run full test suite
 ```
 
-In this example:
-- Wave 1 has 2 items (parsed module + tests)
-- Wave 2 has 3 items (formatter module + tests + test suite)
-- All Wave 1 items run in parallel
-- After Wave 1 completes, all Wave 2 items run in parallel
+In this example, Wave 1 and Wave 2 spawn simultaneously. If Wave 2 depends on Wave 1's output, declare that dependency
+explicitly in plan.md so the orchestrator waits for Wave 1 before delegating Wave 2 items.
 
 ## When to Use Execution Waves
 
@@ -58,7 +56,7 @@ Use execution waves **only** when:
 
 **Do NOT use waves when:**
 
-- Items must run sequentially (later items consume output from earlier ones)
+- Items must run in sequence (later items consume output from earlier ones)
 - Items modify the same files
 - The issue is small enough that parallelism adds no benefit
 - There is only one item (or one wave of items)
@@ -74,7 +72,7 @@ The `work-with-issue` skill communicates this ownership in each subagent's deleg
 
 ## Worktree Sharing
 
-All wave subagents share the same worktree (`WORKTREE_PATH`). They commit and push sequentially to the same branch.
+All wave subagents share the same worktree (`WORKTREE_PATH`). They commit and push to the same branch.
 Each subagent must `git pull --rebase` before pushing to incorporate commits from other waves that completed first.
 
 The `work-merge` phase is transparent to parallelism — it squashes all commits from `TARGET_BRANCH..HEAD` regardless of
@@ -95,26 +93,3 @@ wave's commits have already been pushed). The coordination protocol is:
 
 This ensures that even when subagents complete in unpredictable order, each subagent can eventually push its commits
 without forcing a merge or overwriting other waves' work.
-
-## Architecture Summary
-
-```
-work-with-issue (main agent)
-    |
-    +---> Read plan.md directly
-    |     Detect ## Execution Waves / ### Wave N sections
-    |     Count top-level bullet items per wave
-    |
-    +---> [if 2+ waves] Spawn one subagent per wave (parallel within wave)
-    |         Wave 1: subagent handles all items in Wave 1 (parallel)
-    |         Wave 2: subagent handles all items in Wave 2 (wait for Wave 1, then parallel)
-    |         Worktree: shared
-    |         index.json: NO (Wave 1) / YES (Wave 2, last)
-    |
-    +---> Collect commits from all waves
-    |
-    +---> stakeholder-review (single review of combined work)
-    |
-    +---> work-merge (squashes all commits, single merge)
-```
-

plugin/concepts/token-warning.md

@@ -5,6 +5,8 @@ See LICENSE.md in the project root for license terms.
 -->
 # Workflow: Token Warning and Compaction Handling
 
+> See `plugin/concepts/execution-model.md` for the full execution hierarchy and sub-issue decomposition context.
+
 ## When to Load
 
 Load this workflow when:

plugin/skills/decompose-issue-agent/first-use.md

@@ -6,6 +6,8 @@ See LICENSE.md in the project root for license terms.
 # Decompose Issue
 
 See `${CLAUDE_PLUGIN_ROOT}/concepts/version-paths.md` for version path conventions used throughout this skill.
+See `${CLAUDE_PLUGIN_ROOT}/concepts/execution-model.md` for the full execution hierarchy, wave definitions, and
+sub-issue decomposition context.
 
 ## Purpose
 

plugin/skills/plan-builder-agent/first-use.md

@@ -88,6 +88,9 @@ subagents to fabricate results.
 
 ## Sub-Agent Waves for Parallel Execution
 
+> See `${CLAUDE_PLUGIN_ROOT}/concepts/execution-model.md` for the full wave execution model, hierarchy, and
+> parallelism rules.
+
 When the issue has clearly independent work that can run simultaneously, use `## Sub-Agent Waves` with `### Wave N`
 sections to enable parallel subagent spawning. Use sparingly — only when items genuinely don't depend on each other
 and won't modify the same files.

plugin/skills/work-implement-agent/first-use.md

@@ -5,6 +5,9 @@ See LICENSE.md in the project root for license terms.
 -->
 # Work Phase: Implement
 
+> See `${CLAUDE_PLUGIN_ROOT}/concepts/execution-model.md` for the full execution model, wave definitions, and
+> parallelism rules.
+
 Implement phase for `/cat:work`. Displays preparing/implementing banners, verifies lock ownership,
 and orchestrates subagent execution of the implementation plan.