@luizsantiago/spec-guardrails 3.0.1

package/skills/code-simplify.md

@@ -0,0 +1,49 @@
+# Code Simplify
+
+Lean pass to reduce complexity **without changing behavior**. Complements Execute adequacy A–D and the standing Definition of Done in `engineering-standards.md`.
+
+**Judgment only.** `validate_state.py` does not require a simplify step. Skip with a one-line reason when unused.
+
+## When to Use
+
+Load when **any** of:
+
+- After adequacy **A–D** are green on a **Medium+** task and the diff looks denser than needed
+- Owner asks to simplify, clean up, or refactor with **no behavior change**
+
+## When NOT to Use
+
+Quick one-liners, first RED/GREEN of a task, or when behavior must change (that is a new task / Spec Deviation). Never load in the same working set as `appsec.md`, `qa-strategy.md`, or `ship-ready.md`.
+
+## Procedure
+
+1. **Freeze behavior** — suite / task `Gate` already green; do not start from a red tree.
+2. **Target only this task’s `Files`** — no drive-by modules.
+3. **Simplify** — naming, extract obvious duplication, drop dead code/debug; prefer clarity over cleverness.
+4. **Re-run the same `Gate`** — if anything fails, revert the simplify diff.
+5. **Commit separately** when non-trivial (`refactor(scope): …`), still Conventional Commits.
+
+## Anti-rationalizations
+
+| Excuse | Response |
+| --- | --- |
+| "While I'm here, change the API" | Behavior change needs a task / spec — not this skill |
+| "Tests will catch it later" | Re-run `Gate` before commit |
+| "Bigger cleanup across the package" | Out of `Files` — Deferred Ideas in `STATE.md` |
+
+## Output shape
+
+```markdown
+## Code simplify
+- Applied: yes | skipped — [reason]
+- Files: [paths]
+- Gate: [command] → pass
+- Notes: [optional one line]
+```
+
+## Related
+
+- `references/implement.md` — per-task cycle; offer this skill after A–D on Medium+
+- `engineering-standards.md` — Definition of Done
+- `references/context-limits.md` — at most one conditional sister
+- `ship-ready.md` — launch checklist (separate trigger; never together)

package/skills/engineering-standards.md

