autonomous-coding-toolkit 1.0.0

package/docs/lessons/0041-ambiguous-base-dir-path-nesting.md

@@ -0,0 +1,32 @@
+---
+id: 0041
+title: "Ambiguous base dir variable causes path double-nesting"
+severity: should-fix
+languages: [python, shell, all]
+scope: [universal]
+category: integration-boundaries
+pattern:
+  type: semantic
+  description: "Variable named log_dir already contains subdirectory, but os.path.join adds it again"
+fix: "Name variables to encode their scope (log_base_dir vs intelligence_dir); verify paths before first use"
+example:
+  bad: |
+    log_dir = "/var/logs/app/intelligence"
+    # Developer thinks log_dir is base, adds another level
+    intelligence_output = os.path.join(log_dir, "intelligence", "output.json")
+    # Result: /var/logs/app/intelligence/intelligence/output.json
+  good: |
+    log_base_dir = "/var/logs/app"
+    intelligence_dir = os.path.join(log_base_dir, "intelligence")
+    intelligence_output = os.path.join(intelligence_dir, "output.json")
+    # Result: /var/logs/app/intelligence/output.json
+---
+
+## Observation
+Path variables are created with unclear semantics. A variable named `log_dir` might contain `/var/logs/app` or `/var/logs/app/intelligence`. Later code blindly adds subdirectories without checking the base, resulting in nested duplicates like `intelligence/intelligence/output.json`.
+
+## Insight
+Variable naming doesn't encode the directory's depth or scope. Different developers interpret the same variable name differently, leading to double-nesting or missing levels.
+
+## Lesson
+Name path variables to encode their scope: use `_base_dir` for top-level, `_dir` for specific subdirectories. Verify all paths at initialization time before they're used. Print and assert the structure early: `assert log_base_dir.endswith('/logs/app')` and `assert intelligence_dir.endswith('/intelligence')`. Test with actual filesystem operations to catch these bugs immediately.

package/docs/lessons/0042-spec-compliance-insufficient.md

@@ -0,0 +1,36 @@
+---
+id: 0042
+title: "Spec compliance without quality review misses defensive gaps"
+severity: should-fix
+languages: [all]
+scope: [universal]
+category: integration-boundaries
+pattern:
+  type: semantic
+  description: "Code review checks only spec compliance but misses error handling, cleanup, validation, and timeouts"
+fix: "Include a defensive gaps checklist in code review, separate from spec compliance"
+example:
+  bad: |
+    # Spec: "Call API and return result"
+    def fetch_data(url):
+        response = requests.get(url)  # No timeout, no error handling
+        return response.json()  # Crashes if invalid JSON
+  good: |
+    # Spec + defensive: Call API with timeout, handle errors, validate
+    def fetch_data(url):
+        try:
+            response = requests.get(url, timeout=30)
+            return response.json()
+        except (requests.Timeout, requests.JSONDecodeError) as e:
+            logger.error(f"Fetch failed: {e}")
+            return None
+---
+
+## Observation
+Code review focuses on whether the implementation matches the specification (does it call the API? does it return the result?). It skips defensive programming: timeouts, error handling, input validation, cleanup paths, and null checks. The code is spec-compliant but fragile.
+
+## Insight
+Spec compliance is a floor, not a ceiling. Defensive programming is orthogonal to spec compliance. Reviewers who are trained to check spec often skip defensive gaps because they're not part of the spec.
+
+## Lesson
+Create a separate defensive gaps checklist for code review: Does the code have timeouts? Error handling? Input validation? Cleanup paths? Null checks? Is there logging for failure cases? Run this checklist independently from spec compliance. Make it part of the merge gate, not optional. Test with fault injection and chaos testing to verify defensive behavior.

package/docs/lessons/0043-exact-count-extensible-collections.md

