# Sdd Guardrails

> Continuous validation running inside every stage to prevent errors early. 'Guardrails, not Gates'.

- Skill: `leoheart0125/sdd-guardrails` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add leoheart0125/sdd-guardrails`
- Raw SKILL.md: https://api.skillmd.com/api/skills/leoheart0125/sdd-guardrails/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: leoheart0125 (https://skillmd.com/u/leoheart0125)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/leoheart0125/sdd-guardrails

---


# SDD Guardrails

Unlike a traditional review engine that acts as a blocker at the end of a process, Guardrails run continuously *inside* other skills to provide immediate feedback. Every guardrail failure is a potential lesson.

## Core Responsibilities

1.  **Continuous Validation**: Validate artifacts (JSON, YAML, Code) as they are created.
2.  **Rule Compliance**: Enforce `project_rules.md` programmatically at every stage — design, plan, and implementation.
3.  **Drift Detection**: Compare Implementation vs. Specification.
4.  **Security Scans**: Detect basic security flaws in design/code.
5.  **Lesson Triggers**: Every guardrail fail → fix → pass cycle triggers `/sdd-learn`.

## Commands

-   `/sdd-guard-check <context>`: Run a specific set of checks for the given context (requirements | architecture | api | plan | code).
-   `/sdd-guard-drift`: Compare the current codebase against all spec artifacts that exist for the active feature.
-   `/sdd-guard-report`: Generate a summary of active violations.

## Check Types

### 1. Design Checks (Called by `sdd-design-engine`)
-   **Ambiguity Check**: "Are requirements specific enough?" (flag items with low `confidence_score`)
-   **Coverage Check**: "Do all Use Cases have a Component?"
-   **Contract Check**: "Do interface contracts match their corresponding design units and data models?"
-   **Rule Conflict Check**: "Do generated specs conflict with `project_rules.md`?" — If yes, raise as BLOCKING concern.

### 2. Plan Checks (Called by `sdd-task-planner`) — NEW
-   **Path Convention Check**: Verify each task's `target_path` conforms to the architecture conventions declared in `project_rules.md`.
    -   Read the Architecture section of `project_rules.md` to understand the declared directory structure and layer conventions
    -   Validate that all `target_path` values follow the declared convention
-   **Rule Compliance Check**: Ensure task descriptions align with project rules (naming conventions, testing requirements, etc.)
-   **Dependency Check**: Verify no circular dependencies in task graph

### 3. Implementation Checks (Called by `sdd-implementer`)
-   **Linting**: "Does code follow project style?"
-   **Spec Match**: "Does the implementation conform to the design specs produced for this feature?" — Validate against **whichever spec artifacts are present** (`object_design.json`, `openapi.yaml`, `data_model.json`, `interface_contract.json`). **Skip checks for artifacts that were not produced.**
-   **Test Coverage**: "Are tests generated for this task?"
-   **File Placement**: "Is the file at the `target_path` specified in `tasks.json`?"
-   **Rule Compliance**: "Does the generated code follow Coding Standards, Architecture patterns, and naming conventions declared in `project_rules.md`?" — If violations found, raise as failure and fix before proceeding.

### 4. Artifact Integrity Check (All Phases)
-   **JSON Validity**: All `.json` artifacts (task.json, lesson.json, pattern.json, concerns.json, etc.) MUST be valid JSON parseable by a standard JSON parser.
-   **String Escaping**: String values MUST properly escape: double quotes (`\"`), backslashes (`\\`), newlines (`\n`), tabs (`\t`), and other control characters.
-   **Pre-Write Validation**: Before writing any `.json` file, validate it is well-formed JSON. If validation fails, fix escaping issues before saving.
-   **Failure Protocol**: If a JSON artifact fails validation, treat it as a guardrail failure — fix immediately and record via `/sdd-learn`.

## Rule Compliance Engine

### How It Works

The Rule Compliance Engine is a **programmatic check**, not just a declaration. It runs at specific moments:

#### Timing
| When | Trigger | What is Checked |
|------|---------|-----------------|
| After requirements generated | `sdd-design-engine` calls `/sdd-guard-check requirements` | Spec conflicts with project_rules |
| After architecture generated | `sdd-design-engine` calls `/sdd-guard-check architecture` | Architecture style compliance |
| After tasks generated | `sdd-task-planner` calls `/sdd-guard-check plan` | `target_path` conventions |
| After code generated | `sdd-implementer` calls `/sdd-guard-check code` | File placement, naming, spec match |

#### Architecture Style Compliance

The guardrail check procedure:
1.  Read the Architecture section of `project_rules.md` to understand the declared conventions (directory structure, layer ordering, naming patterns).
2.  For each task in `tasks.json`, validate `target_path` against the declared conventions.
3.  For `architecture.json`, validate component grouping matches the declared style.

The source of truth for what constitutes a valid path is always `project_rules.md` — not any hardcoded assumption about architecture style. Different projects use different grouping strategies (feature-first, layer-first, module-based, etc.), and the guardrail must validate against what the project actually declared.

## Drift Detection Logic

When `/sdd-guard-drift` is called:
1.  Scan `.sdd/spec/<feature-id>/` for **all spec artifacts that exist** (e.g., `object_design.json`, `openapi.yaml`, `data_model.json`, `interface_contract.json`).
2.  Parse implemented code corresponding to the feature.
3.  For each spec artifact found, compare implementation against the spec:
    -   `object_design.json`: Design unit names, method signatures, properties, layer assignments, `kind` designations.
    -   `openapi.yaml`: Parameters (Name, Type, Required), Responses (Code, Schema).
    -   `data_model.json`: Entity fields, types, constraints, relationships vs data-layer implementations.
    -   `interface_contract.json`: CLI args, SDK surface, event schemas, component props/events, GraphQL types, etc.
    -   **Skip** any spec type that was not produced during design.
4.  If mismatch found → Report Drift → Recommend `/sdd-spec-update` or Implementation Fix.

## Lesson Trigger Protocol

**Every guardrail failure that gets fixed is a lesson.** When a check fails and is subsequently resolved:

1.  Record the violation and fix as a lesson via `/sdd-learn`:
    ```json
    {
        "trigger": "guard-check-<context>",
        "advice": "Implementation must exactly match the spec artifact. Do not add undeclared fields or deviate from contracts."
    }
    ```
2.  If the **same lesson triggers twice** across different features → propose promotion to `project_rules.md` via `/sdd-rule-update`.

## Integration

-   **Invoked by**: `sdd-design-engine` (pre-save), `sdd-task-planner` (post-generation), `sdd-implementer` (pre-complete).
-   **Consumes**: `project_rules.md`, `context.json`, Artifacts.
-   **Triggers**: `/sdd-learn` (on fix cycles), `/sdd-rule-update` (on repeated lessons).