agent-sdd 1.0.3

package/rules/spec-driven-development.md

@@ -0,0 +1,69 @@
+# Spec-Driven Development
+
+Spec is the single source of truth for code generation. Change the spec first, then generate code. Behavior in code that is not in the spec is either lifted into the spec or removed; never legitimized silently.
+
+## Atomic unit: typed normative ID
+
+Every normative statement is an ID-element with one of these templates:
+`Behavior`, `Invariant`, `Contract`, `Scenario`, `NFR`, `Constraint`, `Policy`, `Migration`, `Delta`, `GeneratedArtifact`, `ExternalDependency`, `LocalizationContract`, `Surface`, `Partition`, `ImplementationBinding`, `Open-Q`, `ASSUMPTION`.
+
+- IDs are semantically neutral and partition-scoped: `<partition>:<neutral>` (e.g. `billing:REQ-017`). Numbers are never reused.
+- Each field is typed: `enum | scalar_with_unit | range_with_unit | schema_dsl | predicate_dsl | reference | bounded_free_text_with_review`.
+- Required fields take a typed value or explicit `not_applicable + reason`. Empty = invalid.
+- Predicates must be checkable from observable inputs/outputs/state. `Invariant` may use `evidence ∈ {public_api, test_probe, db_constraint, operational_signal}` + `stability ∈ {contractual, internal}` — only `public_api` and `contractual` operational signals are external contract.
+
+## What spec MUST fix
+External behavior · `Surface`/`Contract` boundaries · `Invariant` · external identifiers (API fields, events, CLI, public DB columns, error codes, message_ids) · `ExternalDependency` (third-party providers) · `Policy` (authz/tenant/PII/audit/rate-limit) · `Migration` (data at-rest) · `applicability` (feature_flag, tenant, locale, env, plan_tier, api_version) · `concurrency_model` on boundaries.
+
+## What spec MUST NOT fix
+Internal file/module/class/function names · library/framework choice (unless a `Constraint` with external rationale) · directory layout · internal layering not observable from outside · estimates, schedules, owners.
+
+The agent decides everything not normatively fixed. The agent MUST list its internal decisions in the PR as candidates for new `REQ`/`Constraint`/`Policy`/`ASSUMPTION`.
+
+## Lifecycle and approval
+
+- `lifecycle.status ∈ {draft, proposed, approved, deprecated, removed}` — for every normative template.
+- `draft` — sandbox only (`spike/`). `proposed` — spec-valid, not mergeable. `approved` — implementable. `deprecated` — has `sunset_version` + `replacement_id`. `removed` — has `compatibility_action ∈ {reject, ignore, migrate, no_longer_guaranteed}`.
+- `approval_record` (owner_role, approver_identity, timestamp, change_request) is required for `approved`/`deprecated`/`removed`. **Self-approval by the code-gen agent is forbidden** — also for downgrading `ASSUMPTION` `blocking → advisory`.
+- Approving a Surface requires every referenced normative ID to be `≥ approved` already.
+- Approval is a two-step process. Step 1 records a `pending_approval_record` in a plan-namespace artefact (no change to `lifecycle.status`); step 2 validates the resulting reference graph and atomically materialises `lifecycle.status=approved` plus an ID-level `approval_record`. Between steps the invariant «`approved` ⇒ graph-consistent» is preserved by construction. Self-approval ban applies to step 1 (the attestation), not just to step 2. See `rules/enforcement_registry.md#ENF-002`.
+- `Surface` is the unit of semver. Bumping `Policy` or `Invariant(stability=contractual)` cascades to every referencing Surface: content change ⇒ ≥minor; predicate change ⇒ major.
+
+## Three gates (per partition)
+
+1. **`baseline-valid`** — `Discovery scope` is covered by `coverage_evidence`; `freshness_token` matches input sources. Each `Delta`/`Migration` pins to a `baseline_version`. Stale baseline blocks only the move into `implementation-valid`, not authoring of new `Delta`/`Open-Q`. `baseline_refresh` MUST emit `diff(old, new)` and auto-open `Delta`-stub or `Open-Q` for any change crossing a normative ID footprint.
+2. **`spec-valid`** — structure, Template Requiredness Matrix, field types, no weasel words in normative sections, two-way `ID ↔ Test obligation`, semver per Surface, `approval_record` present, no self-approval, no unresolved `Open-Q.blocking=yes`.
+3. **`implementation-valid`** — every `Test obligation` materialized as ≥1 executable test with `@covers <partition>:<id>`; all `approved` IDs green; `removed` IDs have tests for their `compatibility_action`; agent's internal decisions listed in PR. **Signal, not proof** — for major-bump `Surface`, human review of the test (oracle/assertion summary, input classes, negative oracle) is required.
+
+## Brownfield rules
+
+- `Brownfield baseline` is non-normative until a `REQ`/`Invariant`/`Contract` references it as preserved.
+- Anything outside `Discovery scope` is `unmodeled` — never silently deleted, renamed or rewritten. Expanding scope requires recon.
+- Every behavior change → `Delta` (with `kind`, `compatibility_action`, `tests_old_behavior`, `tests_new_behavior`, `baseline_version`).
+- Data-at-rest changes → `Migration`. Two orthogonal axes: spec-lifecycle `{draft..removed}` (governance) and runtime-state `{pre_cutover, in_progress, cutover_done, rolled_back}` (operational evidence). Cross-partition migrations use `partition_slice[]` + `coordinator_id`, not joint approval.
+- `Invariant`/`Contract` with `data_scope=post_migration:<MIG-ID>` MUST carry `enforcement_stage` pointing to a **deterministic test-controllable marker in the repo** (feature flag, completion sentinel, `cutover_marker`) — never a live deployment signal. CI runs pre/during/post tests by toggling the marker.
+- `implementation-valid` only checks tests applicable to the current Migration runtime-state.
+- Iterative debt budget: each partition tracks `unmodeled` / legitimate-debt that shrinks per PR/sprint. "Bring as-is to target in one PR" is not required.
+
+## Stop conditions (agent MUST raise `Open-Q`, not guess)
+
+Term not in `Glossary` · behavior outside `Discovery scope` · code↔spec contradiction without `Delta` · weasel word in a normative section · removal without `compatibility_action` · missing `Policy`-ref on a boundary · missing `applicability` when an axis variable is detectable · missing `concurrency_model` on a boundary · missing `data_scope` on persistent state · provider-owned behavior without `ExternalDependency` · generated output without `GeneratedArtifact` · text-as-contract without `LocalizationContract` · missing `baseline_version` on `Delta`/`Migration` · `proposed → approved` Surface while a referenced Policy/Contract is not yet approved · `Migration` runtime-state change without updating dependent `enforcement_stage` · structural-breaking diff in `GeneratedArtifact(published_surface=yes)` without major bump.
+
+Stop conditions split by enforcement class: `agent-halt` (reflex on a closed condition — term not in `Glossary`, code↔spec contradiction without `Delta`, removal without `compatibility_action`, missing `Policy`-ref / `applicability` / `concurrency_model` / `data_scope` / `baseline_version` on declared boundaries) and `agent-judgment` (semantic classification — provider-owned → `ExternalDependency`, generated output → `GeneratedArtifact`, text-as-contract → `LocalizationContract`). The split is normative for the PR-report shape: `agent-halt` produces a list of raised `Open-Q`s with trigger references; `agent-judgment` produces a list of classification decisions with rationale. Full mapping in `rules/enforcement_registry.md` rows ENF-005, ENF-006, ENF-023..ENF-034.
+
+## Forbidden in normative sections
+Canonical list lives at `skills/spec-driven-development/data/weasel-words.json`. Two classes: `absolute` (blocked in any normative section) and `modal_in_normative` (`may be`, `might be` — blocked only in template fields marked `is_normative=true`; allowed in `Context`, `Glossary`, comments, and in `Scenario`-prose where the alternative is captured by an explicit `options[]`/branching). See `rules/enforcement_registry.md#ENF-001`. Conditional fields take a value from a closed enum; `not_applicable` requires `reason`.
+
+## PR report (every change)
+- Closed `Test obligation`s and the tests that close them (with oracle/assertion summary, input classes, negative oracle for major-bump).
+- Internal decisions taken (names, structure, libraries) — candidates for new `Constraint`/`Policy`/`ASSUMPTION`.
+- `ASSUMPTION`s used and their `review_by`.
+- Remaining `Open-Q`s and why they don't block this PR.
+- Reduction of `unmodeled` / legitimate-debt budget vs previous PR.
+
+## Agent flow on existing code
+1. Read-only recon → `Discovery scope` + `Brownfield baseline` + `coverage_evidence`. No `Delta`/`Migration` until `baseline-valid`.
+2. Author target → `Surface`/`Contract`/`Policy`/`Constraint`/`Delta`/`Migration` against the baseline.
+3. Make tests fail (red) per `Test obligation` before implementing.
+4. Implement; only modify what the spec authorizes.
+5. Self-review against this rule and `review.md` before presenting.

