@luizsantiago/spec-guardrails 3.0.1

package/skills/references/memory.md

@@ -0,0 +1,98 @@
+# Memory
+
+Project memory that survives session amnesia: decisions, handoff, and resume.
+
+## When to Use
+
+- Session start (resume)
+- Session end (pause / handoff)
+- Any time a project-level decision is made
+- Any time verification produces a grounded lesson
+
+## Artifacts
+
+| File | Owner | Purpose |
+| --- | --- | --- |
+| `.specs/STATE.md` | Agent + owner | Decision log (`AD-NNN`) and handoff snapshot |
+| `.specs/lessons.json` | `lessons.py` | Canonical lessons store |
+| `.specs/LESSONS.md` | `lessons.py` | Generated playbook of confirmed lessons |
+| `.specs/project/PROJECT.md` | Owner | Vision, stack, constraints |
+| `.specs/project/ROADMAP.md` | Owner | Milestones and feature status |
+
+## Resume Protocol
+
+Run at every session start, before writing any code:
+
+1. **Read `STATE.md`** — active feature, phase, next step, blockers.
+2. **Reconcile against git.** The snapshot can be stale; evidence wins:
+   ```bash
+   git branch --show-current
+   git status --porcelain
+   git log --oneline -10
+   ```
+   Compare with `tasks.md` checkboxes. If commits exist for tasks that STATE says are pending, git is right — update STATE.
+3. **Run the project harness** (tests, lint) before adding new code, so you know the starting baseline.
+4. **Load only what this step needs** — the current feature's spec, plus `context.md` or `design.md` when relevant. Never load two feature specs at once. See `context-limits.md`.
+5. **Propose the reconciled next step** and confirm it with the owner when it is ambiguous or stale.
+
+## Pause / Handoff Protocol
+
+Run at session end or at a phase milestone:
+
+1. Refresh every section of `STATE.md` (template below).
+2. Append a grounded lesson with `lessons.py add` if verification failed. Never hand-edit `LESSONS.md`.
+3. Run the relevant gates and tests — never hand off a red tree silently.
+4. Commit `.specs/` per `git-handoff.md`. **Never auto-push.**
+
+## STATE.md Template
+
+```markdown
+# Project State & Decisions
+
+## Active Feature
+- Feature: [name]
+- Phase: [Specify|Discuss|Design|Tasks|Execute|Verify]
+- Branch: [branch-name]
+
+## Next Step (single item)
+- [ ] [one concrete action]
+
+## Blockers
+- [open questions or dependencies, or "none"]
+
+## Deferred Ideas
+- [good ideas found during Execute that were out of scope]
+
+## Decisions
+
+### AD-001: [Decision title]
+- **Date**: [ISO date]
+- **Context**: [why this came up]
+- **Decision**: [what was decided]
+- **Consequences**: [what this constrains going forward]
+```
+
+## Decision Log Rules
+
+- `AD-NNN` numbers are sequential and never reused.
+- Record a decision when it constrains **future work beyond this feature**. Feature-local choices belong in `context.md` or `design.md`.
+- Superseding a decision adds a new `AD-NNN` that references the old one — never edit history in place.
+
+## Lessons Rules
+
+Lessons are owned by `lessons.py`, not by hand. See `lessons.md`.
+
+- Record only from a **grounded failure** in `validation.md`: a surviving mutant, an imprecise acceptance criterion, a failed requirement, or a spec deviation.
+- A clean PASS records nothing.
+- `--source` is mandatory. Candidates are not guidance; only `list --status confirmed` is.
+- Do not edit `LESSONS.md`. The engine generates it from `lessons.json`.
+
+## Rules
+
+- Write every artifact in **English**.
+- Lazy artifacts: never scaffold empty files to look organized.
+- `STATE.md` has exactly one "Next Step" item. A list of five is not a handoff.
+
+## Next
+
+`git-handoff.md` — what to stage, how to word the commit, and why no auto-push.

package/skills/references/project-init.md

