@luizsantiago/spec-guardrails 4.6.0 → 4.8.0

package/README.md

@@ -8,237 +8,325 @@
 
 **Governed spec-driven development for AI coding agents.**
 
-Spec Guardrails installs a working method into your repository: the agent writes down what it is going to build, gets your approval, implements in small waves, and proves the result before calling it done. Nothing about your stack changes — you get written requirements, a task plan, and verification evidence stored as files in the project.
+Agents are fast — and optimistic. They ship code, summarize what they *think* they did, and move on. Spec Guardrails installs a **repeatable contract** into your repo: agree on the goal in writing, break work into provable steps, implement in waves, and verify with evidence that lives in **git**, not in a chat scrollback.
 
-npm: [`@luizsantiago/spec-guardrails`](https://www.npmjs.com/package/@luizsantiago/spec-guardrails) **4.6.x**
+You keep control: the agent proposes; you approve specs and tasks; push, merge, and deploy stay on your terms.
 
----
-
-## What changes in practice
-
-| Without it | With Spec Guardrails |
+| Without Spec Guardrails | With Spec Guardrails |
 | --- | --- |
-| The agent jumps straight to code and says "done" | Requirements are written and approved first, and "done" needs evidence |
-| Each new chat starts from zero | Specs, decisions, and state live in `.specs/` and survive the session |
-| Small fixes and risky features get the same treatment | The agent measures complexity and applies only the depth the change needs |
-| The whole playbook is pasted into every message | One phase guide is loaded per turn, which keeps cost and focus under control |
+| Jumps to code and says “done” | Written goal first; “done” needs evidence |
+| Each chat starts from zero | `.specs/` survives sessions and handoffs |
+| Same ceremony for a typo and a payment flow | Complexity router matches depth to risk |
+| Whole playbook pasted every turn | One skill per turn — lower cost, sharper focus |
 
-You stay in charge of scope: the agent proposes, you approve specs, task plans, and anything that touches git beyond local commits.
+**Platform adapters.** The same kit installs into the skill tree your agent already reads — **Cursor** (`.cursor/skills/`), **Claude Code** (`.claude/skills/`), **GitHub Copilot** (`.github/skills/`), **OpenAI Codex** (`.codex/skills/`), plus root `AGENTS.md` for other tools. By default `install` detects one platform and writes **one** tree; use `--all-platforms` when the repo serves multiple agents. Existing trees are preserved when you switch IDEs.
 
-Read more: [Overview](docs/guide/Overview.md) · [How it works](docs/guide/How-it-works.md) · [Concepts](docs/guide/concepts.md)
+npm: [`@luizsantiago/spec-guardrails`](https://www.npmjs.com/package/@luizsantiago/spec-guardrails) **4.8.x**
+
+**Docs:** [Overview](docs/guide/Overview.md) · [Quick start](docs/guide/Quick-start.md) · [Full guide index](docs/guide/README.md)
 
 ---
 
 ## Install
 
-Run once in your project root:
+Two commands — run both once in your project root:
 
 ```bash
 npx @luizsantiago/spec-guardrails install
 npx @luizsantiago/spec-guardrails doctor
 ```
 
-`install` writes the phase guides for your agent and creates the `.specs/` folder. By default it detects your platform (Cursor, Claude Code, Copilot, or Codex) and installs **one** skill tree plus that platform's adapter entry file. Existing trees are preserved when you switch IDEs. Use `install --all-platforms` for every tree, or `install --platform <id>` to force one.
+| Command | What it does |
+| --- | --- |
+| **`install`** | Copies phase guides and sister skills into your agent tree, creates `.specs/`, installs Python gate scripts |
+| **`doctor`** | Audits readiness — **Process** score (Node workflow) and **Brakes** score (Python gates available). Run after install and after every upgrade |
+
+| Requirement | What you get |
+| --- | --- |
+| **Node.js 18+** | **Required** — CLI, skills, `.specs/` scaffold, full SDD workflow |
+| **Python 3.10+** | **Optional** — enables **Brakes mode** (automatic gates below) |
+
+Re-run `install` after package upgrades — your `.specs/` notes are preserved. Day to day you work in **agent chat**; the agent calls the CLI when a phase needs it.
+
+### Optional presets
 
-Re-run `install` after upgrading the package — your existing `.specs/` notes are preserved. After that, you work in **agent chat**, not in the terminal; the agent calls the CLI and checks when needed.
+Seed team rules and stack hints in `.specs/config.yaml`:
 
-| Requirement | Role |
+```bash
+npx @luizsantiago/spec-guardrails init-config --preset <name>
+npx @luizsantiago/spec-guardrails preset list
+```
+
+| Preset | Typical use |
 | --- | --- |
-| **Node.js 18+** | Required — the CLI and the install step |
-| **Python 3.10+** | Optional — turns on automatic proof at each step |
+| `default` | General SDD |
+| `node-ts` | Node / TypeScript projects |
+| `python` | Python apps (`pytest`, `ruff`) |
+| `python-platform` | Python + optional deploy/infra and/or AI paths per feature — [guide](docs/guide/python-platform.md) |
 
-### Do you need Python?
+**Go deeper:** [Quick start](docs/guide/Quick-start.md) · [Platform parity](docs/guide/Platform-parity.md) · [Migration](docs/guide/Migration.md)
 
-**Node alone is enough to use everything** — every phase, every document, every approval point. The full process runs the same way.
+### Node alone vs Node + Python (gates)
 
-The difference is who decides whether a step is really finished:
+**Node is enough for the full process** — every phase, every artifact, every approval. The agent follows the same hub and phase guides.
 
-- **Without Python** — the agent checks its own work by reading the phase checklist. It works, but you are trusting the agent to be honest when it is eager to move on.
-- **With Python** — the same checks run automatically, and the agent **cannot advance** with half-done work: saying "done" without test evidence, writing a task that matches no requirement, or closing a step with an open question all stop the process until fixed.
+The difference is who decides whether a step is really finished:
 
-In short: Python turns "trust the agent" into "the agent has to prove it."
+| | **Process** (Node only) | **Brakes** (Node + Python) |
+| --- | --- | --- |
+| **Workflow** | Same SDD phases | Same SDD phases |
+| **Who checks** | Agent reads the checklist in skills | Python scripts with **exit codes** |
+| **When something is incomplete** | Agent *should* stop — relies on honesty | Agent **cannot** advance — non-zero = STOP |
+| **Best for** | Learning the method, light teams | Teams that want proof between your approvals |
 
-Which checks exist and what each one requires: [Gates](docs/guide/gates.md) · [Guarantees matrix](docs/guide/Guarantees-matrix.md)
+Add Python when you want those checklists enforced by **exit codes** instead of agent honesty — [what gates check at each boundary](#2-gates-brakes--done-has-to-be-provable). `doctor` reports Process vs Brakes readiness after install and upgrades.
 
-Read more: [Quick start](docs/guide/Quick-start.md) · [Tutorials](docs/guide/tutorials/README.md) · [Platform parity](docs/guide/Platform-parity.md) · [CHANGELOG](docs/CHANGELOG.md)
+**Go deeper:** [Gates reference](docs/guide/gates.md) · [Guarantees matrix](docs/guide/Guarantees-matrix.md) · [Process vs Brakes (FAQ)](docs/guide/FAQ.md#process-vs-brakes)
 
 ---
 
-## How you use it day to day
+## Why teams adopt it — three pillars
 
-You describe your project or the feature you want — in chat, or by pointing the agent at a file such as `prd.md` or `docs/brief.md`. With Spec Guardrails already installed, the agent reads that material plus what is already in the repo and picks up from there if work is in progress (`STATE.md` tells it where you left off).
+Most agent failures are not “bad code in one file.” They are **wrong goal**, **lost context**, or **fake done**. Spec Guardrails attacks those three problems directly.
 
-![Spec Guardrails phase flow — classify, optional elicitation, three human approvals, build loop, verify, archive](https://raw.githubusercontent.com/luizssantiago92/spec-guardrails/main/.assets/flow.svg)
+| Problem | Pillar | One-line win |
+| --- | --- | --- |
+| Built the wrong feature | **Requirements analysis** | Agree on intent before `spec.md` |
+| Skipped steps and called it done | **Gates (Brakes)** | Proof at boundaries, not trust |
+| Every chat starts from zero | **Memory** | `.specs/` in git beats chat history |
 
-The agent never skips your approvals on the full path. Requirements analysis is **suggested**, not forced — if the request is already clear, it goes straight to Specify.
+### 1. Requirements analysis — stop building the wrong thing
 
-Read more: [How it works](docs/guide/How-it-works.md) · [Agent commands](docs/guide/agent-commands.md) · [Glossary](docs/guide/Glossary.md)
+**Without it:** “Add login” becomes three different products in three chats — OAuth vs magic link vs username/password — and you discover the mismatch halfway through a PR.
 
----
+**With `/elicit`:** The agent asks a **small number of sharp questions** (at most five per round, one topic at a time, always with suggested options). It reads what you already wrote (`prd.md`, `docs/brief.md`, kickoff notes) and **does not re-ask** what those files already answer. You approve a **requirements brief** before `spec.md` exists — so vague chat does not harden into vague acceptance criteria.
 
-## How it sizes the work
+| Without analysis | With analysis |
+| --- | --- |
+| Assumptions stay implicit in chat | Assumptions surface early with owners |
+| Spec rewrites mid-build | Spec starts from an approved brief |
+| “I thought you meant…” after code exists | Disagreement costs minutes, not days |
 
-Before starting, the agent classifies the change and loads only what that change needs. A typo does not get a task graph; a payments integration does not skip review.
+It is **suggested**, not mandatory — clear requests can go straight to `/specify`. The win is catching ambiguity **before** the agent treats a half-sentence as a contract.
 
-![Complexity tiers — Quick, Simple, Medium, Complex, Parallel](https://raw.githubusercontent.com/luizssantiago92/spec-guardrails/main/.assets/tiers.svg)
+**4.8+:** optional `elicitation` policy (`require_brief` on Complex), NFR section checks, and `req-analysis diff` for brief↔spec drift — [workshop](docs/guide/tutorials/05-requirements-analysis-workshop.md).
 
-| Complexity | Typical scope | What gets created | Your approvals |
-| --- | --- | --- | --- |
-| **Quick** | ≤3 files, no new dependency, no auth/payments | Code + quick evidence | None (express lane) |
-| **Simple** | Small localized change, 2–5 files | `spec.md` → code → `validation.md` | Spec |
-| **Medium** | Real feature, under ~10 jobs | `spec.md`, `tasks.md` → code → `validation.md` → archive | Spec + tasks |
-| **Complex** | New APIs, architecture, infrastructure | Above + `design.md`, option discussion | Spec + tasks (+ design when used) |
-| **Parallel** | Work safely splittable across agents | Above + `task-graph.md` | Spec + tasks |
+**Go deeper:** [Requirements analysis](docs/guide/requirements-analysis.md) · [/elicit in agent commands](docs/guide/agent-commands.md)
+
+---
 
-This is also why sessions stay affordable: the agent loads one short guide per step instead of the entire playbook.
+### 2. Gates (Brakes) — “done” has to be provable
 
-Read more: [Complexity tiers](docs/guide/concepts.md#complexity-tiers--how-the-agent-chooses-depth) · [Token efficiency](docs/guide/Token-efficiency.md)
+**Process vs Brakes** — who enforces the checklist — is in [Install](#node-alone-vs-node--python-gates). Here is *when* Brakes run: scripts return non-zero = **STOP**; fix the artifact, re-run.
 
----
+| Moment | What gates protect |
+| --- | --- |
+| **Before spec approval** | Criteria are testable (`SHALL`/`MUST`), assumptions documented |
+| **Before task approval** | Every REQ maps to a task; tasks have shape and file ownership |
+| **Each commit** | Conventional message, no empty staged diff, no linter/test bypass in the diff |
+| **Before “feature done”** | Traceability REQ → task → `file:line` evidence; PASS verdict and `Verifier-Mode` in `validation.md` |
+| **After verify FAIL** | Lessons are recorded — failures become rules, not forgotten |
+
+Fifteen+ gates cover planning through close — including `validate-design` (Complex), optional [Python Platform](#python-platform-optional--47) checks, CI template (`templates/ci/guardrails-pr.yml`), and opt-in `install-hooks` for pre-commit. Command list and pipeline order: [gates reference](docs/guide/gates.md).
 
-## What is inside the kit
+---
 
-Each block names what ships in the package, how many pieces there are, and what you get from it. Technical detail lives in the linked guides.
+### 3. Memory — the repo remembers so you do not have to
 
-### Artifacts (12)
+**Without memory:** Every new session starts cold. You re-paste context, re-explain decisions, and hope the model does not contradict last week’s architecture chat.
 
-Plain markdown in `.specs/` — the paper trail that survives the chat and reviews like code in git.
+**With `.specs/`:** `STATE.md` says where you left off. Each feature folder holds spec, tasks, design, and validation. Archive folds shipped work into **domain specs** and `ROADMAP.md`. Failed verifies become **lessons** that constrain the next run.
 
-| File | What it holds |
+| Without `.specs/` | With `.specs/` |
 | --- | --- |
-| `STATE.md` | Active feature, current phase, next step |
-| `requirements-brief.md` | Answers from requirements analysis, signed off by you |
-| `spec.md` | Requirements, acceptance criteria, out of scope |
-| `exploration.md` | Compared solution options (when used) |
-| `design.md` | Technical approach and decisions (when used) |
-| `tasks.md` | Checkable jobs with file ownership |
-| `task-graph.md` | Which jobs can run in parallel (when used) |
-| `validation.md` | Independent verify verdict and proof |
-| `project/PROJECT.md` | Long-lived repo map |
-| `project/ROADMAP.md` | Planned and delivered features |
-| `domains/<slug>/spec.md` | Consolidated domain knowledge after archive |
-| `lessons.json` | Rules learned from past failures |
+| Chat is the source of truth | Git is the source of truth |
+| Handoff = long message | Handoff = read `STATE.md` + feature folder |
+| Same mistake twice | Lessons promote to confirmed rules |
+| “What did we decide about timeouts?” | `memory-retrieve "session timeout"` (optional index) |
+
+The **markdown artifacts alone** already beat chat-only workflows for any team that ships more than one feature. Optional search (keyword, graph, semantic embed) — see [Optional capabilities](#optional-capabilities-off-by-default).
 
-→ [Architecture](docs/guide/Architecture.md)
+**Go deeper:** [Memory guide](docs/guide/Memory.md) · [Brownfield context](docs/guide/brownfield-context.md)
 
-### Skills (1 hub + 19 phase guides + 8 specialists)
+---
 
-Instructions the agent loads **one at a time** — hub `agent-architecture.md` (router + contract), phase guides such as `specify.md`, `tasks.md`, `implement.md`, `validate.md`, and specialists such as `appsec.md`, `qa-strategy.md`, `security-review.md` when the work needs them.
+## Spec-driven development (SDD)
 
-→ [Skills and hub](docs/guide/skills-and-hub.md)
+Under the three pillars sits the **spec-driven method** the agent follows: written phases instead of improvisation. Before work starts, **`classify-change`** picks a complexity tier (Quick → Parallel) so a typo does not get a task graph and a payment flow does not skip review.
 
-### Gates (11)
+Lineage: [tlc-spec-driven](https://github.com/tech-leads-club/agent-skills/tree/main/packages/skills-catalog/skills/(development)/tlc-spec-driven), [loop-engineering](https://github.com/cobusgreyling/loop-engineering), [graph-engineering](https://github.com/codejunkie99/graph-engineering), [loopgate_harness](https://github.com/rxdt/loopgate_harness). **Repo-native harness** — not another desktop runtime.
 
-Automatic checks at step boundaries — each one blocks a specific kind of shortcut:
+![Spec Guardrails phase flow — classify, optional elicitation, approvals, build loop, verify, archive](https://raw.githubusercontent.com/luizssantiago92/spec-guardrails/main/.assets/flow.svg)
 
-| Gate | Stops the agent when… |
-| --- | --- |
-| `validate-req-analysis` | Requirements brief has open questions or no owner approval |
-| `validate-spec` | Spec has no testable acceptance criteria |
-| `analyze-artifacts` | A requirement has no matching task |
-| `validate-tasks` | Tasks are vague or file ownership conflicts |
-| `validate-traceability` | REQ → task → proof chain is broken |
-| `validate-state` | Feature is declared done without evidence |
-| `validate-quick` | Quick-mode fix broke its size or shape rules |
-| `check-commit` | Commit message is not conventional, staged diff is empty, or exceeds `commit.max_staged_lines` |
-| `check-suppressions` | Staged diff adds `# noqa`, `eslint-disable`, `@ts-ignore`, skipped tests, or `--no-verify` |
-| `quality-checks` | Configured project commands (`npm test`, …) fail during `/verify` |
-| `lessons` | A failed verify tries to skip the lesson step |
+### Phase map — what runs when
 
-→ [Gates](docs/guide/gates.md) · [Guarantees matrix](docs/guide/Guarantees-matrix.md)
+| Phase | Required? | What happens | You approve? |
+| --- | --- | --- | --- |
+| **Explore** | Optional | Research before a feature folder exists | — |
+| **Elicit** | Optional | Structured Q&A → requirements brief ([pillar §1](#1-requirements-analysis--stop-building-the-wrong-thing)) | Brief |
+| **Constitution** | Once per project | Project principles (`/constitution`) | Once |
+| **Specify** | Yes (full path) | Written requirements | **Spec** |
+| **Discuss** | When product is gray | Options A/B/C, decision records | As needed |
+| **Design** | When architecture matters | Technical approach in `design.md`; `validate-design` on Complex | As needed |
+| **Solution explore** | When architectures fork (optional — [off by default](#optional-capabilities-off-by-default)) | Compare candidates; record decision | Decision |
+| **Tasks** | When work needs a job list | Atomic tasks, file ownership, REQ coverage | **Tasks** |
+| **Execute** | Yes | `/loop` waves — implement, gate, commit; parallel when files are disjoint | — |
+| **Verify** | Yes | **Independent proof** — fresh context writes `validation.md`; author ≠ verifier | Verdict |
+| **Archive** | After Verify PASS | Fold into domain memory and roadmap | — |
+| **Quick** | Alternative path | ≤3 files, express lane — skips full spec/tasks ceremony | — |
+| **Converge** | On drift | Realign spec ↔ tasks before more Execute | — |
 
-### Requirements analysis
+**Brownfield:** `project-init` maps an existing repo into `.specs/` (`PROJECT.md`, domains, suggested preset) so the agent is not guessing stack every session.
 
-When the request is still fuzzy, the agent asks a **few targeted questions** — at most five per round, one topic at a time, always with suggested options — and never re-asks what your document already answered. You approve the brief before Specify starts.
+**Traceability:** REQ → task → evidence at verify ([pillar §2](#2-gates-brakes--done-has-to-be-provable)); semantic test quality is still your judgment.
 
-→ [Requirements analysis](docs/guide/requirements-analysis.md)
+**Parallel work:** `loop-plan` picks the next wave; `task-graph.md` and git worktrees (`workspace-prepare`) keep parallel agents off the same files.
 
-### Loops
+**Git tiers:** approving spec/tasks authorizes **local work only** (Tier 0). Push, PR, merge, and deploy need your explicit go-ahead — see [git-handoff](docs/guide/agent-commands.md).
 
-Implementation happens in **small waves**: pick the next runnable jobs, test, implement, check, commit, repeat. Parallel work only when two jobs touch different files; if tests fail, the agent retries a bounded number of times before escalating to you.
+![Complexity tiers — Quick, Simple, Medium, Complex, Parallel](https://raw.githubusercontent.com/luizssantiago92/spec-guardrails/main/.assets/tiers.svg)
 
-→ [Loop patterns](docs/guide/loop-patterns.md)
+**Go deeper:** [How it works](docs/guide/How-it-works.md) · [Loop patterns](docs/guide/loop-patterns.md) · [Agent commands](docs/guide/agent-commands.md) · [Concepts](docs/guide/concepts.md)
 
-### Memory (6 commands)
+### Hub and skills — how the agent navigates
 
-`memory-index`, `memory-search`, `memory-query`, `memory-retrieve`, `episodes`, and `code-index` — so a new session or teammate can ask "what did we decide about session timeout?" without you re-explaining. Lessons from verify failures feed back into future runs.
+The **hub** (`agent-architecture.md`) is the map loaded every turn: contract, **complexity router**, gate schedule, phase order, and git tiers. It tells the agent *which* procedure to open next — not the whole playbook at once.
 
-→ [Memory](docs/guide/Memory.md) · [Brownfield context](docs/guide/brownfield-context.md)
+**Phase guides** (`references/`) load **one per turn** (`specify.md`, `tasks.md`, `implement.md`, `validate.md`, …) — roughly **70% fewer skill tokens** than dumping the full kit each message.
 
-### Optional — off by default
+**Sister skills** load only when the work needs extra depth (security, task graphs, platform infra/AI, …). The hub loads **at most one** conditional sister at a time for Verify extras (AppSec, then QA).
 
-| Capability | What it adds |
-| --- | --- |
-| **Semantic memory search** | Find past specs and decisions by meaning, not just keywords |
+For **what each skill does and when to load it**, see the full catalog — hub, nineteen phase guides, ten sister skills:
 
-→ [Memory](docs/guide/Memory.md)
+**Go deeper:** [Skills and hub](docs/guide/skills-and-hub.md) · [Token efficiency](docs/guide/Token-efficiency.md)
 
 ---
 
-## What lands in your repository
+## Python Platform (optional — 4.7+)
+
+**What it is:** an optional **preset and gate pack** for **Python repos** where **some features** also touch **deploy/infra** and/or **AI/LLM** code paths. You do **not** need backend + DevOps + AI on every change — surfaces activate **per feature** when task files match:
 
-| Path | Role |
+| Your feature touches… | What gets documented in `design.md` |
 | --- | --- |
-| `.cursor/skills/` (or detected platform tree) | Phase instructions for your agent |
-| `.specs/STATE.md` | Active feature and next step |
-| `.specs/features/NNN-slug/` | Spec, tasks, and validation per feature |
-| `.specs/guardrails/scripts/` | Python checks (when Brakes mode is on) |
-| `.specs/config.yaml` | Optional project rules and execution policy |
+| Docker, Compose, Terraform, Helm, CI workflows | **Ship Surface** (deploy unit, CI, rollback) |
+| `prompts/`, `evals/`, MCP, RAG, embeddings | **AI Surface** (eval harness, fallback, scope) |
+| Application Python only | Standard SDD — extra surfaces only when paths match |
 
----
+`project-init` may suggest this preset when it detects compose, Terraform, CI, or eval directories — you still opt in.
+
+```bash
+npx @luizsantiago/spec-guardrails init-config --preset python-platform
+```
+
+**Without the preset:** deploy steps live in someone’s head, eval harnesses are “later,” rollback is learned during an incident.
 
-## Honest limits
+**With the preset:** gate `validate-ship-surface` blocks verify when matching paths lack documented surfaces; sisters `python-devops` and `ai-engineering` guide authoring; `feature-overview` adds operational + AI traceability tables.
 
-Gates enforce **structure and evidence in `.specs/`** — not product taste, not whether your tests are clever, and not a full AST review of implementation code. A green gate means the artifact shape and cited proof look complete; you still approve specs and tasks.
+### What Python Platform is **not** (honest)
 
-| Gates check | Gates do **not** check |
+| It is **not** | What we do instead |
 | --- | --- |
-| Spec sections and `SHALL`/`MUST` criteria | Semantic alignment between tests and requirements |
-| REQ → task → validation traceability | Stub or broken source outside cited paths |
-| Commit message shape and suppression patterns | Whether coverage % equals test quality |
-| Commands you list under `quality.checks` | Commands you never configured |
+| LangSmith, Coze Loop, live production traces | Version **contracts** in git + `/verify` evidence |
+| MLOps / eval runtime | Require a **documented** harness — quality is yours |
+| `terraform plan` security or cost review | Structural checks when you configure them |
+| Separate FastAPI/Django presets | Framework patterns in **tutorial appendices** |
 
-See [Guarantees matrix](docs/guide/Guarantees-matrix.md) for the full product view.
+Repos without `python-platform` are unchanged.
+
+**Go deeper:** [Python platform guide](docs/guide/python-platform.md) · [Tutorial 04](docs/guide/tutorials/04-python-platform-ship-surface.md)
 
 ---
 
-## Documentation
+## Optional capabilities (off by default)
 
-| Topic | Start here | Go deeper |
+These ship in the package but stay **disabled or unused until you configure them** — extra guardrails and power tools, not part of the default SDD path.
+
+| Capability | What it adds | Turn on when |
 | --- | --- | --- |
-| Orientation | [Overview](docs/guide/Overview.md) | [Concepts](docs/guide/concepts.md) |
-| First session | [Quick start](docs/guide/Quick-start.md) | [Agent commands](docs/guide/agent-commands.md) |
-| Process model | [How it works](docs/guide/How-it-works.md) | [Loop patterns](docs/guide/loop-patterns.md) |
-| Enforcement | [Gates](docs/guide/gates.md) | [Gates and guarantees](docs/guide/Gates-and-guarantees.md) |
-| Requirements | [Requirements analysis](docs/guide/requirements-analysis.md) | [Agent commands → /elicit](docs/guide/agent-commands.md) |
-| Long-running projects | [Memory](docs/guide/Memory.md) | [Brownfield context](docs/guide/brownfield-context.md) |
-| Questions | [FAQ](docs/guide/FAQ.md) | [Glossary](docs/guide/Glossary.md) · [Stability policy](docs/guide/Stability-policy.md) |
+| **Semantic memory** | Meaning-based search across archived specs (`memory-index embed`) | Many archived features; keyword search is not enough |
+| **`execution-policy`** | Path allow/deny, retry and run budgets in `.specs/config.yaml` | Agent has broad shell or file access |
+| **`context-guard`** | Block edits outside approved task `Files` | You want scope enforcement before edits |
+| **`sandbox check-command`** | Warn or block destructive shell (`rm -rf`, force-push, …) | Agent runs terminal commands unsupervised |
+| **`episodes`** | Short-lived session notes (`episodes record`) | Very long sessions; prune when done |
+| **`solution-explore`** | Formal architecture fork with `exploration.md` | Two+ defensible designs for the same spec |
 
-Full index: [docs/guide/README.md](docs/guide/README.md)
+**Go deeper:** [Agent commands](docs/guide/agent-commands.md) · [Architecture](docs/guide/Architecture.md)
 
 ---
 
-## Contributing
+## More in the kit
 
-Focused improvements are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) for layout, gate stability rules, and local checks.
+| Capability | Role |
+| --- | --- |
+| **`feature-status` / `feature-overview`** | Human-readable checklist and REQ → task → evidence dashboard |
+| **`phase-context`** | Inject team rules from `config.yaml` at a given phase |
+| **Tutorials** | Hands-on paths: quick fix → medium feature → parallel → python platform — [index](docs/guide/tutorials/README.md) |
 
-Edit sources under `skills/`, `lib/`, `scripts/`, and `rules/`; re-run `npm run guardrails -- install` after changing shipped assets, and run `npm test` before every PR.
+**Go deeper:** [Tutorials](docs/guide/tutorials/README.md) · [Ecosystem map](docs/guide/ecosystem.md)
+
+---
+
+## Limitations
+
+Gates enforce **structure and evidence in `.specs/`** — not product taste, not semantic test quality, not a full AST review of implementation code.
+
+| Enforced | Not enforced |
+| --- | --- |
+| Spec shape, REQ → task → proof traceability | Semantic test ↔ REQ alignment |
+| Evidence citations and PASS verdict | Stub code outside cited paths |
+| Ship/AI fields when paths match (platform) | Rollback tested in prod, eval quality |
+| Commit policy and suppression patterns | Coverage % as quality proxy |
+| Commands under `quality.checks` | Commands you never configured |
+
+A green gate means the paperwork looks complete — **you** still approve specs and tasks.
+
+**Go deeper:** [Gates and guarantees](docs/guide/Gates-and-guarantees.md) · [FAQ](docs/guide/FAQ.md)
+
+---
+
+## Contributing
+
+Focused improvements are welcome — [CONTRIBUTING.md](CONTRIBUTING.md). Sources: `skills/`, `lib/`, `scripts/`, `rules/`. Run `npm test` before every PR.
 
 ---
 
 ## Credits
 
-Spec Guardrails adapts patterns from open-source work. These are the projects whose ideas are actually shipped in the package:
+Patterns adapted from open source. **Shipped influences** (skills, gates, or layout consumers install):
 
-| Project | License | Used for |
+| Source | License | What we extracted |
 | --- | --- | --- |
-| [tlc-spec-driven](https://github.com/tech-leads-club/agent-skills/tree/main/packages/skills-catalog/skills/(development)/tlc-spec-driven) | CC-BY-4.0 | Spec → tasks → execute → verify model, `.specs/` layout, gate philosophy |
-| [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills) | MIT | Design-discussion patterns and definition-of-done framing |
-| [graph-engineering](https://github.com/codejunkie99/graph-engineering) | MIT | Task-graph rules behind safe parallel waves |
-| [loop-engineering](https://github.com/cobusgreyling/loop-engineering) | MIT | Wave-based execution model |
-| [loopgate_harness](https://github.com/rxdt/loopgate_harness) | MIT | Suppression-bypass blocking, project-configured quality commands as verify evidence, honest-limits framing, and README diagram layout (proxy-safe SVG; SMIL animation on GitHub) |
+| [tlc-spec-driven](https://github.com/tech-leads-club/agent-skills/tree/main/packages/skills-catalog/skills/(development)/tlc-spec-driven) | CC-BY-4.0 | Spec → tasks → execute → verify phases; `.specs/features/`, `STATE.md`; gate “brakes” philosophy |
+| [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills) | MIT | Discuss-phase options A/B/C; definition-of-done in verify/archive |
+| [graph-engineering](https://github.com/codejunkie99/graph-engineering) | MIT | Task-graph rules; `validate-tasks` graph hygiene |
+| [loop-engineering](https://github.com/cobusgreyling/loop-engineering) | MIT | Execute wave model; [loop-patterns.md](docs/guide/loop-patterns.md) |
+| [Addy Osmani — Loop engineering](https://addyosmani.com/blog/loop-engineering/) | Essay | Loop taxonomy in loop-patterns guide |
+| [awesome-harness-engineering](https://github.com/ai-boost/awesome-harness-engineering) | CC0 | Harness vs app vocabulary in [ecosystem.md](docs/guide/ecosystem.md) |
+| [loopgate_harness](https://github.com/rxdt/loopgate_harness) | MIT | `check-suppressions`; `quality.checks` as verify evidence; `check-commit --staged`; honest-limits framing; README diagram approach |
+| [obra/superpowers](https://github.com/obra/superpowers) | MIT | Two-stage subagent review in `sub-agents.md` |
+
+**Original work here:** Node CLI, Python gates, platform adapters, elicitation (`/elicit`), Python Platform pack (4.7+), SDLC integration helpers (4.8+), memory-index, execution policy, req-analysis tooling.
 
-Everything else — the CLI, the Python checks, the platform adapters, and the requirements-analysis phase — is original work in this repository. Full lineage, including references we cite but do not bundle: [Credits and lineage](docs/guide/credits.md).
+**Cited, not vendored:** [DeepCode](https://github.com/HKUDS/DeepCode), [RepoGraph](https://github.com/ozyyshr/RepoGraph), [NVIDIA SkillSpector](https://github.com/NVIDIA/SkillSpector) — see [credits.md](docs/guide/credits.md).
+
+---
+
+## Documentation
+
+| Topic | Link |
+| --- | --- |
+| Start here | [Overview](docs/guide/Overview.md) · [Quick start](docs/guide/Quick-start.md) · [Tutorials](docs/guide/tutorials/README.md) |
+| Chat & CLI | [Agent commands](docs/guide/agent-commands.md) |
+| Process | [How it works](docs/guide/How-it-works.md) · [Concepts](docs/guide/concepts.md) |
+| Skills (each role) | [Skills and hub](docs/guide/skills-and-hub.md) |
+| Gates | [gates.md](docs/guide/gates.md) · [Guarantees matrix](docs/guide/Guarantees-matrix.md) |
+| Requirements | [requirements-analysis.md](docs/guide/requirements-analysis.md) |
+| Memory | [Memory.md](docs/guide/Memory.md) |
+| Python platform | [python-platform.md](docs/guide/python-platform.md) |
+| Versions | [CHANGELOG](docs/CHANGELOG.md) · [Product history](docs/guide/Product-history.md) |
+| Help | [FAQ](docs/guide/FAQ.md) · [Glossary](docs/guide/Glossary.md) |
+
+Full index: [docs/guide/README.md](docs/guide/README.md)
 
 ---
 

package/index.js

@@ -29,9 +29,11 @@ import {
   featureOverview,
   formatFeatureOverview,
 } from "./lib/feature-overview.js";
+import { featurePrBody } from "./lib/feature-pr-body.js";
 import { featureStatus, formatFeatureStatus } from "./lib/feature-status.js";
 import { GATE_COMMANDS, AUX_COMMANDS, runGate, runGuardrailsScript } from "./lib/gates.js";
 import { install } from "./lib/install.js";
+import { installHooks } from "./lib/install-hooks.js";
 import { parsePlatformArg } from "./lib/platform-detect.js";
 import {
   cleanupWorkspaces,
@@ -95,6 +97,7 @@ Commands:
   req-analysis promote                 Print next steps after brief approval
     [--scope project|feature]          Match the brief scope
   req-analysis validate [brief.md]     Gate: approved requirements brief before /specify
+  req-analysis diff [feature]          Compare brief capabilities vs spec REQ coverage
   req-analysis context                 Assemble kickoff + brief context for Specify
     [--scope project|feature]          Scope (default: project)
     [--slug <feature-slug>]            Feature slug when scope=feature
@@ -112,6 +115,10 @@ Commands:
   feature-overview [feature]           REQ → task → evidence dashboard (markdown)
     [--write]                        Save .specs/features/<feature>/overview.md
     [--json]                         Machine-readable output (no markdown body)
+  feature-pr-body [feature]            Generate GitHub PR description from overview
+    [--json]                         Machine-readable output
+  install-hooks                      Install optional git pre-commit (check-commit, suppressions)
+    [--remove]                       Remove Spec Guardrails-managed pre-commit hook
   phase-context <phase>              Print .specs/config.yaml context + rules for a phase
   doctor [path]                      Audit guardrails readiness (score + next actions)
     [--json]                         Machine-readable output
@@ -183,8 +190,11 @@ Commands:
   loop-plan [tasks.md|feature]       Next Execute wave — parallel groups + sub-agent hints
     [--json]                         Machine-readable plan for agents
   validate-traceability [feature]    REQ → tasks → validation coverage chain
+  validate-ship-surface [feature]    Ship Surface + AI Surface when infra/AI paths in tasks
   validate-quick [quick-folder]      Quick-mode TASK.md / SUMMARY.md structural gate
   validate-req-analysis [brief.md]   Requirements brief gate before /specify (/elicit)
+  validate-design [feature]          design.md structure gate (Complex / Medium+)
+  req-analysis-diff [feature]        Brief capabilities vs spec REQ drift (heuristic)
   validate-state [feature]           Completion gate before declaring a feature done
   check-commit --message "<msg>"     Conventional Commits gate
     [--staged]                       Also reject empty commits and oversized staged diffs
@@ -250,6 +260,28 @@ if (command === "--version" || command === "-v" || command === "version") {
     console.error(`❌ ${err.message}`);
     process.exit(1);
   }
+} else if (command === "install-hooks") {
+  try {
+    let remove = false;
+    for (const arg of args) {
+      if (arg === "--remove") {
+        remove = true;
+      } else {
+        throw new Error("Usage: install-hooks [--remove]");
+      }
+    }
+    const result = await installHooks(process.cwd(), { remove });
+    if (result.action === "installed") {
+      console.log(`✅ Installed pre-commit hook at ${result.path}`);
+    } else if (result.action === "removed") {
+      console.log(`✅ Removed Spec Guardrails pre-commit hook`);
+    } else {
+      console.log(`ℹ️  No Spec Guardrails hook to remove`);
+    }
+  } catch (err) {
+    console.error(`❌ ${err.message}`);
+    process.exit(1);
+  }
 } else if (command === "init-config") {
   try {
     let preset = "default";
@@ -998,6 +1030,10 @@ if (command === "--version" || command === "-v" || command === "version") {
       const briefPath = rest.find((arg) => !arg.startsWith("--"));
       const code = await runGate("validate-req-analysis", briefPath ? [briefPath] : []);
       process.exit(code);
+    } else if (sub === "diff") {
+      const featureArg = rest.find((arg) => !arg.startsWith("--"));
+      const code = await runGate("req-analysis-diff", featureArg ? [featureArg] : []);
+      process.exit(code);
     } else if (sub === "context") {
       let scope = "project";
       let slug = "";
@@ -1028,7 +1064,7 @@ if (command === "--version" || command === "-v" || command === "version") {
       const code = await runGuardrailsScript("req-context", scriptArgs);
       process.exit(code);
     } else {
-      throw new Error("Usage: req-analysis init | discover | promote | validate | context");
+      throw new Error("Usage: req-analysis init | discover | promote | validate | diff | context");
     }
   } catch (err) {
     console.error(`❌ ${err.message}`);
@@ -1113,6 +1149,27 @@ if (command === "--version" || command === "-v" || command === "version") {
     console.error(`❌ ${err.message}`);
     process.exit(1);
   }
+} else if (command === "feature-pr-body") {
+  try {
+    let json = false;
+    const positional = [];
+    for (const arg of args) {
+      if (arg === "--json") {
+        json = true;
+      } else {
+        positional.push(arg);
+      }
+    }
+    const result = await featurePrBody(positional[0]);
+    if (json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      process.stdout.write(result.body);
+    }
+  } catch (err) {
+    console.error(`❌ ${err.message}`);
+    process.exit(1);
+  }
 } else if (AUX_COMMANDS.includes(command)) {
   try {
     const code = await runGuardrailsScript(command, args);