@rsaglobaltech/specgate 0.8.1

package/templates/base/docs/specs/status-model.md.tpl

@@ -0,0 +1,16 @@
+# Status Model
+
+Use these statuses for requirements, scenarios, use cases, and traceability rows.
+
+| Status | Meaning |
+|---|---|
+| Draft | A first version exists. |
+| Needs Clarification | Ambiguities block implementation. |
+| Domain Reviewed | The domain model was reviewed. |
+| Architecture Reviewed | Technical solution and ADRs were reviewed. |
+| Ready for Dev | Implementation can start. |
+| In Dev | Implementation is in progress. |
+| In Review | Change is ready for review. |
+| Verified | Tests, contracts, or acceptance criteria pass. |
+| Released | Available to users or the target environment. |
+| Deprecated | Requirement or scenario was retired. |

package/templates/base/docs/specs/traceability.md.tpl

@@ -0,0 +1,7 @@
+# Traceability Matrix
+
+Map requirements to scenarios, domain model elements, implementation artifacts, and tests.
+
+| Requirement | Scenario ID | Feature file | Use Case | Command/Query | Aggregate | Event | Technical artifact | Test artifact | Status |
+|---|---|---|---|---|---|---|---|---|---|
+| REQ-000 | SCN-000 | `features/core/health.feature` | UC-000 Health baseline | QRY-000 HealthCheckQuery | - | - | `API /health`, smoke test | TBD | Draft |

package/templates/base/docs/specs/use-cases.md.tpl

@@ -0,0 +1,5 @@
+# Use Cases
+
+| ID | Use Case | Actor | Requirement | Command/Query | Aggregate | Emits | Status |
+|---|---|---|---|---|---|---|---|
+| UC-001 | Describe the first use case | Primary actor | REQ-TBD | CMD-001 ExampleCommand | AGG-001 CoreAggregate | EVT-001 ExampleEvent | Draft |

package/templates/base/spec.md.tpl

@@ -0,0 +1,63 @@
+# Spec: {{PROJECT_NAME}}
+
+## 1. Product context
+{{PROJECT_NAME}} operates in the **{{DOMAIN}}** domain and follows a Spec-Driven Development approach.
+
+## 2. Target users
+- Primary users:
+- Secondary users:
+- Internal stakeholders:
+
+## 3. Main objective
+Define functional requirements, domain language, and acceptance criteria clearly before writing implementation code.
+
+## 4. In scope
+- Core workflows for the first release.
+- Acceptance criteria for externally visible behavior.
+- Traceability from requirements to scenarios, domain model, implementation, and tests.
+
+## 5. Out of scope
+- Features that are not mapped to requirements or scenarios.
+- Infrastructure decisions that do not affect the initial implementation.
+- Premature workflow, microservice, CQRS, or Event Sourcing complexity.
+
+## 6. Success criteria
+- Every business feature has traceable Gherkin scenarios.
+- Every scenario maps to a requirement and a technical artifact.
+- Domain terminology is captured before implementation starts.
+- The team can reuse this structure in new projects.
+
+## 7. Initial bounded contexts
+- Core Domain: central business rules.
+- Supporting Domain: integrations and reporting.
+- Generic Domain: identity, auditing, and notifications.
+
+## 8. Key requirements
+
+<!--
+  Add requirements with `specgate req add "<what the requirement does>"`, which
+  writes the row here **and** in docs/specs/traceability.md at the same time.
+
+  Do not hand-write a row here alone. A requirement that exists in this file and
+  not in the matrix fails `specgate validate --strict-tdd` with [TDD-3], and the
+  table below is the one a generated project used to ship pre-filled with an
+  example — so every new project was born with a red gate (H20).
+-->
+
+| ID | Requirement | Priority | Status |
+|---|---|---|---|
+
+## 9. Non-functional requirements
+| ID | Requirement | Quality attribute | Status |
+|---|---|---|---|
+| NFR-001 | Define the first measurable non-functional requirement. | Reliability | Draft |
+
+## 10. Risks and open questions
+| ID | Topic | Impact | Owner | Status |
+|---|---|---|---|---|
+| RISK-001 | Capture the first domain, delivery, or architecture risk. | Medium | TBD | Draft |
+
+## 11. Domain language
+| Term | Meaning | Notes |
+|---|---|---|
+| Example term | Define the term using business language. | Replace with project language. |

package/templates/ci/azure.yml.tpl