@@ -0,0 +1,32 @@
+---
+id: 0043
+title: "Exact count assertions on extensible collections break on addition"
+severity: should-fix
+languages: [python, javascript, all]
+scope: [universal]
+category: test-anti-patterns
+pattern:
+  type: syntactic
+  regex: "assert.*len\\(.*==\\s*\\d+"
+  description: "Test asserts exact collection length that breaks when collection grows"
+fix: "Use >= for extensible collections, or assert specific items exist rather than total count"
+example:
+  bad: |
+    def test_users():
+        users = get_users()
+        assert len(users) == 3  # Breaks when a 4th user is added
+  good: |
+    def test_users():
+        users = get_users()
+        assert len(users) >= 3  # Allows growth
+        assert "alice" in [u.name for u in users]
+---
+
+## Observation
+Tests assert that a collection has an exact count (`assert len(items) == 5`). When the feature grows and items are added to the collection, the test fails even though the new behavior is correct. Tests become brittle and must be updated constantly.
+
+## Insight
+Exact counts are too restrictive for evolving features. The test really cares about specific items being present, not the total count. Switching to exact assertions makes tests fragile to future additions.
+
+## Lesson
+Use `>=` for collection length assertions in tests of extensible collections. Instead of asserting total count, assert that specific items exist: `assert "item" in collection` or `assert any(x.id == 5 for x in items)`. This makes tests resilient to future growth. Only use exact counts for fixed-size collections (e.g., tuple return values).

package/docs/lessons/0044-relative-file-deps-worktree.md

