chore: sync .cursor from suite

Made-with: Cursor

.cursor/skills/implement/SKILL.md

@@ -1,32 +1,31 @@
 ---
 name: implement
 description: |
-  Orchestrate task implementation with dependency-aware batching, parallel subagents, and integrated code review.
+  Implement tasks sequentially with dependency-aware batching and integrated code review.
   Reads flat task files and _dependencies_table.md from TASKS_DIR, computes execution batches via topological sort,
-  launches up to 4 implementer subagents in parallel, runs code-review skill after each batch, and loops until done.
+  implements tasks one at a time in dependency order, runs code-review skill after each batch, and loops until done.
   Use after /decompose has produced task files.
   Trigger phrases:
   - "implement", "start implementation", "implement tasks"
-  - "run implementers", "execute tasks"
+  - "execute tasks"
 category: build
-tags: [implementation, orchestration, batching, parallel, code-review]
+tags: [implementation, batching, code-review]
 disable-model-invocation: true
 ---
 
-# Implementation Orchestrator
+# Implementation Runner
 
-Orchestrate the implementation of all tasks produced by the `/decompose` skill. This skill is a **pure orchestrator** — it does NOT write implementation code itself. It reads task specs, computes execution order, delegates to `implementer` subagents, validates results via the `/code-review` skill, and escalates issues.
+Implement all tasks produced by the `/decompose` skill. This skill reads task specs, computes execution order, writes the code and tests for each task **sequentially** (no subagents, no parallel execution), validates results via the `/code-review` skill, and escalates issues.
 
-The `implementer` agent is the specialist that writes all the code — it receives a task spec, analyzes the codebase, implements the feature, writes tests, and verifies acceptance criteria.
+For each task the main agent receives a task spec, analyzes the codebase, implements the feature, writes tests, and verifies acceptance criteria — then moves on to the next task.
 
 ## Core Principles
 
-- **Orchestrate, don't implement**: this skill delegates all coding to `implementer` subagents
-- **Dependency-aware batching**: tasks run only when all their dependencies are satisfied
-- **Max 4 parallel agents**: never launch more than 4 implementer subagents simultaneously
-- **File isolation**: no two parallel agents may write to the same file
+- **Sequential execution**: implement one task at a time. Do NOT spawn subagents and do NOT run tasks in parallel. (See `.cursor/rules/no-subagents.mdc`.)
+- **Dependency-aware ordering**: tasks run only when all their dependencies are satisfied
+- **Batching for review, not parallelism**: tasks are grouped into batches so `/code-review` and commits operate on a coherent unit of work — all tasks inside a batch are still implemented one after the other
 - **Integrated review**: `/code-review` skill runs automatically after each batch
-- **Auto-start**: batches launch immediately — no user confirmation before a batch
+- **Auto-start**: batches start immediately — no user confirmation before a batch
 - **Gate on failure**: user confirmation is required only when code review returns FAIL
 - **Commit per batch**: after each batch is confirmed, commit. Ask the user whether to push to remote unless the user previously opted into auto-push for this session.
 
@@ -56,7 +55,7 @@ TASKS_DIR/
      - A) Commit or stash stray changes manually, then re-invoke `/implement`
      - B) Agent commits stray changes as a single `chore: WIP pre-implement` commit and proceeds
      - C) Abort
-   - Rationale: implementer subagents edit files in parallel and commit per batch. Unrelated uncommitted changes get silently folded into batch commits otherwise.
+   - Rationale: each batch ends with a commit. Unrelated uncommitted changes would get silently folded into batch commits otherwise.
    - This check is repeated at the start of each batch iteration (see step 6 / step 14 Loop).
 
 ## Algorithm
@@ -78,8 +77,8 @@ TASKS_DIR/
 
 - Topological sort remaining tasks
 - Select tasks whose dependencies are ALL satisfied (completed)
-- If a ready task depends on any task currently being worked on in this batch, it must wait for the next batch
-- Cap the batch at 4 parallel agents
+- A batch is simply a coherent group of tasks for review + commit. Within the batch, tasks are implemented sequentially in topological order.
+- Cap the batch size at a reasonable review scope (default: 4 tasks)
 - If the batch would exceed 20 total complexity points, suggest splitting and let the user decide
 
 ### 4. Assign File Ownership
