autonomous-coding-toolkit 1.0.0

package/docs/lessons/0058-dead-config-keys-never-consumed.md

@@ -0,0 +1,49 @@
+---
+id: 58
+title: "Config keys registered but never consumed are dead knobs"
+severity: should-fix
+languages: [python]
+scope: [project:autonomous-coding-toolkit]
+category: silent-failures
+pattern:
+  type: semantic
+  description: "Config keys registered in a defaults/schema file but never read via get_config or equivalent"
+fix: "Wire every registered config key to a get_config call, or remove the dead registration"
+example:
+  bad: |
+    # config_defaults.py
+    register_config("automation.min_confidence", default=0.7)
+    register_config("automation.max_suggestions", default=5)
+
+    # automation.py — uses hardcoded constants, never reads config
+    MIN_CONFIDENCE = 0.7
+    MAX_SUGGESTIONS = 5
+  good: |
+    # config_defaults.py
+    register_config("automation.min_confidence", default=0.7)
+
+    # automation.py — reads from config system
+    min_confidence = get_config_value("automation.min_confidence")
+---
+
+## Observation
+
+Config keys were registered in a defaults file and exposed in a Settings UI,
+but the consuming module used hardcoded module-level constants instead of
+reading from config. Users could adjust settings that had zero runtime effect.
+
+## Insight
+
+This happens when registration and consumption are built in different work
+batches. Batch N registers the config keys with defaults. Batch N+1
+implements the module with hardcoded constants matching those defaults.
+Neither batch verifies the integration. Dead config is worse than missing
+config — it lies to operators by showing controls that do nothing.
+
+## Lesson
+
+Every config key registration must have a corresponding read call in the
+consuming module. Add a CI check or quality gate step to detect orphaned
+config keys: extract registered keys, extract consumed keys, diff them.
+Config registration and consumption should happen in the same PR, or a
+contract test must verify that every registered key has at least one consumer.

package/docs/lessons/0059-contract-test-shared-structures.md

@@ -0,0 +1,53 @@
+---
+id: 59
+title: "Independently-built shared structures diverge without contract tests"
+severity: should-fix
+languages: [all]
+scope: [universal]
+category: integration-boundaries
+pattern:
+  type: semantic
+  description: "Two modules independently construct the same ordered structure (feature list, column names, schema) without a shared source or contract test"
+fix: "Add a contract test asserting both structures match, or extract a shared source of truth"
+example:
+  bad: |
+    # module_a.py — builds feature list from config iteration
+    features = [f.name for section in config for f in section.fields]
+
+    # module_b.py — builds feature list from manual append
+    features = []
+    features.extend(presence_features)
+    features.extend(pattern_features)
+    # Missing: event_features added to module_a but not here
+  good: |
+    # shared.py — single source of truth
+    def get_feature_names(config):
+        return [f.name for section in config for f in section.fields]
+
+    # OR: contract test
+    def test_feature_names_match():
+        assert module_a.get_features() == module_b.get_features()
+---
+
+## Observation
+
+Two modules independently built the same ordered list (feature names for ML
+column alignment). When a new section was added to one, the other was missed.
+The lists had the same names but different ordering — causing a model trained
+with column 3 = "lights_on" to use column 3 = "people_count" at inference.
+Silent data corruption, no error.
+
+## Insight
+
+When two code paths independently construct a shared structure, a developer
+adding to one path must manually remember to update the other — a human-memory
+contract with no compile-time enforcement. This applies to feature vectors,
+schema definitions, API response formats, config key lists, enum values, and
+any ordered structure where position matters.
+
+## Lesson
+
+When two modules independently build a structure that must match (same
+elements, same order), either: (1) extract a shared source of truth that both
+import, or (2) add a contract test asserting equality. Add the contract test
+BEFORE adding new elements — not after discovering the divergence.

package/docs/lessons/0060-set-e-silent-death-in-runners.md