@@ -0,0 +1,39 @@
+---
+id: 0044
+title: "Relative `file:` deps break in git worktrees"
+severity: should-fix
+languages: [javascript, typescript]
+scope: [universal]
+category: integration-boundaries
+pattern:
+  type: semantic
+  description: "package.json file: dependencies use relative paths that break in git worktrees at different depths"
+fix: "Use workspace protocols, absolute paths resolved at install time, or npm/yarn workspaces"
+example:
+  bad: |
+    // package.json in monorepo/services/api
+    {
+      "dependencies": {
+        "shared": "file:../shared"  // Breaks in worktree
+      }
+    }
+  good: |
+    {
+      "workspaces": [
+        "packages/*",
+        "services/*"
+      ],
+      "dependencies": {
+        "shared": "workspace:*"
+      }
+    }
+---
+
+## Observation
+npm/yarn `file:` dependencies use relative paths. When code is checked out into a git worktree at a different depth than the main repo, the relative path resolves to the wrong location (or doesn't exist). This breaks CI in specific git workflows.
+
+## Insight
+Git worktrees can be created at arbitrary depths relative to the main repo. Relative path dependencies were designed for a single repository layout and fail when the layout changes.
+
+## Lesson
+Use workspace protocols (`workspace:*`) in monorepos instead of `file:` dependencies. If `file:` is necessary, resolve relative paths to absolute paths at install time. For standalone packages, use npm/yarn workspaces or lerna to manage dependencies. Test with `git worktree add` at different depths to verify dependencies resolve correctly.

package/docs/lessons/0045-iterative-design-improvement.md

@@ -0,0 +1,33 @@
+---
+id: 0045
+title: "Iterative 'how would you improve' catches 35% more design gaps"
+severity: should-fix
+languages: [all]
+scope: [universal]
+category: integration-boundaries
+pattern:
+  type: semantic
+  description: "Single-pass design review misses gaps that iterative improvement rounds would catch"
+fix: "Ask 'how would you improve this section?' after each design section; 5 rounds is the sweet spot"
+example:
+  bad: |
+    # Single design pass
+    Review once. Approve. Start building.
+    # Later: discover missing error handling, untested edge case
+  good: |
+    # Iterative design
+    Round 1: "What could break here?" -> Add timeout handling
+    Round 2: "How scale this to 10K items?" -> Add pagination
+    Round 3: "What if database is down?" -> Add circuit breaker
+    Round 4: "How to monitor this?" -> Add metrics
+    Round 5: "Any security risks?" -> Add auth validation
+---
+
+## Observation
+Design review done in a single pass typically covers the happy path. Iterative rounds of "how would you improve this section?" reveal gaps: edge cases, scale limits, failure modes, monitoring, and security issues that a single review missed.
+
+## Insight
+Single-pass review relies on reviewers catching everything. Iterative rounds make gaps explicit by forcing the designer to consider improvements from different angles. Each round builds on the previous one and surfaces new concerns.
+
+## Lesson
+After each major design section, ask "How would you improve this section?" Require at least 3 rounds; 5 is optimal. Each round should surface a new category: performance, fault tolerance, monitoring, security, or operational concerns. Document improvements and rationale. This catches design gaps before implementation and reduces rework later.

package/docs/lessons/0046-plan-assertion-math-bugs.md

@@ -0,0 +1,38 @@
+---
+id: 0046
+title: "Plan-specified test assertions can have math bugs"
+severity: should-fix
+languages: [all]
+scope: [universal]
+category: test-anti-patterns
+pattern:
+  type: semantic
+  description: "Implementation plan specifies test thresholds with math errors that implementer copies verbatim"
+fix: "Verify threshold boundary logic independently before writing the test"
+example:
+  bad: |
+    # Plan says: "Assert that 90% of requests succeed"
+    # Implementer writes (copying from plan):
+    assert success_count / total_count >= 0.9
+    # But 0.9 is already 90%, so this is correct.
+    # But what if plan meant: "Assert that error rate is below 10%"?
+    # assert error_count / total_count <= 0.1  # Different logic
+
+    # Implementer didn't verify the math matched intent
+  good: |
+    # Plan specifies: "Assert 90% success rate (>= 0.9)"
+    # Before implementing, verify:
+    # 90% = 0.9 (correct multiplier)
+    # 10% = 0.1 (correct error rate)
+    # Test with known values: 9/10 = 0.9 ✓
+    assert success_count / total_count >= 0.9
+---
+
+## Observation
+Implementation plans specify test thresholds and assertions. Implementers copy these verbatim without verifying the math. If the plan has a boundary condition error (off-by-one, wrong direction, incorrect multiplier), the implementer creates a test that passes despite incorrect logic.
+
+## Insight
+Plan authors may write thresholds informally or with implicit assumptions. Implementers assume the math is correct and don't double-check. Boundary logic errors slip through undetected.
+
+## Lesson
+Before implementing any threshold-based assertion, verify the math independently. Test with concrete values to confirm the boundary is correct. For example, if the plan says "90% success rate," verify: success_count=9, total=10, then assert 9/10 >= 0.9 should pass. success_count=8, total=10, then assert 8/10 >= 0.9 should fail. Write and run these boundary tests before implementing the main test.

package/docs/lessons/0047-pytest-single-threaded-default.md

@@ -0,0 +1,37 @@
+---
+id: 0047
+title: "pytest runs single-threaded by default -- add xdist"
+severity: should-fix
+languages: [python]
+scope: [framework:pytest]
+category: performance
+pattern:
+  type: semantic
+  description: "pytest test suite runs single-threaded when parallel execution would be significantly faster"
+fix: "Add pytest-xdist to dev deps and addopts = '-n auto' to pytest config"
+example:
+  bad: |
+    # pytest.ini or pyproject.toml
+    [tool.pytest.ini_options]
+    testpaths = ["tests"]
+    # Result: runs tests one at a time (slow)
+
+  good: |
+    # pyproject.toml
+    [tool.pytest.ini_options]
+    testpaths = ["tests"]
+    addopts = "-n auto --dist load"
+
+    # requirements-dev.txt or pyproject.toml
+    pytest-xdist>=3.5.0
+    # Result: runs tests in parallel (fast)
+---
+
+## Observation
+pytest, by default, runs tests sequentially in a single worker process. For test suites with 50+ tests, this is significantly slower than parallel execution. Developers run test suites serially and accept the slow feedback loop, unaware that xdist can parallelize.
+
+## Insight
+pytest-xdist provides automatic parallelization across multiple CPU cores. Running tests in parallel often provides 3-6x speedup on modern hardware, but requires explicit configuration. This is a low-effort, high-impact performance improvement.
+
+## Lesson
+Add `pytest-xdist>=3.5.0` to dev dependencies. Add `addopts = "-n auto --dist load"` to pytest configuration. This parallelizes tests automatically, using all available CPU cores. Use `-n 0` to disable parallelization temporarily for debugging. Test with your specific test suite to measure speedup. For very large test suites, use `-n 6` instead of `-n auto` to prevent memory exhaustion.

package/docs/lessons/0048-integration-wiring-batch.md

@@ -0,0 +1,40 @@
+---
+id: 0048
+title: "Multi-batch plans need explicit integration wiring batch"
+severity: should-fix
+languages: [all]
+scope: [universal]
+category: integration-boundaries
+pattern:
+  type: semantic
+  description: "Multi-batch plan builds components separately but skips the step of wiring them together"
+fix: "Plans with 3+ batches must include a final integration wiring batch"
+example:
+  bad: |
+    # Plan with 3 batches:
+    Batch 1: Build API endpoint
+    Batch 2: Build database schema
+    Batch 3: Build client code
+    # Missing: wire components together
+
+    # Result: Each piece works in isolation, but together they fail
+  good: |
+    # Plan with 4 batches:
+    Batch 1: Build API endpoint
+    Batch 2: Build database schema
+    Batch 3: Build client code
+    Batch 4: Integration wiring
+      - Connect API to database
+      - Connect client to API
+      - Verify end-to-end flow
+      - Run integration tests
+---
+
+## Observation
+Multi-batch plans build components (API, database, client) independently. Each batch passes its own tests. But components aren't wired together during implementation. Integration happens only at the end, revealing coupling issues, interface mismatches, and missing adapters too late.
+
+## Insight
+Batch-driven development optimizes for parallel work but can miss integration points. Components are unit-tested in isolation but may fail when combined. Without an explicit wiring batch, integration is assumed to "just work."
+
+## Lesson
+Plans with 3+ batches must include a final integration wiring batch. This batch connects components built in earlier batches, verifies data flows through the full pipeline, and runs end-to-end integration tests. Include this batch in the plan before implementation starts. Test the full system (not just individual components) after wiring is complete.

package/docs/lessons/0049-ab-verification.md

@@ -0,0 +1,41 @@
+---
+id: 0049
+title: "A/B verification finds zero-overlap bug classes"
+severity: should-fix
+languages: [all]
+scope: [universal]
+category: integration-boundaries
+pattern:
+  type: semantic
+  description: "Using only bottom-up or only top-down review misses entire classes of bugs"
+fix: "Run both bottom-up (code-level) and top-down (architecture-level) review after 3+ batch implementations"
+example:
+  bad: |
+    # Bottom-up only: review each component's code
+    # Result: logic errors caught, but coupling issues missed
+    # Reviewer doesn't see: API expects array, client sends object
+
+    # Top-down only: review architecture diagrams
+    # Result: structure looks good, but off-by-one in retry logic missed
+    # Reviewer doesn't see: code-level bugs
+  good: |
+    # Bottom-up: Review code implementation
+    - Are loops correct? Error handling present? State managed correctly?
+
+    # Top-down: Review architecture
+    - Do components couple correctly? Is data flow end-to-end?
+
+    # Both perspectives together catch more bugs than either alone
+---
+
+## Observation
+Code reviews conducted only from the bottom-up (code-level logic) miss architectural coupling issues. Reviews conducted only from the top-down (architecture diagrams) miss implementation bugs. Different bugs are visible from different angles.
+
+## Insight
+Bugs fall into different categories based on visibility:
+- **Bottom-up visible:** off-by-one errors, null checks, state management, loop logic
+- **Top-down visible:** coupling between components, interface mismatches, data flow breaks, missing error propagation
+- **Requires both:** race conditions, distributed state consistency, integration deadlocks
+
+## Lesson
+Run both bottom-up and top-down review after implementing 3+ batches. Bottom-up: inspect code for logic errors, edge cases, resource cleanup. Top-down: trace data flow end-to-end, verify component interfaces match, check for coupling leaks. Document findings from each perspective. Bugs caught only in top-down review indicate architectural issues; bugs caught only in bottom-up indicate implementation issues. Fix both before declaring done.

package/docs/lessons/0050-editing-sourced-files-during-execution.md

@@ -0,0 +1,33 @@
+---
+id: 50
+title: "Editing files sourced by a running process breaks function signatures"
+severity: blocker
+languages: [shell]
+scope: [project:autonomous-coding-toolkit]
+category: integration-boundaries
+pattern:
+  type: semantic
+  description: "Modifying function signatures in files that are actively sourced by a running bash process (e.g., editing run-plan-notify.sh while run-plan.sh is executing)"
+fix: "Never edit library files while they're being sourced by a running process. Wait for the run to complete, or commit changes that only new runs will pick up."
+example:
+  bad: |
+    # While run-plan.sh is running (sources run-plan-notify.sh at startup):
+    # Edit run-plan-notify.sh to change format_success_message from 6 to 9 params
+    # -> Next batch call crashes with wrong argument count
+  good: |
+    # Wait for run-plan.sh to finish, then edit
+    # Or: make changes backward-compatible (add params with defaults)
+    format_success_message() {
+        local plan="$1" batch="$2" total="${3:-?}" title="${4:-}"
+        # ... rest uses defaults for missing params
+    }
+---
+
+## Observation
+During Phase 4 execution, `run-plan-notify.sh` was edited to add `total_batches` and `batch_title` parameters to `format_success_message` (6 → 9 params). The running `run-plan.sh` process had already sourced the original file at startup. When the next batch called `notify_success` with the old 6-parameter signature, the quality gate detected uncommitted changes and failed.
+
+## Insight
+Bash sources files once at startup — there's no hot-reload. But the *file on disk* is what `git diff` sees. So editing a sourced file creates a two-way failure: (1) the running process uses stale function signatures, and (2) the quality gate sees uncommitted changes. The fix had to be committed to unblock the gate, but that commit changed signatures the running process was still calling with old argument counts.
+
+## Lesson
+Treat sourced library files as immutable during execution. If you must change them: (a) make changes backward-compatible with default parameter values, (b) commit immediately so the quality gate stays clean, and (c) accept that the current run uses the old behavior. Never change function arity in a file that a running process has already sourced.

package/docs/lessons/0051-infrastructure-fixes-cant-self-heal.md

@@ -0,0 +1,30 @@
+---
+id: 51
+title: "Infrastructure fixes in a plan cannot benefit the run executing that plan"
+severity: should-fix
+languages: [shell]
+scope: [project:autonomous-coding-toolkit]
+category: integration-boundaries
+pattern:
+  type: semantic
+  description: "A plan includes tasks that fix the execution infrastructure (e.g., empty batch detection, parser improvements) but the current run-plan.sh process loaded the old code at startup"
+fix: "Place infrastructure fixes in a separate pre-flight plan, or accept that the current run uses old behavior and the fix only helps future runs."
+example:
+  bad: |
+    # Plan Batch 1: Fix empty batch detection in run-plan-headless.sh
+    # -> Fix is committed, but the running bash process already loaded old code
+    # -> Batches 6-19 still spawn claude for empty batches (43s each)
+  good: |
+    # Option A: Separate pre-flight plan for infra fixes, then main plan
+    # Option B: Accept the cost — document that infra fixes are forward-looking
+    # Option C: Use --start-batch to re-run from where infra fix takes effect
+---
+
+## Observation
+The Phase 4 plan included Task 1: "Fix empty batch detection in run-plan-headless.sh." The fix was committed during Batch 1. However, the `run-plan.sh` bash process had already loaded `run-plan-headless.sh` at startup. Batches 6-19 (parser artifacts) still spawned a `claude -p` process for each empty batch (~30-50s each), wasting ~7 minutes and API calls.
+
+## Insight
+Bash reads `source` files once. The running process keeps the in-memory version of all sourced functions. Committing a fix to disk doesn't update the running process — only a new invocation reads the new code. This is fundamentally different from interpreted languages with hot-reload (Python's importlib, Node's require cache invalidation).
+
+## Lesson
+Infrastructure fixes (parser, quality gate, notification format) cannot benefit the execution that implements them. Either: (1) run infra fixes as a separate pre-flight step before the main plan, (2) accept the waste and document it as known, or (3) after the infra batch, stop and re-run with `--resume` so a fresh process loads the fixed code.

package/docs/lessons/0052-uncommitted-changes-poison-quality-gates.md

@@ -0,0 +1,31 @@
+---
+id: 52
+title: "Uncommitted changes from parallel work fail the quality gate git-clean check"
+severity: blocker
+languages: [shell]
+scope: [universal]
+category: integration-boundaries
+pattern:
+  type: semantic
+  description: "Manual edits to files in a worktree where run-plan.sh is executing — the git-clean check in quality-gate.sh detects uncommitted changes and fails the batch"
+fix: "Never make uncommitted changes in a worktree with an active run-plan. Use a separate worktree or commit before the next quality gate runs."
+example:
+  bad: |
+    # run-plan.sh is executing batches in ~/project/
+    # Meanwhile, manually edit scripts/lib/run-plan-notify.sh
+    # -> Quality gate runs check_git_clean() -> finds dirty working tree -> FAIL
+  good: |
+    # Option A: Edit in a separate worktree
+    git worktree add ../project-notify-fix -b fix/notifications
+    # Option B: Commit immediately before next quality gate
+    git add scripts/lib/run-plan-notify.sh && git commit -m "fix: ..."
+---
+
+## Observation
+During Phase 4 execution, Telegram notification format was improved by editing `run-plan-notify.sh` and its test file directly in the worktree where `run-plan.sh` was running. When Batch 9 completed and the quality gate ran `check_git_clean()`, it found 3 uncommitted files and failed the batch. The batch agent then spent a full retry attempt (5+ minutes) trying to fix a problem that wasn't caused by its own work.
+
+## Insight
+The quality gate's git-clean check exists to ensure every batch's work is committed before the next batch starts. It can't distinguish between "the batch agent forgot to commit" and "a human made parallel edits." Both look the same: dirty working tree. The retry agent wastes time investigating a failure it can't fix, since the dirty files aren't part of its batch.
+
+## Lesson
+A worktree with an active run-plan is a no-edit zone. All parallel work must happen in a separate worktree or be committed immediately. If you must edit files in the active worktree, commit them before the next quality gate runs. The cost of a wasted retry (5+ minutes, API calls) far exceeds the cost of a quick commit.

package/docs/lessons/0053-jq-compact-flag-inconsistency.md

@@ -0,0 +1,31 @@
+---
+id: 53
+title: "Missing jq -c flag causes string comparison failures in tests"
+severity: should-fix
+languages: [shell]
+scope: [project:autonomous-coding-toolkit]
+category: test-anti-patterns
+pattern:
+  type: syntactic
+  regex: "assert_eq.*\\$\\(.*jq [^-]"
+  description: "Using jq without -c flag in a string comparison assertion — pretty-printed output won't match compact expected values"
+fix: "Always use jq -c (compact) when the output will be compared as a string. Or compare with jq equality instead of string equality."
+example:
+  bad: |
+    result=$(echo "$json" | jq '.[0] | sort')
+    assert_eq "group is [1]" '[1]' "$result"
+    # FAIL: expected [1], got [\n  1\n]
+  good: |
+    result=$(echo "$json" | jq -c '.[0] | sort')
+    assert_eq "group is [1]" '[1]' "$result"
+    # PASS: both are [1]
+---
+
+## Observation
+In `test-run-plan-team.sh`, three assertions failed because one `jq` call used `jq '.[2] | sort'` (pretty-printed) while the test expected compact JSON `[4]`. The other two calls on adjacent lines correctly used `jq -c`. The inconsistency was introduced when the test was generated — two of three similar lines got the `-c` flag, one didn't.
+
+## Insight
+jq defaults to pretty-printing (multi-line, indented). When output is stored in a variable and compared with `assert_eq`, the multi-line string `[\n  4\n]` never matches the compact string `[4]`. This is invisible until the test runs because the pattern looks correct at a glance. The failure message shows the actual as multi-line, making the `-c` omission obvious only in hindsight.
+
+## Lesson
+In shell test scripts, always use `jq -c` when the result will be compared as a string. Better yet, use `jq -e` for boolean checks or compare with `jq --argjson expected '[4]' '. == $expected'` to avoid format sensitivity entirely.

package/docs/lessons/0054-parser-matches-inside-code-blocks.md

@@ -0,0 +1,30 @@
+---
+id: 54
+title: "Markdown parser matches headers inside code blocks and test fixtures"
+severity: should-fix
+languages: [shell]
+scope: [project:autonomous-coding-toolkit]
+category: silent-failures
+pattern:
+  type: semantic
+  description: "A markdown parser using simple regex (grep/awk) matches ## headers that appear inside fenced code blocks, heredocs, or test fixture content — inflating batch/task counts"
+fix: "Track fenced code block state (``` toggles) and skip matches inside code blocks. Or use a proper markdown AST parser."
+example:
+  bad: |
+    # count_batches uses: grep -c '^## Batch'
+    # Plan has a test fixture with '## Batch 2: Also Real' inside a heredoc
+    # -> Parser counts 19 batches for a 5-batch plan
+  good: |
+    count_batches() {
+        awk '/^```/{fence=!fence} !fence && /^## Batch/{n++} END{print n}' "$1"
+    }
+---
+
+## Observation
+The Phase 4 plan had 5 real batches, but `count_batches` found 19. The extra 14 came from `## Batch` and `### Task` headers inside test fixtures, code examples, and plan documentation sections. Each phantom batch spawned a `claude -p` process (~30-50s each), wasting ~7 minutes and API credits.
+
+## Insight
+Simple `grep '^## Batch'` treats all lines equally — it cannot distinguish a real plan header from one inside a fenced code block (` ``` `), a heredoc, or an inline example. This is a fundamental limitation of line-by-line regex parsing of markdown. The problem compounds: the plan's own test (Task 1) includes sample plan content with headers, creating a recursive parsing trap.
+
+## Lesson
+Any markdown parser that affects execution (batch counting, task extraction) must be code-block-aware. Minimum viable fix: track ` ``` ` fence state with a toggle variable and skip matches inside fences. Better: use a dedicated markdown heading extraction that respects the CommonMark spec. The empty-batch-skip mitigates the cost but doesn't prevent the API calls for the initial `claude -p` attempt on each phantom batch.

package/docs/lessons/0055-agents-compensate-for-garbled-prompts.md

@@ -0,0 +1,31 @@
+---
+id: 55
+title: "LLM agents compensate for garbled batch prompts using cross-batch context"
+severity: nice-to-have
+languages: [all]
+scope: [universal]
+category: integration-boundaries
+pattern:
+  type: semantic
+  description: "An agent receives a malformed or empty batch prompt but successfully infers the correct work from progress.txt, recent git commits, and the full plan file"
+fix: "Design for resilience: include progress notes, recent commits, and the full plan in every batch prompt so agents can self-correct when the parsed batch content is wrong."
+example:
+  bad: |
+    # Batch prompt: "Batch 9: (empty)" with no tasks
+    # Agent has no context -> does nothing or hallucinates
+  good: |
+    # Batch prompt: "Batch 9: (empty)" BUT includes:
+    # - progress.txt with completed tasks listed
+    # - Recent git log showing what's been done
+    # - Full plan file reference
+    # -> Agent reads plan, deduces remaining work, implements correctly
+---
+
+## Observation
+During Phase 4, batches 2 and 9 received garbled prompts — Batch 2 got fake content from a test fixture ("Task 2: Do more / Write more code"), and Batch 9 got an empty batch title. Despite this, both agents successfully implemented the correct plan tasks. Batch 2 implemented Tasks 7-9 (context assembler), and Batch 9 implemented Tasks 10, 11, 12, 15, and 17 (ast-grep + team mode).
+
+## Insight
+The cross-batch context system (progress.txt, recent commits in the prompt, and the plan file reference) provides enough information for agents to self-correct. The agent reads what's been done, compares it to the full plan, and picks up the next logical tasks. This resilience is an emergent property of including redundant context — no single source needs to be correct as long as the ensemble is informative.
+
+## Lesson
+Always include multiple context signals in batch prompts: (1) progress notes listing completed work, (2) recent git commits showing actual changes, (3) the full plan file path for reference. This creates graceful degradation — even when the parser sends wrong batch content, agents can figure out what work remains. The cost is slightly larger prompts; the benefit is resilience to parser bugs.

package/docs/lessons/0056-grep-count-exit-code-on-zero.md

@@ -0,0 +1,42 @@
+---
+id: 56
+title: "grep -c exits 1 on zero matches, breaking || fallback arithmetic"
+severity: should-fix
+languages: [shell]
+scope: [language:bash]
+category: silent-failures
+pattern:
+  type: syntactic
+  regex: "grep\\s+-c.*\\|\\|\\s*echo\\s+[\"']?0[\"']?"
+  description: "grep -c with || echo 0 fallback — produces multiline output on zero matches"
+fix: "Use || true with ${var:-0} default instead of || echo 0"
+example:
+  bad: |
+    count=$(echo "$text" | grep -c "pattern" || echo "0")
+    result=$((count + 1))  # breaks: count="0\n0" from both outputs
+  good: |
+    count=$(echo "$text" | grep -c "pattern" || true)
+    count=${count:-0}
+    result=$((count + 1))
+---
+
+## Observation
+
+`grep -c` returns both the count AND exit code 1 when count is 0.
+With `|| echo "0"`, the fallback fires AND grep's "0" output is kept,
+producing `"0\n0"`. Bash arithmetic `$((0\n0 + 1))` fails with
+"syntax error in expression".
+
+## Insight
+
+`grep -c` violates the common assumption that exit code 1 means "error."
+In grep, exit 1 means "no matches found" — a valid result, not a failure.
+The `|| echo "0"` pattern double-counts because the subshell captures
+grep's stdout ("0") AND the fallback echo ("0") on separate lines.
+
+## Lesson
+
+Never use `grep -c ... || echo "0"` for count fallback. Use
+`grep -c ... || true` to suppress the exit code, then `${var:-0}` as
+the numeric default. This pattern is safe because `|| true` doesn't
+add to stdout — it only prevents `set -e` from aborting the script.

package/docs/lessons/0057-new-artifacts-break-git-clean-gates.md

@@ -0,0 +1,42 @@
+---
+id: 57
+title: "New generated artifacts break git-clean quality gates"
+severity: should-fix
+languages: [all]
+scope: [universal]
+category: integration-boundaries
+pattern:
+  type: semantic
+  description: "Adding a new generated file to a pipeline without updating gitignore and E2E tests"
+fix: "When adding generated artifacts, update .gitignore AND all E2E test gitignore fixtures"
+example:
+  bad: |
+    # Added generate_agents_md() to startup
+    # AGENTS.md created in worktree
+    # E2E test fails: "uncommitted changes in worktree"
+  good: |
+    # Added generate_agents_md() to startup
+    # Updated E2E test .gitignore to include AGENTS.md
+    # E2E test passes: git-clean check ignores AGENTS.md
+---
+
+## Observation
+
+Adding `generate_agents_md()` to the headless runner startup created
+AGENTS.md in the worktree. The function's own unit test passed. But the
+E2E test failed because its git worktree now had an untracked file,
+and the quality gate's `check_git_clean` rejected it.
+
+## Insight
+
+This is Cluster B (Integration Boundaries). When a pipeline generates
+new files, the git-clean check sees them as uncommitted work. Every
+generated artifact needs a corresponding gitignore entry — both in the
+real project AND in test fixtures that simulate the worktree.
+
+## Lesson
+
+Whenever you add a new generated file to a pipeline: (1) add it to the
+project's `.gitignore`, (2) add it to every E2E test fixture's
+`.gitignore`, (3) run the E2E test before committing. The unit test for
+the generator won't catch this because it doesn't run the quality gate.