@luizsantiago/spec-guardrails 3.0.1

package/scripts/validate_tasks.py

@@ -0,0 +1,379 @@
+#!/usr/bin/env python3
+"""Granularity gate for `.specs/features/[feature]/tasks.md`.
+
+Run before presenting a task breakdown for approval:
+
+    python3 validate_tasks.py .specs/features/auth/tasks.md
+    python3 validate_tasks.py auth
+    python3 validate_tasks.py            # when the project has a single feature
+
+Checks:
+  * at least one task with a well-formed ID (T1, T2, ...)
+  * every task carries Requirement, Files, Depends on, Tests, Gate and Done when
+  * Tests and Done when reject placeholder values (none, —, n/a)
+  * dependencies reference existing tasks, never forward, never self
+  * a task never depends on a task in a later `### Phase N` group
+  * dependency graph is acyclic
+  * every requirement ID in sibling spec.md is covered by at least one task
+  * independent tasks do not share Files paths
+  * 3+ tasks require sibling task-graph.md (when validating on disk)
+  * vague task titles are flagged as granularity smells
+
+Exit codes: 0 pass, 1 blocking issues, 2 usage error.
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+from _common import (
+    Report,
+    find_placeholders,
+    normalize_file_path,
+    requirement_ids,
+    resolve_artifact,
+    visible_markdown,
+)
+
+GATE = "validate-tasks"
+
+TASK_HEADING = re.compile(
+    r"^#{2,6}\s*(?P<id>T\d{1,6})\s*[:\-–]?\s*(?P<title>.*)$",
+    re.MULTILINE | re.IGNORECASE,
+)
+FIELD = re.compile(
+    r"^\s*[-*]?\s*\*{0,2}(?P<key>[A-Za-z][A-Za-z ]+?)\*{0,2}\s*:\s*(?P<value>.+?)\s*$",
+    re.MULTILINE,
+)
+# Do not treat REQ-T100 as task T100: a hyphen glued to a letter is not a
+# task-id boundary. Still matches T1, T12, and "see T3".
+TASK_REF = re.compile(r"(?<![A-Za-z0-9-])T(\d{1,6})\b", re.IGNORECASE)
+PHASE_HEADING = re.compile(
+    r"^#{1,6}\s*Phase\s+(?P<number>\d+)\b", re.MULTILINE | re.IGNORECASE
+)
+REQUIREMENT_REF = re.compile(r"\b[A-Z][A-Z0-9]{1,9}-\d{2,4}\b")
+NONE_VALUES = {"-", "—", "–", "none", "n/a", "na", "nenhum", "nenhuma", "no"}
+
+REQUIRED_FIELDS = ("requirement", "files", "depends on", "tests", "gate", "done when")
+# Depends on: — remains valid (no deps). Files/Gate/Tests/Done when reject none/—.
+PLACEHOLDER_FIELDS = frozenset({"done when", "tests", "gate", "files"})
+VAGUE_TITLE_WORDS = {
+    "implement feature",
+    "create form",
+    "build ui",
+    "do backend",
+    "make it work",
+    "finish",
+    "misc",
+    "cleanup",
+    "refactor code",
+}
+
+
+def parse_fields(body: str) -> dict[str, str]:
+    fields: dict[str, str] = {}
+    for match in FIELD.finditer(body):
+        key = match.group("key").strip().lower()
+        value = match.group("value").strip()
+        fields.setdefault(key, value)
+    return fields
+
+
+def split_tasks(text: str) -> list[tuple[str, str, str]]:
+    matches = list(TASK_HEADING.finditer(text))
+    tasks: list[tuple[str, str, str]] = []
+
+    for index, match in enumerate(matches):
+        start = match.end()
+        end = matches[index + 1].start() if index + 1 < len(matches) else len(text)
+        tasks.append(
+            (match.group("id").upper(), match.group("title").strip(), text[start:end])
+        )
+
+    return tasks
+
+
+def task_phases(text: str) -> dict[str, int]:
+    """Map each task ID to the phase it sits under, or 0 when phases are unused."""
+
+    marks = [
+        (match.start(), int(match.group("number")))
+        for match in PHASE_HEADING.finditer(text)
+    ]
+
+    if not marks:
+        return {}
+
+    phases: dict[str, int] = {}
+
+    for match in TASK_HEADING.finditer(text):
+        current = 0
+        for position, number in marks:
+            if position < match.start():
+                current = number
+            else:
+                break
+        phases[match.group("id").upper()] = current
+
+    return phases
+
+
+def parse_dependencies(value: str) -> list[str]:
+    if not value or value.strip().lower() in NONE_VALUES:
+        return []
+    return [f"T{number}" for number in TASK_REF.findall(value)]
+
+
+def parse_files(value: str) -> list[str]:
+    if not value or value.strip().lower() in NONE_VALUES:
+        return []
+    files: list[str] = []
+    for chunk in re.split(r"[,;\n]", value):
+        path = normalize_file_path(chunk)
+        if path and path.lower() not in NONE_VALUES:
+            files.append(path)
+    return files
+
+
+def detect_cycle(graph: dict[str, list[str]]) -> list[str] | None:
+    """Iterative DFS so a long dependency chain cannot blow the call stack."""
+
+    visited: set[str] = set()
+
+    for root in graph:
+        if root in visited:
+            continue
+
+        path: list[str] = []
+        on_path: set[str] = set()
+        stack: list[tuple[str, bool]] = [(root, False)]
+
+        while stack:
+            node, expanded = stack.pop()
+
+            if expanded:
+                path.pop()
+                on_path.discard(node)
+                continue
+
+            if node in visited:
+                continue
+
+            if node in on_path:
+                return path[path.index(node):] + [node]
+
+            visited.add(node)
+            path.append(node)
+            on_path.add(node)
+            stack.append((node, True))
+
+            for neighbour in graph.get(node, []):
+                if neighbour in on_path:
+                    return path[path.index(neighbour):] + [neighbour]
+                if neighbour not in visited:
+                    stack.append((neighbour, False))
+
+    return None
+
+
+def reachable(graph: dict[str, list[str]], start: str, goal: str) -> bool:
+    if start == goal:
+        return True
+    seen = {start}
+    stack = [start]
+    while stack:
+        node = stack.pop()
+        for neighbour in graph.get(node, []):
+            if neighbour == goal:
+                return True
+            if neighbour not in seen:
+                seen.add(neighbour)
+                stack.append(neighbour)
+    return False
+
+
+def build_report(
+    target: str,
+    text: str,
+    *,
+    spec_text: str | None = None,
+    feature_dir: Path | None = None,
+) -> Report:
+    report = Report(gate=GATE, target=target)
+    visible = visible_markdown(text)
+    tasks = split_tasks(visible)
+
+    if not tasks:
+        report.error("no tasks found - use '### T1: Short imperative title'")
+        return report
+
+    report.ok(f"{len(tasks)} task(s) with well-formed IDs")
+
+    order: dict[str, int] = {}
+    graph: dict[str, list[str]] = {}
+    seen: set[str] = set()
+    covered_requirements: set[str] = set()
+    files_by_task: dict[str, list[str]] = {}
+
+    for position, (task_id, title, body) in enumerate(tasks):
+        if task_id in seen:
+            report.error(f"duplicate task ID: {task_id}")
+        seen.add(task_id)
+        order[task_id] = position
+
+        if not title:
+            report.error(f"{task_id}: heading has no title")
+        elif title.strip().lower() in VAGUE_TITLE_WORDS:
+            report.error(f"{task_id}: title is not atomic: '{title}'")
+        elif len(title.split()) < 3:
+            report.warn(f"{task_id}: title may be too coarse: '{title}'")
+
+        fields = parse_fields(body)
+
+        for required in REQUIRED_FIELDS:
+            value = fields.get(required, "")
+            missing = not value
+            if required in PLACEHOLDER_FIELDS and value.strip().lower() in NONE_VALUES:
+                missing = True
+            if required == "files" and value and not parse_files(value):
+                missing = True
+            if missing:
+                report.error(f"{task_id}: missing '{required.title()}' field")
+
+        requirement = fields.get("requirement", "")
+        if requirement and not REQUIREMENT_REF.search(requirement):
+            report.error(
+                f"{task_id}: Requirement '{requirement}' does not reference a spec ID"
+            )
+        covered_requirements.update(REQUIREMENT_REF.findall(requirement))
+
+        files_by_task[task_id] = parse_files(fields.get("files", ""))
+        graph[task_id] = parse_dependencies(fields.get("depends on", ""))
+
+    phases = task_phases(visible)
+    if phases:
+        report.ok(f"{len(set(phases.values()))} execution phase(s) detected")
+
+    for task_id, dependencies in graph.items():
+        for dependency in dependencies:
+            if dependency == task_id:
+                report.error(f"{task_id}: depends on itself")
+            elif dependency not in seen:
+                report.error(f"{task_id}: depends on unknown task {dependency}")
+            elif order[dependency] > order[task_id]:
+                report.error(
+                    f"{task_id}: forward dependency on {dependency} "
+                    "- reorder tasks so dependencies come first"
+                )
+            elif phases.get(dependency, 0) > phases.get(task_id, 0):
+                report.error(
+                    f"{task_id} (phase {phases.get(task_id, 0)}): depends on "
+                    f"{dependency} from phase {phases[dependency]} "
+                    "- a phase never depends on a later one"
+                )
+
+    cycle = detect_cycle(graph)
+    if cycle:
+        report.error(f"dependency cycle detected: {' -> '.join(cycle)}")
+    else:
+        report.ok("dependency graph is acyclic")
+
+    independent = [task_id for task_id, deps in graph.items() if not deps]
+    if len(independent) > 1:
+        report.ok(
+            f"{len(independent)} task(s) without dependencies - candidates for parallel work "
+            "(see task-graph-engineering.md)"
+        )
+
+    owners: dict[str, list[str]] = {}
+    for task_id, paths in files_by_task.items():
+        for path in paths:
+            owners.setdefault(path, []).append(task_id)
+
+    for path, writers in owners.items():
+        if len(writers) < 2:
+            continue
+        for index, left in enumerate(writers):
+            for right in writers[index + 1 :]:
+                if reachable(graph, left, right) or reachable(graph, right, left):
+                    continue
+                report.error(
+                    f"{left} and {right} both write '{path}' with no dependency "
+                    "between them - merge the tasks or make one depend on the other"
+                )
+
+    if spec_text is not None:
+        spec_requirements = requirement_ids(visible_markdown(spec_text))
+        if spec_requirements:
+            missing = [
+                requirement_id
+                for requirement_id in spec_requirements
+                if requirement_id not in covered_requirements
+            ]
+            if missing:
+                for requirement_id in missing:
+                    report.error(
+                        f"spec requirement {requirement_id} has no task "
+                        "- map it in a task Requirement field"
+                    )
+            else:
+                report.ok(
+                    f"all {len(spec_requirements)} spec requirement(s) covered by tasks"
+                )
+
+    placeholders = find_placeholders(text)
+    if placeholders:
+        for item in placeholders[:10]:
+            report.error(f"unresolved placeholder at {item}")
+    else:
+        report.ok("no unresolved placeholders")
+
+    if len(seen) >= 3 and feature_dir is not None:
+        graph_path = feature_dir / "task-graph.md"
+        if graph_path.is_file():
+            report.ok("task-graph.md present for 3+ task breakdown")
+        else:
+            report.error(
+                "3+ tasks require task-graph.md - draw the DAG before approval "
+                "(see task-graph-engineering.md)"
+            )
+
+    return report
+
+
+def _load_sibling_spec(tasks_path: Path) -> str | None:
+    spec_path = tasks_path.parent / "spec.md"
+    if spec_path.is_file():
+        return spec_path.read_text(encoding="utf-8")
+    return None
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Validate a feature tasks.md")
+    parser.add_argument(
+        "tasks",
+        nargs="?",
+        help="feature name, feature directory, or path to tasks.md",
+    )
+    parser.add_argument(
+        "--strict",
+        action="store_true",
+        help="treat warnings as blocking failures",
+    )
+    args = parser.parse_args(argv)
+
+    path, text = resolve_artifact(args.tasks, "tasks.md", GATE)
+    report = build_report(
+        str(path),
+        text,
+        spec_text=_load_sibling_spec(path),
+        feature_dir=path.parent,
+    )
+    return report.emit(strict=args.strict)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/agent-architecture.md

@@ -0,0 +1,221 @@
+---
+name: agent-architecture
+description: Spec-Driven Development hub for AI-assisted engineering. Progressive disclosure (~70% fewer skill tokens vs dumping the full kit). Adaptive phases with Python gates, independent verifier, discrimination sensor, evidence-or-zero, and .specs/ memory. Triggers on "specify feature", "design", "break into tasks", "implement", "verify", "quick fix", "resume work", "handoff".
+---
+
+# Agent Architecture (Hub)
+
+Spec-Driven Development (SDD) guardrails for AI-assisted software engineering.
+Replaces "Vibe Coding" with adaptive phases backed by persistent memory, sister skills, and gates enforced by code.
+
+**Token cost.** Load a working set, not the archive — see `references/context-limits.md`. Progressive phase loading is ~70% fewer skill tokens than dumping hub + all references + sister skills every turn; a Medium feature is typically ~80% cheaper in skill tokens than naive full reloads.
+
+This file is the contract and the map. Phase procedures live in `references/`; cross-cutting concerns live in sister skills.
+
+## Critical Rules (read before acting)
+
+**Reference files.** Phase procedures live in `references/` next to this file (`.cursor/skills/references/`, `.claude/skills/references/`). Read a reference **completely** before acting on it. Never act on a partial read. Load the working set per `references/context-limits.md` — one feature at a time, current phase only.
+
+**Gate scripts.** Structural gates live in `.specs/guardrails/scripts/` at the project root. Run them with `python3`; never assume a project-local `scripts/` directory belongs to Spec Guardrails.
+
+**Execution contract — non-negotiable, holds even if no reference file is open:**
+
+1. **Test-First Imperative** — Tests derive from the spec's acceptance criteria and assert spec-defined outcomes. They never mirror the implementation. No production code before spec and derived tests are approved.
+2. **Gate before done** — A task is complete only when the project harness (tests, linter, compiler) passes. The runner decides, never self-assessment.
+3. **One atomic commit per task** — Mark the task complete in `tasks.md` and include that update in the same commit. Never batch tasks; never weaken, skip, or delete tests to make them pass.
+4. **Author ≠ verifier** — After the last task, `/verify` runs with a fresh, clean context that never wrote the code. It is mandatory, not prompted.
+5. **Blast radius (git tiers)** — Approving a spec or tasks authorizes **Tier 0** local work only. Higher tiers need owner go-ahead.
+
+| Tier | Authorized by spec/tasks approval | Owner go-ahead required |
+| --- | --- | --- |
+| **0 — Local sandbox** | `feature-init`, feature folder, `git checkout -b feat/NNN-slug`, local commits (code + `.specs/`) | — |
+| **1 — Share** | — | `git push`, open/update PR for this feature |
+| **2 — External impact** | — | merge to default branch, deploy/release, force-push, production data or secrets |
+
+Quick tier skips dedicated feature branches — commit on the current branch. See `git-handoff.md` for phase triggers.
+
+## Deterministic Gates
+
+Structural gates run **before** owner review, so they cannot drift when the model forgets a step.
+
+| When | Command |
+| --- | --- |
+| Before `/specify` (Medium+) | `npx @luizsantiago/spec-guardrails feature-init "<description>"` (Tier 0) |
+| Optional project config | `init-config --preset node-ts` or `install --preset python` (see `preset list`) |
+| Before confirming a spec | `python3 .specs/guardrails/scripts/validate_spec.py [feature]` |
+| Before approving tasks | `python3 .specs/guardrails/scripts/analyze_artifacts.py [feature]` |
+| Before presenting tasks for approval | `python3 .specs/guardrails/scripts/validate_tasks.py [feature]` |
+| On each commit | `python3 .specs/guardrails/scripts/check_commit.py --message "<message>"` |
+| Before declaring a feature done | `python3 .specs/guardrails/scripts/validate_state.py [feature]` |
+| After Verify PASS | `npx @luizsantiago/spec-guardrails archive-feature [feature]` (Tier 0) |
+| Before a phase procedure (optional) | `npx @luizsantiago/spec-guardrails phase-context <phase>` |
+| After a FAIL verdict | `python3 .specs/guardrails/scripts/lessons.py add --source .specs/features/[feature]/validation.md` |
+
+Gates accept a feature name, a feature directory, or a path to the artifact. With no argument they auto-detect when the project has exactly one feature; with several they list candidates and exit 2. A spec is rejected unless every criterion uses `SHALL` or `MUST` and `## Assumptions` is present.
+
+A **non-zero exit means STOP** — fix the artifact, then re-run the gate. Never continue past a failing gate.
+
+**Degraded mode.** If Python 3 or shell execution is unavailable, say so once, then perform the same checks by reading the artifact against the reference checklist. Degraded mode never lowers the standard; it only changes who runs the check.
+
+## Phase Map
+
+```
+EXPLORE (optional) → SPECIFY → DISCUSS (conditional) → DESIGN (optional) → TASKS (optional) → ANALYZE → EXECUTE (loop) → VERIFY → ARCHIVE
+```
+
+| Phase | Required | Reference | Sister skill | Gate |
+| --- | --- | --- | --- | --- |
+| **Explore** | Optional | `references/explore.md` | — | — |
+| **Constitution** | Once per project | `references/constitution.md` | — | — |
+| **Specify** | Yes | `references/specify.md` | — | `validate_spec.py` |
+| **Discuss** | Conditional | `references/discuss.md` | — | — |
+| **Design** | No | `references/design.md` | — | — |
+| **Tasks** | No | `references/tasks.md` | `task-graph-engineering.md` | `validate_tasks.py` |
+| **Analyze** | Before task approval | `references/analyze.md` | — | `analyze_artifacts.py` |
+| **Execute** | Yes | `references/implement.md` | `engineering-standards.md` | `check_commit.py` |
+| **Verify** | Yes | `references/validate.md` | `security-review.md` | `validate_state.py` |
+| **Archive** | After Verify PASS | `references/archive.md` | `git-handoff.md` | `archive-feature` |
+| **Converge** | On drift | `references/converge.md` | — | `analyze_artifacts.py` |
+| **Handoff** | Yes | `references/memory.md` | `git-handoff.md` | — |
+| **Quick** | Alternative | `references/quick-mode.md` | — | `check_commit.py` |
+| **Context** | Always | `references/context-limits.md` | — | — |
+| **Sub-agents** | When batched | `references/sub-agents.md` | `task-graph-engineering.md` | — |
+| **Lessons** | On FAIL | `references/lessons.md` | — | `lessons.py` |
+
+Context is a load rule, not a pipeline phase. Read it when the session is long or the feature has more than a handful of tasks. Sub-agents is the Execute scaling protocol — offer only when the task graph needs more than one batch; see `references/sub-agents.md`. Lessons is a FAIL-path step, not a sequential phase — see `references/lessons.md`.
+
+## Conditional sister skills
+
+Not in the default phase-map cell. Load only on `/verify` after `validate.md` + `security-review.md`, and **at most one in context at a time**.
+
+| Skill | Load when | Skip when |
+| --- | --- | --- |
+| `appsec.md` | **Complex**, or auth / payments / PII / secrets / upload / SSRF / network trust boundary | Quick; Simple without those surfaces; copy/docs/styling |
+| `qa-strategy.md` | **Complex**, or multi-step user-facing flow, or owner asked for regression/QA | Quick; Simple one-file; evidence-or-zero alone is enough |
+
+**Sequence.** If both triggers fire: AppSec → write `## AppSec` → **drop** `appsec.md` from the working set → QA → write `## QA`. Never load both together. Neither section is enforced by `validate_state.py` (verifier judgment).
+
+## Complexity Router
+
+Complexity determines depth. Do not run every phase on every change.
+
+| Tier | Scope | Path |
+| --- | --- | --- |
+| **Quick** | ≤3 files, no design decisions, no new dependencies | `references/quick-mode.md` — describe, implement, verify, commit |
+| **Simple** | 2–5 files, localized change | Specify → Execute → Verify |
+| **Medium** | New feature, <10 tasks | Specify → Tasks → Execute → Verify |
+| **Complex** | New architecture, API surface, infra | Specify → Discuss → Design → Tasks → Execute → Verify |
+| **Parallel** | Splittable work, multiple agents | Above + `/task-graph` per `task-graph-engineering.md` |
+
+**Hub Medium vs gate Medium+.** Router tiers above choose phase depth (hub **Medium** = new feature, under 10 tasks). The completion gate’s **Medium+** is separate: `design.md` with content, **or** 4+ tasks, **or** 2+ phases — that is when a discrimination-sensor outcome is blocking. A hub-Medium feature with only three tasks can be below gate Medium+.
+
+**Rules**
+
+- **Specify and Verify are always required on the full pipeline** — you must know WHAT was asked and prove it was delivered. **Quick** is the exception: the express lane in `references/quick-mode.md` (describe → implement → verify → commit) with only `check_commit.py` as a structural gate.
+- **Design is skipped** when there are no architectural decisions and no new patterns.
+- **Tasks is skipped** when there are ≤3 obvious steps.
+- **Discuss is triggered inside Specify** when the feature touches persistence, external calls, auth, payments, concurrency, or state transitions, or when the owner's intent is ambiguous.
+- **Safety valve** — Even when Tasks is skipped, Execute starts by listing atomic steps inline. If that listing reveals more than 5 steps or real dependencies, STOP and create a formal `tasks.md`; the Tasks phase was skipped in error.
+
+When in doubt, start at **Medium** and drop phases only with owner approval.
+
+## Persistent Memory (`.specs/`)
+
+| Path | Purpose |
+| --- | --- |
+| `.specs/STATE.md` | Decision log (`AD-NNN`) and handoff snapshot |
+| `.specs/lessons.json` | Canonical lessons store, owned by `lessons.py` |
+| `.specs/LESSONS.md` | Generated playbook of confirmed lessons — read, never write |
+| `.specs/project/PROJECT.md` | Vision, stack, constraints (when the project defines them) |
+| `.specs/project/CONSTITUTION.md` | Governing principles (when Constitution ran) |
+| `.specs/project/ROADMAP.md` | Milestones and feature status |
+| `.specs/config.yaml` | Optional project context and per-phase rules |
+| `.specs/domains/[domain]/spec.md` | Long-lived domain truth after Archive |
+| `.specs/quick/NNN-slug/` | Quick-mode tasks and summaries |
+| `.specs/features/[feature]/spec.md` | Requirements (use `NNN-slug` from `feature-init`) |
+| `.specs/features/[feature]/context.md` | Owner decisions for gray areas (only when Discuss ran) |
+| `.specs/features/[feature]/design.md` | Architecture (Complex tier) |
+| `.specs/features/[feature]/tasks.md` | Atomic task breakdown |
+| `.specs/features/[feature]/task-graph.md` | Job DAG and parallel groups (when applicable) |
+| `.specs/features/[feature]/validation.md` | Independent verification report |
+| `.specs/guardrails/scripts/` | Deterministic gate scripts |
+
+**Create artifacts lazily.** Write a file only when its phase actually produces content. Never scaffold an empty `design.md`, `tasks.md`, or `context.md` — an empty file claims a phase ran when it did not. Absence is the correct state for a skipped phase.
+
+Read `STATE.md` at session start; update it at session end. See `references/memory.md` and `git-handoff.md`.
+
+## Loop Engineering & Harness
+
+- **Correction Loop** — If the project harness fails, fix and retest up to 3 times before escalating to the owner.
+- **Operational Harness** — Quality is enforced by test runners, linters, and compilers, never by AI self-declaration.
+- **Fix → re-verify** — Gaps found in Verify become fix tasks; the loop is bounded to 3 iterations before escalating.
+
+## Knowledge Verification Chain
+
+Follow in strict order when making any technical decision:
+
+1. **Codebase** — Conventions and patterns already in use
+2. **Project docs** — README, `docs/`, `.specs/STATE.md` decisions
+3. **MCP / Context** — Up-to-date library documentation via tools
+4. **Web search** — Official docs and community patterns
+5. **Uncertainty** — Say "I don't know" and flag it. Never invent APIs or behaviors.
+
+Never skip to step 5 while steps 1–4 are available. Fabrication cascades through design, tasks, and implementation.
+
+## Output Behavior
+
+- **Do the work; do not narrate the machinery.** Produce the artifact instead of announcing the phase.
+- **Match effort to the work.** Heavy reasoning for design and ambiguity; fast execution for mechanical tasks.
+- **Write artifacts in a plain, decided voice.** Lead with the verdict; cut filler and hedging.
+- **Artifacts in English** — code, tests, commits, and `.specs/` documents (see `engineering-standards.md`). Chat language is the owner's personal setting, not guardrails rule.
+
+## Model Selection
+
+- **Planning** (Specify, Discuss, Design, Tasks): high-reasoning models
+- **Execution loop**: fast, cost-effective models
+- **Verifier**: mid-to-high tier — it performs adversarial reasoning and designs mutants
+
+## Sister Skills
+
+| Skill | Layer |
+| --- | --- |
+| `task-graph-engineering.md` | Topology — task DAG, parallelism, diamond verify |
+| `engineering-standards.md` | Quality — secure coding, one writer per file, artifact language |
+| `security-review.md` | Verification — OWASP checklist for `/verify` |
+| `appsec.md` | Conditional AppSec — threat sketch; Complex / attack surface only |
+| `qa-strategy.md` | Conditional QA — smoke/regression; after AppSec if both apply |
+| `code-simplify.md` | Conditional simplify — after A–D on Medium+ or owner ask; no behavior change |
+| `ship-ready.md` | Conditional ship checklist — owner ask only; does not authorize push |
+| `git-handoff.md` | Persistence — git sync, STATE template, session handoff |
+
+Project rules: `.cursor/rules/engineering-baseline.mdc` (always applied in Cursor).
+
+## Optional companion: Full Stack Floor Map
+
+When [`@luizsantiago/fullstack-floor-map`](https://www.npmjs.com/package/@luizsantiago/fullstack-floor-map) is installed, **Execute** may load one **Lane** layer manual and at most one catalog specialist per turn; **`/verify` stays Guardrails-only** (no Lane manuals, no catalog). Floor Map **0.5.0 (planned)** adds **Desk** memory under `.specs/desks/` for specialist continuity and handoff — companion-owned, not Guardrails gates. Pairing contract: [Companion: Full Stack Floor Map](https://github.com/luizssantiago92/spec-guardrails/blob/main/docs/guide/Companion-fullstack-floor-map.md).
+
+## Commands
+
+| Command | Reference | Action |
+| --- | --- | --- |
+| `/explore` | `references/explore.md` | Think through ideas before Specify |
+| `/project-init` | `references/project-init.md` | Brownfield: map repo → PROJECT + domain stubs |
+| `/constitution` | `references/constitution.md` | Create project governing principles |
+| `/specify` | `references/specify.md` | `feature-init` then requirements; EARS; delta specs |
+| `/discuss` | `references/discuss.md` | Resolve gray areas into `context.md` |
+| `/plan` | `references/design.md` | Create technical design |
+| `/tasks` | `references/tasks.md` | Atomic breakdown; coverage matrix (authoring) |
+| `/analyze` | `references/analyze.md` | Cross-artifact consistency before task approval |
+| `/task-graph` | `task-graph-engineering.md` | Draw or revise the job DAG |
+| `/loop` | `references/implement.md` | Orchestrate Execute — `loop-plan`, parallel sub-agents, adequacy A–D |
+| `/verify` | `references/validate.md` | Independent validation; lean UAT; conditional AppSec/QA |
+| `/converge` | `references/converge.md` | Reassess drift; append remaining tasks |
+| `/archive` | `references/archive.md` | Fold verified feature into domain truth |
+| `/quick` | `references/quick-mode.md` | Express lane for ≤3-file changes (no feature branch) |
+| `/handoff` | `references/memory.md` | Update STATE, commit `.specs/` (Tier 0; no push) |
+| `/sync-spec` | `git-handoff.md` | Commit current feature artifacts only |
+| `/lessons` | `references/lessons.md` | Record or load grounded lessons |
+
+## Credits
+
+Lineage and inspiration (CC-BY / MIT notices): see the repository [Credits](https://github.com/luizssantiago92/spec-guardrails#credits) — TLC Spec-Driven, Addy Osmani agent-skills, graph-engineering.

package/skills/appsec.md

@@ -0,0 +1,83 @@
+# AppSec
+
+Lean application-security pass for **Complex** work or features with a real attack surface. Complements `security-review.md` (OWASP checklist on `/verify`) — it does **not** replace that checklist.
+
+**Judgment only.** `validate_state.py` does not require an `## AppSec` section. A skip with reason is valid. This skill does not make the product “secure”; it structures a short threat look and when to escalate to a human.
+
+## When to Use
+
+Load during `/verify` **after** the base Verify steps (`validate.md` + `security-review.md`) when **any** of:
+
+- Hub tier is **Complex**
+- Feature touches auth, sessions, tokens, payments, PII, secrets, file upload, SSRF/URL fetch, or a network trust boundary
+
+## When NOT to Use
+
+Do **not** load on Quick, Simple without the surfaces above, copy/docs, or pure styling. Record:
+
+`AppSec: skipped — no Complex tier and no auth/PII/payment/network surface`
+
+Never load this skill in the same working set as `qa-strategy.md`. If both triggers fire: finish AppSec, **drop** this file from context, then load QA.
+
+## Relationship to security-review
+
+| Concern | Where |
+| --- | --- |
+| OWASP checklist / lightweight path | `security-review.md` (always on Verify) |
+| Threat sketch, boundaries, escalate | **This skill** (conditional) |
+
+Do not paste the OWASP list here. Reuse the Security Review result; deepen only the boundary and abuse cases.
+
+## Procedure (about 15 minutes)
+
+### 1. Threat sketch
+
+Write briefly (in `validation.md` under `## AppSec`, or in `design.md` if Design already captured it):
+
+- **Assets** — what must stay confidential or integral (tokens, PII, money, admin actions)
+- **Actors** — anonymous, authenticated user, admin, external service
+- **Trust boundaries** — browser ↔ API, API ↔ DB, API ↔ third party
+- **Top 3 abuse cases** — concrete misuse (IDOR on resource X, token reuse, inject into field Y)
+
+### 2. Focus list (pass / fail / N/A + one-line note)
+
+Check only what the diff touches:
+
+| Focus | Ask |
+| --- | --- |
+| AuthZ / IDOR | Can user A reach user B’s resource by changing an id? |
+| Secrets | Credentials or keys only in env / secret store — not source, logs, or client storage? |
+| Injection / XSS | User input parameterized or escaped on the paths this feature added? |
+| Critical deps | New or bumped deps with known critical/high issues addressed or documented? |
+| PII in logs | New log/response paths avoid raw PII? |
+
+For checklist depth, return to `security-review.md`.
+
+### 3. Escalate (stop and ask the owner)
+
+Escalate instead of `Result: pass` when the feature introduces or materially changes:
+
+- Payment capture or money movement
+- Homegrown cryptography
+- New multi-tenant isolation
+- “We are not sure” on a trust boundary the owner must accept
+
+## Output shape
+
+```markdown
+## AppSec
+- Applied: yes | skipped — [reason]
+- Boundaries: [browser↔API / …]
+- Top risks: [1], [2], [3]
+- Focus: authZ … | secrets … | injection … | deps … | PII logs …
+- Result: pass | fail | escalate
+```
+
+`fail` or `escalate` → Gaps bullet + fix or owner decision before `Verdict: PASS` (verifier judgment; not a structural gate).
+
+## Related
+
+- `security-review.md` — OWASP Verify checklist
+- `references/validate.md` — Verify procedure; load AppSec then drop before QA
+- `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) — AppSec is non-guarantee / judgment