autonomous-coding-toolkit 1.0.0

package/docs/lessons/0075-research-artifacts-must-persist.md

@@ -0,0 +1,32 @@
+---
+id: 75
+title: "Research artifacts must persist — ephemeral research is wasted research"
+severity: should-fix
+languages: [all]
+scope: [universal]
+category: context-retrieval
+pattern:
+  type: semantic
+  description: "Research findings discussed in conversation but never written to a file. When context resets (new session, /clear, context compression), all research is lost and must be redone."
+fix: "Every research activity must produce a durable file artifact. Write findings to tasks/research-<slug>.md immediately. Never rely on conversation context for research persistence."
+example:
+  bad: |
+    # Agent researches 3 libraries, compares trade-offs
+    # Findings exist only in conversation
+    # User does /clear
+    # Next session: "What libraries did we evaluate?" — gone
+  good: |
+    # Agent researches 3 libraries, writes tasks/research-auth-libs.md
+    # File includes: comparison table, recommendation, blocking issues
+    # User does /clear
+    # Next session reads the file — full context preserved
+---
+
+## Observation
+Research conducted during brainstorming or planning was discussed in conversation but never written to a file. When the session ended or context compressed, all research findings were lost. The next session had to redo the same research, often reaching different conclusions.
+
+## Insight
+Conversation context is ephemeral by design — context windows compress, sessions end, `/clear` resets everything. Research that exists only in conversation has the same durability as spoken words. File artifacts are the only mechanism that survives context boundaries.
+
+## Lesson
+Always make a file. Every research activity, design decision, and investigation produces a durable artifact at `tasks/research-<slug>.md`. No ephemeral research — files survive context resets, conversation context doesn't.

package/docs/lessons/0076-wrong-decomposition-contaminates-downstream.md

@@ -0,0 +1,30 @@
+---
+id: 76
+title: "Wrong decomposition contaminates all downstream batches"
+severity: blocker
+languages: [all]
+scope: [universal]
+category: planning-control-flow
+pattern:
+  type: semantic
+  description: "A plan decomposes work into batches where an early batch has the wrong boundary — wrong files, wrong order, or wrong grouping. All subsequent batches inherit the wrong foundation and compound the error."
+fix: "Validate decomposition before execution: check that batch boundaries align with module boundaries, dependencies flow forward (never backward), and each batch is independently testable."
+example:
+  bad: |
+    # Batch 1: Create API + frontend (too broad, untestable)
+    # Batch 2: Add tests (tests written after, not with)
+    # Batch 3: Integration (discovers Batch 1 was wrong)
+  good: |
+    # Batch 1: Create API with tests (independently verifiable)
+    # Batch 2: Create frontend with tests (independently verifiable)
+    # Batch 3: Integration wiring with e2e test
+---
+
+## Observation
+A plan decomposed a feature into 5 batches. Batch 1 grouped files incorrectly — putting the data model and the API handler in the same batch when they had different dependencies. Every subsequent batch built on batch 1's incorrect structure. By batch 4, the agent was fighting the architecture instead of building on it.
+
+## Insight
+Decomposition errors are the most expensive kind of plan bug because they compound. Each batch that builds on a wrong foundation adds more code that depends on the wrong structure. The cost to fix grows quadratically with the number of affected batches.
+
+## Lesson
+Validate plan decomposition before executing. Check: Does each batch align with a natural module boundary? Do dependencies flow strictly forward (batch N never depends on batch N+1)? Is each batch independently testable? A 10-minute decomposition review prevents multi-hour rework.

package/docs/lessons/0077-cherry-pick-merges-need-manual-resolution.md

@@ -0,0 +1,30 @@
+---
+id: 77
+title: "Cherry-pick merges from parallel worktrees need manual conflict resolution"
+severity: should-fix
+languages: [all]
+scope: [project:autonomous-coding-toolkit]
+category: planning-control-flow
+pattern:
+  type: semantic
+  description: "Multiple agents work in parallel worktrees on the same files. Cherry-picking the winner's commits into main creates merge conflicts that automated tools cannot resolve correctly because they lack the semantic context of why each change was made."
+fix: "When cherry-picking from parallel worktrees, always use interactive conflict resolution. Never auto-resolve with --theirs or --ours. Review each conflict with the judge agent's scoring context."
+example:
+  bad: |
+    git cherry-pick abc123 --strategy-option theirs  # blindly takes one side
+    # Loses valuable changes from the other worktree
+  good: |
+    git cherry-pick abc123  # stops on conflict
+    # Review each conflict with context from judge's scoring
+    # Manually merge best-of-both changes
+    git add resolved-file.py && git cherry-pick --continue
+---
+
+## Observation
+In competitive mode, two agents implemented the same batch in separate worktrees. The judge picked a winner, but cherry-picking the winner's commits into the main worktree produced merge conflicts in 3 files. Using `--theirs` to auto-resolve discarded valuable fixes from the losing agent that the judge had flagged for best-of-both synthesis.
+
+## Insight
+Cherry-pick conflicts between parallel implementations are semantically rich — each side made deliberate, different choices. Automated resolution strategies (`--theirs`, `--ours`) discard information. Only a reviewer with the judge's scoring context can correctly merge the best of both.
+
+## Lesson
+Never auto-resolve cherry-pick conflicts from parallel worktrees. Use interactive resolution with the judge agent's scoring context. The mandatory best-of-both synthesis in competitive mode means both sides have value — the conflict resolution is where that value is captured.