@@ -0,0 +1,62 @@
+# Project Init (Brownfield)
+
+Map an existing codebase into `.specs/` project memory before the first `/specify`.
+
+## When to Use
+
+- Adopting Spec Guardrails on a repo that already has code
+- Owner wants domain specs and `PROJECT.md` before feature work
+- Before `/constitution` or the first Medium+ feature on a brownfield repo
+
+## When NOT to Use
+
+- Greenfield repo with no code yet — use `install` + `feature-init`
+- Quick-tier-only work with no domain map — optional
+
+## Inputs
+
+- Repository layout (`packages/`, `apps/`, `src/domains/`, etc.)
+- Stack markers (`package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`)
+- Optional `.specs/config.yaml` preset choice
+
+## Output
+
+- `.specs/project/PROJECT.md` — vision, detected stack, domain map
+- `.specs/project/ROADMAP.md` — planned domain drafting items
+- `.specs/domains/[domain]/spec.md` — brownfield stubs (one per detected/manual domain)
+- `.specs/config.yaml` — from auto-detected or chosen preset (when missing)
+
+## Procedure
+
+1. **Run the scan (Tier 0):**
+   ```bash
+   npx @luizsantiago/spec-guardrails project-init --dry-run
+   npx @luizsantiago/spec-guardrails project-init [--preset node-ts] [--domains auth,billing]
+   ```
+2. **Review with the owner** — edit `PROJECT.md`, trim false-positive domains, fill Vision/Constraints.
+3. **Draft domain truth** — replace stub requirements in `.specs/domains/*/spec.md` from code review (or leave stubs until features archive in).
+4. **Optional constitution** — `references/constitution.md` when principles are not yet written.
+5. **First feature** — `feature-init` then `specify.md` using **delta specs** when domain truth exists.
+
+## Flags
+
+| Flag | Effect |
+| --- | --- |
+| `--dry-run` | Print stack/domains only |
+| `--preset <name>` | Force config preset (`default`, `node-ts`, `python`) |
+| `--domains a,b` | Manual domain list (overrides auto-detect) |
+| `--no-domains` | Skip domain folder scaffolding |
+| `--no-project` | Skip `PROJECT.md` |
+| `--force` | Overwrite generated project/domain/config files |
+
+## Rules
+
+- Scan results are **hints**, not approved requirements.
+- Never treat stub domain specs as enforced gates — populate or merge via `archive-feature`.
+- Commit `.specs/project/` and `.specs/domains/` locally (Tier 0); push needs owner go-ahead.
+
+## Next
+
+- Principles missing → `constitution.md`
+- First change → `feature-init` then `specify.md` (delta spec when brownfield)
+- Back → `agent-architecture.md`

package/skills/references/quick-mode.md