@@ -0,0 +1,98 @@
+# Engineering Standards
+
+Cross-cutting engineering policies for all implementation and verification work.
+Apply during **Execute** and **Verify** phases, and whenever writing or reviewing code.
+
+## When to Use
+
+- Implementing features (`/loop`)
+- Reviewing code (`/verify`)
+- Fixing bugs, refactors, or dependency updates
+- Any task that touches source code, tests, or infrastructure
+
+## Artifact Language
+
+Every project artifact is written in **English**: source code, tests, comments and docstrings, commit messages, PR titles and descriptions, `.specs/` documents, and identifier names.
+
+Chat language is a personal preference, not guardrails rule. Set it as a global rule in your agent settings if you want replies in another language.
+
+## Secure Coding
+
+- **Never commit secrets** — API keys, tokens, passwords, private keys belong in env vars or secret managers.
+- **Validate all inputs** — sanitize user input; use parameterized queries; avoid string concatenation in SQL.
+- **Fail closed** — auth/authz errors must deny access; never fall back to permissive defaults.
+- **Least privilege** — minimal scopes for tokens, IAM roles, and database users.
+- **Dependencies** — prefer well-maintained packages; run audit before adding; pin versions in lockfiles.
+- **Error handling** — no silent swallow; log without PII or secrets.
+- **HTTPS only** — no plaintext credentials or sensitive data over HTTP.
+
+## Code Quality
+
+- **Follow existing conventions** — read surrounding code before adding new patterns.
+- **Surgical changes** — touch only the files the current task requires.
+- **No scope creep** — good ideas outside the task go to `.specs/STATE.md` under Deferred Ideas, never into the diff.
+- **Small, focused diffs** — one logical change per commit; avoid drive-by refactors.
+- **DRY with judgment** — extract duplication when it improves clarity, not prematurely.
+- **Explicit over clever** — readable code beats clever one-liners.
+- **Types & lint** — respect TypeScript strict mode, ESLint, Prettier, or project equivalents.
+- **Dead code** — remove unused imports, variables, and commented-out blocks.
+
+## Testing Standards
+
+- Tests derived from acceptance criteria (see `agent-architecture.md`).
+- Cover happy path, edge cases, and failure modes.
+- No flaky tests — isolate external dependencies with mocks/fakes.
+- Assert behavior, not implementation details (unless testing internals is intentional).
+- Test names describe scenario and expected outcome in English.
+- **Never weaken a test to make a gate pass** — no skipping, deleting, or loosening assertions.
+
+## Definition of Done (standing bar)
+
+Project-wide readiness — **judgment**, not `validate_state.py`. Clear acceptance criteria **and**: tests for this change pass; diff stays in task `Files`; lint/types if the project has them; no secrets/PII in source or logs; no debug dumps or dead commented code; honest Gaps (never PASS with open gaps).
+
+## Parallel Work Guardrails
+
+- **One writer per file** — no two agents or jobs mutate the same file in the same round (see `task-graph-engineering.md`)
+- **Disjoint ownership** — parallel tasks must touch different files or modules
+
+## Git & PR Hygiene
+
+```
+feat(scope): add user authentication
+fix(api): handle null response from payment gateway
+docs(readme): update install instructions
+test(auth): add session expiry edge case
+```
+
+Validate the message before committing:
+
+```bash
+python3 .specs/guardrails/scripts/check_commit.py --message "feat(auth): add token refresh"
+```
+
+Optionally wire it as a git `commit-msg` hook so the rule holds without agent involvement.
+
+- One concern per PR when possible.
+- Link to spec requirement IDs (e.g. `REQ-003`) in PR description.
+- Include test evidence (file:line) for each REQ addressed — not just a summary.
+- Never force-push shared branches without coordination (Tier 2).
+- **Git blast radius (tiers)** — Tier 0 local work is authorized by spec/tasks approval. Tier 1 (`push`, PR) and Tier 2 (merge, deploy, force-push) require explicit owner go-ahead. See `git-handoff.md`.
+
+## Logging & Observability
+
+- Structured logs where the project supports them.
+- Include correlation/request IDs in server-side logs.
+- No secrets, tokens, or full PII in logs.
+- Metrics and traces for critical paths when infrastructure allows.
+
+## Related Skills
+
+- `agent-architecture.md` — SDD hub, execution contract, gates
+- `references/implement.md` — per-task execution cycle
+- `security-review.md` — deep checklist for `/verify` phase
+- `git-handoff.md` — git sync and session handoff for `.specs/`
+- `task-graph-engineering.md` — task DAG and parallelism rules
+
+## Related Rules
+
+Project rules: `.cursor/rules/engineering-baseline.mdc` (always applied in Cursor).

package/skills/git-handoff.md