@@ -0,0 +1,53 @@
+---
+id: 60
+title: "set -e kills long-running bash scripts silently when inter-step commands fail"
+severity: blocker
+languages: [shell]
+scope: [project:autonomous-coding-toolkit]
+category: silent-failures
+pattern:
+  type: semantic
+  description: "Bash script uses set -euo pipefail without EXIT trap or guards around non-critical inter-step operations (notifications, logging, context injection). Any unguarded command failure silently terminates the entire script."
+fix: "Add trap '_log_exit $?' EXIT for diagnostics, trap '' HUP PIPE for background survival, and wrap non-critical commands in { ... } || warn blocks"
+example:
+  bad: |
+    set -euo pipefail
+    for batch in ...; do
+        context=$(generate_context) # guarded
+        sed '...' "$file" > "$tmp"  # NOT guarded — kills script on failure
+        run_batch
+        notify_success "$batch"     # NOT guarded — kills script on failure
+    done
+  good: |
+    set -euo pipefail
+    trap '_log_exit $?' EXIT
+    trap '' HUP PIPE
+    for batch in ...; do
+        context=$(generate_context || true)
+        { sed '...' "$file" > "$tmp"; } || echo "WARNING: context injection failed" >&2
+        run_batch
+        { notify_success "$batch"; } || echo "WARNING: notification failed" >&2
+    done
+---
+
+## Observation
+
+`run-plan.sh` repeatedly died silently between batches during headless execution. The process simply vanished — no error output, no log entry, no state update. The script completed one batch successfully, then disappeared before starting the next.
+
+Log files showed the last batch succeeded (quality gate passed, state updated), but the process was gone. Restarting with `--start-batch N` always worked for the next batch, then died again.
+
+## Insight
+
+Three compounding factors:
+
+1. **`set -euo pipefail` with no EXIT trap.** Any command returning non-zero anywhere in the inter-batch code (CLAUDE.md sed manipulation, notification calls, failure pattern recording) kills the script instantly. Since there's no EXIT trap, the death is completely silent — no stack trace, no error message, no breadcrumb.
+
+2. **No signal handling — specifically SIGPIPE (confirmed).** The script pipes `claude -p` output through `tee` to write to both a log file and stdout. When stdout is a pipe to a task manager (Claude Code background task), the pipe can close between batches. `tee` then receives SIGPIPE (signal 13, exit code 141), which kills the process. Background processes need `trap '' HUP PIPE` to survive both terminal disconnects and broken pipes.
+
+3. **Non-critical operations not guarded.** The loop contained ~15 unguarded commands between the critical path (run batch → quality gate). Notifications, context injection, sed transformations, git log summaries — all could fail for transient reasons, and each failure was fatal under `set -e`.
+
+The pattern is: `set -e` is for correctness on the *critical path*. But when a long-running script has both critical operations (batch execution, quality gates) and non-critical operations (notifications, logging, context assembly), `set -e` can't distinguish between them. Non-critical failures become critical kills.
+
+## Lesson
+
+Long-running bash scripts with `set -e` must: (1) add `trap '_log_exit $?' EXIT` so unexpected terminations leave diagnostic breadcrumbs, (2) add `trap '' HUP` if they run in the background, and (3) wrap every non-critical operation in `{ commands; } || warn` blocks so transient failures don't kill the entire pipeline. The rule: if losing this operation wouldn't invalidate the batch, it must not be able to kill the script.

package/docs/lessons/0061-context-injection-dirty-state.md

