Governance Chain

The governance chain connects edikt's two systems — architecture governance & compliance and Agentic SDLC governance — into a single traceable path from intent to implementation to verification.

Two systems working together:

Architecture governance & compliance — ADRs, invariants, and guidelines are your current engineering decisions. They compile into four rendered surfaces under .claude/rules/: an always-loaded ambient core, per-topic files, a glob-keyed directive-index.yaml that drives write-time enforcement, and a manifest — see Compile for the full render model. edikt's writes are confined to co-located <artifact>.edikt.yaml sidecars and the compiled surfaces above. The prose .md you author is never touched by gov:compile — the boundary between human-owned and tool-owned bytes is structural, not definitional. See Sidecar Architecture.

Agentic SDLC governance — (Brainstorm) → (Discovery) → PRD → Spec → Artifacts → Plan → Execute → Drift. Brainstorm and discovery are optional, conditional entry points — an idea can go straight to a PRD. Each step feeds the next. Each is constrained by compiled decisions and produces new ones. PRDs and specs use the same split as ADRs and invariants: a narrative .md for humans plus a co-located .yaml sidecar that's the actual structured source of truth — FRs, ACs, coverage mappings, revision history. See Traceability below for what's really in each.

They connect at three points:

• Governance constrains the spec — existing ADRs and invariants inform the technical design
• Compiled directives are active during plan and execution — the model follows them automatically
• Drift verifies the implementation against governance — did we build what we decided?

The details of each mechanism have their own pages:

• Quality Gates — block on critical findings during plan and execution
• Compiled Directives — how ADRs become enforcement
• Drift Detection — the verification step
• Specialist Agents — specialist review at each phase
• Rule Packs — coding standards that fire automatically

The conversation that drives it

You don't type commands in sequence — you say what you need, and the model runs the right step.

The chain doesn't have to start at the PRD. When the idea itself isn't settled yet, two optional steps come before it — neither is mandatory, and they don't have to be used together.

"Let's brainstorm this"

The model opens a free-form, project-grounded conversation, pulling in specialist agents as relevant topics surface. When the conversation converges, you choose what it becomes: a PRD, a spec — brainstorm can formalize straight into either one — or just a saved brainstorm doc (BRAIN-NNN) to pick up later. Discovery is not a required stop in between.

"Run discovery on this" (fresh, or /edikt:sdlc:discovery BRAIN-003 to lift a saved brainstorm)

Use discovery when the idea has unknowns worth resolving before you commit to requirements — it's a peer command to brainstorm, not a wrapper around it, so it can start from scratch or lift a brainstorm's findings as a seed. It interviews you on what's known, what's uncertain, what would change your mind, and the smallest experiment that resolves the biggest unknown, then it always graduates into a PRD.

From here, the chain most people mean when they say "the governance chain":

"Write a PRD for Stripe webhook delivery with retry logic and idempotency"

The model generates structured requirements with acceptance criteria grounded in your project context. Review it, mark it accepted.

"Write a spec for PRD-005"

The model checks that PRD-005 is accepted, then routes to architect, scans your codebase and ADRs, and generates a technical specification. The spec references the PRD and any relevant ADRs.

"Generate spec artifacts for SPEC-005"

The model produces the implementable outputs: data model, API contracts, migrations, test strategy. Each artifact references the spec it came from.

"Create a plan for SPEC-005"

The model breaks the spec into phases, routes each to specialist agents for pre-flight review, and returns findings before any code is written.

What pre-flight and revision actually catch

Two things worth knowing before you get here. First: pre-flight criteria validation reads the spec's acceptance criteria literally, against your actual codebase — not against what sounds plausible. If SPEC-005 claims a duplicate webhook delivery returns 409 Conflict, but your error package has no such response and every other conflict in the API returns 422 Unprocessable Entity, pre-flight flags it before a plan phase inherits the wrong criterion.

Second: some gaps don't show up in review at all — they show up while writing the test. A retry scheduler can pass every code review and still have no protection against double-delivery if the worker crashes and restarts mid-retry. That's the kind of gap a "does the retry stop after N attempts" test won't catch, but a "does a mid-retry crash-restart still deliver exactly once" test will. When it does, the spec gets a new requirement, and the chain records why.

Then you execute. The model builds with enforced standards, the active plan phase injected on every prompt.

Each phase's completion triggers post-flight — a composite review, not a single check. L1 is the phase's own criteria-verify verdict. L2 asks whether the phase's diff violates any compiled ADR or invariant. L3 routes the same diff to the domain specialists the changed files call for (/edikt:sdlc:code-review, also invocable standalone anytime you want a second opinion). A synthesizer dedupes all three into one report before the phase can flip to done.

"Does the implementation match the spec?"

The model runs drift detection — comparing what got built against the PRD acceptance criteria, spec requirements, artifact contracts, and ADR compliance.

The full sequence, with the two optional entry points in parentheses:

(brainstorm) → (discovery) → PRD → spec → artifacts → plan → execute → drift detection

Command references: /edikt:brainstorm, /edikt:sdlc:discovery, /edikt:sdlc:prd, /edikt:sdlc:spec, /edikt:sdlc:artifacts, /edikt:sdlc:plan, /edikt:sdlc:post-flight, /edikt:sdlc:code-review, /edikt:sdlc:drift

State machine

Each step in the chain has a status. The chain enforces a strict progression: each artifact must be accepted before the next step can begin.