@@ -0,0 +1,84 @@
+# Quick Mode
+
+Express lane for small, low-risk changes. Full pipeline ceremony would cost more than the change itself.
+
+## When to Use
+
+All of these must hold:
+
+- 3 files or fewer
+- No architectural decision
+- No new dependency
+- No change to auth, payments, or data migrations
+- The fix is describable in one sentence
+
+Typical: a bug fix, a copy change, a config tweak, a version bump.
+
+## When NOT to Use
+
+If any guardrail is exceeded, stop and route to `specify.md`. Explicitly:
+
+| Signal | Route to |
+| --- | --- |
+| More than 3 files | `specify.md` → Simple tier |
+| A design decision appears | `design.md` |
+| More than 5 steps emerge | `tasks.md` |
+| Auth, payments, or data safety touched | Full pipeline + `security-review.md` |
+
+Announce the switch — do not silently expand a quick task into a feature.
+
+## Output
+
+`.specs/quick/NNN-slug/`
+
+| File | Content |
+| --- | --- |
+| `TASK.md` | What, where, approach, verification |
+| `SUMMARY.md` | What changed, commit hash, evidence |
+
+`NNN` is sequential across the project (`001`, `002`, …).
+
+## Procedure
+
+1. **Restate the change in one sentence**, name the files, and state how you will verify it.
+2. **Write `TASK.md`** before touching code. Two minutes of writing prevents the wrong fix.
+3. **Write or extend a test** that fails for the current defect. A quick fix with no test is only allowed for changes with no behavior — copy, formatting, comments.
+4. **Implement the smallest change.**
+5. **Run the project harness** — tests and linter.
+6. **Commit atomically**, Conventional Commits format:
+   ```bash
+   python3 .specs/guardrails/scripts/check_commit.py --message "fix(theme): persist dark mode preference"
+   ```
+7. **Write `SUMMARY.md`** with the commit hash and the evidence line.
+8. **Record a lesson** with `lessons.py add --source` if the defect revealed a gap that will recur and a `validation.md` exists. Quick-mode copy fixes usually record nothing.
+
+## Verification Standard
+
+Quick mode compresses ceremony, not carelessness — but it is **not** the full Verify gate:
+
+- Prove the change with a test or an explicit, documented manual check.
+- Record evidence in `SUMMARY.md` (`file:line` or the exact manual steps). That is a **process** requirement; `validate_state.py` does not run on Quick artifacts.
+- Blast radius still applies — local commit only; `git push` and deploy need an explicit go-ahead.
+- If any Quick guardrail is exceeded, stop and route to `specify.md` (see When NOT to Use).
+
+## Templates
+
+```markdown
+# Quick Task: [one-line title]
+
+- **Files**: src/hooks/useTheme.ts
+- **Approach**: persist the preference to localStorage on toggle
+- **Verify**: toggle dark mode, reload, preference persists
+```
+
+```markdown
+# Summary
+
+- **Changed**: persisted theme preference on toggle
+- **Commit**: fix(theme): persist dark mode preference (a1b2c3d)
+- **Evidence**: test/hooks/useTheme.test.ts:18
+```
+
+## Next
+
+Back to normal work. If the same class of defect appears again, promote it to a real feature with `specify.md`.

package/skills/references/specify.md