package/docs/lessons/0078-static-review-without-live-test.md

@@ -0,0 +1,30 @@
+---
+id: 78
+title: "Static review without live test optimizes for the wrong risk class"
+severity: should-fix
+languages: [all]
+scope: [universal]
+category: planning-control-flow
+pattern:
+  type: semantic
+  description: "Relying solely on static code review (reading code, checking patterns) without running the code in a live environment. Static review catches structural issues but misses behavioral bugs that only manifest at runtime."
+fix: "Always combine static review with at least one live integration test. One live test catches more real bugs than six static reviewers."
+example:
+  bad: |
+    # 6 review agents read the code
+    # All report "looks good"
+    # Deploy → runtime error on first request
+  good: |
+    # 2 review agents read the code
+    # 1 integration test runs the actual pipeline
+    # Runtime error caught before deploy
+---
+
+## Observation
+A code change was reviewed by six static analysis agents. All reported the code was correct. On deployment, the first real request triggered a runtime error that none of the static reviewers could have caught — the bug was in the interaction between two components at runtime, not in either component's code.
+
+## Insight
+Static review and live testing catch non-overlapping bug classes. Static review finds structural issues (wrong patterns, missing imports, type errors). Live testing finds behavioral issues (wrong data flow, timing bugs, environment-dependent failures). Investing only in static review creates a false sense of confidence.
+
+## Lesson
+Always combine static review (at most 2 agents — diminishing returns after that) with at least one live integration test. The audit method should always be: static review for structural correctness + live test for behavioral correctness. One live test is worth six static reviewers.

package/docs/lessons/0079-integration-wiring-batch-required.md

@@ -0,0 +1,32 @@
+---
+id: 79
+title: "Multi-batch plans need an explicit integration wiring batch"
+severity: should-fix
+languages: [all]
+scope: [universal]
+category: planning-control-flow
+pattern:
+  type: semantic
+  description: "A multi-batch plan where each batch creates separate components but no batch is dedicated to wiring them together. Each component passes its own tests but the pipeline is disconnected."
+fix: "Add an explicit integration wiring batch at the end (or at natural integration points) that connects components and runs end-to-end tests. The wiring batch should have no new feature code — only imports, configuration, and integration tests."
+example:
+  bad: |
+    # Batch 1: Build parser (tests pass)
+    # Batch 2: Build formatter (tests pass)
+    # Batch 3: Build CLI (tests pass)
+    # Result: CLI doesn't call parser, parser doesn't feed formatter
+  good: |
+    # Batch 1: Build parser (tests pass)
+    # Batch 2: Build formatter (tests pass)
+    # Batch 3: Wire parser → formatter, integration test
+    # Batch 4: Build CLI using wired pipeline, e2e test
+---
+
+## Observation
+A 5-batch plan created 5 separate components. Each batch had thorough unit tests and all passed. But the components were never wired together — no batch was responsible for integration. The final "verify" step discovered that the components couldn't communicate because they used incompatible interfaces.
+
+## Insight
+When each batch is scoped to a single component, integration is an implicit assumption — "someone will wire these together." But in autonomous execution, implicit assumptions don't get executed. Each batch follows its explicit instructions, and if no batch says "wire X to Y", it doesn't happen.
+
+## Lesson
+Every multi-batch plan with 3+ components needs at least one explicit integration wiring batch. This batch should: import all components, configure their connections, and run at least one end-to-end test that traces data through the full pipeline. No new feature code — only wiring and verification.

package/docs/lessons/FRAMEWORK.md

