autonomous-coding-toolkit 1.0.0

package/docs/CONTRIBUTING.md

@@ -0,0 +1,125 @@
+# Contributing Lessons
+
+The autonomous-coding-toolkit improves with every user's production failures. When you encounter a bug caused by an anti-pattern, you can submit it as a lesson that becomes an automated check for every user.
+
+## How Lessons Become Checks
+
+```
+You encounter a bug
+  → Run /submit-lesson to capture it
+  → PR is opened against this repo
+  → Maintainer reviews and merges
+  → Lesson file lands in docs/lessons/
+  → lesson-check.sh picks up syntactic patterns automatically
+  → lesson-scanner agent picks up semantic patterns automatically
+  → Every user's next scan catches that anti-pattern
+```
+
+**Two tiers of enforcement:**
+
+| Tier | Type | Speed | How it works |
+|------|------|-------|-------------|
+| Fast | Syntactic (grep-detectable) | <2 seconds | `lesson-check.sh` reads the lesson's `regex` field and runs `grep -P` |
+| Deep | Semantic (needs context) | Minutes | `lesson-scanner` agent reads the lesson's `description` and `example` fields |
+
+Adding a lesson file is all it takes — no code changes to the scanner or check script.
+
+## Submitting a Lesson
+
+### Option 1: Use the `/submit-lesson` command (recommended)
+
+Inside a Claude Code session with this toolkit installed:
+
+```
+/submit-lesson "bare except clauses hide failures in production"
+```
+
+The command walks you through:
+1. Describing the bug
+2. Classifying severity and category
+3. Generating a grep pattern (if syntactic)
+4. Writing the lesson file
+5. Opening a PR
+
+### Option 2: Manual PR
+
+1. Copy `docs/lessons/TEMPLATE.md` to `docs/lessons/NNNN-<slug>.md`
+2. Fill in the YAML frontmatter and body sections
+3. Open a PR with title: `lesson: <short description>`
+
+## Lesson File Format
+
+Every lesson file has YAML frontmatter that the tools parse:
+
+```yaml
+---
+id: 7                              # Auto-assigned sequential ID
+title: "Short descriptive title"
+severity: blocker                  # blocker | should-fix | nice-to-have
+languages: [python]                # python | javascript | typescript | shell | all
+category: silent-failures          # See categories below
+pattern:
+  type: syntactic                  # syntactic | semantic
+  regex: "^\\s*except\\s*:"       # grep -P pattern (syntactic only)
+  description: "what to look for"
+fix: "how to fix it"
+example:
+  bad: |
+    <anti-pattern code>
+  good: |
+    <correct code>
+---
+
+## Observation
+[What happened — the bug, the symptom]
+
+## Insight
+[Why it happened — the root cause]
+
+## Lesson
+[The rule to follow going forward]
+```
+
+## 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 |
+
+## Severity Guide
+
+| Severity | When to use | Examples |
+|----------|------------|---------|
+| `blocker` | Data loss, crashes, silent corruption | Bare except swallowing errors, async def returning coroutine instead of result |
+| `should-fix` | Subtle bugs, degraded behavior, tech debt | Leaked connections, hardcoded test counts, missing callbacks |
+| `nice-to-have` | Code smells, future risks, style | Naming issues, missing type hints, suboptimal patterns |
+
+## Quality Bar
+
+Before submitting, verify:
+
+1. **Real bug** — The lesson comes from a bug you actually encountered, not a hypothetical
+2. **Regex accuracy** (syntactic only) — The regex catches the bad example and does NOT match the good example
+3. **Clear description** — Someone unfamiliar with your codebase can understand the anti-pattern
+4. **Actionable fix** — The fix section tells you what to do, not just "be careful"
+5. **Realistic example** — The bad/good examples are from real code (anonymized if needed)
+
+## Review Process
+
+1. **Automated checks** — PR CI verifies the YAML frontmatter parses correctly and required fields are present
+2. **Regex testing** — Maintainer tests the regex against real codebases for false positive rate
+3. **Category review** — Maintainer verifies severity and category are appropriate
+4. **Merge** — Once approved, the lesson is immediately available to all users on next toolkit update
+
+## What Makes a Great Lesson
+
+The best lessons:
+- Come from bugs that took >30 minutes to debug
+- Have a syntactic pattern (grep-detectable = instant enforcement for everyone)
+- Apply across multiple projects (not just your specific codebase)
+- Include the "why" — understanding the mechanism prevents the entire class of bug, not just this instance