@@ -0,0 +1,144 @@
+# Specify
+
+Capture WHAT to build as testable, traceable requirements. Always required (except Quick tier).
+
+## When to Use
+
+- Any change beyond the Quick tier (see `quick-mode.md`)
+- Before writing production code or tests
+
+## When NOT to Use
+
+- Quick-tier changes (≤3 files, no design decisions) — use `quick-mode.md`
+
+## Inputs
+
+- Owner's request, in their own words
+- `.specs/STATE.md` decisions (`AD-NNN`) relevant to this area
+- `.specs/project/CONSTITUTION.md` when present
+- `.specs/LESSONS.md` entries that apply — load them with `python3 .specs/guardrails/scripts/lessons.py list --status confirmed`
+- Existing codebase conventions
+- `context-limits.md` — this feature only; do not load sibling specs
+
+## Output
+
+`.specs/features/[NNN-slug]/spec.md` (created by `feature-init`)
+
+## Procedure
+
+0. **Allocate feature identity (Tier 0).** Before drafting:
+   ```bash
+   npx @luizsantiago/spec-guardrails feature-init "owner description here"
+   ```
+   Creates `.specs/features/003-slug/`, updates `STATE.md`, and `git checkout -b feat/003-slug`. Skip on Quick tier.
+   Optional project context: `npx @luizsantiago/spec-guardrails phase-context specify` when `.specs/config.yaml` exists.
+1. **Act as a thinking partner, not an interviewer.** Challenge vagueness; restate the goal in one sentence and confirm it.
+2. **Surface assumptions before drafting criteria.** State stack/auth/data guesses and ask for corrections; lasting ones go under `## Assumptions` only after that (or after `discuss.md`).
+3. **Mark unknowns explicitly.** Use `[NEEDS CLARIFICATION: specific question]` — never guess. Resolve or remove before owner approval.
+4. **Load confirmed lessons.** Run `python3 .specs/guardrails/scripts/lessons.py list --status confirmed` and apply every rule that matches this work. Candidates are not guidance.
+5. **Detect gray areas.** If the feature touches persistence, external calls, auth, payments, concurrency, or state transitions — or if intent is ambiguous — run `discuss.md` before finalizing.
+6. **Choose spec shape:**
+   - **Greenfield** — full spec (`## Requirements`, `## Assumptions`, `## Out of Scope`)
+   - **Brownfield** — delta spec (`## ADDED Requirements`, `## MODIFIED Requirements`, `## REMOVED Requirements`)
+7. **Write requirements with stable IDs.** `REQ-001`, `AUTH-002` — prefix plus a zero-padded number. IDs never change once approved; retire them instead.
+8. **Write binary acceptance criteria.** Every criterion is objectively pass or fail. The gate **blocks** a criterion that does not state a required outcome with `SHALL` or `MUST`. Soft verbs (`should`, `will`, `can`, `may`) are not testable — rewrite them before confirming.
+   Prefer **EARS** (one pattern per criterion). The gate **warns** when a `SHALL`/`MUST` line has no `WHEN`/`IF` … `THEN` trigger; missing EARS is not a hard fail.
+
+   | Pattern | Shape | Use when |
+   | --- | --- | --- |
+   | Ubiquitous | The system SHALL [invariant] | Always-on constraints |
+   | Event-driven | WHEN [trigger] THEN the system SHALL [outcome] | A discrete action or event |
+   | State-driven | WHILE [state] the system SHALL [outcome] | Behavior that holds during a state |
+   | Optional-feature | WHERE [capability] the system SHALL [outcome] | Flag- or plan-gated behavior |
+   | Unwanted-behavior | IF [undesired] THEN the system SHALL [outcome] | Errors, invalid input, timeouts |
+   | Complex | WHILE [state], WHEN [trigger] the system SHALL [outcome] | Combined state + event |
+
+   One criterion = one behavior. Use concrete values (status, code, bound), not “gracefully” or “quickly”.
+9. **State out of scope explicitly.** This is what prevents scope creep during Execute.
+10. **Record assumptions.** Anything inferred rather than confirmed goes under `## Assumptions`. The section is required; write `- none` only when nothing was inferred.
+11. **Run the gate.** Fix every blocking issue before showing the spec to the owner.
+12. **Get approval.** Do not write implementation code until the spec and derived tests are approved.
+13. **Commit spec (Tier 0).** `docs(spec): add requirements for 003-slug`
+
+## Gate
+
+```bash
+python3 .specs/guardrails/scripts/validate_spec.py .specs/features/[feature]/spec.md
+python3 .specs/guardrails/scripts/validate_spec.py [feature]
+python3 .specs/guardrails/scripts/validate_spec.py          # single-feature projects
+```
+
+Checks required sections (`Requirements`, `Assumptions`, `Out of Scope`), well-formed IDs, a `SHALL`/`MUST` outcome per criterion, and unresolved placeholders. Sections, IDs, criteria, and placeholders are read from visible markdown — fenced samples and HTML comments do not count. A criterion with `SHALL` but no `WHEN`/`IF` … `THEN` trigger is a warning. Non-zero exit means STOP.
+
+## Template
+
+```markdown
+# Spec: [Feature]
+
+## Goal
+[One sentence: what the owner gets when this ships.]
+
+## Requirements
+
+### REQ-001: [Short title]
+- **Acceptance Criteria**: WHEN [valid credentials are submitted] THEN the system SHALL [create a session]  <!-- event-driven -->
+- IF [the token is expired] THEN the system SHALL [return 401 with code TOKEN_EXPIRED]  <!-- unwanted-behavior -->
+
+### REQ-002: [Short title]
+- **Acceptance Criteria**: WHILE [a session is active] the system SHALL [reject reuse of a rotated refresh token]  <!-- state-driven -->
+- The system SHALL [store passwords only as argon2 hashes]  <!-- ubiquitous -->
+
+## Assumptions
+- [Anything inferred rather than confirmed]
+
+## Out of Scope
+- [Explicitly excluded work]
+```
+
+### Delta spec (brownfield)
+
+```markdown
+# Spec: 004-dark-mode (delta)
+
+## Goal
+Add theme switching without new dependencies.
+
+## ADDED Requirements
+
+### UI-001: Theme toggle
+- **Acceptance Criteria**: WHEN the user clicks the theme toggle THEN the system SHALL persist the choice in localStorage
+
+## MODIFIED Requirements
+
+### AUTH-001: Session banner
+- **Acceptance Criteria**: WHILE dark mode is active the system SHALL render the session banner with contrast ratio ≥ 4.5:1
+
+## REMOVED Requirements
+- none
+
+## Assumptions
+- CSS variables already exist for primary colors
+
+## Out of Scope
+- Server-side theme preference sync
+```
+
+## Anti-Patterns
+
+| Avoid | Prefer |
+| --- | --- |
+| "Login should work well" | "WHEN valid credentials are submitted THEN the system SHALL create a session" |
+| "The system will return 401" | "WHEN the token is expired THEN the system SHALL return 401 with code `TOKEN_EXPIRED`" |
+| Omitting `## Assumptions` | Record inferences, or write `- none` |
+| Guessing when unsure | `[NEEDS CLARIFICATION: auth method not specified]` |
+| Manual slug folders without numbering | `feature-init` before drafting |
+| Renaming `REQ-001` mid-flight | Retire the ID and add a new one |
+| Implementation detail in the spec | Keep HOW in `design.md` |
+
+## Next
+
+- Gray areas remain → `discuss.md`
+- Tasks drafted → `analyze.md` before approval
+- Architectural decisions needed → `design.md`
+- ≤3 obvious steps → `implement.md`
+- Otherwise → `tasks.md`