@@ -0,0 +1,50 @@
+---
+id: 61
+title: "Context injection into tracked files creates dirty git state when subprocess commits"
+severity: should-fix
+languages: [shell]
+scope: [project:autonomous-coding-toolkit]
+category: integration-boundaries
+pattern:
+  type: semantic
+  description: "Script injects temporary content into a tracked file (e.g., CLAUDE.md), runs a subprocess that may commit that file, then tries to restore from backup — creating a diff against the committed version."
+fix: "Use git checkout -- <file> to restore to HEAD state instead of backup-based restoration. Fall back to backup only if file was never tracked."
+example:
+  bad: |
+    backup=$(cat "$file")
+    echo "$context" >> "$file"
+    run_subprocess  # subprocess commits $file with injected content
+    echo "$backup" > "$file"  # now differs from HEAD — dirty state
+  good: |
+    echo "$context" >> "$file"
+    run_subprocess
+    git checkout -- "$file" 2>/dev/null || {
+        # fallback: file was never tracked
+        if [[ "$existed_before" == false ]]; then
+            rm -f "$file"
+        fi
+    }
+---
+
+## Observation
+
+`run-plan.sh` injects per-batch context into `CLAUDE.md` before each batch (a `## Run-Plan: Batch N` section with failure patterns, prior batch summaries, and referenced files). After the batch completes, it restores CLAUDE.md from a backup taken before injection.
+
+Batch 5 failed the quality gate with "uncommitted changes to CLAUDE.md" even though the batch itself passed all tests. The issue: the Claude subprocess committed CLAUDE.md with the injected context as part of its work. The restoration code then wrote the pre-injection backup, creating a diff against the now-committed HEAD that included the injected content.
+
+## Insight
+
+This is an integration boundary bug between two phases that both touch the same file:
+
+1. **Orchestrator phase** — injects context into CLAUDE.md, expects to restore it after
+2. **Subprocess phase** — sees CLAUDE.md as a project file, may commit it with its changes
+
+The backup-based restoration assumes CLAUDE.md's HEAD hasn't changed during the subprocess run. But if the subprocess commits the file (which is correct behavior — it should commit its changes), the backup is now out of date. Writing the backup creates a diff between HEAD (with injected content) and the working tree (without it).
+
+The fix is to use `git checkout -- CLAUDE.md` which always restores to whatever HEAD currently is — regardless of whether the subprocess committed the injected version.
+
+Edge case: if CLAUDE.md was never tracked (created fresh by injection), `git checkout` fails. Fall back to `rm -f` in that case.
+
+## Lesson
+
+When injecting temporary content into tracked files before running a subprocess that may commit, never restore from an in-memory backup. The subprocess may commit the modified version, making the backup stale. Use `git checkout -- <file>` to restore to HEAD state, which is always correct regardless of whether the subprocess committed. Guard the edge case where the file wasn't previously tracked.

package/docs/lessons/0062-sibling-bug-neighborhood-scan.md

@@ -0,0 +1,29 @@
+---
+id: 62
+title: "Sibling bugs hide next to the fix"
+severity: should-fix
+languages: [all]
+scope: [project:autonomous-coding-toolkit]
+category: integration-boundaries
+pattern:
+  type: semantic
+  description: "When fixing a bug in a function, scan adjacent functions in the same file for the same root cause pattern"
+fix: "After fixing a function, grep the same file for the same anti-pattern in sibling functions"
+example:
+  bad: |
+    # Fix complete_batch's --argjson crash, ship it
+    # (set_quality_gate has the same crash 30 lines below)
+  good: |
+    # Fix complete_batch's --argjson crash
+    # Scan file: grep -n 'argjson' run-plan-state.sh
+    # Found same pattern in set_quality_gate — fix both
+---
+
+## Observation
+In Phase 1 bug fixes, 2 of 8 tasks had code quality reviewers find the exact same bug in a sibling function within the same file. `set_quality_gate` had the same `--argjson` crash as `complete_batch`. The API curl lacked `--connect-timeout` just like the health check curl 6 lines above it.
+
+## Insight
+Implementers fix what the ticket says. The same root cause often exists in nearby code written at the same time with the same assumptions. Fresh-context subagents don't carry knowledge of what was just fixed, so they can't pattern-match on "I just fixed this — is there another one?"
+
+## Lesson
+After fixing a bug, grep the entire file for the same anti-pattern before committing. If the root cause is a bad API usage (like `--argjson` with strings), search for all call sites of that API in the file. Code review should always check: "does this same bug exist anywhere else in this file?"

package/docs/lessons/0063-one-flag-two-lifetimes.md