package/docs/lessons/0001-bare-exception-swallowing.md

@@ -0,0 +1,34 @@
+---
+id: 1
+title: "Bare exception swallowing hides failures"
+severity: blocker
+languages: [python]
+scope: [language:python]
+category: silent-failures
+pattern:
+  type: syntactic
+  regex: "^\\s*except\\s*:"
+  description: "bare except clause without logging"
+fix: "Always log the exception before returning a fallback: except Exception as e: logger.error(..., exc_info=True)"
+example:
+  bad: |
+    try:
+        result = api_call()
+    except:
+        return default_value
+  good: |
+    try:
+        result = api_call()
+    except Exception as e:
+        logger.error("API call failed", exc_info=True)
+        return default_value
+---
+
+## Observation
+Bare `except:` clauses silently swallow all exceptions including KeyboardInterrupt, SystemExit, and MemoryError. When the fallback value is returned, there's no log trail to indicate a failure occurred, making debugging impossible.
+
+## Insight
+The root cause is a habit of writing "safe" exception handling that catches everything. The Python exception hierarchy means `except:` catches far more than intended. Combined with no logging, failures become invisible.
+
+## Lesson
+Never use bare `except:` — always catch a specific exception class and log before returning a fallback. The 3-line rule: within 3 lines of an except clause, there must be a logging call.

package/docs/lessons/0002-async-def-without-await.md

@@ -0,0 +1,28 @@
+---
+id: 2
+title: "async def without await returns truthy coroutine"
+severity: blocker
+languages: [python]
+scope: [language:python]
+category: async-traps
+pattern:
+  type: semantic
+  description: "async def function body contains no await, async for, or async with — returns coroutine object instead of result"
+fix: "Either add await for async I/O operations, or remove the async keyword if the function does no async work"
+example:
+  bad: |
+    async def get_data():
+        return database.query("SELECT *")  # Returns coroutine, not result
+  good: |
+    async def get_data():
+        return await database.query("SELECT *")
+---
+
+## Observation
+An `async def` function that never uses `await`, `async for`, or `async with` returns a coroutine object instead of its result. Since coroutine objects are truthy, code like `if await get_data():` silently succeeds with a truthy coroutine even when the actual data would be falsy.
+
+## Insight
+This is insidious because the function appears to work — it returns something truthy, no exceptions are raised, no warnings are logged. The bug only surfaces when the return value is used for its actual content rather than truthiness.
+
+## Lesson
+Every `async def` must contain at least one `await`, `async for`, or `async with`. If it doesn't need any, remove the `async` keyword. This check requires multi-line analysis (scanning the full function body), so it's a semantic check in the lesson-scanner.

package/docs/lessons/0003-create-task-without-callback.md

@@ -0,0 +1,28 @@
+---
+id: 3
+title: "asyncio.create_task without done_callback swallows exceptions"
+severity: should-fix
+languages: [python]
+scope: [language:python]
+category: silent-failures
+pattern:
+  type: semantic
+  description: "create_task() call without add_done_callback within 5 lines — untracked task may swallow exceptions silently"
+fix: "Add a done_callback that logs exceptions: task.add_done_callback(lambda t: t.exception() and logger.error(...))"
+example:
+  bad: |
+    task = asyncio.create_task(process_event(data))
+    # No callback — if process_event raises, you'll never know
+  good: |
+    task = asyncio.create_task(process_event(data))
+    task.add_done_callback(lambda t: t.exception() and logger.error("Task failed", exc_info=t.exception()))
+---
+
+## Observation
+`asyncio.create_task()` launches a coroutine as a background task. If the task raises an exception and nobody awaits it or checks its result, Python logs a "Task exception was never retrieved" warning at garbage collection time — which may be much later or not at all.
+
+## Insight
+Fire-and-forget tasks are a common pattern but they create invisible failure paths. The exception is silently stored in the task object and only surfaces (maybe) when the task is garbage collected.
+
+## Lesson
+Every `create_task()` call should be followed within 5 lines by `add_done_callback()` that handles exceptions. Alternatively, store the task and await it later.