Step	Status values	Gate
PRD	draft → accepted	spec requires accepted PRD
Spec	draft → accepted	spec-artifacts requires accepted spec
Artifacts	draft → accepted (per artifact)	plan requires accepted artifacts
Plan phases	pending → in-progress → done (or blocked/stuck/skipped)	Execution proceeds phase by phase; post-flight gates each phase's done transition
Drift report	generated on demand	Closes the loop — accepted vs. built

Attempting to write a spec on a draft PRD produces a hard block:

BLOCKED  PRD-005 status is "draft".
         PRDs must be accepted before generating a spec.
         Review the PRD and change status to "accepted" first.

This isn't a suggestion. The gate exists because a draft PRD represents unresolved requirements — building a technical specification on top of unresolved requirements produces wasted work.

What gets captured at each step

PRD — functional requirements, non-functional requirements, acceptance criteria, open questions. The product intent, in structured form.

Spec — architecture approach, components, trade-offs, alternatives considered, references to ADRs and invariants. The engineering response to the PRD.

Artifacts — design blueprints generated from the spec. Format depends on database type:

• data-model.mmd (SQL), data-model.schema.yaml (MongoDB), or data-model.md (DynamoDB/KV) — entities, relationships, indexes
• contracts/api.yaml — OpenAPI 3.0 endpoint definitions, request/response shapes, error codes
• migrations/ — numbered SQL migration files with up/down/backfill/risk (SQL and mixed only)
• test-strategy.md — unit, integration, and edge case coverage
• contracts/events.yaml — AsyncAPI 2.6 event schemas, producers, consumers
• fixtures.yaml — portable seed data for dev and testing
• config-spec.md — environment variables, feature flags

Plan — phased execution with pre-flight specialist review. Each phase is reviewed by the domain agents before any code is written.

Post-flight report — composite of the phase's criteria-verify verdict (L1), a governance-diff check against compiled ADRs and invariants (L2), and specialist findings (L3), deduplicated by a synthesizer. Saved per phase to .edikt/state/post-flight/.

Drift report — comparison of implementation against spec, PRD acceptance criteria, artifact contracts, ADR decisions, and invariants. Saved to the spec folder.

Traceability

Every artifact in the chain carries references to what it came from — but the identity fields you see in a .md's frontmatter are only half the story. PRDs and specs each pair their narrative .md with a co-located .yaml sidecar, and the sidecar is where the actual traceability data — requirements, acceptance criteria, coverage mappings — lives. Same split as ADRs and invariants, applied to the SDLC side.

# spec.md frontmatter — identity and references only
type: spec
id: SPEC-005
source_prd: PRD-005
references:
  adrs: [ADR-001, ADR-003]
  invariants: [INV-001]
status: accepted

# spec.yaml — the sidecar, structured source of truth
source_prd_coverage:
  prd: PRD-005
  covered:
    - fr: FR-001
      by: [SR-001, SR-002]
  deferred: []
  uncovered: []
acceptance_criteria:
  - id: AC-001-1        # passed through from the PRD, byte-equal, never renumbered
    fr: FR-001
    given: "..."
    when: "..."
    then: "..."
  - id: SAC-001          # added by the spec itself — architectural-layer criteria
    source: spec

Every PRD FR-NNN must be covered by at least one spec SR-NNN, deferred with a stated reason, or explicitly listed as uncovered — nothing falls through silently. The spec's own SPEC-{NNN} folder holds spec.md + spec.yaml side by side; /edikt:sdlc:spec-review re-checks this coverage any time the spec is hand-edited after generation.

# artifact frontmatter — no separate sidecar; this is the whole record
type: artifact
artifact_type: data-model
spec: SPEC-005
status: draft
reviewed_by: dba

When drift detection runs, it follows these references backward through the chain — checking implementation against artifacts, artifacts against the spec's FR coverage, spec against PRD acceptance criteria.

Why this matters

Without the chain, the engineering cycle is scattered: requirements in Notion, decisions in Slack, specs in someone's head, verification by hope. The chain creates a single, version-controlled, machine-readable path from "what we decided to build" to "what we actually built."

The drift check closes the loop. It's not optional ceremony — it's the mechanism that makes the governance chain a governance chain rather than a documentation exercise.

Artifact lifecycle

Every artifact in the chain follows a status lifecycle:

draft → accepted → in-progress → implemented → superseded

Transition	Trigger	Who
draft → accepted	Change status: in frontmatter	Manual
accepted → in-progress	Plan starts a phase referencing this artifact	Auto
in-progress → implemented	Drift finds no violations	Auto
any → superseded	Create replacement artifact	Manual

Enforcement across commands:

• /edikt:sdlc:plan warns when artifacts are still draft — lists them by name and offers to proceed with Known Risks or stop
• /edikt:sdlc:drift skips draft and superseded artifacts, validates the rest
• /edikt:doctor flags artifacts stuck in draft for more than 7 days

When to use it

You don't have to use the full chain for every piece of work. For ad hoc tasks, edikt's rules and hooks govern the session without PRD or spec. The chain is for features where traceability matters — where you need to verify that implementation matches intent.

For new features, the chain is the right default. Describe what you want to build, let the model generate acceptance criteria, review and accept it, then proceed. If the feature itself isn't defined yet, start earlier — with a brainstorm to explore it, or a discovery doc if it has unknowns worth resolving before writing requirements.

See /edikt:brainstorm, /edikt:sdlc:discovery, /edikt:sdlc:prd, /edikt:sdlc:spec, /edikt:sdlc:artifacts, /edikt:sdlc:plan, /edikt:sdlc:drift.