@@ -0,0 +1,161 @@
+# Lessons Learned Framework
+
+Synthesized from three methodologies adapted for personal infrastructure and AI system development.
+
+## Source Frameworks
+
+| Framework | Contribution | Reference |
+|-----------|-------------|-----------|
+| **Army CALL OIL** | Maturity taxonomy (Observation → Insight → Lesson → Lesson Learned) | CALL Handbook 11-33 |
+| **PMI PMBOK** | Structured register (category, root cause, corrective action, keywords) | PMI Lessons Learned Register |
+| **Lean Six Sigma** | Analysis tools (5 Whys, Fishbone 6M, A3 format, DMAIC phases) | LSS Green Belt (Notion: Tri-County LEAN Six Sigma Made EZ) |
+
+## OIL Maturity Taxonomy
+
+Not every finding is a "lesson learned." The Army's OIL taxonomy provides a promotion path:
+
+### Tier 1: Observation
+**"What happened."** Raw conditions, symptoms, and facts from an incident.
+- Requires: Date, system, files involved, factual description
+- Example: "Intraday snapshots showed entities.total: 0 despite 14,392 logbook events"
+- Status: `observed`
+
+### Tier 2: Insight
+**"What it means."** Analysis connecting observation to root cause. Uses 5 Whys or Fishbone to dig below symptoms.
+- Requires: Root cause identified, impact assessed, "why" chain documented
+- Example: "Decorator-based collector registry was never imported, so CollectorRegistry.all() returned empty dict"
+- Status: `analyzed`
+
+### Tier 3: Lesson
+**"What to do about it."** Proposed corrective action — specific, implementable, testable.
+- Requires: Corrective action described, preventive measure proposed, owner identified
+- Example: "Add integration test verifying collector count >= 15; add import comment pattern to all decorator registries"
+- Status: `proposed`
+
+### Tier 4: Lesson Learned
+**"Validated behavioral change."** The corrective action has been implemented, tested, AND confirmed to prevent recurrence. This is the highest tier — most entries won't reach it immediately.
+- Requires: Implementation proof (commit, test, config change), validation evidence, sustain plan
+- Example: "Test added (commit abc123), collector count assertion catches this class of bug. No recurrence in 30 days."
+- Status: `validated`
+
+**Key distinction:** A lesson is *proposed*. A lesson learned is *proven*. Most entries start as Tier 1-2 and promote over time.
+
+## Lesson Structure (A3-Inspired)
+
+Each lesson follows a compressed A3 format — the same one-page problem-solution structure from the Green Belt coursework, adapted for technical lessons:
+
+```
+# Lesson: [Title]
+
+**Date:** YYYY-MM-DD
+**System:** [Project name]
+**Tier:** observation | insight | lesson | lesson_learned
+**Category:** [See categories below]
+**Keywords:** [comma-separated for retrieval]
+**Files:** [affected files]
+
+## Observation (What Happened)
+[Factual description of the incident/discovery. Include data contradictions.]
+
+## Analysis (Root Cause — 5 Whys)
+Why #1: [surface cause]
+Why #2: [deeper cause]
+Why #3: [root cause — stop at the deepest controllable cause]
+
+## Corrective Actions
+| # | Action | Status | Owner | Evidence |
+|---|--------|--------|-------|----------|
+| 1 | [specific action] | proposed/implemented/validated | [who] | [commit/test/config] |
+
+## Ripple Effects
+[What other systems/services/pipelines does this touch?]
+
+## Sustain Plan
+- [ ] 7-day check: [what to verify]
+- [ ] 30-day check: [confirm no recurrence]
+- [ ] Contingency: [if corrective action doesn't hold]
+
+## Key Takeaway
+[One sentence. The thing you'd tell someone in 10 seconds.]
+```
+
+## Categories
+
+Aligned to the system hierarchy — when searching for patterns, filter by category:
+
+| Category | Scope | Examples |
+|----------|-------|---------|
+| `data-model` | Schema, inheritance, data flow assumptions | HA entity→device→area chain |
+| `registration` | Module loading, decorator patterns, import side effects | Collector registry empty |
+| `cold-start` | First-run behavior, missing baselines, graceful degradation | Predictions 0 for missing weekday |
+| `integration` | Cross-service dependencies, shared state, API contracts | Engine↔Hub JSON schema coupling |
+| `deployment` | Service config, systemd, env vars, restart behavior | ~/.env export syntax |
+| `monitoring` | Alert logic, noise suppression, false positives, staleness | Stuck sensor alerts |
+| `ui` | Frontend assumptions, data display, user-facing bugs | Area counts showing 0 |
+| `testing` | Coverage gaps, mock masking, smoke tests | Mocked collectors hiding registration bug |
+| `performance` | Resource contention, memory, Ollama scheduling | Timer deconfliction |
+| `security` | Auth, secrets, permissions | Credential exposure |
+
+## Analysis Tools
+
+### 5 Whys (Primary)
+Use for most lessons. Stop at the deepest **controllable** root cause.
+
+### Fishbone / 6M (Complex Issues)
+When 5 Whys branches into multiple causes, use the 6M categories adapted for infrastructure:
+- **Method:** Process/workflow gap (no smoke test after refactor)
+- **Machine:** System/service failure (Ollama contention, OOM)
+- **Material:** Data quality (stale cache, missing baselines)
+- **Manpower:** Knowledge gap (didn't know HA inheritance model)
+- **Management:** Process gap (no review step, no sustain plan)
+- **Mother Nature:** External factor (upstream API change, network)
+
+### Pareto Principle
+When reviewing lessons over time: **most frequent category ≠ most impactful category.** Track both. Optimize for impact, not frequency.
+
+## Lifecycle & Promotion
+
+```
+observed → analyzed → proposed → validated
+   ↑          ↑          ↑          ↑
+ Incident   5 Whys    Action     Proof +
+  logged    done      defined    30-day
+                                 sustain
+```
+
+**Promotion criteria:**
+- `observed → analyzed`: Root cause identified via 5 Whys or Fishbone
+- `analyzed → proposed`: Corrective action defined with owner and timeline
+- `proposed → validated`: Action implemented + evidence of behavioral change (test passing, config applied, no recurrence for 30 days)
+
+**Review cadence:** Check `proposed` items monthly. If no action in 60 days, either implement or archive with reason.
+
+## Connecting to MEMORY.md
+
+MEMORY.md carries **one-line summaries** pointing to full lesson files:
+
+```markdown
+## Lessons Learned
+- `docs/lessons/2026-02-14-area-entity-resolution.md` — HA entity→device→area chain [lesson_learned]
+- `docs/lessons/2026-02-14-collector-registration.md` — Decorator registries need explicit imports [lesson]
+```
+
+The `[tier]` tag shows maturity at a glance. Update when tier changes.
+
+## Cross-Framework Mapping
+
+For career transition context — how these frameworks translate:
+
+| Military | LSS | PMI | This System |
+|----------|-----|-----|-------------|
+| AAR (After Action Review) | Kaizen session | Retrospective | Lesson file creation |
+| MDMP (Military Decision Making) | DMAIC | Planning process | Plan docs in docs/plans/ |
+| OPORD | A3 Report | Project charter | CLAUDE.md + plan doc |
+| IPB | VSM + SIPOC | Stakeholder analysis | System audit (/ha-audit, /status) |
+| F3EAD cycle | PDCA cycle | Monitor & Control | Counter system (/counter, /check, /reflect) |
+
+## File Naming
+
+`docs/lessons/YYYY-MM-DD-short-description.md`
+
+One lesson per file. If an incident produces multiple independent lessons, split them.

package/docs/lessons/SUMMARY.md

@@ -0,0 +1,201 @@
+# Lessons Learned — Summary
+
+79 lessons captured from autonomous coding workflows. Each is a standalone markdown file with YAML frontmatter, grep-detectable patterns (syntactic) or AI-reviewable descriptions (semantic), and concrete fix guidance.
+
+## Quick Reference
+
+| ID | Title | Category | Severity | Type |
+|----|-------|----------|----------|------|
+| 0001 | Bare exception swallowing hides failures | silent-failures | blocker | syntactic |
+| 0002 | async def without await returns truthy coroutine | async-traps | blocker | semantic |
+| 0003 | asyncio.create_task without done_callback swallows exceptions | silent-failures | should-fix | semantic |
+| 0004 | Hardcoded count assertions break when datasets grow | test-anti-patterns | should-fix | syntactic |
+| 0005 | sqlite3 connections leak without closing() context manager | silent-failures | should-fix | syntactic |
+| 0006 | .venv/bin/pip installs to wrong site-packages | integration-boundaries | should-fix | syntactic |
+| 0007 | Runner state file rejected by own git-clean check | integration-boundaries | should-fix | semantic |
+| 0008 | Quality gate blind spot for non-standard test suites | silent-failures | should-fix | semantic |
+| 0009 | Plan parser over-count burns empty API calls | silent-failures | should-fix | semantic |
+| 0010 | `local` outside function silently misbehaves in bash | silent-failures | blocker | syntactic |
+| 0011 | Batch execution writes tests for unimplemented code | integration-boundaries | should-fix | semantic |
+| 0012 | API rejects markdown with unescaped special chars | integration-boundaries | nice-to-have | semantic |
+| 0013 | `export` prefix in env files breaks naive parsing | silent-failures | should-fix | syntactic |
+| 0014 | Decorator registries are import-time side effects | silent-failures | should-fix | semantic |
+| 0015 | Frontend-backend schema drift invisible until e2e trace | integration-boundaries | should-fix | semantic |
+| 0016 | Event-driven systems must seed current state on startup | integration-boundaries | should-fix | semantic |
+| 0017 | Copy-pasted logic between modules diverges silently | integration-boundaries | should-fix | semantic |
+| 0018 | Every layer passes its test while full pipeline is broken | integration-boundaries | should-fix | semantic |
+| 0019 | systemd EnvironmentFile ignores `export` keyword | silent-failures | should-fix | syntactic |
+| 0020 | Persist state incrementally before expensive work | silent-failures | should-fix | semantic |
+| 0021 | Dual-axis testing: horizontal sweep + vertical trace | integration-boundaries | should-fix | semantic |
+| 0022 | Build tool JSX factory shadowed by arrow params | silent-failures | blocker | syntactic |
+| 0023 | Static analysis spiral — chasing lint fixes creates more bugs | test-anti-patterns | should-fix | semantic |
+| 0024 | Shared pipeline features must share implementation | integration-boundaries | should-fix | semantic |
+| 0025 | Defense-in-depth: validate at all entry points | integration-boundaries | should-fix | semantic |
+| 0026 | Linter with no rules enabled = false enforcement | silent-failures | should-fix | semantic |
+| 0027 | JSX silently drops wrong prop names | silent-failures | should-fix | semantic |
+| 0028 | Never embed infrastructure details in client-side code | silent-failures | blocker | syntactic |
+| 0029 | Never write secret values into committed files | silent-failures | blocker | syntactic |
+| 0030 | Cache/registry updates must merge, never replace | integration-boundaries | should-fix | semantic |
+| 0031 | Verify units at every boundary (0-1 vs 0-100) | integration-boundaries | should-fix | semantic |
+| 0032 | Module lifecycle: subscribe after init, unsubscribe on shutdown | resource-lifecycle | should-fix | semantic |
+| 0033 | Async iteration over mutable collections needs snapshot | async-traps | blocker | syntactic |
+| 0034 | Caller-side missing await silently discards work | async-traps | blocker | semantic |
+| 0035 | Duplicate registration IDs cause silent overwrite | silent-failures | should-fix | semantic |
+| 0036 | WebSocket dirty disconnects raise RuntimeError, not close | resource-lifecycle | should-fix | semantic |
+| 0037 | Parallel agents sharing worktree corrupt staging area | integration-boundaries | blocker | semantic |
+| 0038 | Subscribe without stored ref = cannot unsubscribe | resource-lifecycle | should-fix | syntactic |
+| 0039 | Fallback `or default()` hides initialization bugs | silent-failures | should-fix | semantic |
+| 0040 | Process all events when 5% are relevant — filter first | performance | should-fix | semantic |
+| 0041 | Ambiguous base dir variable causes path double-nesting | integration-boundaries | should-fix | semantic |
+| 0042 | Spec compliance without quality review misses defensive gaps | integration-boundaries | should-fix | semantic |
+| 0043 | Exact count assertions on extensible collections break on addition | test-anti-patterns | should-fix | syntactic |
+| 0044 | Relative `file:` deps break in git worktrees | integration-boundaries | should-fix | semantic |
+| 0045 | Iterative "how would you improve" catches 35% more design gaps | integration-boundaries | should-fix | semantic |
+| 0046 | Plan-specified test assertions can have math bugs | test-anti-patterns | should-fix | semantic |
+| 0047 | pytest runs single-threaded by default — add xdist | performance | should-fix | semantic |
+| 0048 | Multi-batch plans need explicit integration wiring batch | integration-boundaries | should-fix | semantic |
+| 0049 | A/B verification finds zero-overlap bug classes | integration-boundaries | should-fix | semantic |
+| 0050 | Editing files sourced by a running process breaks function signatures | integration-boundaries | blocker | semantic |
+| 0051 | Infrastructure fixes in a plan cannot benefit the run executing that plan | integration-boundaries | should-fix | semantic |
+| 0052 | Uncommitted changes from parallel work fail the quality gate git-clean check | integration-boundaries | blocker | semantic |
+| 0053 | Missing jq -c flag causes string comparison failures in tests | test-anti-patterns | should-fix | syntactic |
+| 0054 | Markdown parser matches headers inside code blocks and test fixtures | silent-failures | should-fix | semantic |
+| 0055 | LLM agents compensate for garbled batch prompts using cross-batch context | integration-boundaries | nice-to-have | semantic |
+| 0056 | grep -c exits 1 on zero matches, breaking || fallback arithmetic | silent-failures | should-fix | syntactic |
+| 0057 | New generated artifacts break git-clean quality gates | integration-boundaries | should-fix | semantic |
+| 0058 | Dead config keys never consumed by any module | silent-failures | should-fix | semantic |
+| 0059 | Contract test shared structures across producer and consumer | test-anti-patterns | should-fix | semantic |
+| 0060 | set -e kills long-running bash scripts silently on inter-step failures | silent-failures | blocker | semantic |
+| 0061 | Context injection into tracked files creates dirty git state when subprocess commits | integration-boundaries | should-fix | semantic |
+| 0062 | Sibling bugs hide next to the fix | integration-boundaries | should-fix | semantic |
+| 0063 | One boolean flag serving two lifetimes is a conflation bug | silent-failures | should-fix | semantic |
+| 0064 | Tests that pass for the wrong reason provide false confidence | test-anti-patterns | should-fix | syntactic |
+| 0065 | pipefail grep count double output | silent-failures | should-fix | syntactic |
+| 0066 | local keyword outside function | silent-failures | blocker | syntactic |
+| 0067 | stdin hang non-interactive shell | silent-failures | should-fix | semantic |
+| 0068 | Agent builds the wrong thing correctly | specification-drift | blocker | semantic |
+| 0069 | Plan quality dominates execution quality 3:1 | specification-drift | should-fix | semantic |
+| 0070 | Spec echo-back prevents 60% of agent failures | specification-drift | should-fix | semantic |
+| 0071 | Positive instructions outperform negative ones for LLMs | specification-drift | should-fix | semantic |
+| 0072 | Lost in the Middle — context placement affects accuracy 20pp | context-retrieval | should-fix | semantic |
+| 0073 | Unscoped lessons cause 67% false positive rate at scale | context-retrieval | should-fix | semantic |
+| 0074 | Stale context injection sends wrong batch's state | context-retrieval | should-fix | semantic |
+| 0075 | Research artifacts must persist — ephemeral research is wasted | context-retrieval | should-fix | semantic |
+| 0076 | Wrong decomposition contaminates all downstream batches | planning-control-flow | blocker | semantic |
+| 0077 | Cherry-pick merges from parallel worktrees need manual resolution | planning-control-flow | should-fix | semantic |
+| 0078 | Static review without live test optimizes for wrong risk class | planning-control-flow | should-fix | semantic |
+| 0079 | Multi-batch plans need explicit integration wiring batch | planning-control-flow | should-fix | semantic |
+
+## Root Cause Clusters
+
+### Cluster A: Silent Failures
+
+Something fails but produces no error, no log, no crash. The system continues with wrong data or missing functionality. You only discover the failure when a downstream consumer produces garbage — hours or days later.
+
+**Lessons:** 0001, 0003, 0005, 0008, 0009, 0010, 0013, 0014, 0019, 0020, 0022, 0026, 0027, 0028, 0029, 0035, 0039, 0054, 0056, 0058, 0060, 0063
+
+**Also silent (async/lifecycle):** 0002, 0033, 0034 (async bugs are silent failures with extra steps), 0032, 0036, 0038 (lifecycle bugs cause silent resource leaks)
+
+**Pattern:** The failure mode is always the same — no exception, no log line, no crash. The operation appears to succeed. The root cause varies: swallowed exceptions (0001, 0003), wrong tool configuration (0008, 0026), implicit behavior (0010, 0014, 0019, 0022), or missing validation (0028, 0029).
+
+**Defense:** Every `except` block logs before returning. Every tool configuration is tested against a known-bad input. Every implicit behavior is documented with an explicit test.
+
+### Cluster B: Integration Boundaries
+
+Each component works alone. The bug hides at the seam between two components — where one produces output and another consumes it. Unit tests pass. Integration fails.
+
+**Lessons:** 0006, 0007, 0011, 0012, 0015, 0016, 0017, 0018, 0021, 0024, 0025, 0030, 0031, 0037, 0041, 0042, 0044, 0045, 0048, 0049, 0050, 0051, 0052, 0055, 0057, 0059, 0061, 0062
+
+**Pattern:** Producer and consumer agree on the interface but disagree on semantics — units (0031), schema shape (0015), path depth (0041), or lifecycle timing (0016). Each passes its own tests because each tests against its own assumptions, not the other's reality.
+
+**Defense:** Dual-axis testing (0021) — horizontal sweep confirms every interface exists, vertical trace confirms data flows end-to-end. Contract tests between producer and consumer. Shared schema definitions instead of independent copies.
+
+### Cluster C: Cold-Start Assumptions
+
+Works in steady state, fails on restart or first boot. The system depends on state that accumulates during runtime — event history, caches, registries — and produces wrong results when that state is empty.
+
+**Lessons:** 0016, 0020, 0035, 0039
+
+**Pattern:** The system is designed for the happy path (events flowing, caches warm, registries populated) and never tested from a cold start. First-boot behavior is an afterthought — or never thought of at all.
+
+**Defense:** Test every component from empty state. Seed current state on startup via REST/query (0016). Checkpoint state incrementally (0020). Validate initialization rather than falling back silently (0039).
+
+### Cluster D: Specification Drift
+
+The agent builds the wrong thing correctly. Code passes tests, but tests validate the agent's interpretation — not the user's intent. The spec was misunderstood, and no echo-back step caught it.
+
+**Lessons:** 0068, 0069, 0070, 0071
+
+**Pattern:** The agent reads requirements, forms an interpretation, writes code and tests against that interpretation, and everything passes. The divergence from user intent is invisible because the feedback loop is closed — the agent grades its own homework.
+
+**Defense:** Echo back requirements before implementing. Score plan quality before execution. Use positive instructions ("do Y") instead of negative ("don't do X"). The echo-back gate catches 60%+ of failures.
+
+### Cluster E: Context & Retrieval
+
+Information is available but buried, misscoped, or placed in the wrong position within the context window. The agent has access to the right data but doesn't use it effectively.
+
+**Lessons:** 0072, 0073, 0074, 0075
+
+**Pattern:** Critical requirements are lost in the middle of long context (0072), irrelevant lessons fire due to missing scope (0073), stale context from a previous batch pollutes the current one (0074), or research findings exist only in conversation and are lost on context reset (0075).
+
+**Defense:** Place task at top, requirements at bottom (U-shaped attention). Scope lessons to projects. Use ephemeral context injection for batch-scoped data. Always write research to files.
+
+### Cluster F: Planning & Control Flow
+
+The plan itself is wrong — wrong decomposition, wrong integration assumptions, or wrong verification strategy. Individual batches execute correctly but the overall result is broken.
+
+**Lessons:** 0076, 0077, 0078, 0079
+
+**Pattern:** Decomposition errors compound downstream (0076), parallel worktree merges need semantic conflict resolution (0077), static review alone misses runtime bugs (0078), and components built in separate batches are never wired together (0079).
+
+**Defense:** Validate decomposition before execution. Add explicit integration wiring batches. Combine static review with live testing. Use interactive conflict resolution for cherry-picks.
+
+## Six Rules to Build By
+
+1. **Log before fallback.** Every `except`, every `catch`, every `|| true` — log the failure before returning a default. Silent fallbacks are the #1 source of invisible bugs. (0001, 0003, 0039)
+
+2. **Test from cold start.** If your system depends on accumulated state, test it from empty. Seed current state on boot, checkpoint incrementally, and verify initialization completed before proceeding. (0016, 0020, 0035)
+
+3. **One source of truth.** When two components need the same logic, schema, or configuration — one owns it, the other imports it. Independent copies diverge. Always. (0015, 0017, 0024, 0030)
+
+4. **Verify at boundaries.** Every time data crosses a boundary (module to module, service to service, human to machine), verify the contract: types, units, format, completeness. Don't trust, verify. (0025, 0031, 0042)
+
+5. **Trace end-to-end.** Unit tests are necessary but not sufficient. At least one test must trace a single input through every layer to the final output. If it takes too long to write, the architecture has too many layers. (0018, 0021, 0048)
+
+6. **Make failures visible.** Every gate, check, and quality tool must be tested against a known-bad input to prove it actually catches something. A tool that reports "0 issues" on any input is worse than no tool. (0008, 0026, 0043)
+
+## Diagnostic Shortcuts
+
+When you see this symptom, check these lessons first.
+
+| Symptom | Check First |
+|---------|-------------|
+| Feature works but produces no output on restart | 0016, 0020 |
+| Tests pass but feature doesn't work end-to-end | 0018, 0021, 0048 |
+| Exception happens but no log entry appears | 0001, 0003, 0034 |
+| Script works on one machine, fails on another | 0010, 0019 |
+| Quality gate reports "no issues" on bad code | 0008, 0026 |
+| Frontend shows stale or wrong data | 0015, 0031 |
+| Registry/cache missing entries after update | 0030, 0035 |
+| WebSocket connection drops without error | 0036, 0038 |
+| Async function appears to do nothing | 0002, 0034 |
+| Build works locally but fails in CI/worktree | 0037, 0044 |
+| Component renders blank in JSX | 0022, 0027 |
+| API rejects message that looks correct | 0012, 0013 |
+| Secret value appears in git log | 0029 |
+| Test suite takes 10x longer than expected | 0047 |
+| Test breaks every time collection grows | 0004, 0043 |
+| Lint fix creates new lint failures | 0023 |
+| Plan looks complete but integration is broken | 0011, 0042, 0045, 0049 |
+| Quality gate fails but batch agent didn't cause it | 0050, 0052 |
+| Infrastructure fix committed but not taking effect | 0051 |
+| Parser finds more batches/tasks than plan actually has | 0054 |
+| jq assertion fails with multiline vs compact mismatch | 0053 |
+| Agent implements correct work despite garbled prompt | 0055 |
+| Bash arithmetic fails with "syntax error in expression" | 0056 |
+| Quality gate fails with "uncommitted changes" after adding new feature | 0007, 0052, 0057, 0061 |
+| Long-running bash script dies silently between steps | 0060 |
+| Config key exists but has no effect | 0058 |
+| Fixed a bug but same bug exists in sibling function | 0062 |
+| Boolean flag means different things at different times | 0063 |
+| Test passes but reversing the fix doesn't break it | 0064 |

package/docs/lessons/TEMPLATE.md

@@ -0,0 +1,85 @@
+# Lesson Template
+
+Copy this file to `docs/lessons/NNNN-<slug>.md` where NNNN is the next sequential ID.
+
+```yaml
+---
+id: <next sequential number>
+title: "<Short descriptive title — what the anti-pattern IS>"
+severity: <blocker|should-fix|nice-to-have>
+languages: [<python|javascript|typescript|shell|all>]
+scope: [<universal|language:X|framework:X|domain:X|project:X>]  # optional, defaults to universal
+category: <async-traps|resource-lifecycle|silent-failures|integration-boundaries|test-anti-patterns|performance>
+pattern:
+  type: <syntactic|semantic>
+  regex: "<grep -P pattern>"       # Required for syntactic, omit for semantic
+  description: "<what to look for>"
+fix: "<one-line description of the correct approach>"
+positive_alternative: "<optional — what TO DO instead, phrased positively>"
+example:
+  bad: |
+    <2-5 lines showing the anti-pattern>
+  good: |
+    <2-5 lines showing the correct code>
+---
+
+## Observation
+<What happened — the bug, the symptom, the impact. Be factual and specific.>
+
+## Insight
+<Why it happened — the root cause, the mechanism that makes this dangerous.>
+
+## Lesson
+<The rule to follow. One paragraph, actionable, testable.>
+```
+
+## Field Guide
+
+### Severity
+- **blocker** — Data loss, crashes, silent corruption. Must fix before merge.
+- **should-fix** — Subtle bugs, degraded behavior, tech debt. Fix in this sprint.
+- **nice-to-have** — Code smells, future risk. Fix when touching the file.
+
+### Pattern Type
+- **syntactic** — Detectable by grep. Requires a `regex` field. Used by `lesson-check.sh` for instant enforcement (<2s). Aim for near-zero false positives.
+- **semantic** — Needs context to detect. Requires a `description` field. Used by the `lesson-scanner` agent during verification. Can have higher false positive tolerance since AI reviews context.
+
+### Categories
+| Category | What it covers |
+|----------|---------------|
+| `async-traps` | Forgotten awaits, concurrent modification, coroutine misuse |
+| `resource-lifecycle` | Leaked connections, missing cleanup, subscription without unsubscribe |
+| `silent-failures` | Bare exceptions, swallowed errors, lost stack traces |
+| `integration-boundaries` | Cross-module bugs, path issues, API contract mismatches |
+| `test-anti-patterns` | Brittle assertions, mocking the wrong thing, false confidence |
+| `performance` | Missing filters, unnecessary work, resource waste |
+| `specification-drift` | Misinterpreted requirements, wrong implementation, plan quality failures |
+| `context-retrieval` | Lost context, stale injection, misscoped lessons, ephemeral research |
+| `planning-control-flow` | Wrong decomposition, missing integration wiring, cherry-pick conflicts |
+
+### Scope (Project-Level Filtering)
+Scope controls which projects a lesson applies to. Language filtering (`languages:`) picks files; scope filtering picks projects. Both are orthogonal.
+
+| Tag Format | Example | Matches |
+|------------|---------|---------|
+| `universal` | `[universal]` | All projects (default) |
+| `language:<lang>` | `[language:python]` | Projects with that language |
+| `framework:<name>` | `[framework:pytest]` | Projects using that framework |
+| `domain:<name>` | `[domain:ha-aria]` | Domain-specific projects |
+| `project:<name>` | `[project:autonomous-coding-toolkit]` | Exact project match |
+
+Default when omitted: `[universal]` — backward compatible.
+
+### Writing Good Regex Patterns
+- Test with `grep -P "<pattern>" <your_file>` before submitting
+- Escape special characters: `\\.` for literal dot, `\\(` for literal paren
+- Use `\\b` for word boundaries to reduce false positives
+- Use `\\s` for any whitespace
+- Prefer patterns that match the *structure* of the anti-pattern, not specific variable names
+
+## Examples
+
+See existing lessons in this directory for reference:
+- `0001-bare-exception-swallowing.md` — syntactic, blocker
+- `0002-async-def-without-await.md` — semantic, blocker
+- `0003-create-task-without-callback.md` — semantic, should-fix