package/docs/lessons/0004-hardcoded-test-counts.md

@@ -0,0 +1,28 @@
+---
+id: 4
+title: "Hardcoded count assertions break when datasets grow"
+severity: should-fix
+languages: [python, javascript, typescript]
+scope: [universal]
+category: test-anti-patterns
+pattern:
+  type: syntactic
+  regex: "assert.*==\\s*\\d+|expect\\(.*\\)\\.toBe\\(\\d+\\)|assert_equal.*\\d+"
+  description: "test assertion comparing count to a hardcoded number"
+fix: "Use >= for extensible collections, or assert against a computed expected value rather than a magic number"
+example:
+  bad: |
+    assert len(collectors) == 15  # Breaks when a 16th collector is added
+  good: |
+    assert len(collectors) >= 15  # Passes as collection grows
+    # Or better: assert expected_collector in collectors
+---
+
+## Observation
+Tests that assert exact counts (e.g., `assert len(items) == 15`) break every time a new item is added to an extensible collection. This creates friction where adding a feature requires updating unrelated test files.
+
+## Insight
+Exact count assertions conflate "the collection is not empty and has the expected items" with "the collection has exactly N items." The former is what you usually want to test; the latter creates brittle coupling.
+
+## Lesson
+For extensible collections, use `>=` assertions or check for specific members. Reserve exact count assertions for fixed-size structures where the count is genuinely part of the contract.

package/docs/lessons/0005-sqlite-without-closing.md

@@ -0,0 +1,33 @@
+---
+id: 5
+title: "sqlite3 connections leak without closing() context manager"
+severity: should-fix
+languages: [python]
+scope: [language:python]
+category: silent-failures
+pattern:
+  type: syntactic
+  regex: "sqlite3\\.connect\\("
+  description: "sqlite3.connect() — verify closing() context manager is used (with conn: manages transactions, not connections)"
+fix: "Use contextlib.closing(): with closing(sqlite3.connect(db_path)) as conn:"
+example:
+  bad: |
+    conn = sqlite3.connect("data.db")
+    with conn:
+        conn.execute("INSERT ...")
+    # Connection never explicitly closed — relies on GC
+  good: |
+    from contextlib import closing
+    with closing(sqlite3.connect("data.db")) as conn:
+        with conn:
+            conn.execute("INSERT ...")
+---
+
+## Observation
+`with conn:` in sqlite3 manages transactions (auto-commit/rollback), NOT the connection lifecycle. The connection remains open until garbage collected. Under load or in long-running processes, this leaks file descriptors.
+
+## Insight
+Python's sqlite3 `with` statement is misleading — it looks like a resource manager but only manages transactions. The actual connection close requires either `conn.close()` or `contextlib.closing()`.
+
+## Lesson
+Always wrap `sqlite3.connect()` in `contextlib.closing()` for reliable cleanup. The pattern is: `with closing(connect(...)) as conn: with conn: ...` — outer for lifecycle, inner for transactions.

package/docs/lessons/0006-venv-pip-path.md

@@ -0,0 +1,27 @@
+---
+id: 6
+title: ".venv/bin/pip installs to wrong site-packages"
+severity: should-fix
+languages: [python, shell]
+scope: [language:python, framework:pytest]
+category: integration-boundaries
+pattern:
+  type: syntactic
+  regex: "\\.venv/bin/pip\\b"
+  description: ".venv/bin/pip instead of .venv/bin/python -m pip — pip shebang may point to wrong Python"
+fix: "Use .venv/bin/python -m pip to ensure packages install into the correct virtual environment"
+example:
+  bad: |
+    .venv/bin/pip install requests
+  good: |
+    .venv/bin/python -m pip install requests
+---
+
+## Observation
+When multiple Python versions exist on the system (e.g., system Python + Homebrew Python), `.venv/bin/pip` may resolve to the wrong Python interpreter via its shebang line. Packages install into the wrong site-packages directory, making them invisible to the venv's Python.
+
+## Insight
+The pip executable's shebang (`#!/path/to/python`) is set at venv creation time. If PATH changes or another Python is installed later, the shebang becomes stale. Using `python -m pip` always uses the Python that's running it.
+
+## Lesson
+Never call `.venv/bin/pip` directly. Always use `.venv/bin/python -m pip` to guarantee the correct interpreter and site-packages directory.

