@luizsantiago/spec-guardrails 3.0.1

package/skills/references/context-limits.md

@@ -0,0 +1,73 @@
+# Context Limits
+
+How much to load, in what order, and when to stop. Cross-cutting: every phase reads this when the session is long or the feature is large.
+
+The hub already says read a reference completely before acting on it. This file is the budget for everything else — specs, diffs, sister skills, and prior features.
+
+## Budget
+
+Treat context as a working set, not an archive. Prefer a complete read of a small set over a partial read of a large set.
+
+| Slot | Load | Do not load |
+| --- | --- | --- |
+| Contract | Hub + the current phase reference + the sister skill that table names | The other phase references |
+| Feature | This feature's `spec.md`; `context.md` / `design.md` / `tasks.md` only when that phase ran | Sibling feature specs |
+| Memory | `STATE.md` Next Step, Blockers, and `AD-NNN` that constrain this area; `lessons.py list --status confirmed` | Candidates, quarantined entries, other features' `validation.md` |
+| Code | Files named on the current task | The rest of the module "for orientation" |
+| Verify | Spec + diff range + the tests the spec names; `security-review.md` | The author's session notes |
+| Conditional sister | **At most one** of `appsec.md`, `qa-strategy.md`, `code-simplify.md`, or `ship-ready.md`, and only when that skill’s trigger says so | Two or more at once; AppSec/QA on Quick/Simple without a trigger; ship-ready during normal Verify |
+
+If the working set no longer fits, drop code search leftovers first, then prior-phase artifacts you have already turned into the current artifact, then sister skills that are not in the phase map cell. Drop a finished conditional sister before loading the next (e.g. AppSec before QA; never hold simplify or ship with AppSec/QA).
+
+## Load order
+
+1. Reconcile `STATE.md` against git (`memory.md`).
+2. Open the hub only if the phase or the router is in doubt.
+3. Open the current phase reference completely.
+4. Open the sister skill the phase map names, if any.
+5. On Verify only: if an AppSec trigger fired, open `appsec.md`, act, then drop it before opening `qa-strategy.md` (never both). Skip both on Quick/Simple without triggers. Do **not** auto-load `ship-ready.md` here.
+6. On Execute (Medium+ after A–D, or owner ask): optionally open **only** `code-simplify.md`, then drop it.
+7. On explicit ship/deploy ask (after Verify PASS): open **only** `ship-ready.md`.
+8. Open this feature's artifacts for the current phase — never two features at once.
+9. Open source files the current task lists.
+
+Skip a step when its output is already in the working set from earlier in the same session.
+
+## Artifact size
+
+Write artifacts so they can be loaded whole.
+
+| Artifact | Soft limit | If it overflows |
+| --- | --- | --- |
+| `spec.md` | ~150 lines | Split a second feature; do not hide requirements in `context.md` |
+| `design.md` | ~150 lines | Link to existing code instead of pasting it |
+| `tasks.md` | ~200 lines | Group under `### Phase N`; keep fields to one line each |
+| `validation.md` | ~150 lines | One row per criterion and per mutant; no log dumps |
+| `STATE.md` | keep Next Step to one item | Archive resolved blockers; never let it become a diary |
+| Phase reference | ~220 lines | Cut an example before cutting a rule |
+
+These are authoring limits, not gate checks. The gates cannot count lines; you can.
+
+## Session rules
+
+- **One feature in focus.** Loading a second spec to "stay consistent" is how the wrong ID lands in `tasks.md`.
+- **Do not reload a reference you already followed** in this session unless a gate failed and you need the checklist again.
+- **Search is not loading.** A grep hit is a pointer; read the file only when the current task names it or the spec cites it.
+- **Sub-agents get a subset.** A worker receives the task, the spec IDs it serves, and its `Files` list — not the whole hub and not sibling tasks.
+- **Verify starts empty.** The verifier does not inherit the author's working set. That is the point of Author ≠ verifier.
+
+## When the budget is already blown
+
+1. Stop generating. Write what you know is missing into `STATE.md` Next Step.
+2. Drop everything that is not the current task's files and the current phase reference.
+3. Resume from the phase reference, not from memory of a previous plan.
+
+A confused session produces a confused spec. Resetting context is cheaper than a wrong `REQ`.
+
+## Related
+
+- `agent-architecture.md` — phase map (which reference belongs to which phase); conditional AppSec / QA
+- `appsec.md` / `qa-strategy.md` — conditional sisters (one at a time on Verify)
+- `memory.md` — resume protocol (what to reconcile before loading)
+- `task-graph-engineering.md` — what a sub-agent is allowed to receive
+- `references/implement.md` — per-task cycle (load only the current task's files)

package/skills/references/converge.md

@@ -0,0 +1,47 @@
+# Converge
+
+Reassess the codebase against spec/plan/tasks and append remaining work.
+
+## When to Use
+
+- Long Execute session — drift suspected
+- Owner asks "what's left?"
+- Partial implementation landed outside the task list
+- After merging upstream changes into a feature branch
+
+## When NOT to Use
+
+- Before Tasks exist
+- During Verify (use `validate.md` instead)
+
+## Inputs
+
+- Current feature artifacts (`spec.md`, `tasks.md`, `design.md`)
+- Git diff and test status
+- `.specs/STATE.md`
+
+## Output
+
+Updated `tasks.md` with new tasks for uncovered work (append only — do not rewrite completed tasks).
+
+## Procedure
+
+1. **Re-read the spec** — list every REQ and whether tests exist for its outcome.
+2. **Audit the diff** — files changed outside task `Files` fields are scope drift or missing tasks.
+3. **Run analyze** — `analyze_artifacts.py [feature]`.
+4. **Append tasks** for gaps using the standard task template in `tasks.md`.
+5. **Update STATE** Next Step to the first open task.
+6. **Commit** `.specs/` changes (Tier 0) — no push.
+
+## Rules
+
+- Never delete completed task checkboxes.
+- Never weaken tests to match partial implementation.
+- New tasks need Requirement, Files, Depends on, Tests, Gate, Done when.
+- Re-run `validate_tasks.py` after editing tasks.
+
+## Next
+
+- Resume → `implement.md`
+- Spec itself wrong → `specify.md` (delta spec for brownfield)
+- Back → `agent-architecture.md`

package/skills/references/design.md

@@ -0,0 +1,88 @@
+# Design
+
+Define HOW to build it: architecture, components, reuse, and risk. Optional phase.
+
+## When to Use
+
+- New architecture, new API surface, or infrastructure change
+- Unfamiliar technology or a pattern the codebase does not have yet
+- More than one defensible approach with real trade-offs
+
+## When NOT to Use
+
+- Straightforward changes with no architectural decision — design inline during Execute
+- Bug fixes, copy changes, config tweaks
+
+Skipping Design is the default for Simple and Medium tiers.
+
+## Inputs
+
+- Approved `spec.md`
+- `context.md` when Discuss ran
+- `.specs/STATE.md` decisions (`AD-NNN`)
+- Confirmed lessons: `python3 .specs/guardrails/scripts/lessons.py list --status confirmed`
+- Existing codebase structure and conventions
+- `context-limits.md` — this feature only
+
+## Output
+
+`.specs/features/[feature]/design.md`
+
+## Procedure
+
+1. **Map what already exists.** List the components you will reuse before proposing new ones. Reuse beats invention.
+2. **Load confirmed lessons** that constrain this design (`lessons.py list --status confirmed`).
+3. **Follow the Knowledge Verification Chain** for anything unfamiliar: codebase → project docs → MCP/Context → web search → flag uncertainty. Never fabricate an API.
+4. **Choose an approach and state it definitively.** Record the alternatives you rejected and why — that is the part future readers need.
+5. **Draw the shape.** A small component table and a step-by-step data-flow table beat three vague paragraphs.
+6. **Name the risks** and the mitigation for each. A risk without a mitigation is a blocker.
+7. **Link every component back to requirement IDs.** Anything that serves no `REQ` is scope creep.
+8. **Promote project-wide decisions** to `STATE.md` as `AD-NNN` (see `memory.md`).
+
+## Template
+
+```markdown
+# Design: [Feature]
+
+## Approach
+[The chosen approach in two or three sentences.]
+
+## Components
+
+| Component | Responsibility | New or reuse | Serves |
+| --- | --- | --- | --- |
+| [name] | [what it does] | reuse `src/...` | REQ-001 |
+
+## Data Flow
+
+| Step | From | To | Payload / notes |
+| ---: | --- | --- | --- |
+| 1 | Client | API | [request] |
+| 2 | API | Service | [validated input] |
+| 3 | Service | Store | [persistence] |
+
+## Decisions
+
+### AD-00X: [Decision]
+- **Chosen**: [option]
+- **Rejected**: [option] because [reason]
+
+## Risks
+
+| Risk | Impact | Mitigation |
+| --- | --- | --- |
+| [risk] | [impact] | [mitigation] |
+
+## Out of Scope for This Design
+- [explicitly excluded]
+```
+
+## Rules
+
+- No implementation code in `design.md` — interfaces and signatures only when they clarify a contract.
+- If the design reveals that the spec is wrong or incomplete, stop and update `spec.md` first; re-run the spec gate.
+- Prefer the smallest design that satisfies the spec. Extensibility that no requirement asks for is speculation.
+
+## Next
+
+`tasks.md` — break the design into atomic tasks.

package/skills/references/discuss.md

@@ -0,0 +1,68 @@
+# Discuss
+
+Resolve gray areas with the owner before they become guesses in code. Runs inside Specify, never as a standalone phase.
+
+## When to Use
+
+Trigger automatically when the feature has any of these dimensions and the spec does not already answer them:
+
+| Dimension | Typical gray area |
+| --- | --- |
+| Persistence / state | What survives a refresh, a restart, a logout? |
+| External calls | Timeout, retry, and failure behavior |
+| Auth | Who can see or do this; what happens when denied |
+| Payments | Partial failure, refunds, idempotency |
+| Concurrency | Two users or tabs acting at once |
+| State transitions | Which transitions are legal; what is irreversible |
+| User-facing behavior | Empty, loading, and error states |
+
+Also trigger when the owner's request has more than one reasonable interpretation.
+
+## When NOT to Use
+
+- The answer is already in `spec.md`, `STATE.md`, or established codebase convention
+- The decision is purely technical with no owner-visible consequence — that belongs in `design.md`
+
+## Inputs
+
+- Draft `spec.md`
+- `.specs/STATE.md` decisions
+
+## Output
+
+`.specs/features/[feature]/context.md` — created only when Discuss actually runs.
+
+## Procedure
+
+1. **List the gray areas** you found, grouped by dimension. Keep it short — no more than five at a time.
+2. **Ask one gray area at a time** (unless the owner asks for a batch).
+3. **Offer concrete options**, not open questions. "Should the session expire after 24h, 7d, or on browser close?" beats "How should sessions work?"
+4. **State your recommendation and why.** The owner should be able to answer "yes" and move on.
+5. **Wait for an explicit yes** or option letter before writing `context.md` — soft “sounds fine” is not enough.
+6. **Record the decision verbatim** in `context.md`, with the rationale and the date.
+7. **Fold consequences back into `spec.md`** as acceptance criteria — `context.md` records the decision; the spec records the testable outcome.
+8. **Escalate irreversible choices.** Anything expensive to undo gets an explicit confirmation (see the human gate in `task-graph-engineering.md`).
+
+## Template
+
+```markdown
+# Context: [Feature]
+
+## D-001: [Question in one line]
+- **Options considered**: A) ... B) ... C) ...
+- **Decision**: [what the owner chose]
+- **Rationale**: [why]
+- **Consequences**: [which REQ IDs this affects]
+- **Date**: [ISO date]
+```
+
+## Rules
+
+- Write `context.md` in **English**, whatever language the conversation happens in (see `engineering-standards.md`).
+- Never invent an answer to keep momentum. An unanswered gray area is a blocker, not a detail.
+- If the owner defers a decision, record it as an open question in `STATE.md` under Blockers.
+- Project-wide decisions graduate to `STATE.md` as `AD-NNN` (see `memory.md`).
+
+## Next
+
+Return to `specify.md`, update the spec, and re-run the spec gate.

package/skills/references/explore.md

@@ -0,0 +1,61 @@
+# Explore
+
+Think through an idea before committing to a spec. No artifacts required.
+
+## When to Use
+
+- The goal is fuzzy ("make auth better", "add dark mode somehow")
+- You need to compare options against the existing codebase
+- The owner is not sure what to build yet
+- Before `/specify` on any non-Quick change
+
+## When NOT to Use
+
+- The owner already gave a clear, testable goal — go to `/specify`
+- Quick-tier fixes (≤3 files) — use `quick-mode.md`
+
+## Inputs
+
+- Owner's question or idea, in their own words
+- Existing codebase (read relevant modules only)
+- `.specs/project/CONSTITUTION.md` when it exists
+- `.specs/project/PROJECT.md` when it exists
+- `context-limits.md` — do not load sibling feature specs
+
+## Output
+
+None required. Optionally capture decisions in chat. When the idea crystallizes, transition to `/specify`.
+
+## Procedure
+
+1. **Read the code that matters.** Skim the area the idea touches; name files and patterns you found.
+2. **Restate the problem** in one sentence and confirm it with the owner.
+3. **Offer 2–3 options** with trade-offs (complexity, dependencies, risk). Recommend one.
+4. **Surface unknowns** with `[NEEDS CLARIFICATION: specific question]` — do not guess.
+5. **Estimate complexity** using the hub router (Quick / Simple / Medium / Complex).
+6. **Transition** when the owner picks a direction:
+   ```bash
+   npx @luizsantiago/spec-guardrails feature-init "chat with presence"
+   ```
+   Then open `references/specify.md`.
+
+## Rules
+
+- No production code during Explore.
+- No `spec.md` until `/specify` runs (after `feature-init`).
+- No scaffolding empty `design.md` or `tasks.md`.
+- Keep the working set small — hub + this file + targeted code reads.
+
+## Anti-Patterns
+
+| Avoid | Prefer |
+| --- | --- |
+| Jumping to implementation | Options + recommendation first |
+| Writing a full spec during Explore | Transition to Specify when scope is clear |
+| Guessing auth/data choices | `[NEEDS CLARIFICATION: ...]` markers |
+
+## Next
+
+- Scope is clear → `feature-init` then `specify.md`
+- Gray areas remain → `discuss.md` inside Specify
+- Back → `agent-architecture.md`

package/skills/references/implement.md

@@ -0,0 +1,175 @@
+# Implement (Execute / Loop)
+
+Orchestrate tasks from `tasks.md` and `task-graph.md`: **parallel waves with sub-agents** when files are disjoint, otherwise **one task at a time** inline. Always required after Specify (and Tasks, when it ran).
+
+## When to Use
+
+- Every feature after Specify (and Tasks, when it ran)
+
+## Inputs
+
+- Approved `spec.md`, plus `design.md`, `tasks.md`, `task-graph.md` when they exist
+- Confirmed lessons: `python3 .specs/guardrails/scripts/lessons.py list --status confirmed`
+- `engineering-standards.md` for code quality and artifact language
+- `context-limits.md` — load only this feature and the files the current task names
+
+## Outputs
+
+- Production code and tests
+- One atomic commit per task
+- Updated `tasks.md` checkboxes
+
+## Before Starting
+
+1. Read this file completely.
+2. **Discover this repo’s test command** from `package.json`, `Makefile`, CI, or README — prefer the focused command the task `Gate` names. Do not assume `npm test` if the project uses another runner.
+3. Run `python3 .specs/guardrails/scripts/validate_tasks.py` when a formal `tasks.md` exists.
+4. If Tasks was skipped, list the atomic steps inline now. More than 5 steps or real dependencies means the Tasks phase was skipped in error — stop and create `tasks.md`.
+5. **Plan the wave** — run `python3 .specs/guardrails/scripts/loop_plan.py [feature]` (or `loop-plan --json`) at the start of Execute and after every batch completes. It lists the next runnable tasks and marks **parallel groups** (disjoint `Files`) vs inline work.
+6. When `loop-plan` shows a **parallel group** (2+ tasks), offer sub-agent dispatch per `task-graph-engineering.md` and `sub-agents.md`. Offer and wait; never auto-spawn. Large features (roughly 8+ tasks total) also warrant batching across waves.
+7. Confirm you are the only writer for each file this task names. Two parallel tasks never share a file in the same round.
+
+## Orchestration (each /loop round)
+
+```
+loop-plan → dispatch (parallel sub-agents | inline) → merge → loop-plan → … → /verify
+```
+
+1. **loop-plan** — Read the next wave: which tasks have satisfied dependencies and disjoint file ownership.
+2. **Dispatch**
+   - **Parallel group (2+ tasks):** one sub-agent per task with the worker brief in `sub-agents.md`. Cap at 3 workers + 1 verifier (see `task-graph-engineering.md`).
+   - **Single task:** run the per-task cycle below inline (or as sole worker).
+3. **Merge** — After a parallel round, confirm every task is `[x]`, commits exist, and the project harness passes once on the integrated tree.
+4. **Repeat** — Run `loop-plan` again until all tasks are complete, then close Execute.
+
+Do not start the next wave until the current wave is fully committed. Parallelism is **inside** a wave only when `Files` do not overlap.
+
+## Per-Task Cycle
+
+```
+Plan → Test → Implement → Gate → Commit → Next
+```
+
+1. **Plan** — Restate the task's `Done when` criterion and the files you will touch. Nothing else gets touched.
+2. **Test first** — Write the test derived from the acceptance criteria. It must fail for the right reason before you write production code.
+3. **Implement** — The smallest change that makes the test pass, following the conventions already in the codebase.
+4. **Gate** — Run the task's `Gate` command. The runner decides, not your judgment. On failure, follow the playbook below.
+5. **Mark complete** — Check the task box in `tasks.md` in the same change set.
+6. **Commit** — One atomic commit including the code, the tests, and the `tasks.md` update — only after Adequacy A–D pass.
+
+```bash
+python3 .specs/guardrails/scripts/check_commit.py --message "feat(auth): add token refresh"
+git add [files] .specs/features/[feature]/tasks.md
+git commit -m "feat(auth): add token refresh"
+```
+
+## Adequacy (before commit)
+
+Verifier judgment, not a structural gate. If any check is No, do not commit — continue the cycle or escalate.
+
+| Check | Ask |
+| --- | --- |
+| **A Outcome** | Does the new test assert this task’s `Done when` / spec criterion (not merely that code ran)? |
+| **B Scope** | Do `git status` and the task `Files` list agree — no sibling files in the index? |
+| **C Gate** | Did this task’s `Gate` command pass? |
+| **D Spec** | No extra behavior outside the spec? If the spec is wrong, stop and follow Spec Deviation (`SPEC_DEVIATION`) — do not adapt in code. |
+
+A gate that passes while A or D fails is not done.
+
+**Anti-rationalizations (judgment):** “test after code” → no, RED first (**A**). “Gate green = done” → still need **A**/**D**. “Nearby sibling files” → stay in `Files` (**B**). “Spec is slightly wrong” → Spec Deviation, never silent adapt (**D**).
+
+**Optional simplify.** On Medium+ after A–D (or when the owner asks), offer to load **only** `code-simplify.md`, then drop it — never with AppSec/QA/ship-ready. Judgment; not gated.
+
+## Gate Failure Playbook
+
+A failing gate is information. Do not skip, delete, or loosen a test to make it pass.
+
+| Failure | First move | Then |
+| --- | --- | --- |
+| New test fails for the wrong reason | Fix the test until it asserts the spec outcome and fails because the production code is missing | Re-run |
+| New test fails for the right reason | Implement the smallest production change | Re-run |
+| Existing test regresses | Revert unrelated edits; keep the diff inside the task's `Files` list | Re-run |
+| Lint / types | Fix only what this task introduced | Re-run |
+| `check_commit.py` | Rewrite the message; do not commit with `--no-verify` | Re-run |
+| Flaky or order-dependent test | Isolate the external dependency; never retry-until-green | Re-run |
+
+Retry the same task up to **3 times**. After the third failure, stop the loop and escalate to the owner with: the command that failed, the last error, the files touched, and the option you recommend.
+
+A gate that passes while `Done when` is still false is not done. Write the missing assertion and continue the cycle.
+
+**Right-reason test.** The new test must fail because the production behavior is absent, not because of a typo, a wrong import, or an assertion that cannot succeed. Read the failure once. If the message is about setup, fix the test; if it is the spec outcome (401 vs 200, missing field, wrong code), then implement.
+
+**Commit checklist.** Before `git commit`: the task box is checked, `check_commit.py` has passed on the exact message, `Files` in the task and `git status` agree, and no sibling file is in the index. An unchecked box in a "done" commit fails `validate_state.py` later and wastes a verify round.
+
+## Spec Deviation
+
+Implementation sometimes proves the spec wrong — an ID that cannot be satisfied, an outcome the platform cannot produce, a missing error path.
+
+1. **Stop the loop.** Do not "adapt" the spec in code.
+2. Update `spec.md`, keep the original requirement ID, and add a new ID only for genuinely new behavior.
+3. Record the change in `STATE.md` under Decisions or Deferred Ideas.
+4. Re-run `validate_spec.py`. Re-derive affected tests.
+5. Resume Execute only after the owner approves the delta.
+
+A silent spec change during Execute is a process failure, not a shortcut.
+
+## Parallel Task Conflicts
+
+When this task is part of a parallel group (see `task-graph.md`):
+
+- Touch only the files listed on this task. A file that another in-flight task owns is out of bounds, even for an import fix — leave a note in `STATE.md` instead.
+- If you discover the split was wrong (two tasks must edit the same file), stop both, merge them into one sequential task, and re-run `validate_tasks.py`.
+- Do not "just finish" a sibling's work because you are already in the module. That is how one-writer-per-file breaks.
+
+## When to Stop and Escalate
+
+Stop immediately, with a written recommendation, when any of these are true:
+
+- The third gate retry still fails
+- The work needs a file this task does not own, and the owner of that file is another in-flight task
+- A gray area appears that Specify did not settle — return to `discuss.md`, do not guess
+- Auth, payments, or data destruction is required and was not in the approved spec
+- The remaining work is no longer the approved task list (scope doubled, architecture flipped)
+
+Escalation is a handoff, not a pause to keep coding. Update `STATE.md` Next Step to the decision you need, then wait.
+
+## Mid-loop Discoveries
+
+| Discovery | Action |
+| --- | --- |
+| Extra file required by this task | Amend `Files` on the current task, confirm no sibling owns it, continue |
+| Extra behavior required by the spec | New task, or a spec delta — not a drive-by in this commit |
+| Better design than `design.md` | Record in `STATE.md` Deferred Ideas; do not redesign mid-task |
+| Dead code adjacent to the change | Leave it unless the task's `Done when` names it |
+| Test harness cannot express the criterion | Escalate; do not lower the criterion to what is easy to test |
+
+## Rules
+
+- **Surgical changes** — Touch only what the task requires. No drive-by refactors.
+- **No scope creep** — Good ideas that are not in the task go to `STATE.md` under Deferred Ideas, not into the diff.
+- **One writer per file** — Two parallel tasks never mutate the same file in the same round.
+- **Never weaken tests** — Do not skip, delete, or loosen a test to make a gate pass.
+- **Blast radius** — Local commits are authorized by task approval. `git push`, deploy, and destructive operations need an explicit go-ahead.
+
+## Commit Format
+
+Conventional Commits, English, one concern per commit:
+
+```
+feat(auth): add token refresh
+fix(cart): prevent negative quantity on decrement
+test(auth): cover session expiry edge case
+docs(spec): record validation report for auth
+```
+
+## Closing Execute
+
+When the last task is complete:
+
+1. Run the full project harness once more (tests, linter, build).
+2. Trigger `/verify` with a fresh context — mandatory, never prompted. See `validate.md`.
+3. Do not declare the feature done until `validate_state.py` passes.
+
+## Next
+
+`validate.md` — independent verification.

package/skills/references/lessons.md

@@ -0,0 +1,71 @@
+# Lessons
+
+How to record, promote, and load grounded lessons. The engine owns the files; this reference owns the judgment.
+
+## When to Use
+
+- The last step of `/verify` when the verdict is FAIL for a grounded reason
+- The first step of `/specify` and `/plan`, loading only confirmed lessons
+- After a confirmed lesson was loaded and the same failure still happened (`penalize`)
+
+## When NOT to Use
+
+- A clean PASS — record nothing
+- A preference, a style nit, or anything not evidenced in `validation.md`
+- Hand-editing `.specs/LESSONS.md` or `.specs/lessons.json`
+
+## Files
+
+| Path | Owner | Role |
+| --- | --- | --- |
+| `.specs/lessons.json` | `lessons.py` | Canonical store |
+| `.specs/LESSONS.md` | `lessons.py` | Rendered playbook — read, never write |
+| `.specs/guardrails/scripts/lessons.py` | Harness | `add`, `list`, `penalize`, `prune`, `status` |
+
+## How to Phrase
+
+A lesson is a trigger plus a rule the next agent can apply without the original thread:
+
+```bash
+python3 .specs/guardrails/scripts/lessons.py add \
+  --title "Assert error codes, not just status" \
+  --trigger "mutant returning 403 instead of 401 survived" \
+  --rule "Acceptance criteria must name the error code, and tests must assert it" \
+  --source .specs/features/auth/validation.md:41
+```
+
+`--source` is mandatory and must point at a non-empty `validation.md`. A lesson without evidence is opinion, and the engine refuses it.
+
+Titles and rules are deduped after normalization (casefold, accents stripped, punctuation ignored). Rephrase the same idea and it attaches to the existing ID instead of creating a twin.
+
+## Lifecycle
+
+```
+FAIL with evidence → add (candidate)
+candidate seen in 2 distinct features → confirmed (guidance)
+confirmed loaded but the same failure recurs → penalize
+2 penalties → quarantined (stop loading)
+candidate idle 90 days → prune
+```
+
+Same-feature recurrence does not promote. One noisy feature must not turn a guess into a house rule.
+
+## When to Load
+
+At the start of Specify and Design:
+
+```bash
+python3 .specs/guardrails/scripts/lessons.py list --status confirmed
+```
+
+Apply every confirmed rule that matches this work. Candidates are not guidance — they live in `lessons.json` until a second feature corroborates them.
+
+If a confirmed lesson was in the working set and the same gap still appears in `/verify`, penalize it with the new `validation.md` as `--source`. Two penalties quarantine it.
+
+## Degraded mode
+
+Without Python the engine does not run. Do not write `LESSONS.md` by hand to compensate — that file is generated, and a hand-written entry has no store, no dedup, and no promotion. Note the gap in `STATE.md` and record the lesson once Python is available.
+
+## Next
+
+Return to `validate.md` after recording, or to `specify.md` / `design.md` after loading.