@@ -0,0 +1,40 @@
+# Generated by `specgate ci init --provider azure`
+# Spec-Driven Development gate for Azure Pipelines.
+trigger:
+  branches:
+    include: [main]
+pr:
+  branches:
+    include: ['*']
+
+pool:
+  vmImage: ubuntu-latest
+
+steps:
+  - task: NodeTool@0
+    inputs:
+      versionSpec: '22.x'
+    displayName: Use Node.js 22
+
+  - script: npx @rsaglobaltech/specgate@{{SPECGATE_VERSION}} validate . --strict-tdd
+    displayName: Validate specs (strict TDD)
+
+  # Supply-chain gate: fails when rendered pack content no longer matches the
+  # digest pinned in .specops.lock. Skipped when no packs are installed.
+  - script: |
+      if [ -f .specops.lock ]; then
+        npx @rsaglobaltech/specgate@{{SPECGATE_VERSION}} validate . --against-lock
+      else
+        echo "No .specops.lock — no packs installed, nothing to check."
+      fi
+    displayName: Check pack drift
+
+  - script: npx @rsaglobaltech/specgate@{{SPECGATE_VERSION}} plan --project-dir . --format json > $(Build.ArtifactStagingDirectory)/spec-plan.json
+    condition: always()
+    displayName: Export pending-work plan
+
+  - task: PublishBuildArtifacts@1
+    condition: always()
+    inputs:
+      pathToPublish: $(Build.ArtifactStagingDirectory)/spec-plan.json
+      artifactName: spec-plan

package/templates/ci/github.yml.tpl

@@ -0,0 +1,40 @@
+# Generated by `specgate ci init --provider github`
+# Spec-Driven Development gate: no PR merges if a requirement loses its
+# feature file, its test artifact, or its traceability row.
+name: Spec gate
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  spec-gate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+      - name: Validate specs (strict TDD)
+        run: npx @rsaglobaltech/specgate@{{SPECGATE_VERSION}} validate . --strict-tdd
+      # Supply-chain gate: fails when the rendered pack content no longer
+      # matches the digest pinned in .specops.lock — a moved tag, a rewritten
+      # history, or a hand-edited generated file. Skipped when the project
+      # installs no packs.
+      - name: Check pack drift
+        run: |
+          if [ -f .specops.lock ]; then
+            npx @rsaglobaltech/specgate@{{SPECGATE_VERSION}} validate . --against-lock
+          else
+            echo "No .specops.lock — no packs installed, nothing to check."
+          fi
+      - name: Export pending-work plan
+        if: always()
+        run: npx @rsaglobaltech/specgate@{{SPECGATE_VERSION}} plan --project-dir . --format json > spec-plan.json
+      - name: Upload plan artifact
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: spec-plan
+          path: spec-plan.json

package/templates/ci/gitlab.yml.tpl

@@ -0,0 +1,21 @@
+# Generated by `specgate ci init --provider gitlab`
+# Spec-Driven Development gate for GitLab CI. If your project already has a
+# .gitlab-ci.yml, paste the `spec-gate` job into it instead.
+spec-gate:
+  image: node:22
+  stage: test
+  script:
+    - npx @rsaglobaltech/specgate@{{SPECGATE_VERSION}} validate . --strict-tdd
+    # Supply-chain gate: fails when rendered pack content no longer matches the
+    # digest pinned in .specops.lock. Skipped when no packs are installed.
+    - >
+      if [ -f .specops.lock ]; then
+        npx @rsaglobaltech/specgate@{{SPECGATE_VERSION}} validate . --against-lock;
+      else
+        echo "No .specops.lock — no packs installed, nothing to check.";
+      fi
+    - npx @rsaglobaltech/specgate@{{SPECGATE_VERSION}} plan --project-dir . --format json > spec-plan.json
+  artifacts:
+    when: always
+    paths:
+      - spec-plan.json

package/templates/ci/jenkins.tpl