package/docs/lessons/0007-runner-state-self-rejection.md

@@ -0,0 +1,35 @@
+---
+id: 7
+title: "Runner state file rejected by own git-clean check"
+severity: should-fix
+languages: [shell, all]
+scope: [project:autonomous-coding-toolkit]
+category: integration-boundaries
+pattern:
+  type: semantic
+  description: "Tool-generated state files rejected by the tool's own git-clean check"
+fix: "Add tool-generated state files to .gitignore before the first run"
+example:
+  bad: |
+    #!/bin/bash
+    # Runner creates state file
+    echo '{"batch":1}' > .run-plan-state.json
+    # Later, quality gate rejects it
+    git status --porcelain | grep -q . && echo "ERROR: untracked files"
+  good: |
+    # .gitignore includes state file
+    echo ".run-plan-state.json" >> .gitignore
+    # Runner creates state file (now ignored)
+    echo '{"batch":1}' > .run-plan-state.json
+    # Quality gate passes
+    git status --porcelain | grep -q . || echo "OK: repo clean"
+---
+
+## Observation
+A tool (e.g., plan runner) creates a state file (e.g., `.run-plan-state.json`) to persist execution progress. The tool's own quality gate includes a git-clean check that rejects untracked files. The tool creates the file, then its quality gate fails because the file is untracked.
+
+## Insight
+The root cause is a missing `.gitignore` entry. Tool-generated state files are not version-controlled artifacts — they're runtime metadata. If the tool creates them but the `.gitignore` doesn't exclude them, every tool run will create a file that the next quality gate rejects. This is a self-inflicted tooling loop.
+
+## Lesson
+Any tool that generates state files must add those files to `.gitignore` before the tool's first run. State files (`.state.json`, `.run-plan-state.json`, progress markers) are never version-controlled. The `.gitignore` is part of the tool's bootstrap, not the tool's runtime.

package/docs/lessons/0008-quality-gate-blind-spot.md

@@ -0,0 +1,33 @@
+---
+id: 8
+title: "Quality gate blind spot for non-standard test suites"
+severity: should-fix
+languages: [shell, all]
+scope: [project:autonomous-coding-toolkit]
+category: silent-failures
+pattern:
+  type: semantic
+  description: "Quality gate auto-detects only standard test frameworks, missing custom test suites"
+fix: "Detect custom test runners by convention (executable run-all-tests.sh, test-*.sh glob)"
+example:
+  bad: |
+    # Quality gate checks only standard frameworks
+    if [[ -f pytest.ini ]]; then pytest; fi
+    if [[ -f package.json ]]; then npm test; fi
+    if [[ -f Makefile ]]; then make test; fi
+    # Custom bash suite test-*.sh is never discovered
+  good: |
+    # Also check for executable test runners and test globs
+    if [[ -x run-all-tests.sh ]]; then ./run-all-tests.sh; fi
+    if ls test-*.sh &>/dev/null; then for t in test-*.sh; do ./"$t"; done; fi
+    # Plus standard framework checks...
+---
+
+## Observation
+Quality gates that auto-detect test frameworks (pytest, npm test, make test) fail to discover custom test suites written as bash scripts (`test-integration.sh`, `test-smoke.sh`) or other non-standard runners. The gate reports "no tests detected" and passes, while hundreds of assertions exist and are never executed.
+
+## Insight
+The root cause is convention-based detection that assumes all projects use a standard framework. Custom runners are often ignored because they're not a recognized pattern. The gate author knows pytest/npm/make but not the project's own conventions, leading to a blind spot.
+
+## Lesson
+Quality gates must detect tests by multiple conventions: (1) standard frameworks (pytest, npm test, make), (2) executable scripts matching `test-*.sh`, and (3) a convention file like `run-all-tests.sh` that the project defines. If a gate only knows standard frameworks, it will miss half the projects using custom runners.

