@laitszkin/apollo-toolkit 4.1.1 → 4.1.2

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to this repository are documented in this file.
 
+## [v4.1.2] - 2026-06-04
+
+### Changed
+
+- **review skill**: Added cross-requirement connection analysis and group review agents. Per-requirement review is now mandatory; connected requirements are grouped for dedicated interaction-level review.
+- **plan skill**: File overlap is now a hard gate for parallel workers — only tasks with zero file overlap may run in parallel.
+- **qa skill**: File overlap is now a hard gate for parallel fix workers — only fixes with zero file overlap may run in parallel.
+
 ## [v4.1.1] - 2026-06-04
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@laitszkin/apollo-toolkit",
-  "version": "4.1.1",
+  "version": "4.1.2",
   "description": "Apollo Toolkit npm installer for managed skill copying across Codex, OpenClaw, and Trae.",
   "license": "MIT",
   "author": "LaiTszKin",

package/skills/plan/SKILL.md

@@ -53,7 +53,7 @@ Decompose the architecture design from DESIGN.md into tasks precise to the file
 
 **Decide whether each task needs an independent worker:**
 - Touches ≥2 files → needs independent worker
-- No file overlap between tasks → can run in parallel workers
+- **No file overlap between tasks → workers may run in parallel.** This is permitted ONLY when file lists have ZERO overlap across all workers within the same batch. Any shared file between tasks means sequential execution — this is a hard constraint to prevent overwrite conflicts.
 - File overlap or logical dependency between tasks → must run sequentially
 - Purely procedural operations (lockfile update, merge, commit) → no worker needed; coordinator handles directly
 
@@ -78,13 +78,13 @@ Analyze dependencies between specs:
 
 Output: Spec DAG.
 
-### 5. Detect File Overlap
+### 5. Detect File Overlap (Parallelism Gate)
 
-Perform file overlap detection across all task units:
+File overlap detection is the **gate that determines parallelism**. Perform this across all task units:
 
 1. Collect the file list each task unit is expected to modify
-2. Compare file lists and mark overlaps
-3. File-overlapping task units must not run in parallel and cannot be assigned to different workers
+2. Compare file lists and mark overlaps — zero overlap is the **only** condition for parallel execution
+3. Any file overlap at all → must be sequential. This is a hard constraint — never dispatch parallel workers for tasks sharing a file
 
 ### 6. Write Worker Prompts (One Per Dispatchable Task)
 
@@ -114,8 +114,8 @@ Tasks that do not need a worker (purely procedural operations) do not get a work
 
 Based on dependency analysis and file overlap detection, build the batch schedule → PROMPT.md Section 7 (Batch Schedule).
 
-**Batch partitioning principles:**
-- Within the same batch: tasks have no file overlap and no logical dependency → can dispatch workers in parallel
+**Batch partitioning principles (file overlap is the hard gate):**
+- Within the same batch: tasks must have ZERO file overlap — only then may they dispatch workers in parallel. File-overlapping tasks must be placed in separate sequential batches regardless of dependency
 - Between batches: the previous batch must complete and pass its gate before the next batch begins
 - A final integration batch handles housekeeping tasks (lockfile update, final test suite)
 

package/skills/qa/SKILL.md

@@ -84,17 +84,18 @@ Design principles:
 
 ### 5. Analyze Fix Dependencies → FIX.md Section 4
 
-- **File overlap dependency**: Multiple issues touch the same area of the same file → must be sequential
+- **File overlap dependency**: Multiple issues touch the same file → must be sequential. This is a hard constraint — parallel workers are only permitted when file sets have ZERO overlap, regardless of logical independence
 - **Logical dependency**: Fix B depends on Fix A being completed first
 - **Independent issues**: No file overlap and no logical dependency → can be parallel
 - **Regression test dependency**: Regression tests must run after their corresponding fix is complete (tests verify the fixed code)
 
-### 6. Detect File Overlap
+### 6. Detect File Overlap (Parallelism Gate)
+
+File overlap detection is the **gate that determines parallel vs sequential execution**. Perform this across all fixes and regression tests:
 
-Perform file overlap detection across all fixes and regression tests:
 1. Collect the file list for each fix and regression test
-2. Compare file lists and mark overlaps
-3. Overlapping work must not run in parallel and cannot be assigned to different workers
+2. Compare file lists and mark overlaps — zero overlap is the only condition for parallel execution
+3. Any file overlap at all → must be sequential. This is a hard constraint — never dispatch parallel workers for overlapping files
 
 ### 7. Write Worker Prompts
 
@@ -144,9 +145,9 @@ Each regression test worker prompt must include:
 
 ### 8. Create Batch Schedule → FIX.md Section 7
 
