Merge remote-tracking branch 'origin/makima/soryu-co-soryu---makima--update-supervisor-plannin-73cfc378' into makima/directive-soryu-co-soryu---makima-19fd3e1d-v1777404059makima/directive-soryu-co-soryu---makima-19fd3e1d-v1777404059

1 files changed, 69 insertions, 19 deletions

diff --git a/makima/src/orchestration/directive.rs b/makima/src/orchestration/directive.rs
index b9ff3fe..22e2f02 100644
--- a/makima/src/orchestration/directive.rs
+++ b/makima/src/orchestration/directive.rs
@@ -1600,10 +1600,10 @@ If step B modifies files created/changed by step A, step B MUST list step A in i
 step B will start from a blank worktree and won't see step A's changes at all.
 
 Guidelines:
-- For sequential work, create a linear chain: step1 → step2 → step3 (each depends on the previous).
-- Only omit dependsOn for truly independent steps that can start from a fresh checkout.
-- Parallel steps that share no files can omit mutual dependencies, but if they both build on a prior step
-  they should BOTH list that prior step in dependsOn.
+- STRONGLY PREFER LINEAR CHAINS: Default to creating a linear chain where each step depends on the previous (step1 -> step2 -> step3). This avoids merge conflicts when combining branches.
+- Only use parallel steps (same orderIndex, no mutual dependsOn) when tasks are TRULY independent - they modify completely different files/modules AND can start from a fresh checkout without any shared state.
+- When in doubt, make it sequential. The cost of unnecessary serialization is much lower than the cost of merge conflicts.
+- Each step in a linear chain inherits the previous steps worktree, so later steps can see and build on earlier work.
 
 IMPORTANT: Each step's taskPlan must be self-contained. The executing instance won't have your planning context.
 
@@ -1715,7 +1715,6 @@ git fetch origin
 NEW_BRANCH="{directive_branch}-v$(date +%s)"
 git checkout -b "$NEW_BRANCH" origin/{base_branch}
 {merge_commands}
-git push -u origin "$NEW_BRANCH"
 ```
 
 For each step branch merge above, if a merge fails with conflicts:
@@ -1723,7 +1722,25 @@ For each step branch merge above, if a merge fails with conflicts:
 2. If that also fails, manually resolve the conflicts, `git add .`, and `git commit --no-edit`
 3. Continue with remaining merges
 
-3. Generate a descriptive PR title and create a new PR:
+## CRITICAL: Pre-merge verification
+
+Before pushing or creating the PR, you MUST verify:
+1. Check that the combined changes match the directive goal: {goal}
+2. After merging all step branches, run the build to verify it compiles:
+   - If this is a Rust project: `cargo check` in the relevant crate directory
+   - If there is a frontend: `cd frontend && npm install && npx tsc --noEmit`
+3. If the build fails, fix the issues before pushing.
+4. Review the diff to ensure no merge artifacts (duplicate code, conflict markers) exist:
+   `git diff origin/{base_branch}...HEAD --stat` and spot-check large files.
+
+Do NOT create a PR if the build is broken. Fix issues first.
+
+3. Push the branch:
+```
+git push -u origin "$NEW_BRANCH"
+```
+
+4. Generate a descriptive PR title and create a new PR:
 
 Based on the steps completed above, generate a descriptive PR title that summarizes the actual changes (not just the directive name "{title}"). The title should:
 - Be concise (under 72 characters)
@@ -1736,13 +1753,13 @@ gh pr create --title "<YOUR_GENERATED_TITLE>" --body "{pr_body}" --head "$NEW_BR
 ```
 Replace <YOUR_GENERATED_TITLE> with the concise descriptive title you generated.
 
-4. Store the new PR URL:
+6. Store the new PR URL:
 ```
 makima directive update --pr-url "<URL_FROM_GH_PR_CREATE>"
 ```
 Replace the URL with the actual PR URL from the `gh pr create` output. This step is CRITICAL.
 
-5. Update the directive pr_branch to the new branch name:
+7. Update the directive pr_branch to the new branch name:
 ```
 makima directive update --pr-branch "$NEW_BRANCH"
 ```
@@ -1761,7 +1778,6 @@ git checkout {directive_branch}
 git pull origin {directive_branch}
 git merge origin/{base_branch} --no-edit
 {merge_commands}