package/docs/lessons/0009-parser-overcount-empty-batches.md

@@ -0,0 +1,36 @@
+---
+id: 9
+title: "Plan parser over-count burns empty API calls"
+severity: should-fix
+languages: [shell, all]
+scope: [project:autonomous-coding-toolkit]
+category: silent-failures
+pattern:
+  type: semantic
+  description: "Plan parser counts batch headers without checking if batch has content"
+fix: "Check get_batch_text is non-empty before executing a batch"
+example:
+  bad: |
+    # Parser counts headers
+    batch_count=$(grep -c "^## Batch" plan.md)
+    for batch in $(seq 1 $batch_count); do
+        # Each batch triggers an agent, even if empty
+        run_batch "$batch"
+    done
+  good: |
+    # Parser checks if batch has content
+    for batch in $(seq 1 $batch_count); do
+        text=$(get_batch_text "$batch")
+        [[ -z "$text" ]] && continue  # Skip empty batches
+        run_batch "$batch"
+    done
+---
+
+## Observation
+A plan parser counts batch headers (e.g., `## Batch 1`, `## Batch 2`) to determine how many batches to execute. If the plan has trailing or empty headers, the count includes them. Each phantom batch spawns an agent context that discovers "nothing to do" — a wasted API call, time, and context.
+
+## Insight
+The root cause is counting headers separately from extracting batch content. A header exists (line count is easy) but its content may be empty. Parser assumes every header has work, which is false for malformed or trailing headers.
+
+## Lesson
+Never count batch headers separately. Always extract the batch content first, then check if it's non-empty before executing. Skip empty batches silently. This prevents wasted agent spawns and keeps the pipeline efficient.

package/docs/lessons/0010-local-outside-function-bash.md

@@ -0,0 +1,33 @@
+---
+id: 10
+title: "`local` outside function silently misbehaves in bash"
+severity: blocker
+languages: [shell]
+scope: [language:bash]
+category: silent-failures
+pattern:
+  type: syntactic
+  regex: "^local "
+  description: "`local` keyword used at script top-level, outside any function"
+fix: "Never use `local` outside a function; use plain variable assignment at script scope"
+example:
+  bad: |
+    #!/bin/bash
+    local result="value"
+    echo "Result: $result"
+    # Works on some shells, fails/ignored on others
+  good: |
+    #!/bin/bash
+    result="value"
+    echo "Result: $result"
+    # Works consistently across all shells
+---
+
+## Observation
+A bash script uses the `local` keyword at script top-level, outside any function. The script works on one machine but fails on another, or silently produces empty values on a third. The `local` keyword is not portable when used outside function scope.
+
+## Insight
+In bash, `local` is only defined for use within functions — it declares a variable in the local function scope. At script scope, `local` is undefined behavior. Some shells silently accept and ignore it (variable remains undefined), others error. Creating scripts that work on one machine but fail on another due to shell differences.
+
+## Lesson
+Never use `local` outside a function. At script scope, use plain variable assignment (`var=value`). Functions use `local var=value` for local scope. Script scope has no `local` keyword — all variables are global by default. Grep patterns checking for `^local ` are syntactic checks to catch this at write time.

package/docs/lessons/0011-batch-tests-for-unimplemented-code.md