@@ -0,0 +1,35 @@
+// Generated by `specgate ci init --provider jenkins`
+// Spec-Driven Development gate for Jenkins (declarative pipeline).
+// If your project already has a Jenkinsfile, paste the 'Spec gate' stage in.
+pipeline {
+    agent {
+        docker { image 'node:22' }
+    }
+    stages {
+        stage('Spec gate') {
+            steps {
+                sh 'npx @rsaglobaltech/specgate@{{SPECGATE_VERSION}} validate . --strict-tdd'
+            }
+        }
+        // Supply-chain gate: fails when rendered pack content no longer
+        // matches the digest pinned in .specops.lock. Skipped when the
+        // project installs no packs.
+        stage('Pack drift') {
+            steps {
+                sh '''
+                    if [ -f .specops.lock ]; then
+                        npx @rsaglobaltech/specgate@{{SPECGATE_VERSION}} validate . --against-lock
+                    else
+                        echo "No .specops.lock — no packs installed, nothing to check."
+                    fi
+                '''
+            }
+        }
+    }
+    post {
+        always {
+            sh 'npx @rsaglobaltech/specgate@{{SPECGATE_VERSION}} plan --project-dir . --format json > spec-plan.json || true'
+            archiveArtifacts artifacts: 'spec-plan.json', allowEmptyArchive: true
+        }
+    }
+}

package/templates/contracts/AI_RULES.md.tpl

@@ -0,0 +1,55 @@
+# AI_RULES.md — {{PROJECT_NAME}} Contract Layer
+
+> **Scope:** This file governs AI-assisted development in the `{{PROJECT_SLUG}}` contract layer.
+> All AI tools (Claude, Copilot, etc.) must follow these rules before generating or modifying any contract artefact.
+
+## 1. Contract-First Mandate
+
+Never write provider implementation code before the OpenAPI / AsyncAPI specification exists and is reviewed.
+Every endpoint and every event must have a corresponding entry in `contracts/openapi/` or `contracts/asyncapi/` **before** any code is generated for it.
+
+## 2. Consumer-Driven Test Coverage (TDD Rule 1)
+
+For every API contract (`AC-*` in `pack.yaml`), at least one Pact interaction must exist in `contracts/pacts/`.
+Do not mark a contract as `Verified` in the traceability matrix until the Pact test passes in CI.
+
+## 3. No Breaking Changes Without Versioning (TDD Rule 2)
+
+Before modifying any schema file:
+1. Check `breaking_change_rules` in `pack.yaml` for the relevant contract.
+2. If the change matches a breaking-change rule, bump the contract's major version and create a new schema file (`provider-v2.yaml`). Do **not** overwrite the existing version.
+3. Update `api_contracts[].schema_ref` to point to the new version.
+
+## 4. Traceability Gate (TDD Rule 3)
+
+Every contract entry (`AC-*`) must be traceable to a requirement (`REQ-*`) via `api_contracts[].requirement`.
+Do not add a contract without a corresponding requirement, and do not close a requirement without at least one associated contract or consumer-driven test.
+
+## 5. Status Promotion Rules (TDD Rule 4)
+
+A contract record in `docs/specs/contract-traceability.md` may only advance past `Ready for Dev` when:
+- The schema file referenced by `schema_ref` exists and validates against its format spec (OpenAPI 3.x / AsyncAPI 2.x).
+- At least one `CDT-*` entry links this contract's provider.
+- The corresponding Pact file exists on disk.
+
+Do not auto-promote status. Status changes must be explicit edits to the traceability document, committed with a message explaining the promotion reason.
+
+## 6. Test Artifact Must Not Be TBD (TDD Rule 5)
+
+In `docs/specs/contract-traceability.md`, the **Test Artifact** column must never contain `TBD` for a record whose **Status** is `In Dev` or later.
+If the test artifact is not yet known, keep the record at `Draft` or `Needs Clarification`.
+
+## 7. Schema Files Are Source of Truth
+
+- OpenAPI / AsyncAPI files in `contracts/` are the authoritative contract.
+- Generated client stubs, server stubs, and mock servers derive from these — never the reverse.
+- If a generated file conflicts with the schema, the schema wins. Update the schema deliberately, not the generated file.
+
+## References
+
+- Requirements: see `pack.yaml` → `requirements[]`
+- API Contracts: see `pack.yaml` → `api_contracts[]`
+- Consumer-Driven Tests: see `pack.yaml` → `consumer_driven_tests[]`
+- Breaking-Change Rules: see `pack.yaml` → `breaking_change_rules[]`
+- Traceability: `docs/specs/contract-traceability.md`
+- Test Strategy: `docs/specs/test-strategy.md`

package/templates/contracts/asyncapi-stub.yaml.tpl