-**Batch partitioning principles:**
-- Fix batches: Ordered by dependencies. P0 issues first.
-- Regression test batches: Dispatched **after all fixes are complete**, because tests verify the fixed code. Regression tests without file overlap can run in parallel.
+**Batch partitioning principles (file overlap is the hard gate):**
+- Fix batches: Ordered by dependencies. P0 issues first. Within each batch, workers require ZERO file overlap to run in parallel — overlapping fixes must be sequentialized across sub-batches
+- Regression test batches: Dispatched **after all fixes are complete**, because tests verify the fixed code. Regression tests without file overlap can run in parallel; those sharing files must be sequential
 - Final batch: Full test suite + lint + confirmation that all issues are resolved.
 
 **Typical schedule:**

package/skills/review/SKILL.md

@@ -32,7 +32,7 @@ Using each requirement's implementation scope and affected files (from DESIGN.md
 
 ### 2. Dispatch Per-requirement Subagents
 
-Create one subagent per requirement (Requirement N). All subagents can review source code in parallel.
+**Mandatory: one agent per requirement.** Every `### Requirement N` must have its own dedicated review agent. Never merge requirements or skip any requirement. All subagents can review source code in parallel.
 
 **If a previous REPORT.md exists**: Condense its verdict and key findings into one history entry. Prepend it to the Review History section, keeping all past rounds. Then perform a fresh review — do not let prior results bias the new assessment.
 
@@ -58,19 +58,51 @@ Each subagent's task:
 | **P2 — Requirement Risk** | Functionality is correct but there are potential risks (architecture deviation, security weakness, performance bottleneck). This finding does **NOT** affect current requirement satisfaction. | → Needs Attention |
 | **P3 — Suggestion** | Functionality is fully correct. Code can be improved but nothing is blocking. This finding does **NOT** affect any requirement's satisfaction. | → Ready to Merge |
 
-If the same code corresponds to multiple requirements, cross-agent findings are handled in the synthesis phase.
+### 3. Identify Cross-requirement Connections
 
-### 3. Synthesize Review Results
+After all per-requirement subagents have completed, analyze the collected findings and requirement scopes to detect interactions:
 
-Collect all subagent findings and synthesize:
+- **Shared modules**: Multiple requirements touch the same code modules or utilities
+- **Shared data structures**: Multiple requirements read/write the same data structures or state
+- **Functional coupling**: One requirement's output feeds into another's input path
+- **Same-file modifications**: Multiple requirements modify the same file (merge conflict risk)
+- **Findings cross-references**: Individual agents flagged code that affects multiple requirements
+
+Group connected requirements into **Requirement Groups**:
+
+- Two requirements are connected if they share any interaction type above
+- Connections are transitive: if A connects to B and B connects to C, all three form one group
+- An isolated requirement (no connections to any other) is its own group of size 1
+
+Output: Requirement Groups list, each with:
+- Grouped requirement IDs
+- Interaction type (shared module, shared data, functional coupling, file overlap)
+- Interaction summary for group-level review
+
+### 4. Dispatch Group Subagents
+
+Create one review agent per Requirement Group. Each group agent reviews the **interactions between requirements** within its group:
+
+1. Read the individual review findings for all requirements in the group
+2. Focus on interaction-level concerns:
+   - **Interface mismatch**: One requirement's output consumed by another — does the contract align?
+   - **Side effect risk**: Changes for one requirement break assumptions of another
+   - **Merge conflict potential**: Same-file modifications require careful ordering
+   - **Architecture consistency**: Combined changes maintain DESIGN.md integrity
+3. Classify interaction findings using the same severity scale (P0-P3)
+4. Report findings scoped to the group interaction
+
+### 5. Synthesize Review Results
+
+Collect findings from both per-requirement and group subagents:
 
 1. **Dedup overlapping findings**: Merge identical issues found by multiple agents into a single finding. Preserve dimension-specific notes from each agent.
-2. **Resort by severity**: Reorder all findings by P0 → P3 across the entire list (not per-agent order).
+2. **Resort by severity**: Reorder all findings by P0 → P3 across the entire list.
 3. **Collapse empty severity levels**: If a severity level has zero findings, do NOT generate its table header or column labels.
-4. **Cross-requirement interaction check**: Identify code introduced for one requirement that modifies shared modules or data structures used by another requirement. Flag these as potential interaction risks (P2).
-5. **Conditional dimension summary**: If total findings exceed 5, include a one-line summary of finding counts per dimension. Otherwise omit — the findings table itself is sufficient.
+4. **Include group-level findings**: Cross-requirement interaction findings sit alongside individual findings.
+5. **Conditional dimension summary**: If total findings exceed 5, include a one-line summary of finding counts per dimension. Otherwise omit.
 
-### 4. Generate REPORT.md
+### 6. Generate REPORT.md
 
 Use `assets/templates/REPORT.md` and populate accordingly.
 
@@ -88,8 +120,6 @@ Include the following sections:
 | No P0/P1, has P2 findings | Needs Attention |
 | Only P3 or no findings | Ready to Merge |
 
-The verdict is derived directly from the severity of findings. P0 and P1 are defined as "requirement not satisfied" — if they exist, the review must fail. If only P3 exists, requirements are satisfied and no P3 finding can block a merge.
-
 **The report must NOT contain** fix suggestions, root cause analysis, or verification methods. These are handled by the `qa` skill.
 
 ## References