@@ -0,0 +1,31 @@
+---
+id: 63
+title: "One boolean flag serving two lifetimes is a conflation bug"
+severity: should-fix
+languages: [shell, python, javascript]
+scope: [universal]
+category: silent-failures
+pattern:
+  type: semantic
+  description: "A boolean flag that is set in one lifecycle (e.g., per-iteration) but read in another (e.g., post-loop) — the flag's meaning changes depending on when you read it"
+fix: "Split into separate variables with explicit lifecycle names (e.g., _baseline_stash_created vs _winner_stash_created)"
+example:
+  bad: |
+    _stash_created=false
+    # Set during per-candidate loop (baseline purpose)
+    # Read after loop ends (winner purpose)
+    # Same flag, different meanings at different times
+  good: |
+    _baseline_stash_created=false
+    _winner_stash_created=false
+    # Each flag has one meaning throughout its entire lifetime
+---
+
+## Observation
+In the sampling stash fix (#27), `_stash_created` tracked both "was the baseline stashed?" (per-candidate lifecycle) and "was the winner stashed?" (post-loop lifecycle). When candidate 0 passed and its winner state was stashed, the next candidate's restore code popped the winner stash thinking it was the baseline.
+
+## Insight
+A boolean with two meanings at different points in time is a state machine with implicit transitions. The transitions are invisible because the variable name doesn't change — only the programmer's mental model of what it represents changes. This is especially dangerous in loops where the flag is set in one iteration and read in a different context.
+
+## Lesson
+When a flag variable is set in one code block and read in a different block with a different purpose, split it into named variables that encode their purpose. The variable name should make its lifecycle explicit. If you can't describe when the flag is "active" in one sentence, it needs to be split.

package/docs/lessons/0064-test-passes-wrong-reason.md

@@ -0,0 +1,31 @@
+---
+id: 64
+title: "Tests that pass for the wrong reason provide false confidence"
+severity: should-fix
+languages: [all]
+scope: [universal]
+category: test-anti-patterns
+pattern:
+  type: syntactic
+  regex: "\\bPATH=\"[^\":]*\""
+  description: "PATH assignment without colon (no prepend/append) — replaces entire PATH, removing all other commands from the environment"
+fix: "Verify the test fails when the fix is reverted. Ensure test setup affects only the variable under test, not its dependencies."
+example:
+  bad: |
+    # Test: free is missing → exit 2
+    PATH="/fake/bin"  # removes awk too!
+    check_memory_available 4  # exits 2 because awk is missing, not free
+  good: |
+    # Test: free is missing → exit 2
+    PATH="/fake/bin:$PATH"  # fake free, real awk
+    check_memory_available 4  # exits 2 because free outputs nothing
+---
+
+## Observation
+A test to verify `check_memory_available` returns exit 2 when `free` is unavailable set `PATH="/fake/bin"` (replacing entire PATH). This also removed `awk`, so the function returned exit 2 because awk failed — not because free was missing. The test passed, but it wasn't testing what it claimed.
+
+## Insight
+Tests that replace environment state (PATH, env vars, config files) can have blast radius beyond the intended target. The test author thinks they're isolating one variable, but they're changing a system-wide setting that affects multiple tools in the pipeline.
+
+## Lesson
+When mocking system commands, prepend to PATH (`PATH="$fake:$PATH"`) rather than replacing it. After writing a test, revert the fix and verify the test fails — if it still passes, it's testing the wrong thing. Name tests to describe the code path they exercise, not just the expected outcome.

package/docs/lessons/0065-pipefail-grep-count-double-output.md

@@ -0,0 +1,39 @@
+---
+id: 65
+title: "pipefail + grep -c + fallback produces double output"
+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 piped with || echo 0 under set -o pipefail produces '0\\n0' — grep writes 0, then fallback also writes 0"
+fix: "Wrap grep -c in a helper function that captures the exit code internally, or use || true inside a subshell"
+positive_alternative: "Use a _count_matches helper: result=$(grep -c ... || true); echo \"${result:-0}\""
+example:
+  bad: |
+    set -euo pipefail
+    count=$(echo "$text" | grep -c "pattern" || echo 0)
+    # Produces "0\n0" when no match — grep outputs 0, then fallback also outputs 0
+  good: |
+    set -euo pipefail
+    _count_matches() {
+        local result exit_code=0
+        result=$(grep -ciE "$1" 2>&1) || exit_code=$?
+        [[ $exit_code -le 1 ]] && echo "${result:-0}" || echo "0"
+    }
+    count=$(echo "$text" | _count_matches "pattern")
+---
+
+## Observation
+
+In `validate-plan-quality.sh`, scoring functions used `grep -ciE "pattern" || echo 0` to count matches safely. Under `set -euo pipefail`, when grep found zero matches (exit 1), both grep's output ("0") AND the fallback ("0") were written to stdout, producing "0\n0" instead of "0".
+
+## Insight
+
+`set -o pipefail` propagates the non-zero exit from grep through the pipe, causing the `|| echo 0` fallback to execute. But grep already wrote "0" to stdout before exiting. The fallback then appends another "0". This is invisible in most tests because `[[ "0\n0" -gt 0 ]]` still works in bash (it reads the first line), but it corrupts any downstream parsing.
+
+## Lesson
+
+Never use `command || echo default` for commands that write output before failing. Instead, capture the exit code in a wrapper function and handle it explicitly. The `_count_matches` pattern works: run grep inside the function, capture exit code, distinguish "no matches" (exit 1, normal) from "grep error" (exit 2+, unexpected).

package/docs/lessons/0066-local-keyword-outside-function.md

@@ -0,0 +1,37 @@
+---
+id: 66
+title: "local keyword used outside function scope"
+severity: should-fix
+languages: [shell]
+scope: [language:bash]
+category: silent-failures
+pattern:
+  type: semantic
+  description: "bash `local` keyword outside a function body — undefined behavior, works in bash but fails in dash/sh and is technically a bug"
+fix: "Only use `local` inside function bodies. At script top-level, just assign the variable directly."
+positive_alternative: "Remove `local` from top-level variable assignments; use plain assignment instead"
+example:
+  bad: |
+    # At script top-level (not inside a function)
+    if [[ "$JSON_OUTPUT" == true ]]; then
+        local escaped_plan
+        escaped_plan=$(printf '%s' "$PLAN_FILE" | jq -Rs '.')
+    fi
+  good: |
+    # At script top-level — no local keyword
+    if [[ "$JSON_OUTPUT" == true ]]; then
+        escaped_plan=$(printf '%s' "$PLAN_FILE" | jq -Rs '.')
+    fi
+---
+
+## Observation
+
+In `validate-plan-quality.sh`, the JSON output block at the script's top level used `local escaped_plan` to declare a variable. This worked in bash but is technically undefined behavior — `local` is only valid inside functions.
+
+## Insight
+
+Bash tolerates `local` outside functions (it just creates a regular variable), but this is a portability landmine. If the script is ever sourced by another script or run with `dash`/`sh`, it fails. It also misleads readers into thinking the code is inside a function when it isn't.
+
+## Lesson
+
+Reserve `local` for function bodies exclusively. At script top-level, use plain variable assignment. This is especially important in scripts that use `source` chains, where the boundary between "inside a function" and "top-level" blurs across files.

package/docs/lessons/0067-stdin-hang-non-interactive-shell.md

@@ -0,0 +1,36 @@
+---
+id: 67
+title: "Scripts hang when stdin is a socket or pipe in non-interactive shells"
+severity: should-fix
+languages: [shell]
+scope: [project:autonomous-coding-toolkit]
+category: silent-failures
+pattern:
+  type: semantic
+  description: "Script reads from stdin without redirection — hangs in CI, Claude Code, cron, or any environment where stdin is not a terminal"
+fix: "Add </dev/null to commands that may read stdin, or redirect stdin at the test harness level"
+positive_alternative: "Run subprocesses with explicit stdin: bash script.sh </dev/null"
+example:
+  bad: |
+    # Test harness — stdin inherited from parent (may be socket/pipe)
+    for t in scripts/tests/test-*.sh; do
+        bash "$t" >/dev/null 2>&1
+    done
+  good: |
+    # Test harness — stdin explicitly from /dev/null
+    for t in scripts/tests/test-*.sh; do
+        bash "$t" </dev/null >/dev/null 2>&1
+    done
+---
+
+## Observation
+
+Running the test suite from Claude Code's shell caused `test-lesson-check.sh` to hang indefinitely. The process was blocked on `unix_stream_read_generic` — reading from a Unix socket that served as stdin in the Claude environment. Multiple stale processes accumulated across retries.
+
+## Insight
+
+Claude Code (and similar environments like CI runners, cron jobs, tmux send-keys) connects stdin to non-terminal file descriptors. Any script that reads stdin — even indirectly through a command like `read`, `cat` without args, or a tool that checks for piped input — will block forever waiting for data that never arrives. This is invisible in interactive testing because the terminal provides EOF on Ctrl+D.
+
+## Lesson
+
+Always redirect stdin from `/dev/null` when invoking scripts in non-interactive contexts. The safest place is the test harness loop itself (`bash "$t" </dev/null`), which protects all tests regardless of what they do internally. For individual scripts, audit for stdin-reading commands and add explicit `/dev/null` redirection.

package/docs/lessons/0068-agent-builds-wrong-thing-correctly.md

@@ -0,0 +1,31 @@
+---
+id: 68
+title: "Agent builds the wrong thing correctly"
+severity: blocker
+languages: [all]
+scope: [universal]
+category: specification-drift
+pattern:
+  type: semantic
+  description: "Agent misinterprets requirements — code passes tests but doesn't match the actual spec. Tests were written against the agent's interpretation, not the user's intent."
+fix: "Before implementation, echo back the spec in your own words and get explicit user confirmation. Write acceptance criteria from the spec, not from your interpretation."
+example:
+  bad: |
+    # User asks for "retry with backoff"
+    # Agent implements retry with fixed 1s delay
+    # Test checks retry happens — passes
+    # But spec meant exponential backoff
+  good: |
+    # Echo back: "I'll implement retry with exponential backoff: 1s, 2s, 4s, 8s, max 30s"
+    # User confirms or corrects
+    # Write test that verifies exponential timing
+---
+
+## Observation
+An agent received a feature request, implemented it with full test coverage, and all tests passed. But the implementation didn't match what the user actually wanted — the agent's interpretation of the requirements diverged from the user's intent. The bug was only discovered during manual review.
+
+## Insight
+When an agent writes both the implementation AND the tests, the tests validate the agent's understanding, not the user's requirements. This creates a closed loop where wrong code passes wrong tests. The spec is the only external anchor — but agents often skip the echo-back step that would catch misinterpretation.
+
+## Lesson
+Always echo back requirements before implementing. The echo-back gate catches the 60%+ of failures that come from spec misunderstanding (not from coding errors). Write acceptance criteria from the original spec text, not from your paraphrase of it.

package/docs/lessons/0069-plan-quality-dominates-execution.md

@@ -0,0 +1,30 @@
+---
+id: 69
+title: "Plan quality dominates execution quality 3:1"
+severity: should-fix
+languages: [all]
+scope: [universal]
+category: specification-drift
+pattern:
+  type: semantic
+  description: "Investing heavily in execution optimization (retries, sampling, model routing) while the plan itself has gaps, ambiguities, or wrong decomposition. A bad plan executed perfectly still produces wrong output."
+fix: "Invest in plan quality first: scorecard the plan for completeness, correctness of decomposition, and dependency ordering before starting execution."
+example:
+  bad: |
+    # Plan says "add authentication" with no detail
+    # Execution uses MAB + competitive mode + 3 retries
+    # Result: perfectly executed wrong authentication scheme
+  good: |
+    # Plan specifies: JWT with refresh tokens, 15min access TTL
+    # Plan scorecard: all tasks have acceptance criteria
+    # Simple headless execution gets it right first try
+---
+
+## Observation
+Across multiple autonomous coding runs, the correlation between plan quality and final output quality was 3x stronger than the correlation between execution quality (retries, model choice, sampling) and output quality. The best execution infrastructure cannot compensate for a plan that decomposes the work incorrectly or omits critical requirements.
+
+## Insight
+Plan quality and execution quality are not interchangeable investments. A well-specified plan with simple execution beats a vague plan with sophisticated execution infrastructure. The plan is the specification — if it's wrong, every downstream batch inherits the error.
+
+## Lesson
+Score your plan before executing it. Check: Does every task have clear acceptance criteria? Are dependencies correctly ordered? Are there any ambiguous requirements? A 30-minute plan review saves hours of execution rework.

package/docs/lessons/0070-spec-echo-back-prevents-drift.md

@@ -0,0 +1,31 @@
+---
+id: 70
+title: "Spec echo-back prevents 60% of agent failures"
+severity: should-fix
+languages: [all]
+scope: [universal]
+category: specification-drift
+pattern:
+  type: semantic
+  description: "Agent proceeds directly from requirements to implementation without restating the requirements in its own words and confirming understanding with the user."
+fix: "Add an echo-back gate: agent restates requirements, user confirms or corrects, only then proceed to implementation."
+example:
+  bad: |
+    User: "Add rate limiting to the API"
+    Agent: *immediately starts coding*
+  good: |
+    User: "Add rate limiting to the API"
+    Agent: "I'll add token bucket rate limiting at 100 req/min per IP,
+            with 429 responses and Retry-After header. Correct?"
+    User: "Yes, but 60 req/min"
+    Agent: *now implements with correct limit*
+---
+
+## Observation
+Analysis of autonomous coding failures showed that 60%+ of failures stemmed from spec misunderstanding, not from coding errors. The agent understood the words but not the intent — implementing a technically correct solution to the wrong problem.
+
+## Insight
+Spec misunderstanding is invisible until late in the process because the agent's implementation is internally consistent. Tests pass because they test the agent's interpretation. The echo-back step forces the misunderstanding to surface before any code is written.
+
+## Lesson
+Before implementing any feature, restate the requirements in your own words and confirm with the user. This single step prevents more failures than any amount of testing or code review.

package/docs/lessons/0071-positive-instructions-outperform-negative.md

@@ -0,0 +1,30 @@
+---
+id: 71
+title: "Positive instructions outperform negative ones for LLMs"
+severity: should-fix
+languages: [all]
+scope: [universal]
+category: specification-drift
+pattern:
+  type: semantic
+  description: "Instructions phrased as 'don't do X' instead of 'do Y'. Negative instructions trigger the Pink Elephant Problem — the model encodes the forbidden pattern and may reproduce it."
+fix: "Rephrase negative instructions as positive alternatives: instead of 'don't use var', write 'use const or let'."
+example:
+  bad: |
+    # Don't use bare except clauses
+    # Don't hardcode test counts
+    # Don't use .venv/bin/pip
+  good: |
+    # Always catch specific exception classes and log
+    # Use threshold assertions (>=) for extensible collections
+    # Use .venv/bin/python -m pip for correct site-packages
+---
+
+## Observation
+When lesson files and instructions used negative phrasing ("don't do X"), agents occasionally reproduced the exact anti-pattern described — the Pink Elephant Problem. Positive phrasing ("do Y instead") consistently produced better compliance.
+
+## Insight
+LLMs process instructions by encoding all tokens, including the forbidden pattern. "Don't use bare except" encodes "bare except" as a salient concept. "Always catch specific exception classes" encodes the correct pattern directly. The model follows what it encodes most strongly.
+
+## Lesson
+Write instructions as positive alternatives: "do Y" outperforms "don't do X" for LLM compliance. When writing lessons, always include a `positive_alternative` that the agent can follow directly.

package/docs/lessons/0072-lost-in-the-middle-context-placement.md

@@ -0,0 +1,30 @@
+---
+id: 72
+title: "Lost in the Middle — context placement affects accuracy 20pp"
+severity: should-fix
+languages: [all]
+scope: [universal]
+category: context-retrieval
+pattern:
+  type: semantic
+  description: "Critical instructions or requirements placed in the middle of a long context window, where LLM attention is weakest. Task description buried after long preambles or between large code blocks."
+fix: "Place the task at the top of the context and requirements at the bottom. Keep the middle for reference material that's useful but not critical."
+example:
+  bad: |
+    [500 lines of project context]
+    [task description buried here]
+    [300 lines of code examples]
+  good: |
+    [task description — FIRST]
+    [reference material in middle]
+    [requirements and constraints — LAST]
+---
+
+## Observation
+Research on LLM context windows shows a U-shaped attention curve: models attend most strongly to the beginning and end of context, with accuracy dropping up to 20 percentage points for information placed in the middle. When critical instructions were placed mid-context, agents missed them reliably.
+
+## Insight
+The "Lost in the Middle" effect means context order matters as much as context content. A perfectly written requirement placed in the wrong position has the same effect as a missing requirement. This is especially relevant for context injection in autonomous pipelines.
+
+## Lesson
+Structure all context injection with task at the top and requirements at the bottom. Use the middle for supplementary reference material. For `run-plan-context.sh`, this means: batch description first, prior art and warnings in the middle, acceptance criteria last.

package/docs/lessons/0073-unscoped-lessons-cause-false-positives.md

@@ -0,0 +1,30 @@
+---
+id: 73
+title: "Unscoped lessons cause 67% false positive rate at scale"
+severity: should-fix
+languages: [all]
+scope: [project:autonomous-coding-toolkit]
+category: context-retrieval
+pattern:
+  type: semantic
+  description: "Lesson files without scope metadata applied universally to all projects, causing irrelevant violations to fire on projects where the anti-pattern cannot occur."
+fix: "Add scope: tags to every lesson. Use detect_project_scope() to filter lessons by project context. Default to [universal] only for genuinely cross-cutting patterns."
+example:
+  bad: |
+    # Lesson about HA automation keys fires on a React project
+    # Lesson about JSX factory fires on a Python-only project
+    # 67% of violations are irrelevant noise
+  good: |
+    scope: [domain:ha-aria]  # Only fires on HA projects
+    scope: [language:javascript, framework:preact]  # Only fires on JSX projects
+    scope: [universal]  # Genuinely applies everywhere
+---
+
+## Observation
+As the lesson library grew past ~50 lessons, the false positive rate on any given project reached 67%. Lessons about Home Assistant automation keys fired on React projects. Lessons about JSX factory issues fired on Python-only projects. Developers started ignoring lesson-check output entirely.
+
+## Insight
+Without scope metadata, every lesson fires everywhere. This is correct for universal patterns (bare except, missing await) but wrong for domain-specific patterns. The noise from irrelevant violations drowns the signal from real issues, causing the entire system to be ignored.
+
+## Lesson
+Every lesson needs scope metadata. Use `scope: [universal]` only for patterns that genuinely apply to all projects. For everything else, scope to language, framework, domain, or specific project. The scope system keeps signal-to-noise high as the library scales.

package/docs/lessons/0074-stale-context-injection-wrong-batch.md

@@ -0,0 +1,32 @@
+---
+id: 74
+title: "Stale context injection sends wrong batch's state to next agent"
+severity: should-fix
+languages: [shell]
+scope: [project:autonomous-coding-toolkit]
+category: context-retrieval
+pattern:
+  type: semantic
+  description: "Context injection (CLAUDE.md modifications, AGENTS.md generation) from a previous batch persists into the next batch because the injection writes to tracked files and the git-clean check fails, or the injection is not cleaned up between batches."
+fix: "Context injection must be idempotent and batch-scoped. Clean up injected context after each batch. Use temporary files or environment variables instead of modifying tracked files."
+example:
+  bad: |
+    # Batch 3 context injected into CLAUDE.md
+    # Batch 3 fails, retries
+    # Batch 4 starts — still sees Batch 3's context in CLAUDE.md
+    # Agent makes decisions based on stale context
+  good: |
+    # Context injected into /tmp/batch-context.md
+    # Passed via --context flag or environment variable
+    # Automatically cleaned up between batches
+    # Each batch starts with fresh, correct context
+---
+
+## Observation
+Context injection that modified tracked files (like appending to CLAUDE.md) created dirty git state between batches. The next batch's agent inherited the previous batch's context injection, making decisions based on stale information. When batch 3 failed and batch 4 started, batch 4 still saw batch 3's failure context.
+
+## Insight
+Context injection into version-controlled files conflates two lifetimes: the file's permanent content and the batch's temporary context. The git-clean quality gate catches this as "uncommitted changes" but the root cause is architectural — using the wrong persistence mechanism for ephemeral data.
+
+## Lesson
+Never inject batch-scoped context into tracked files. Use temporary files, environment variables, or the context budget in `run-plan-context.sh` which is designed for ephemeral, per-batch context injection.