@@ -0,0 +1,213 @@
+# Git Handoff
+
+Version project memory and spec artifacts in git at phase boundaries and session end.
+Sister skill to `agent-architecture.md` — SDD defines *what* to build; this skill defines *when and how* to persist progress in git.
+
+## When to Use
+
+- End of any agent session (mandatory handoff)
+- After **Specify**, **Tasks**, or **Verify** phases complete
+- Before switching branches, agents, or human reviewers
+- When `STATE.md` or `.specs/features/` changed materially
+
+## Resume: Reconcile Before Trusting STATE
+
+The handoff snapshot can be stale. At session start, reconcile it against git — **evidence wins**:
+
+```bash
+git branch --show-current
+git status --porcelain
+git log --oneline -10
+```
+
+Compare with `tasks.md` checkboxes. If commits exist for tasks STATE lists as pending, update STATE before doing anything else. Full procedure: `references/memory.md`.
+
+## Sister Skills (use together)
+
+| Skill | Role |
+| --- | --- |
+| `agent-architecture.md` | Process — Specify → Verify workflow |
+| `engineering-standards.md` | Quality — secure coding, commit format, artifact language |
+| `security-review.md` | Verification — OWASP checklist for `/verify` |
+| `task-graph-engineering.md` | Topology — task DAG and parallelism |
+| **`git-handoff.md`** | **Persistence — git sync for `.specs/` and handoff** |
+
+## What to Commit
+
+### Always commit (project memory)
+
+```
+.specs/STATE.md
+.specs/LESSONS.md
+.specs/lessons.json
+.specs/project/**/*
+.specs/features/**/*
+.specs/quick/**/*
+.specs/guardrails/scripts/**/*
+```
+
+Treat `.specs/` as **versioned product documentation**, not ephemeral notes. The gate scripts under `.specs/guardrails/scripts/` are committed on purpose — the team and CI run the same gates as the agent.
+
+### Never commit via handoff
+
+```
+.cursor/skills/          # installed by spec-guardrails; upstream is spec-guardrails repo
+.claude/skills/
+.cursor/rules/             # unless team customized — then commit intentionally
+node_modules/
+.env, secrets, credentials
+```
+
+### Code commits
+
+Follow `engineering-standards.md` — separate commits for code vs docs when possible.
+
+## Git Blast Radius (Tiers)
+
+Structural gates enforce artifact quality. Git tiers enforce **what leaves the machine**.
+
+| Tier | Auto on phase trigger | Owner go-ahead |
+| --- | --- | --- |
+| **0 — Local** | `feature-init`, `git checkout -b feat/NNN-slug`, commits for spec/tasks/code/STATE | — |
+| **1 — Share** | — | `git push`, open/update PR |
+| **2 — External** | — | merge, deploy, force-push, production data |
+
+### Tier 0 triggers (automatic — no ask)
+
+| Phase complete | Git action |
+| --- | --- |
+| `/specify` start | `feature-init "<description>"` → folder + branch + STATE |
+| Spec approved | Commit `spec.md` (+ `context.md` if Discuss ran) |
+| Tasks approved | Commit `tasks.md` (+ `task-graph.md` if created) |
+| Execute (each task) | Atomic code commit per task |
+| Verify PASS | Commit `validation.md` |
+| `/handoff` | Commit `.specs/` snapshot |
+| `/archive` | Commit ROADMAP + domain spec merge |
+
+**Quick tier:** no dedicated branch — commit on current branch.
+
+### Tier 1 — share (explicit once per feature)
+
+Stop after local commits. Owner says "push" / "open PR" before:
+
+```bash
+git push -u origin feat/003-chat-system
+```
+
+### Tier 2 — external (explicit per action)
+
+Merge, deploy, tags, force-push — each needs a separate go-ahead. `ship-ready.md` documents readiness; it never authorizes push.
+
+## Handoff Workflow (`/handoff`)
+
+Run at session end or phase milestone:
+
+### 1. Update memory
+
+Use this structure in `.specs/STATE.md`:
+
+```markdown
+## Active Feature
+- Feature: [name]
+- Phase: [Specify|Design|Tasks|Execute|Verify]
+- Branch: [branch-name]
+
+## Decisions (this session)
+- [decision and rationale]
+
+## Next Step (single item)
+- [ ] [one concrete action]
+
+## Blockers
+- [open questions or dependencies]
+```
+
+- Refresh all sections above each handoff
+- Record a grounded lesson with `lessons.py add` if verification failed. Never hand-edit `LESSONS.md`.
+
+### 2. Validate before commit
+
+- Run relevant tests / linters (operational harness — not self-declaration)
+- Ensure no secrets in staged files
+- Commit messages in **English** (Conventional Commits):
+  ```bash
+  python3 .specs/guardrails/scripts/check_commit.py --message "docs(spec): update STATE handoff for auth"
+  ```
+
+### 3. Stage and commit
+
+```bash
+git add .specs/
+git status   # review — no secrets, no accidental paths
+git commit -m "docs(spec): update STATE handoff for [feature]"
+```
+
+### 4. Do NOT auto-push (Tier 1)
+
+Stop after commit. Owner handles `git push` and PRs (Tier 1).
+
+## Commit Messages by Phase
+
+| Phase completed | Example commit |
+| --- | --- |
+| Specify | `docs(spec): add REQ-001 auth requirements` |
+| Design | `docs(spec): design OAuth flow for auth feature` |
+| Tasks | `docs(spec): task breakdown for auth feature` |
+| Task graph | `docs(spec): add task graph for auth feature` |
+| Verify | `docs(spec): validation report auth feature` |
+| Session handoff | `docs(spec): update STATE handoff — auth in progress` |
+| Lessons learned | `docs(spec): record lesson — JWT expiry edge case` |
+
+## Phase Boundary Rules
+
+| Event | Git action |
+| --- | --- |
+| Spec approved | Commit `spec.md` (+ `context.md` when Discuss ran) |
+| Tasks approved | Commit `tasks.md` (+ `task-graph.md` if created) |
+| Verify passed | Commit `validation.md` after `validate_state.py` passes |
+| Execute loop | Atomic code commits per task (existing Execute rules) |
+| Session ends | `/handoff` — always update STATE + commit `.specs/` |
+
+## `.gitignore` Guidance
+
+Ensure target projects **do not** ignore `.specs/`:
+
+```gitignore
+# Keep .specs/ tracked — it is project memory
+# DO NOT add: .specs/
+```
+
+Agent tooling and Python bytecode stay ignored:
+
+```gitignore
+.cursor/skills/
+.claude/skills/
+.specs/guardrails/scripts/__pycache__/
+```
+
+The gate scripts themselves are committed; only their compiled bytecode is ignored.
+
+## Evidence-or-Zero for Handoff
+
+A handoff is complete only when:
+
+1. `STATE.md` has a concrete "Next step" line
+2. `git log -1` shows the handoff commit
+3. Staged files were reviewed (no secrets)
+
+Commit messages and every `.specs/` artifact are written in **English**.
+
+## Related Commands
+
+| Command | Action |
+| --- | --- |
+| `/handoff` | End session — update STATE, commit `.specs/`, no push |
+| `/sync-spec` | Commit current feature spec artifacts only (`spec.md`, `tasks.md`, `task-graph.md`, etc.) |
+| `/verify` | After verify — commit `validation.md` (see `references/validate.md`) |
+
+## Related Skills
+
+- `agent-architecture.md` — SDD hub, execution contract, gates
+- `references/memory.md` — STATE semantics, decision log, reconcile protocol
+- `engineering-standards.md` — commit format and blast radius
+- `task-graph-engineering.md` — commit `task-graph.md` at phase boundaries

