Operational Layer

The harness core

.sdlc/ is the runtime-neutral harness core — procedural DSL, workflow contracts, gate scripts, trace store, and materialization tooling.

It is not the agent runtime. It is not the application. It is the operational infrastructure that governs long-horizon cognitive execution: what stages exist, when transitions are permitted, where state lives, and how integrity is verified.

The runtime adapter ({specialization_layer}/) binds a specific agent environment to this harness. See Runtime Layer.

Everything structurally meaningful flows from .sdlc/sdlc.yaml — the operational source of truth.

---

Directory map

.sdlc/
├── sdlc.yaml              # DSL — authoritative operational contract
├── INDEX.md               # Navigational source of truth
├── handoffs/              # Session continuity
├── context/decisions/     # Architecture Decision Records
├── workflows/             # Stage contracts (runtime-neutral YAML)
├── integrations/          # Generated plug-in manifests (empty until init)
├── specs/                 # Feature specifications
├── runs/                  # E2E orchestration manifests
├── evidence/              # QA artifacts (gitignored, worktree-local)
├── playbooks/             # Domain procedures (lazy catalog)
├── bin/                   # Deterministic gate and orchestration scripts
├── templates/             # Spec, ticket, handoff, ADR templates
├── pipeline/              # Integration mutator
└── trace/                 # Cognitive trace event store

---

sdlc.yaml — the DSL

Workspace

workspace:
  target_root: .              # any path — your application root
  profile: auto               # detected or declared stack

Decouples SDLC from application layout (ADR-011). Gate scripts and CI read target_root via sdlc_dsl_bindings.py. The authoring repo uses app/ as a dogfooding convention — not a requirement.

Runtime

runtime:
  engine: cursor
  specialization_layer: .cursor/
  hooks: .cursor/hooks.json

Points to the active adapter. See Runtime Layer.

Gates

gates:
  integration: [integration-report, joint-e2e-pass]
  deploy: [ci-target-aligned, staging-smoke-or-url]
  post-deploy: [evidence-manifest, production-http-200]
  reflect: [reflect-report-pass]

Declared here, enforced in sdlc_gate_check.py, validated by doctor. See Gates.

Integrations index

integrations: {}    # empty after install; populated at init

After init, only selected providers appear. Each entry points to a generated manifest. See Integrations.

Constraints

constraints:
  worktrees_mandatory: true
  no_direct_commits_to_main: true
  plane_ticket_required: true    # means: work-items ticket required
  handoff_required_on_completion: true

Structural invariants. The ticket constraint applies to whichever provider occupies the work_items slot.

Workflows binding

workflows:
  feature:
    definition: .sdlc/workflows/feature-flow.yaml
    trigger: /implement-feature
    agents: [planner, implementer, reviewer, qa]

Links commands to YAML stage contracts. See Workflows.

---

INDEX.md

Bracket-notation navigational index. Scoped hydration on session start — not a playbook catalog.

Every new document registers here immediately. Playbook catalog lives in playbooks/PLAYBOOKS.md (lazy).

---

Workflows directory

Runtime-neutral YAML in .sdlc/workflows/. Registry and composition rules in Workflows and .sdlc/workflows/README.md.

---

Integrations directory

Generated at init — not shipped pre-filled. See Integrations.

---

Runtime scripts (bin/)

Script	Role
sdlc_gate_check.py	Stage/ticket transition gates
sdlc_e2e_manifest.py	Run manifest lifecycle
sdlc_playbook.py	Playbook catalog, resolve, provision, learn
sdlc_workspace_rebind.py	Retarget target_root
sdlc_protocol_guard.py	Orchestrator path allowlist
sdlc_dsl_bindings.py	Path resolution from DSL

Agents invoke these scripts. They do not reimplement gate logic in natural language.

---

Handoffs, runs, ADRs

Handoffs — .sdlc/handoffs/LATEST.md is session continuity. Stub handoffs fail mark-done gate.

Runs — .sdlc/runs/{run_id}/manifest.yaml tracks orchestrator state. Updates via sdlc_e2e_manifest.py CLI only.

ADRs — .sdlc/context/decisions/ records architectural reasoning. Indexed in memories and INDEX.

---

Operational consequences

DSL is the root. Workflows, gates, integration index, and constraints all derive from sdlc.yaml.

Integrations are projections. Empty integrations/ after install is valid.

bin/ is enforcement. Natural language cannot substitute for gate scripts.

Operational layer survives runtime swap. Adapter change does not touch .sdlc/workflows/ or gate scripts.