@@ -0,0 +1,36 @@
+---
+id: 11
+title: "Batch execution writes tests for unimplemented code"
+severity: should-fix
+languages: [all]
+scope: [universal]
+category: integration-boundaries
+pattern:
+  type: semantic
+  description: "Tests in batch N reference code that won't exist until batch N+1"
+fix: "Plan tasks so each batch is self-contained — tests only reference code from the same or earlier batches"
+example:
+  bad: |
+    # Plan with forward-looking test
+    ## Batch 3: Add tests for pipeline
+    - Write tests that call pipeline.transform() (not written yet)
+
+    ## Batch 4: Implement pipeline
+    - Implement the transform() method
+  good: |
+    # Plan with self-contained batches
+    ## Batch 3: Implement pipeline
+    - Implement the transform() method
+
+    ## Batch 4: Add tests for pipeline
+    - Write tests that call pipeline.transform() (now exists)
+---
+
+## Observation
+When a plan has batches 1-7 and batch 3's agent writes tests expecting batch 4's code, those tests fail until batch 4 runs. The agent does TDD correctly for its own batch (writes test, implements code) but accidentally creates forward dependencies when tests reference not-yet-implemented code from future batches.
+
+## Insight
+The root cause is batching by concern instead of by dependency. The planner thinks "batch 3 is tests, batch 4 is implementation" without considering that tests depend on the code existing. Tests can't pass (or even import) if the code they reference isn't in the codebase yet.
+
+## Lesson
+Plan tasks so each batch is self-contained. Tests reference only code from the same batch (TDD: write test, write code) or earlier batches (tested code). Never have batch N's tests reference batch N+1's code. If you need to test something, implement it in the same batch or an earlier batch.

package/docs/lessons/0012-api-markdown-unescaped-chars.md

