feat: add implementation-notes tracking to code and review phases

src/prompt/context.rs

@@ -90,6 +90,7 @@ pub fn build_context_for_phase(
     let testspec_path = task_dir.join("testspec.md");
     let plan_path = task_dir.join("plan.md");
     let verify_path = task_dir.join("verify.md");
+    let impl_notes_path = task_dir.join("implementation-notes.md");
     let figma_path = task_dir.join("figma.md");
     let patterns_path = memory_dir.join("patterns.md");
     let domain_glossary_path = memory_dir.join("domain-glossary.md");
@@ -197,6 +198,9 @@ pub fn build_context_for_phase(
             if let Some(r) = has_content_ref(&testspec_path) {
                 context_files.push(r);
             }
+            if let Some(r) = has_content_ref(&impl_notes_path) {
+                context_files.push(r);
+            }
         }
     }
 

templates/agents/code-agent.md

@@ -22,6 +22,7 @@ pass with the minimal working change. Summarize every decision made during imple
 
 1. Production code changes per the plan
 2. Test code matching each case in testspec.md
+3. `.zforge/tasks/{{task_id}}/implementation-notes.md` — running log of decisions not in the spec, plan deviations, tradeoffs, and anything the reviewer should know. Append as you go.
 
 ## Rules
 

templates/agents/review-agent.md

@@ -17,6 +17,7 @@ You review only — you do not implement fixes.
 - `.zforge/tasks/{{task_id}}/testspec.md`
 - `.zforge/tasks/{{task_id}}/plan.md`
 - `.zforge/tasks/{{task_id}}/verify.md` — test run results
+- `.zforge/tasks/{{task_id}}/implementation-notes.md` — decisions, plan deviations, and tradeoffs recorded during coding (if present)
 
 ## Output
 

templates/code.tmpl

@@ -17,6 +17,7 @@ Open these only if the plan or testspec is ambiguous:
 5. Extract shared logic only when it's actually reused
 6. Run tests — all must pass
 7. Verify coverage meets testspec.md targets
+8. As you implement, keep a running log in `.zforge/tasks/{{task_id}}/implementation-notes.md`. Record every decision not covered by the spec, every deliberate change from the plan, every tradeoff you made, and anything else the reviewer should know. Append entries as you go — do not wait until the end.
 
 ## Constraints
 - Language: {{language}}

templates/review.tmpl

@@ -64,3 +64,4 @@ reviewed: false
 - Call out any testspec case IDs that are missing coverage.
 - Base every observation on evidence from the artifact files — not assumptions.
 - Keep pattern extraction limited to reusable lessons from this implementation.
+- If `implementation-notes.md` exists, read it before reviewing — use it to understand why deviations happened before judging them.