@@ -89,11 +88,12 @@ The authoritative file-ownership map is `_docs/02_document/module-layout.md` (pr
 For each task in the batch:
 - Read the task spec's **Component** field.
 - Look up the component in `_docs/02_document/module-layout.md` → Per-Component Mapping.
-- Set **OWNED** = the component's `Owns` glob (exclusive write for the duration of the batch).
+- Set **OWNED** = the component's `Owns` glob (the files this task is allowed to write).
 - Set **READ-ONLY** = Public API files of every component in the component's `Imports from` list, plus all `shared/*` Public API files.
 - Set **FORBIDDEN** = every other component's `Owns` glob, and every other component's internal (non-Public API) files.
 - If the task is a shared / cross-cutting task (lives under `shared/*`), OWNED = that shared directory; READ-ONLY = nothing; FORBIDDEN = every component directory.
-- If two tasks in the same batch map to the same component or overlapping `Owns` globs, schedule them sequentially instead of in parallel.
+
+Since execution is sequential, there is no parallel-write conflict to resolve; ownership here is a **scope discipline** check — it stops a task from drifting into unrelated components even when alone.
 
 If `_docs/02_document/module-layout.md` is missing or the component is not found:
 - STOP the batch.
@@ -102,31 +102,30 @@ If `_docs/02_document/module-layout.md` is missing or the component is not found
 
 ### 5. Update Tracker Status → In Progress
 
-For each task in the batch, transition its ticket status to **In Progress** via the configured work item tracker (see `protocols.md` for tracker detection) before launching the implementer. If `tracker: local`, skip this step.
+For each task in the batch, transition its ticket status to **In Progress** via the configured work item tracker (see `protocols.md` for tracker detection) before starting work. If `tracker: local`, skip this step.
 
-### 6. Launch Implementer Subagents
+### 6. Implement Tasks Sequentially
 
-**Per-batch dirty-tree re-check**: before launching subagents, run `git status --porcelain`. On the first batch this is guaranteed clean by the prerequisite check. On subsequent batches, the previous batch ended with a commit so the tree should still be clean. If the tree is dirty at this point, STOP and surface the dirty files to the user using the same A/B/C choice as the prerequisite check. The most likely causes are a failed commit in the previous batch, a user who edited files mid-loop, or a pre-commit hook that re-wrote files and was not captured.
+**Per-batch dirty-tree re-check**: before starting the batch, run `git status --porcelain`. On the first batch this is guaranteed clean by the prerequisite check. On subsequent batches, the previous batch ended with a commit so the tree should still be clean. If the tree is dirty at this point, STOP and surface the dirty files to the user using the same A/B/C choice as the prerequisite check. The most likely causes are a failed commit in the previous batch, a user who edited files mid-loop, or a pre-commit hook that re-wrote files and was not captured.
 
-For each task in the batch, launch an `implementer` subagent with:
-- Path to the task spec file
-- List of files OWNED (exclusive write access)
-- List of files READ-ONLY
-- List of files FORBIDDEN
-- **Explicit instruction**: the implementer must write or update tests that validate each acceptance criterion in the task spec. If a test cannot run in the current environment (e.g., TensorRT requires GPU), the test must still be written and skip with a clear reason.
+For each task in the batch **in topological order, one at a time**:
+1. Read the task spec file.
+2. Respect the file-ownership envelope computed in Step 4 (OWNED / READ-ONLY / FORBIDDEN).
+3. Implement the feature and write/update tests for every acceptance criterion in the spec. If a test cannot run in the current environment (e.g., TensorRT requires GPU), the test must still be written and skip with a clear reason.
+4. Run the relevant tests locally before moving on to the next task in the batch. If tests fail, fix in-place — do not defer.
+5. Capture a short per-task status line (files changed, tests pass/fail, any blockers) for the batch report.
 
-Launch all subagents immediately — no user confirmation.
+Do NOT spawn subagents and do NOT attempt to implement two tasks simultaneously, even if they touch disjoint files. See `.cursor/rules/no-subagents.mdc`.
 
-### 7. Monitor
+### 7. Collect Status
 
-- Wait for all subagents to complete
-- Collect structured status reports from each implementer
-- If any implementer reports "Blocked", log the blocker and continue with others
+- After all tasks in the batch are finished, aggregate the per-task status lines into a structured batch status.
+- If any task reported "Blocked", log the blocker with the failing task's ID and continue — the batch report will surface it.
 
-**Stuck detection** — while monitoring, watch for these signals per subagent:
-- Same file modified 3+ times without test pass rate improving → flag as stuck, stop the subagent, report as Blocked
-- Subagent has not produced new output for an extended period → flag as potentially hung
-- If a subagent is flagged as stuck, do NOT let it continue looping — stop it and record the blocker in the batch report
+**Stuck detection** — while implementing a task, watch for these signals in your own progress:
+- The same file has been rewritten 3+ times without tests going green → stop, mark the task Blocked, and move to the next task in the batch (the user will be asked at the end of the batch).
+- You have tried 3+ distinct approaches without evidence-driven progress → stop, mark Blocked, move on.
+- Do NOT loop indefinitely on a single task. Record the blocker and proceed.
 
 ### 8. AC Test Coverage Verification
 
@@ -139,8 +138,8 @@ Before code review, verify that every acceptance criterion in each task spec has
    - **Not covered**: no test exists for this AC
 
 If any AC is **Not covered**:
-- This is a **BLOCKING** failure — the implementer must write the missing test before proceeding
-- Re-launch the implementer with the specific ACs that need tests
+- This is a **BLOCKING** failure — the missing test must be written before proceeding
+- Go back to the offending task, add tests for the specific ACs that lack coverage, then re-run this check
 - If the test cannot run in the current environment (GPU required, platform-specific, external service), the test must still exist and skip with `pytest.mark.skipif` or `pytest.skip()` explaining the prerequisite
 - A skipped test counts as **Covered** — the test exists and will run when the environment allows
 
@@ -264,9 +263,9 @@ After each batch, produce a structured report:
 
 | Situation | Action |
 |-----------|--------|
-| Implementer fails same approach 3+ times | Stop it, escalate to user |
+| Same task rewritten 3+ times without green tests | Mark Blocked, continue batch, escalate at batch end |
 | Task blocked on external dependency (not in task list) | Report and skip |
-| File ownership conflict unresolvable | ASK user |
+| File ownership violated (task wrote outside OWNED) | ASK user |
 | Test failure after final test run | Delegate to test-run skill — blocking gate |
 | All tasks complete | Report final summary, suggest final commit |
 | `_dependencies_table.md` missing | STOP — run `/decompose` first |
@@ -281,7 +280,7 @@ Each batch commit serves as a rollback checkpoint. If recovery is needed:
 
 ## Safety Rules
 
-- Never launch tasks whose dependencies are not yet completed
-- Never allow two parallel agents to write to the same file
-- If a subagent fails or is flagged as stuck, stop it and report — do not let it loop indefinitely
+- Never start a task whose dependencies are not yet completed
+- Never run tasks in parallel and never spawn subagents — see `.cursor/rules/no-subagents.mdc`
+- If a task is flagged as stuck, stop working on it and report — do not let it loop indefinitely
 - Always run the full test suite after all batches complete (step 15)

.cursor/skills/implement/references/batching-algorithm.md

@@ -3,29 +3,31 @@
 ## Topological Sort with Batch Grouping
 
 The `/implement` skill uses a topological sort to determine execution order,
-then groups tasks into batches for parallel execution.
+then groups tasks into batches for code review and commit. Execution within a
+batch is **sequential** — see `.cursor/rules/no-subagents.mdc`.
 
 ## Algorithm
 
 1. Build adjacency list from `_dependencies_table.md`
 2. Compute in-degree for each task node
-3. Initialize batch 0 with all nodes that have in-degree 0
+3. Initialize the ready set with all nodes that have in-degree 0
 4. For each batch:
-   a. Select up to 4 tasks from the ready set
-   b. Check file ownership — if two tasks would write the same file, defer one to the next batch
-   c. Launch selected tasks as parallel implementer subagents
-   d. When all complete, remove them from the graph and decrement in-degrees of dependents
-   e. Add newly zero-in-degree nodes to the next batch's ready set
+   a. Select up to 4 tasks from the ready set (default batch size cap)
+   b. Implement the selected tasks one at a time in topological order
+   c. When all tasks in the batch complete, remove them from the graph and
+      decrement in-degrees of dependents
+   d. Add newly zero-in-degree nodes to the ready set
 5. Repeat until the graph is empty
 
-## File Ownership Conflict Resolution
+## Ordering Inside a Batch
 
-When two tasks in the same batch map to overlapping files:
-- Prefer to run the lower-numbered task first (it's more foundational)
-- Defer the higher-numbered task to the next batch
-- If both have equal priority, ask the user
+Tasks inside a batch are executed in topological order — a task is only
+started after every task it depends on (inside the batch or in a previous
+batch) is done. When two tasks have the same topological rank, prefer the
+lower-numbered (more foundational) task first.
 
 ## Complexity Budget
 
 Each batch should not exceed 20 total complexity points.
 If it does, split the batch and let the user choose which tasks to include.
+The budget exists to keep the per-batch code review scope reviewable.