@@ -0,0 +1,33 @@
+---
+id: 12
+title: "API rejects markdown with unescaped special chars"
+severity: nice-to-have
+languages: [python, javascript, all]
+scope: [universal]
+category: integration-boundaries
+pattern:
+  type: semantic
+  description: "Message API rejects text containing unescaped markdown special characters"
+fix: "Either escape all special characters or use plain text mode as default with markdown as opt-in"
+example:
+  bad: |
+    # Message with unescaped markdown chars
+    message = "Task: _compile_flags = ['-O2', '-Wall']"
+    response = api.send_message(message, parse_mode="Markdown")
+    # API rejects: parse error due to _ chars
+  good: |
+    # Either escape special chars
+    message = "Task: \\_compile\\_flags = ['-O2', '-Wall']"
+    response = api.send_message(message, parse_mode="Markdown")
+    # Or use plain text by default
+    response = api.send_message(message)  # parse_mode=None
+---
+
+## Observation
+An API with `parse_mode=Markdown` rejects messages containing unescaped special characters like `_`, `*`, `[`, `]`. The message silently fails or returns a parse error. Code that works with one message format fails with another that contains these characters.
+
+## Insight
+The root cause is assuming plain text is safe to send with markdown parsing enabled. Markdown interpreters are strict — any `_` or `*` is interpreted as formatting syntax. If the text literally needs to include these characters (like code snippets or file paths), they must be escaped or the parser must be disabled.
+
+## Lesson
+When sending messages to APIs with markdown parsing, either: (1) escape all special characters (`_`, `*`, `[`, `]`, `` ` ``) in the text, or (2) use plain text mode by default and require opt-in for markdown. Never assume plain text is safe with markdown parsing enabled.

package/docs/lessons/0013-export-prefix-env-parsing.md

@@ -0,0 +1,33 @@
+---
+id: 13
+title: "`export` prefix in env files breaks naive parsing"
+severity: should-fix
+languages: [shell]
+scope: [language:bash]
+category: silent-failures
+pattern:
+  type: syntactic
+  regex: "cut -d= -f2"
+  description: "Env file parser using cut without stripping export prefix"
+fix: "Strip `export ` prefix before parsing: sed 's/^export //'"
+example:
+  bad: |
+    # .env file with export prefix
+    # export API_KEY=secret123
+    # Read without stripping export
+    value=$(grep "API_KEY" .env | cut -d= -f2)
+    # Works for KEY=value but fails for export KEY=value
+  good: |
+    # Strip export prefix before parsing
+    value=$(grep "API_KEY" .env | sed 's/^export //' | cut -d= -f2)
+    # Works for both KEY=value and export KEY=value
+---
+
+## Observation
+`.env` files commonly use `export VAR=value` syntax (for shell-source-ability). A parser uses `grep VAR= file | cut -d= -f2` to extract values. For lines like `KEY=value` it works fine. For lines with `export KEY=value`, the `cut` command returns the correct value, but if the parsing step checks for the line format first (e.g., expecting no `export` prefix), it silently skips those lines.
+
+## Insight
+The root cause is assuming `.env` format is always `KEY=value` without the `export` keyword. Many `.env` files use `export` for shell-sourcing (so they can be sourced with `source .env`). Parsers that don't account for this prefix will silently skip or misparse those lines.
+
+## Lesson
+`.env` file parsers should strip the `export` prefix before parsing. Use `sed 's/^export //'` to normalize lines, then parse. This handles both `KEY=value` and `export KEY=value` consistently. Never assume the format — always normalize first.

package/docs/lessons/0014-decorator-registry-import-side-effect.md

@@ -0,0 +1,43 @@
+---
+id: 14
+title: "Decorator registries are import-time side effects"
+severity: should-fix
+languages: [python]
+scope: [language:python]
+category: silent-failures
+pattern:
+  type: semantic
+  description: "Decorator-based registry remains empty because module with decorated functions is never imported"
+fix: "Ensure all modules with registrations are imported in __init__.py or an explicit loader"
+example:
+  bad: |
+    # handlers.py
+    @register("command")
+    def handle_command(): pass
+
+    # main.py
+    # registry.get_all() returns empty — handlers.py was never imported
+    from registry import registry
+    for handler in registry.get_all():  # Empty!
+        handler()
+  good: |
+    # handlers.py (same as above)
+    @register("command")
+    def handle_command(): pass
+
+    # main.py
+    # Explicitly import to trigger decorators
+    from . import handlers  # This runs the decorators
+    from registry import registry
+    for handler in registry.get_all():  # Has handlers now
+        handler()
+---
+
+## Observation
+A Python project uses decorator-based registration (`@register("name")` adds a function to a registry). The registry is empty at runtime even though decorated functions exist in the codebase. No error is raised — the registry just returns an empty list.
+
+## Insight
+Decorator-based registries execute at import time. If the module containing decorated functions is never imported (perhaps `main.py` only imports specific modules), the decorators never run and the registry stays empty. The mistake is assuming the module will be imported implicitly, when it must be imported explicitly.
+
+## Lesson
+Decorator-based registries require explicit imports of all modules that have decorated functions. Add imports to `__init__.py` or a loader module that's guaranteed to run. Document this requirement. Alternatively, use a registration function that's called explicitly, instead of relying on import-time side effects. Never assume a module is imported — always be explicit.

package/docs/lessons/0015-frontend-backend-schema-drift.md

@@ -0,0 +1,43 @@
+---
+id: 15
+title: "Frontend-backend schema drift invisible until e2e trace"
+severity: should-fix
+languages: [typescript, javascript, python, all]
+scope: [universal]
+category: integration-boundaries
+pattern:
+  type: semantic
+  description: "Frontend and backend define the same data shape independently and drift over time"
+fix: "Shared schema definition (types generated from API schema) or contract tests"
+example:
+  bad: |
+    # Backend (Python)
+    def get_user():
+        return {"id": 1, "name": "Alice", "email": "alice@example.com"}
+
+    # Frontend (TypeScript, independent definition)
+    interface User { id: number; name: string; }
+    // Missing email field! Silent bug.
+  good: |
+    # Shared schema (OpenAPI/GraphQL)
+    components:
+      schemas:
+        User:
+          type: object
+          properties:
+            id: { type: integer }
+            name: { type: string }
+            email: { type: string }
+
+    # Generated TypeScript (from schema)
+    // User interface auto-generated, always in sync
+---
+
+## Observation
+Frontend and backend define the same data shape (User, Product, etc.) independently. Over time they drift — backend adds an `email` field to User, frontend's User interface doesn't include it. The field is silently ignored on the frontend. No error until a feature tries to use the field and finds it missing.
+
+## Insight
+The root cause is separate schema definitions. Each layer maintains its own types, and they're never synchronized. Backend and frontend evolve independently. The drift is invisible because both sides are "correct" within their own codebase — TypeScript compiles, Python runs, API calls succeed. Only end-to-end traces reveal the mismatch.
+
+## Lesson
+Never define schemas independently in frontend and backend. Use a single source of truth: OpenAPI, GraphQL schema, Protobuf, or equivalent. Generate types from the shared schema. Alternatively, use contract tests that verify the API response matches what the frontend expects. The contract must be version-controlled and tested.