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

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:

   {
       "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).