package/skills/references/sub-agents.md

@@ -0,0 +1,117 @@
+# Sub-Agents
+
+Operational protocol for multi-agent Execute. Sister material to `task-graph-engineering.md`
+(topology) — this file is the **payload, summary, failure, and merge** contract.
+
+## When to Use
+
+- `loop-plan` shows a parallel group with 2+ ready tasks (disjoint `Files`)
+- `task-graph.md` marks a parallel group and the owner accepted the split
+- `tasks.md` packs into more than one ~7-task batch (roughly more than 8 tasks total)
+- Diamond verify needs a fresh context that never wrote the code
+
+## When NOT to Use
+
+- ≤8 tasks that fit one batch — execute inline
+- Sequential work where each step needs the previous step's full picture
+- The owner declined the sub-agent offer
+
+**Never auto-spawn.** Offer the split, wait for an explicit yes.
+
+## Batch packing
+
+1. Walk `### Phase N` groups in order (or document order when phases are unused).
+2. Pack consecutive **whole** phases into a batch until the batch would exceed ~7 tasks.
+3. Never split a phase across workers.
+4. Batches run **sequentially**. Parallelism lives *inside* a batch only when `task-graph.md` marks a parallel group and Files are disjoint.
+
+## Worker payload
+
+Hand each worker exactly this and nothing else from sibling features:
+
+```markdown
+# Worker brief
+
+- Feature: [feature]
+- Batch: B[n] of [total]
+- Tasks: T[a] … T[b] (in order)
+- Spec excerpt: only the REQ IDs those tasks name
+- Files ownership: the union of those tasks' Files fields (exclusive)
+- Constraints: AD-NNN that apply; confirmed lessons that apply
+- Forbidden: git push, deploy, editing files outside ownership, spawning further sub-agents
+```
+
+Load per `context-limits.md`. Do not paste the author's chat.
+
+## Worker loop
+
+For each task in order:
+
+1. Read the task fields. Implement test-first from the named criteria.
+2. Run the task `Gate`. Non-zero → fix (max 3 loops) or stop and report failure.
+3. Run `check_commit.py` on the message, mark the task `[x]`, commit atomically.
+4. Do not start the next task until the commit exists.
+
+## Compact summary (required return)
+
+Every worker returns this shape — no narrative dump:
+
+```markdown
+## Batch B[n] summary
+- Status: PASS | FAIL
+- Tasks done: T1, T2
+- Commits: abc1234, def5678
+- Tests: 12 passed / 0 failed
+- Deviations: none | [what changed vs tasks.md]
+- Blockers: none | [gate output excerpt]
+```
+
+## Failure handling
+
+| Event | Action |
+| --- | --- |
+| Gate fails 3 times on one task | Stop the batch. Return FAIL summary. Do not continue later tasks in the batch. |
+| Worker edits a file outside ownership | Treat as FAIL. Merge owner reverts or reassigns. |
+| Batch FAIL | Orchestrator does not start the next batch. Escalate or rewrite tasks. |
+| Verify FAIL | Gaps become fix tasks; fix → re-verify loop bounded to 3, then escalate. |
+
+## Merge owner
+
+One agent (usually the orchestrator) owns merge after each batch and after Verify:
+
+1. Confirm every task checkbox in the batch is `[x]` and commits are present.
+2. Run the project harness once on the integrated tree.
+3. Resolve conflicts; never ask two workers to touch the same file in the same round.
+4. Only after the final batch: dispatch the **Verifier** (fresh context). See `validate.md`.
+5. Hand off via `git-handoff.md` — push only with an explicit go-ahead.
+
+## Verifier dispatch
+
+Always-on after the last task commit. Payload:
+
+- `spec.md` (+ `context.md` when present)
+- Diff range for the feature
+- Tests named by the spec / tasks
+- `security-review.md` checklist
+- **Not** the author chat, worker summaries as proof, or `STATE.md` Next Step as evidence
+
+The verifier writes `validation.md` and runs `validate_state.py`. A PASS WITH GAPS is FAIL.
+
+## Model tier (optional)
+
+When Spec Guardrails can pick a model per sub-agent:
+
+| Role | Tier |
+| --- | --- |
+| Mechanical batch | Fast |
+| Ambiguous / core-domain batch | High reasoning |
+| Verifier | Mid-to-high |
+
+Otherwise ignore and invest more care on heavy steps.
+
+## Related
+
+- `task-graph-engineering.md` — DAG, stop rule, diamond, one writer per file
+- `references/implement.md` — when to offer delegation
+- `references/validate.md` — verifier procedure
+- `references/context-limits.md` — what a worker may load