-git push origin {directive_branch}
 ```
 
 Already-merged branches will be a no-op. If a merge fails with conflicts:
@@ -1769,6 +1785,23 @@ Already-merged branches will be a no-op. If a merge fails with conflicts:
 2. If that also fails, manually resolve the conflicts, `git add .`, and `git commit --no-edit`
 3. Continue with remaining merges
 
+## CRITICAL: Post-merge verification
+
+After merging step branches but BEFORE pushing:
+1. Verify the combined changes still align with the directive goal: {goal}
+2. Run the build:
+   - If this is a Rust project: `cargo check`
+   - If there is a frontend: `cd frontend && npm install && npx tsc --noEmit`
+3. Check for merge artifacts: `git diff --name-only` and review any files that had conflicts.
+4. If the build fails or there are merge artifacts, fix them before pushing.
+
+Do NOT push broken code. Fix any issues first.
+
+Then push:
+```
+git push origin {directive_branch}
+```
+
 If you encounter issues you cannot resolve (e.g., persistent merge conflicts, PR update failures), you can ask for help:
   makima directive ask "Your question" --phaseguard
 "#,
@@ -1795,11 +1828,33 @@ Goal: {goal}
 Steps completed:
 {step_summary}
 
-Run these commands to create a combined branch and PR:
+Run these commands to create a combined branch:
 ```
 git fetch origin
 git checkout -b {directive_branch} origin/{base_branch}
 {merge_commands}
+```
+
+For each step branch merge, if a merge fails with conflicts:
+1. First try: `git merge --abort` then retry with `git merge <the-failing-branch> -X theirs --no-edit`
+2. If that also fails, manually resolve the conflicts, `git add .`, and `git commit --no-edit`
+3. Continue with remaining merges
+
+## CRITICAL: Pre-merge verification
+
+Before creating the PR, you MUST verify:
+1. Check that the combined changes match the directive goal: {goal}
+2. After merging all step branches, run the build to verify it compiles:
+   - If this is a Rust project: `cargo check` in the relevant crate directory
+   - If there is a frontend: `cd frontend && npm install && npx tsc --noEmit`
+3. If the build fails, fix the issues before pushing.
+4. Review the diff to ensure no merge artifacts (duplicate code, conflict markers) exist:
+   `git diff origin/{base_branch}...HEAD --stat` and spot-check large files.
+
+Do NOT create a PR if the build is broken. Fix issues first.
+
+Now push and create the PR:
+```
 git push -u origin {directive_branch}
 ```
 
@@ -1826,11 +1881,6 @@ makima directive update --pr-url "https://github.com/..."
 ```
 Replace the URL with the actual PR URL from the `gh pr create` output. This step is CRITICAL — the PR will not be tracked by the directive system without it.
 
-For each step branch merge, if a merge fails with conflicts:
-1. First try: `git merge --abort` then retry with `git merge <the-failing-branch> -X theirs --no-edit`
-2. If that also fails, manually resolve the conflicts, `git add .`, and `git commit --no-edit`
-3. Continue with remaining merges
-
 If you encounter issues you cannot resolve (e.g., persistent merge conflicts, PR creation failures), you can ask for help:
   makima directive ask "Your question" --phaseguard
 "#,
@@ -2191,10 +2241,10 @@ If step B modifies files created/changed by step A, step B MUST list step A in i
 step B will start from a blank worktree and won't see step A's changes at all.
 
 Guidelines:
-- For sequential work, create a linear chain: step1 → step2 → step3 (each depends on the previous).
-- Only omit dependsOn for truly independent steps that can start from a fresh checkout.
-- Parallel steps that share no files can omit mutual dependencies, but if they both build on a prior step
-  they should BOTH list that prior step in dependsOn.
+- STRONGLY PREFER LINEAR CHAINS: Default to creating a linear chain where each step depends on the previous (step1 -> step2 -> step3). This avoids merge conflicts when combining branches.
+- Only use parallel steps (same orderIndex, no mutual dependsOn) when tasks are TRULY independent - they modify completely different files/modules AND can start from a fresh checkout without any shared state.
+- When in doubt, make it sequential. The cost of unnecessary serialization is much lower than the cost of merge conflicts.
+- Each step in a linear chain inherits the previous steps worktree, so later steps can see and build on earlier work.
 
 IMPORTANT: Each step's taskPlan must be self-contained. The executing instance won't have your planning context.