package/rules/tdd-sdd.md

@@ -0,0 +1,127 @@
+# TDD — SDD Addendum
+
+Extends `@rules/tdd.md` for projects that carry `.sdd/config.json`.
+The Red→Green→Refactor cycle still holds, but the **source of the Red test**
+and the **definition of done** are anchored to the spec.
+
+## Where Red comes from
+
+Red tests are not invented from intuition. Each Red test closes a
+`Test obligation` declared on a normative ID (`Behavior` / `Invariant` /
+`Contract` / `Migration` / `Delta`). One ID may declare several obligations
+(happy path, boundary, negative) — each is its own Red test, written one at
+a time.
+
+If you can't trace a test to a `Test obligation`, the test doesn't belong.
+Either raise an `Open-Q` to extend the spec, or skip the test. Tests that
+don't trace to a normative ID become candidates for new
+`Constraint` / `Policy` / `ASSUMPTION` — raise them, don't smuggle them in
+as silent green-keepers.
+
+## The full SDD-TDD chain
+
+For every change:
+
+1. **Spec** — author / amend the relevant ID(s) and their `Test obligation`s.
+2. **Spec-lint** — `sdd lint` exit 0 (gate `spec-valid`).
+3. **Red** — for each open `Test obligation`, write one failing test
+   carrying `@covers <partition>:<id>`. Test fails on assertion, not on a
+   missing import. One Red at a time.
+4. **Green** — minimum code to turn the current Red green. Only what the
+   spec authorizes — no behavior outside an approved ID.
+5. **Refactor** — structure only, tests stay green, observable behavior
+   on `approved` IDs unchanged.
+6. **Implementation-valid** — `sdd ready` exit 0
+   (gate `implementation-valid`). Coverage holes surface here.
+
+Skipping any step (writing code before Red, committing on `sdd ready`
+exit 1, etc.) violates the SDD invariant "spec is the source of truth".
+See `@sdd/sdd-cli-usage.md` for command-by-command gate mapping.
+
+## `@covers` markers
+
+Every Red test that closes a `Test obligation` must carry
+`@covers <partition>:<id>` (in a comment, or the language-equivalent
+location `sdd ready` reads in this project). Missing markers surface as
+`[uncovered]` even if the test exists and passes.
+
+If a `Test obligation` is `not_applicable`, the spec must carry an explicit
+`not_applicable + reason`. No `@covers` and no Red test in that case — do
+not fabricate a trivial test to silence the gate
+(see `@rules/tdd.md` → Anti-patterns: TDD theatre).
+
+## Migration runtime-state
+
+`Migration` carries two orthogonal axes — spec-lifecycle (`draft..removed`)
+governs `sdd lint`; `runtime_state ∈ {pre_cutover, in_progress,
+cutover_done, rolled_back}` governs which tests are applicable.
+
+Tests for `Invariant` / `Contract` with `data_scope = post_migration:<MIG-ID>`
+must be wired to the `enforcement_stage` marker (feature flag, completion
+sentinel, `cutover_marker`) so CI can deterministically toggle pre / during
+/ post. Live deployment signals as the marker are forbidden
+(see `@sdd/spec-driven-development.md` → Brownfield rules).
+
+`sdd ready` only checks tests applicable to the current `runtime_state`.
+A pre-cutover test that's red after `runtime_state=cutover_done` is not a
+gate failure — it's an obsolete test. Re-scope via spec or delete as part
+of cutover.
+
+## Removed IDs — replace, don't drop
+
+When an ID transitions to `removed`, do not silently delete its tests.
+Replace each test with one that verifies the declared `compatibility_action`:
+
+- `reject` → old input now produces the typed error.
+- `ignore` → old input is accepted but produces no effect.
+- `migrate` → old input is transformed per spec.
+- `no_longer_guaranteed` → test removed; document the gap in PR
+  (ENF-007B).
+
+Removing a test without replacing it is a coverage drop and `sdd ready`
+will flag it.
+
+## Major-bump Surface
+
+For a Surface with a major bump (predicate change on `Policy` or
+`Invariant(stability=contractual)`) the Red test alone is signal, not
+proof. `implementation-valid` passes mechanically, but ENF-004B requires
+human review of:
+
+- input classes the test covers,
+- negative oracle (what must NOT pass),
+- assertion summary.
+
+When the agent writes a major-bump Red, name these three explicitly in the
+test docstring or PR description. The reviewer needs them to validate
+oracle quality.
+
+## Halt mid-Red
+
+While writing a Red test, halt and raise `Open-Q` if you hit:
+
+- a term not in `Glossary`,
+- behavior outside `Discovery scope`,
+- code↔spec contradiction without a `Delta`,
+- missing `Policy` ref, `applicability`, `concurrency_model`, or
+  `data_scope` on a boundary the test exercises,
+- missing `baseline_version` on the `Delta` / `Migration` you're closing.
+
+Do not improvise the test to "make progress". Full stop-condition list:
+`@sdd/spec-driven-development.md` → Stop conditions.
+
+## Refactor under SDD
+
+Refactor must keep tests green **and** preserve every observable behavior
+declared on `approved` IDs:
+
+- Internal renaming, extraction, dedup → fine.
+- Updating an `ImplementationBinding` target (file / class / function) →
+  fine, as long as the binding is updated in lockstep.
+- Renaming a public `Surface` field, changing a `Contract` shape, altering
+  an `Invariant` predicate → **not refactor**. That's a `Delta` —
+  stop, edit spec, re-lint, re-Red.
+
+If you discover a missing `Test obligation` mid-refactor, finish the
+refactor commit, then go back to Spec → Red. Don't extend the obligation
+list inside a refactor commit (see `@rules/commits.md` → Granularity).