package/skills/references/tasks.md

@@ -0,0 +1,178 @@
+# Tasks
+
+Break the work into atomic tasks with real dependencies and binary done criteria. Optional phase.
+
+## When to Use
+
+- More than 3 obvious steps
+- Multiple files, modules, or people involved
+- Any work that could be split across parallel agents
+
+## When NOT to Use
+
+- ≤3 obvious steps — list them inline at the start of Execute instead
+
+**Safety valve:** if the inline listing in Execute reveals more than 5 steps or real dependencies, STOP and create a formal `tasks.md`. The Tasks phase was skipped in error.
+
+## Inputs
+
+- Approved `spec.md` (and `design.md` when it exists)
+- `task-graph-engineering.md` for topology rules
+- `context-limits.md` if the breakdown is large — keep each task's file list short enough to load
+
+## Output
+
+`.specs/features/[feature]/tasks.md`, plus `task-graph.md` when the feature has 3+ tasks or parallel work.
+
+## Procedure
+
+1. **Write one task per deliverable.** A task is something you would hand to a single agent and check in one commit.
+2. **Prefer vertical slices.** One thin verifiable path per **feature** (e.g. register), not “all schema then all APIs then all UI” as *phases*. If `.cursor/rules/fullstack-layer.mdc` is present (`@luizsantiago/fullstack-floor-map`), keep each task `Files` list on **one Lane** (path layer; 0.4.x docs may still say “Floor”). Split UI vs API into T1/T2 with `Depends on`. Vertical still means a thin *feature*, not one task mixing `apps/web` + `apps/api`. See [Companion: Full Stack Floor Map](https://github.com/luizssantiago92/spec-guardrails/blob/main/docs/guide/Companion-fullstack-floor-map.md).
+3. **Give every task the full field set.** Authoring and the gate require all six:
+   - `Requirement` — the spec ID it serves (gated)
+   - `Files` — where the change lands (gated; required; `none` / `—` rejected; overlap across independent tasks blocks)
+   - `Depends on` — real dependencies only, or `—` (gated; `—` means none)
+   - `Tests` — the test file that proves it (gated; `none` / `—` rejected)
+   - `Gate` — the command that must pass (gated; `none` / `—` rejected)
+   - `Done when` — binary criterion (gated; `none` / `—` rejected)
+4. **Delete fake edges.** For every "and then", ask whether the next task actually reads the previous task's output. If not, the edge is fake — remove it and the tasks can run in parallel. See `task-graph-engineering.md`.
+5. **Order tasks so dependencies come first.** Forward dependencies fail the gate. When grouping under `### Phase N`, a task must not depend on a task in a later phase.
+6. **Apply the stop rule.** Only split work that never reads its siblings' results; sequential work stays with one agent.
+7. **Cover every acceptance criterion.** Fill `## Test Coverage Matrix` and `## Gate Check Commands` **before** presenting the list. An unmapped requirement is a missing task. Align each task `Tests` / `Gate` field with those sections.
+8. **Draw the graph** in `task-graph.md` when there are 3+ tasks or any parallel group.
+9. **Run analyze, then the tasks gate**, then present the breakdown for approval.
+   ```bash
+   python3 .specs/guardrails/scripts/analyze_artifacts.py [feature]
+   python3 .specs/guardrails/scripts/validate_tasks.py [feature]
+   ```
+
+**Authoring vs gate.** `validate_tasks.py` already enforces REQ coverage and `Tests`/`Gate` fields. The matrix and Gate Check Commands sections are an owner/verifier checklist (judgment) until a future form gate — do not skip them when Tasks ran.
+
+## Gate
+
+```bash
+python3 .specs/guardrails/scripts/validate_tasks.py .specs/features/[feature]/tasks.md
+python3 .specs/guardrails/scripts/validate_tasks.py [feature]
+python3 .specs/guardrails/scripts/validate_tasks.py          # single-feature projects
+```
+
+Checks task IDs, required fields (including `Files` and `Done when`), dependency direction, later-phase dependencies, cycles, granularity smells, **spec requirement coverage**, and **Files overlap** across independent tasks. `Files`/`Tests`/`Gate`/`Done when` set to `none` or `—` fail. Non-zero exit means STOP.
+
+Task headings, fields, and spec requirement IDs are read from visible markdown — fenced samples and HTML comments do not count. When a sibling `spec.md` exists, every requirement heading ID under `## Requirements` must appear in at least one task `Requirement` field. Independent tasks (no dependency path either way) must not share a path in `Files` (`./path`, `/path`, `../path`, quotes, markdown links, case variants, and `path` count as one).
+
+The gate does not check that `Done when` is philosophically binary — you do. A passing gate is necessary, not sufficient. Path overlap uses the shared `normalize_file_path` helper (quotes, markdown links, `./`, `/`, `../`, drive letters, casefold).
+
+## Execution Plan (phases)
+
+Use `### Phase N` when the work has a real staging constraint (schema before handlers, handlers before UI). Phases are ordered groups, not a second ID scheme.
+
+```markdown
+# Tasks: Authentication
+
+### Phase 1
+
+### T1: Create session token module
+- **Requirement**: REQ-001
+- **Files**: src/auth/token.ts
+- **Depends on**: —
+- **Tests**: test/auth/token.test.ts
+- **Gate**: npm test
+- **Done when**: module signs and verifies tokens
+- [ ] complete
+
+### Phase 2
+
+### T2: Add login endpoint handler
+- **Requirement**: REQ-001
+- **Files**: src/routes/login.ts
+- **Depends on**: T1
+- **Tests**: test/routes/login.test.ts
+- **Gate**: npm test
+- **Done when**: endpoint returns 200 for valid credentials
+- [ ] complete
+```
+
+Rules the gate enforces:
+
+- A task in Phase 1 must not depend on a task in Phase 2 or later
+- Document order still matters: dependencies must appear before dependents
+- Tasks with no phase heading are treated as phase 0 (ungrouped) and may depend only on other ungrouped or earlier-phase tasks
+
+Do not invent phases to make the list look organized. Two tasks that can run in the same round belong in the same phase, or in no phase at all.
+
+## Template
+
+```markdown
+# Tasks: [Feature]
+
+### T1: [Imperative, specific title]
+- **Requirement**: REQ-001
+- **Files**: src/auth/token.ts
+- **Depends on**: —
+- **Tests**: test/auth/token.test.ts
+- **Gate**: npm test
+- **Done when**: token module signs and verifies tokens
+- [ ] complete
+
+### T2: [Imperative, specific title]
+- **Requirement**: REQ-001
+- **Files**: src/routes/login.ts
+- **Depends on**: T1
+- **Tests**: test/routes/login.test.ts
+- **Gate**: npm test
+- **Done when**: endpoint returns 200 for valid credentials
+- [ ] complete
+
+## Test Coverage Matrix
+| Requirement | Task | Tests | Notes |
+| --- | --- | --- | --- |
+| REQ-001 | T1, T2 | test/auth/token.test.ts, test/routes/login.test.ts | |
+
+## Gate Check Commands
+| Level | Command |
+| --- | --- |
+| Task | the per-task `Gate` field |
+| Feature | npm test |
+```
+
+## Granularity
+
+| Too coarse | Atomic |
+| --- | --- |
+| "Create form" | T1: add email input component · T2: add email validation · T3: add submit handler |
+| "Implement feature" | One task per file or per contract |
+| "Fix bugs" | One task per reproducible defect |
+| "Add auth" | T1: token module · T2: login handler · T3: refresh handler |
+| "Write tests" | The tests belong on the task that produces the behavior, not as a follow-up |
+
+A task that cannot be verified by a single named test is not atomic yet. A title under three words is a smell the gate warns about (`"Add endpoint"` → `"Add login endpoint handler"`).
+
+## Good and bad dependencies
+
+| Edge | Real or fake | Why |
+| --- | --- | --- |
+| Login handler depends on token module | Real | The handler imports and calls the module |
+| README update depends on login tests | Fake | README does not read test output |
+| Refresh handler depends on login handler | Fake, unless it shares a type the login task creates | Same auth package can land in parallel if files differ |
+| UI form depends on API contract | Real if the form types are generated from the handler | Otherwise the form can mock the contract and run in parallel |
+
+Delete fake edges before drawing `task-graph.md`. Most first drafts hide two or three.
+
+## Coverage matrix
+
+Before approval, map every spec requirement heading under `## Requirements` to at least one task. Every task `Tests` path should appear in the matrix. Fill `## Test Coverage Matrix` and `## Gate Check Commands` in `tasks.md` (see Template).
+
+| Requirement | Task | Tests | Notes |
+| --- | --- | --- | --- |
+| REQ-001 | T2 | test/routes/login.test.ts | valid credentials → session |
+| REQ-001 | T2 | test/routes/login.test.ts | invalid → 401 `AUTH_INVALID` |
+| REQ-002 | T3 | test/routes/refresh.test.ts | refresh rotates the token |
+
+A requirement with no row is unimplemented by construction. Do not present the breakdown until the matrix is complete. The Python gate already fails uncovered REQ IDs; the table is for humans and Execute.
+
+`Files` lists on parallel tasks must be disjoint. If two tasks name the same file, they are one task, or they are sequential.
+
+## Next
+
+- 3+ tasks or parallel groups → `/task-graph` per `task-graph-engineering.md`
+- Otherwise → `implement.md`