package/skills/qa-strategy.md

@@ -0,0 +1,83 @@
+# QA Strategy
+
+Lean product-QA pass for **Complex** work, multi-step user-facing flows, or explicit regression asks. Complements `/verify` evidence-or-zero and lean Interactive UAT — it does **not** rewrite those procedures.
+
+**Judgment only.** `validate_state.py` does not require an `## QA` section. A skip with reason is valid. This skill does not prove product quality by itself; it focuses smoke, regression, and where bugs go.
+
+## When to Use
+
+Load during `/verify` when **any** of:
+
+- Hub tier is **Complex**
+- User-facing flow with multiple observable steps (not a single static screen)
+- Owner asked for regression / QA focus on this feature
+
+If `appsec.md` also triggered: run AppSec **first**, drop it from context, **then** load this skill. Never hold AppSec and QA in the same working set.
+
+## When NOT to Use
+
+Do **not** load on Quick, Simple one-file fixes, or Verify already covered by evidence-or-zero alone with no multi-step UI. Record:
+
+`QA: skipped — no Complex tier, no multi-step UI, no explicit regression ask`
+
+## Relationship to Verify
+
+| Concern | Where |
+| --- | --- |
+| Spec-anchored tests, sensor, evidence-or-zero, verdict | `references/validate.md` |
+| OWASP checklist | `security-review.md` |
+| Lean walkthrough script | `references/validate.md` § Interactive UAT |
+| Smoke / regression focus / pyramid reminder | **This skill** (conditional) |
+
+Do not duplicate the mutant catalog or UAT protocol here — link and apply.
+
+## Procedure
+
+### 1. Risk → cases
+
+From `spec.md` REQs and the critical user path, list:
+
+- **Smoke** — few checks that the feature’s happy path still works
+- **Regression focus** — adjacent areas most likely broken by this diff
+- **Edge** — only boundaries the spec actually constrains (no invented matrix)
+
+Keep the list short. A TLC-style full coverage matrix is out of scope for this skill.
+
+### 2. Pyramid reminder
+
+- **Unit** — domain rules and pure logic named by acceptance criteria  
+- **Integration** — API / DB / auth boundaries this feature touches  
+- **E2E** — at most the one critical happy path; do not E2E every REQ  
+
+Weak tests (`toBeDefined()`, empty 2xx) stay a Verify gap — see `validate.md`.
+
+### 3. Bug vs Gaps
+
+| Finding | Treat as |
+| --- | --- |
+| Product behavior wrong vs spec / UAT | **Bug** → fix task under Execute |
+| Missing `file:line`, weak assertion, sensor, open Gaps | **Verify Gap** → catalog in `validate.md` |
+| Security checklist / AppSec fail | Security / AppSec path — not a QA label |
+
+### 4. UAT
+
+If Complex + user-facing, follow **Interactive UAT** in `validate.md` after this QA pass (or as the last Verify step). Do not redefine severity tables here.
+
+## Output shape
+
+```markdown
+## QA
+- Applied: yes | skipped — [reason]
+- Smoke: [short list]
+- Regression focus: [short list]
+- Result: pass | fail | skipped
+```
+
+`fail` → Gaps or fix tasks; do not leave `Verdict: PASS` while QA Result is fail (verifier judgment; not a structural gate).
+
+## Related
+
+- `references/validate.md` — Verify + lean UAT; sequential AppSec → QA load rule
+- `appsec.md` — conditional AppSec (run before this skill when both apply)
+- `references/context-limits.md` — at most one conditional sister in context
+- [Gate stability](https://github.com/luizssantiago92/spec-guardrails/blob/main/prd/gate-stability.md) — QA / UAT are non-guarantees

package/skills/references/analyze.md

@@ -0,0 +1,56 @@
+# Analyze
+
+Cross-artifact consistency check before implementation.
+
+## When to Use
+
+- After Tasks are drafted, before owner approves them
+- After a large spec or tasks edit mid-feature
+- When something "feels off" between spec, design, and tasks
+
+## When NOT to Use
+
+- Before a spec exists
+- Quick tier (no tasks.md)
+
+## Inputs
+
+- `.specs/features/[feature]/spec.md`
+- `.specs/features/[feature]/tasks.md` when present
+- `.specs/features/[feature]/design.md` when present
+- `.specs/STATE.md`
+
+## Output
+
+Fix list in chat; update artifacts until the gate passes.
+
+## Procedure
+
+1. **Run the gate:**
+   ```bash
+   python3 .specs/guardrails/scripts/analyze_artifacts.py [feature]
+   npx @luizsantiago/spec-guardrails analyze-artifacts [feature]
+   ```
+2. **Fix every blocking error** — missing REQ coverage, orphan task Requirement IDs.
+3. **Resolve warnings** before owner approval:
+   - Open `[NEEDS CLARIFICATION]` markers
+   - STATE branch ≠ current git branch → reconcile per `memory.md`
+   - Empty `design.md` on Complex work → write design or drop the file
+4. **Re-run until PASS** (use `--strict` before final approval if warnings remain).
+
+## What the gate checks
+
+| Check | Blocks? |
+| --- | --- |
+| Spec REQ without task coverage | Yes |
+| Task Requirement references unknown REQ | Yes |
+| Open `[NEEDS CLARIFICATION]` | Warn (`--strict` blocks) |
+| STATE branch ≠ git branch | Warn |
+| design.md nearly empty with tasks present | Warn |
+
+## Next
+
+- PASS → present tasks to owner for approval, then `implement.md`
+- Spec gaps → `specify.md`
+- Architecture gaps → `design.md`
+- Back → `tasks.md`

package/skills/references/archive.md

@@ -0,0 +1,60 @@
+# Archive
+
+Fold a verified feature back into long-lived project memory after Verify PASS.
+
+## When to Use
+
+- `validate_state.py` passed with verdict PASS/PASSED
+- Owner confirms the feature is complete
+- Brownfield: delta specs need merging into domain truth
+
+## When NOT to Use
+
+- Verify still failing or open Gaps
+- Quick-tier work (optional — update ROADMAP only)
+
+## Inputs
+
+- `.specs/features/[feature]/validation.md` (PASS)
+- Feature artifacts: `spec.md`, optional `design.md`
+- `.specs/project/ROADMAP.md` when present
+- Domain specs under `.specs/domains/` when the project uses them
+
+## Output
+
+- ROADMAP entry updated
+- Optional domain spec merge (brownfield)
+- STATE.md cleared for next feature
+- Feature folder kept (historical record)
+
+## Procedure
+
+0. **Load project context (optional)** — `npx @luizsantiago/spec-guardrails phase-context archive` when `.specs/config.yaml` exists.
+1. **Confirm PASS** — `validate_state.py [feature]` exit 0.
+2. **Run archive CLI (Tier 0)** — merges domain truth and updates ROADMAP + STATE:
+   ```bash
+   npx @luizsantiago/spec-guardrails archive-feature [feature] [--domain <slug>]
+   ```
+   Flags: `--no-roadmap`, `--no-domain`, `--no-state` for partial runs; `--skip-verify` for recovery only.
+3. **Review domain diff** — owner approves the merged `.specs/domains/[domain]/spec.md` before Tier 1 push.
+4. **Commit** archive updates (Tier 0):
+   ```bash
+   git commit -m "docs(spec): archive 003-chat-system"
+   ```
+5. **Tier 1 optional** — owner may push branch / open PR separately.
+
+## Delta merge rules
+
+| Section | Action |
+| --- | --- |
+| ADDED | Append new REQ blocks to domain spec |
+| MODIFIED | Replace matching REQ blocks by ID |
+| REMOVED | Delete REQ blocks listed by ID; note in ROADMAP |
+
+Never merge without owner approval of the domain spec diff.
+
+## Next
+
+- New work → `feature-init` then `specify.md`
+- Push for review → owner go-ahead (Tier 1)
+- Back → `validate.md`

package/skills/references/constitution.md

@@ -0,0 +1,66 @@
+# Constitution
+
+Establish project governing principles that guide every phase.
+
+## When to Use
+
+- First guardrails session on a new project
+- Owner asks to define or refresh engineering principles
+- Before the first Medium+ feature when `.specs/project/CONSTITUTION.md` is missing
+
+## When NOT to Use
+
+- Per-feature decisions — use `context.md` or `design.md`
+- Quick fixes with no principle impact
+
+## Inputs
+
+- Owner's values (quality, testing, UX, performance, security posture)
+- Existing README, ADRs, team standards
+- `.specs/project/PROJECT.md` when present
+
+## Output
+
+`.specs/project/CONSTITUTION.md`
+
+## Procedure
+
+1. **Interview lightly.** Ask what must never regress (tests, accessibility, latency, security).
+2. **Draft principles** as numbered, testable statements — not slogans.
+3. **Link to enforcement** — which gate or skill checks each principle (when applicable).
+4. **Get approval** before treating the constitution as binding.
+5. **Commit** with `docs(spec): add project constitution` (Tier 0).
+
+## Template
+
+```markdown
+# Project Constitution
+
+## Principles
+
+### C-001: Test-first delivery
+- Every feature change MUST include tests derived from acceptance criteria before merge.
+
+### C-002: Security baseline
+- Auth and PII surfaces MUST pass OWASP review in `/verify`.
+
+### C-003: User-facing quality
+- UI changes MUST remain accessible and consistent with existing patterns.
+
+## Non-Negotiables
+- No secrets in git
+- No skipping structural gates
+
+## Amendment
+- Supersede with a new C-NNN entry and reference the old one — never edit history in place.
+```
+
+## Gate
+
+No Python gate. Constitution compliance is checked by judgment in Specify, Design, Execute, and Verify.
+
+## Next
+
+- First feature → `feature-init` then `specify.md`
+- Principles constrain architecture → reference C-NNN in `design.md`
+- Back → `agent-architecture.md`