package/rules/workflow-sdd.md

@@ -0,0 +1,56 @@
+# Workflow — SDD Addendum
+
+Extends `@rules/workflow.md` for projects that use Spec-Driven Development.
+When the project carries `.sdd/config.json`, the steps below are mandatory
+and override the trivial-task exception in `@rules/workflow.md`.
+
+## Specification-First Development
+If the project has a specification (e.g. `/spec` folder):
+1. **Read spec first** — before any code changes, review the relevant spec files
+2. **Update spec** — make all changes in the specification first
+3. **Lint spec** — `sdd lint` MUST exit 0 before proceeding (see `sdd-cli-usage.md`)
+4. **Get approval** — confirm spec changes with the user before touching code; for `proposed → approved` use `sdd approve` (attestation) + `sdd finalize` (atomic flip)
+5. **Implement** — write code that matches the updated specification
+6. **Ready check** — `sdd ready` MUST exit 0 before proposing commit
+- Code MUST stay in sync with the spec at all times
+- Never change code without a corresponding spec update
+- Never bypass `sdd ready` exit 1 to land a commit
+
+### Preflight before any Edit/Write to code
+Before the first `Edit`/`Write`/`MultiEdit` on a non-spec file in a session,
+explicitly verify:
+1. Does this project have a specification directory (`/spec` or equivalent)?
+2. If yes — name the exact spec file(s) that govern the change and confirm
+   they are already updated and approved for this task. If they are not,
+   STOP and go back to step Spec.
+3. State both answers in chat before the tool call. Silent skipping is the
+   failure mode this rule exists to prevent.
+
+This preflight applies even in Auto mode and even on tasks that look trivial.
+Spec-presence overrides the "trivial task" exception in `@rules/workflow.md`.
+
+## SDD-augmented Development Workflow
+The numbered steps from `@rules/workflow.md` are extended as follows when
+the project has a specification:
+
+1. **Understand** — read the task, explore relevant code
+2. **Clarify** — ask questions if requirements are ambiguous
+3. **Spec** — update the specification first (see above)
+3a. **Spec-lint** — run `sdd lint`; do not proceed until exit 0 (only when project carries `.sdd/config.json`)
+4. **Implement** — write code following the conventions above
+5. **Review** — self-review changes against CLAUDE.md rules before presenting
+5a. **Ready** — run `sdd ready`; do not commit until exit 0 (only when project carries `.sdd/config.json`)
+6. **Commit** — create a commit only when user approves
+7. **Push** — push only when user explicitly asks
+
+Pause-for-approval rule is widened: pause between **Spec → Implement** and
+between **Review → Commit** (instead of just the second).
+
+## sdd-cli integration
+
+The `sdd` CLI is part of the SDD workflow when the project carries
+`.sdd/config.json` and a `BrownfieldBaseline` block. Operational rules,
+phase-to-command mapping, and troubleshooting are in
+`@sdd/sdd-cli-usage.md`. The lint reminder is wired via
+`sdd/hooks/sdd-lint-reminder.sh` (PreToolUse on Edit/Write/MultiEdit for
+spec files).