@@ -0,0 +1,24 @@
+asyncapi: "2.6.0"
+info:
+  title: "{{PROVIDER_SERVICE}} Events"
+  version: "1.0.0"
+  description: |
+    AsyncAPI contract for events published by {{PROVIDER_SERVICE}}.
+    Generated by specgate from the contracts pack.
+channels:
+  {{PROJECT_SLUG}}/events:
+    subscribe:
+      summary: Domain events published by {{PROVIDER_SERVICE}}
+      message:
+        name: DomainEvent
+        payload:
+          type: object
+          properties:
+            eventId:
+              type: string
+              format: uuid
+            occurredAt:
+              type: string
+              format: date-time
+            eventType:
+              type: string

package/templates/contracts/contract-traceability.md.tpl

@@ -0,0 +1,10 @@
+# Contract Traceability Matrix — {{PROJECT_NAME}}
+
+| Requirement | Contract ID | Contract Title | Type | Test Artifact | Status |
+|---|---|---|---|---|---|
+| REQ-001 | AC-001 | {{PROVIDER_SERVICE}} REST API — v1 | REST | CDT-001 | Draft |
+| REQ-004 | AC-002 | {{PROVIDER_SERVICE}} Events — v1 | AsyncAPI | TBD | Draft |
+
+**Legend:**
+- `TBD` in Test Artifact = no Pact test exists yet (blocks promotion past `Ready for Dev`)
+- Status values follow the same lifecycle as the domain traceability matrix

package/templates/contracts/openapi-stub.yaml.tpl

@@ -0,0 +1,29 @@
+openapi: "3.1.0"
+info:
+  title: "{{PROVIDER_SERVICE}} API"
+  version: "1.0.0"
+  description: |
+    REST API contract for {{PROJECT_NAME}}.
+    Generated by specgate from the contracts pack.
+    Replace stub paths with real endpoint definitions.
+servers:
+  - url: "https://api.{{PROJECT_SLUG}}.example.com/v1"
+    description: Production
+  - url: "http://localhost:8080/v1"
+    description: Local development
+paths:
+  /health:
+    get:
+      operationId: getHealth
+      summary: Health check
+      responses:
+        "200":
+          description: Service is healthy
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  status:
+                    type: string
+                    example: ok

package/templates/contracts/test-strategy.md.tpl

@@ -0,0 +1,94 @@
+# Test Strategy — {{PROJECT_NAME}} Contract Layer
+
+**Project:** {{PROJECT_NAME}} (`{{PROJECT_SLUG}}`)
+**Provider:** {{PROVIDER_SERVICE}}
+**Consumer:** {{CONSUMER_SERVICE}}
+**Date:** <!-- filled in at expand time -->
+**Status:** Draft
+
+## Overview
+
+This document describes the contract-testing strategy for the `{{PROJECT_SLUG}}` project.
+It follows the **Consumer-Driven Contract Testing** (CDCT) pattern, where consumers publish their
+expected interactions (Pact files) and providers verify them in CI before any release.
+
+## Testing Pyramid
+
+```
+          ┌───────────────────┐
+          │   E2E / Integration│   ← minimal; catch wiring errors only
+          ├───────────────────┤
+          │  Contract Tests    │   ← primary gate; Pact consumer + provider
+          ├───────────────────┤
+          │    Schema Tests    │   ← validate OpenAPI / AsyncAPI files on every commit
+          ├───────────────────┤
+          │    Unit Tests      │   ← serialisation, mapping, validation logic
+          └───────────────────┘
+```
+
+## TDD Rules Enforced by `validate --strict-tdd`
+
+| Rule | Check | Gate |
+|------|-------|------|
+| **TDD-1** | Every `AC-*` has at least one `CDT-*` linking it | Pre-merge |
+| **TDD-2** | No `Test Artifact = TBD` when Status ≥ `In Dev` | Pre-merge |
+| **TDD-3** | Every requirement has a traceability row | Pre-merge |
+| **TDD-4** | No duplicate scenario/contract IDs | Pre-merge |
+| **TDD-5** | Breaking-change rules documented for every `AC-*` | Pre-merge |
+| **TDD-6** | Schema files referenced by `schema_ref` must exist on disk | Pre-merge |
+
+## Contract Test Workflow
+
+### Consumer side
+
+1. Write a failing Pact test describing the expected HTTP interaction.
+2. Run the Pact test — it generates `contracts/pacts/{{CONSUMER_SERVICE}}-{{PROVIDER_SERVICE}}.json`.
+3. Commit the Pact file alongside the consumer feature.
+4. Open a PR — CI runs `validate --strict-tdd` to confirm the Pact file is registered.
+
+### Provider side
+
+1. Pull the latest Pact file from the repository (or Pact Broker if configured).
+2. Run provider verification: `pact-provider-verifier` or the framework-native equivalent.
+3. Only after verification passes may the provider merge a change that touches a contracted endpoint.
+
+## Schema Validation
+
+OpenAPI files are validated on every CI run:
+
+```bash
+npx @redocly/cli lint contracts/openapi/provider-v1.yaml
+```
+
+AsyncAPI files:
+
+```bash
+npx @asyncapi/cli validate contracts/asyncapi/provider-events-v1.yaml
+```
+
+These commands run in the `contract-lint` CI step before any contract tests.
+
+## Breaking-Change Detection
+
+Before merging any change to a `contracts/` schema file:
+
+1. Run `oasdiff breaking contracts/openapi/provider-v1.yaml contracts/openapi/provider-v1-proposed.yaml`.
+2. If any breaking change is detected, increment the major version and update `pack.yaml`.
+3. Maintain the old version for consumers still pinned to it.
+
+## Coverage Requirements
+
+| Metric | Threshold |
+|--------|-----------|
+| Pact interactions per endpoint | ≥ 1 happy path + ≥ 1 error path |
+| Provider verification pass rate | 100% on main |
+| Schema lint errors | 0 on main |
+| Strict-TDD gate (`validate --strict-tdd`) | Must pass on every PR |
+
+## References
+
+- API Contracts: `pack.yaml` → `api_contracts[]`
+- Consumer-Driven Tests: `pack.yaml` → `consumer_driven_tests[]`
+- Breaking-Change Rules: `pack.yaml` → `breaking_change_rules[]`
+- AI Rules: `AI_RULES.md`
+- Traceability: `docs/specs/contract-traceability.md`

