Materialization

Why materialization exists

A procedural DSL declares what the runtime harness must sustain. Declarations alone drift.

Agents optimistically report completion. Integration configs get edited by hand and desync from the DSL index. Gates exist in markdown but not in code. CI paths point at the wrong target_root.

The materialization layer closes the gap between DSL specification and verifiable runtime state through deterministic scripts and init flows.

Core principle: runtime state cannot depend only on probabilistic inference.

---

Materialization map

.sdlc/sdlc.yaml (DSL declaration)
        ↓
┌───────────────────────────────────────────────────┐
│  Materialization Layer                            │
│                                                   │
│  /sdlc:init          → bind workspace, generate   │
│                        integration manifests      │
│  /sdlc:config        → mutate integrations        │
│  /sdlc:doctor        → validate alignment         │
│  sdlc_gate_check.py  → enforce stage transitions  │
│  sdlc_workspace_rebind.py → retarget paths        │
│  integration-mutator.ts   → manifest generation   │
└───────────────────────────────────────────────────┘
        ↓
Verifiable runtime state (manifests, credentials, gates, CI paths)

---

Install → init → operational

Phase 1: Install (CLI, deterministic)

npx @jambu/ai-native-sdlc@latest install [--runtime cursor|claude|openclaw|hermes-agent]

Materializes:

• .sdlc/ templates — DSL skeleton, workflows, gate scripts, playbook schema
• {specialization_layer}/ — runtime adapter reference implementation
• scripts/ — git hooks

Does not materialize:

• Application code changes
• Integration manifests
• Credentials
• Stack-specific adapter rules

Result: status: uninitialized, empty integrations: index.

Phase 2: Init (agent, conversational)

/sdlc:init [intent]

Runs bootstrap-flow.yaml. The runtime:

1. Discovers repository structure (/sdlc:discovery)
2. Binds workspace.target_root and profile
3. Walks lifecycle slots — user selects providers per slot
4. Generates integration manifests via skills + integration mutator
5. Materializes stack-specific rules in the adapter
6. Wires CI templates if ci slot selected
7. Sets status: operational

After init, the project is integrated end-to-end: same workflow library, bound to this repository’s paths, integrations, and constraints.

Init on a Python monolith, a Turborepo, and an empty directory produces the same harness — different DSL specialization.

Phase 3: Mutate (post-init)

/sdlc:config swap work_items from plane to jira
/sdlc:config add observability posthog

Same mutator pipeline as init. Doctor re-validates after every mutation.

---

Doctor — alignment gate

/sdlc:doctor is the primary materialization validator. Check groups:

Group	Validates
DSL sync	sdlc.yaml declarations match filesystem
Integration credentials	secrets_required from active manifests present in local + CI
Hook registration	Git hooks installed in clone/worktree
Baseline tags	sdlc_baseline_tag consistent with HEAD
Gate declaration	gates: in DSL matches sdlc_gate_check.py
Directory indices	README inventory in every indexed directory

Doctor failure means the harness is misaligned — not that the agent needs better prompts.

---

Gate scripts — transition enforcement

sdlc_gate_check.py materializes DSL gate declarations into exit-code enforcement.

Before a stage or ticket transition:

python3 .sdlc/bin/sdlc_gate_check.py --stage execution --run-id {id}
python3 .sdlc/bin/sdlc_gate_check.py --ticket JAMBU-34 --run-id {id}

Checks manifest fields, filesystem artifacts, feature-flow success criteria, handoff quality. Exit code 1 blocks the transition unconditionally.

Gates declared in DSL. Gates enforced in code. Doctor validates sync. No gate exists only in prose.

See Gates.

---

Integration manifest generation

Integration manifests are generated artifacts, not shipped product:

Catalog template (npm package, read-only)
    ↓
Slot selection at init/config
    ↓
integration-mutator.ts
    ↓
.sdlc/integrations/{provider}/{provider}.yaml
    ↓
sdlc.yaml integrations: index entry
    ↓
Doctor credential validation

Each manifest owns secrets_required, API bindings, and slot annotation. Skills read manifests at runtime — workflows reference operations, not vendor names.

If Jira is declared but JIRA_API_TOKEN is missing, doctor reports it procedurally. The harness does not proceed as if the integration exists.

See Integrations.

---

Workspace rebind

When target_root changes:

python3 .sdlc/bin/sdlc_workspace_rebind.py --target packages/api --profile python-fastapi

Materializes path changes across:

• sdlc.yaml workspace block
• CI workflow working-directory fields
• Deploy integration bindings
• Architecture memory references

Blocked until doctor gate workspace:ci-target-aligned passes.

---

Capability provisioning

Materialization extends beyond config files. When the DSL or a workflow declares a capability requirement:

Capability declared (e.g., playwright QA, OpenAI realtime, Three.js)
    ↓
Runtime identifies required playbooks
    ↓
sdlc_playbook.py provision
    ↓
Agent receives procedural specification
    ↓
Environment validated (deps, API keys, MCP availability)

If OpenAI realtime is required but API key is absent, materialization surfaces the gap — the harness acts to restore operational integrity rather than proceeding with implicit assumptions.

---

SDLC baseline materialization

/sdlc:baseline captures harness evolution into a versioned git tag (sdlc_baseline_tag):

• .sdlc/ structural changes
• adapter infrastructure
• CI templates
• gate script updates
• new playbooks in harness catalog

Application feature code never enters the SDLC baseline. Baseline materialization is procedural versioning — reproducible harness state across teams and environments.

---

Operational consequences

Init is the materialization event. Before init, the harness exists as templates. After init, it exists as a bound operational system.

Doctor is continuous materialization audit. Not a one-time check — run after structural changes, integration swaps, baseline advances.

Gate failure is information. Blocked transitions indicate missing artifacts, not agent incompetence. Fix the state; do not override with prose.

Manual edits drift. Integration manifests, manifest YAML, and DSL should change through materialization paths — init, config, CLI — not ad-hoc file edits.