package/schema/sdd.config.schema.json

@@ -0,0 +1,104 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/cyberash-dev/sdd-cli/blob/main/schema/sdd.config.schema.json",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["spec_file", "baseline_id", "discovery_scope", "mechanism"],
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "spec_file": {
+      "type": "string",
+      "minLength": 1
+    },
+    "baseline_id": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*(:[a-z][a-z0-9-]*)*:[A-Z]+-[0-9]+$"
+    },
+    "discovery_scope": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "footprint": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "binding_id_prefix": {
+          "type": "string",
+          "default": "IMP-"
+        },
+        "binding_field": {
+          "type": "string",
+          "default": "binding"
+        }
+      }
+    },
+    "mechanism": {
+      "type": "string",
+      "enum": ["git_tree_hash_v1"]
+    },
+    "lint": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "spec_files": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "approver_blocklist": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "partition_glob": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
+    "partitions": {
+      "type": "object",
+      "patternProperties": {
+        "^[a-z][a-z0-9-]*(:[a-z][a-z0-9-]*)*$": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["spec_paths"],
+          "properties": {
+            "spec_paths": {
+              "type": "array",
+              "minItems": 1,
+              "items": { "type": "string", "minLength": 1 }
+            },
+            "test_paths": {
+              "type": "array",
+              "items": { "type": "string", "minLength": 1 }
+            },
+            "sandbox_paths": {
+              "type": "array",
+              "items": { "type": "string", "minLength": 1 }
+            }
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "test_paths": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "sandbox_paths": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "plans_dir": {
+      "type": "string",
+      "minLength": 1,
+      "default": ".sdd/plans"
+    }
+  }
+}