package/templates/frontend/AI_RULES.md.tpl

@@ -0,0 +1,34 @@
+# AI Rules - Frontend ({{PROJECT_NAME}})
+
+## Role
+You are the Lead Frontend Engineer and UX owner. Implement strictly from `spec.md` and `features/`.
+
+## Project Initialization & Stack
+- Project: {{PROJECT_NAME}} ({{PROJECT_SLUG}})
+- Domain: {{DOMAIN}}
+- Stack: {{STACK}}
+- Architecture: {{ARCHITECTURE}}
+- API integration: {{API_STYLE}}
+- Testing: {{TESTING}}
+
+## Stack Rules
+- Do not infer or replace the stack from preference or prior projects.
+- If any stack field is `TBD`, stop implementation and update `AI_RULES.md` or `spec.md` with the Product Owner first.
+
+## Non-Negotiables
+- Componentization and reusability by default.
+- Responsive behavior as acceptance criteria.
+- No implementation without a traceability entry.
+
+## Domain Modeling Rules
+{{ARCHITECTURE_MODELING_RULES}}
+
+## Pre-Implementation Gates
+{{ARCHITECTURE_GATES}}
+
+## Workflow
+1. Read `spec.md`.
+{{ARCHITECTURE_READS}}
+3. Read scenarios in `features/`.
+4. Update `docs/specs/traceability.md`.
+5. Build UI until acceptance criteria pass.

package/templates/frontend/features/core/health.feature.tpl

@@ -0,0 +1,6 @@
+Feature: Frontend baseline availability
+  @REQ-000 @SCN-000
+  Scenario: Main entry page is reachable
+    Given the web application is running
+    When I navigate to the "/" route
+    Then I should see the main application shell

package/templates/harness/harness.config.yaml.tpl

@@ -0,0 +1,74 @@
+# Generated by `specgate harness init`
+#
+# Per-project defaults for `specgate harness run`. Every key is optional, and any
+# CLI flag overrides what is written here.
+harness_version: 1
+
+# The agent invocation. `{prompt_file}` is replaced with the path to the
+# generated per-requirement prompt.
+#
+# Left commented out on purpose: which agent runs this is your choice and your
+# credentials, and a default committed here is a default somebody pays for by
+# accident. Pass it explicitly the first few times:
+#
+#   specgate harness run --req REQ-001 --agent "claude -p < {prompt_file}"
+#
+# Then uncomment the line you settled on.
+#
+# agent: "claude -p < {prompt_file}"
+# agent: "cursor-agent -p < {prompt_file}"
+# agent: "aider --yes --message-file {prompt_file}"
+
+# Or name a profile from .harness/profiles.yaml, so the team commits the
+# commands it uses and each environment picks one:
+#
+#   agent_profile: local-claude
+#
+#   # .harness/profiles.yaml
+#   profiles_version: 1
+#   profiles:
+#     local-claude:
+#       agent: "claude -p < {prompt_file}"
+#     ci:
+#       agent: "aider --yes --message-file {prompt_file}"
+#
+# An explicit `agent:` wins over a profile.
+
+# An *additional* gate, on top of the `validate --strict-tdd` the harness always
+# runs. Left commented out when no build file gave it away — an unset key is
+# safe, whereas a placeholder that exits 0 would be a gate that always passes.
+#
+# Three placeholders are substituted per requirement, so the gate can run the
+# scenario belonging to the requirement under test:
+#
+#   {req}           REQ-007
+#   {scenario}      SCN-007
+#   {feature_file}  features/billing/refund.feature
+#
+# Worth using. The gate runs before `specgate done`, so the requirement is still
+# Draft and `validate --strict-tdd` does not yet demand its test — without one
+# of these, a requirement can be marked Implemented with its scenario never run:
+#
+#   test_cmd: "npm run verify && npm run test:e2e -- {feature_file}"
+#
+# The harness runs each requirement in a fresh git worktree, which contains only
+# what git tracks — so there is no node_modules. Install first if your gate
+# needs one, or the agent will spend its attempt doing it:
+#
+#   test_cmd: "npm ci && npm run verify && npm run test:e2e -- {feature_file}"
+{{TEST_CMD_LINE}}
+
+# Retries per requirement, each one fed the previous failure. Past three, the
+# loop is usually stuck on something a human needs to read.
+max_attempts: 3
+
+# Universal directives — Role, Active Project Boundary, Execution Policy —
+# prepended to every per-requirement prompt. Use `prompt_prefix` for a
+# one-liner; the file form exists because the realistic version is multi-line.
+prompt_prefix_file: ./.harness/prompt-prefix.md
+
+# CI mode: push each green branch and open a PR, leaving review to a human.
+# The harness never merges.
+# push: true
+# remote: origin
+# pr_cmd: "gh pr create --head {branch} --title '{req} via harness' --fill"

package/templates/harness/prompt-prefix.md.tpl

@@ -0,0 +1,60 @@
+<!-- Generated by `specgate harness init`. Edit freely — this is
+     your project's voice, and the harness prepends it verbatim to every
+     per-requirement prompt. -->
+
+# Role
+
+You are a senior engineer implementing **one requirement** of {{PROJECT_NAME}}.
+
+The specification is not a suggestion. Every requirement already has a
+scenario, a use case and a place in the traceability matrix, written before
+any code existed. Your job is to satisfy the scenario, not to redesign the
+domain.
+
+# Active project boundary
+
+**Do not edit these.** They are the specification, and several are regenerated
+from a domain pack:
+
+- `features/**/*.feature` — the Gherkin scenarios. If a scenario looks wrong,
+  stop and say so in your final message. Editing a scenario so your code
+  passes is the one failure mode that makes this whole exercise worthless.
+- `docs/specs/**` — spec.md, the traceability matrix, domain model, use cases,
+  commands, events, aggregates, ADRs. `specgate done` updates the matrix; you do
+  not.
+- `AI_RULES.md`, `spec.md`, `.specops.lock`, `.specops/**`.
+
+**Do edit these:**
+
+- the implementation source tree.
+- the tests.
+- `features/step_definitions/**` and `features/support/**` — step definitions
+  are code, not specification. This is the one place inside `features/` you
+  own.
+
+# Execution policy
+
+1. Read the requirement and its scenario under `features/` before writing
+   anything.
+2. Write or extend the step definitions so the scenario fails **for the right
+   reason** — a missing implementation, not a typo in a step.
+3. Implement the smallest thing that makes it pass. Unit-test the pure parts:
+   the scenario proves the wiring, the unit tests pin the rules.
+4. Run the gate before declaring done:
+
+   ```bash
+   {{GATE_COMMAND}}
+   ```
+
+5. Do not invent requirements. If the scenario does not ask for it, it is not
+   in scope, however obviously useful it seems.
+
+# Definition of done
+
+- The scenario for this requirement passes.
+- The gate command above is green.
+- You have not touched `features/**/*.feature` or `docs/specs/**`.
+
+If you cannot meet the definition of done, say precisely which part failed and
+why. A clear report of a blocked requirement is worth more than a green run
+that skipped the scenario.