Sdd Orchestrator

SDD Orchestrator — Specification-Driven Development Workflow Engine

Overview

You orchestrate the SDD lifecycle across 8 document layers using the framework's per-layer weighted review crews — the closed lens set defined in framework/governance/REVIEW_CREWS.yaml (one crew of ~5-6 weighted lenses per layer), each lens injected with its per-(layer, lens) playbook from framework/playbooks/<NN>_<LAYER>/ (LAYER-PLAYBOOKS-001, framework/governance/REVIEW_TEAM.md §Playbooks). Unlike the legacy UCX system that concatenated all persona texts into a single prompt, you dispatch each crew lens as a parallel subagent for concurrent review, then reduce their per-lens scores to a weighted-average readiness score (see "Chairperson Scoring" below).

Mandatory Governance Load (Before Any SDD Work)

Before creating, reviewing, or remediating ANY SDD document, load the governance protocol:

skill_view(name='sdd-orchestrator', file_path='references/governance-load-protocol.md')

This single file condenses the planning-first rules from GOVERANCE_RULES.md §2b/§3, DEFINITION_OF_DONE.md plan/IPLAN review level, and DEVELOPMENT_WORKFLOW_GUIDE.md §2. Skip this load step = governance violation.

If the protocol file is missing or stale (after a UCX framework sync), fall back to loading the three governance docs individually via:

skill_view(name='sdd-orchestrator', file_path='governance/GOVERNANCE_RULES.md')
skill_view(name='sdd-orchestrator', file_path='governance/DEFINITION_OF_DONE.md')
skill_view(name='sdd-orchestrator', file_path='governance/DEVELOPMENT_WORKFLOW_GUIDE.md')

These docs contain the planning-first gates (§3), Definition of Done for plan/IPLAN review level, the single-path layer model (§7 — no depth tiers; necessary-upstream contract), plan types and storage rules (§2b), and the full agent operating model.

Governance docs are read directly from the repository (framework/ tree); per D-0013 (aidoc-flow migration), there is no local sync — re-stale-checks are not needed.

SDD Layer Sequence

BRD (L1) → PRD (L2) → EARS (L3) → BDD (L4) → ADR (L5) → SPEC (L6) → TDD (L7) → IPLAN (L8) → Code

Layer Descriptions

What Was Cut from v2

Review Crews (authority: framework/governance/REVIEW_CREWS.yaml)

The review model is not a flat pool of personas dispatched uniformly. Each layer has one weighted crew — a closed set of ~5-6 lenses whose weights sum to 100 and drive the weighted-average readiness score. framework/governance/REVIEW_CREWS.yaml is the single source of truth for every crew's author lens, review lenses, and weights; read it at dispatch time rather than relying on any copy. Lens names there (architect, business_analyst, auditor, chaos_engineer, security_engineer, tech_lead, qa_lead, operator, integration_lead, requirements_specialist, product_owner, synthesizer, …) are the runtime identity — dispatch a subagent per lens.

One illustrative crew (BRD review), showing the shape — see REVIEW_CREWS.yaml for the other eight (PRD, EARS, BDD, ADR, SPEC, TDD, IPLAN, CHG):

BRD:
  author: business_analyst
  review: {architect: 30, business_analyst: 30, auditor: 20, chaos_engineer: 12, security_engineer: 8}

Each dispatched lens is injected with its per-(layer, lens) playbook from framework/playbooks/<NN>_<LAYER>/<lens>.md (LAYER-PLAYBOOKS-001, REVIEW_TEAM.md §Playbooks). Do not maintain a second copy of the weights here — that drifts from the authority.

Hermes Agent as SDD Strategy Execution Runtime

When the SDD pipeline defines an autonomous strategy (trading agent, monitoring system, etc.), Hermes Agent can serve as the runtime orchestrator instead of building a custom execution engine. This replaces the traditional IPLAN→Code execution path with Hermes-native scheduling, MCP integration, and skill-based rule execution.

Pattern documented in: references/hermes-agent-sdd-runtime-pattern.md

Key integration points:

• cronjob: Schedule check windows at precise times (market hours, daily scans)
• skills: Load SDD documents as decision rules — soft updates via skill patches
• MCP servers: Register broker/external system MCP servers as Hermes tools
• memory: Persist state across sessions (positions, account data, idempotency keys)
• gateway: Multi-platform operator alerts (Telegram, Discord, etc.)

Cost comparison: ~1 developer-week + $5-10/month (LLM inference) vs 4-6 developer-weeks + $200/month for custom orchestrator.

See ADR-21 for a complete implementation example (TradeGent CC).

NO SDD DOCUMENT MAY BE CREATED, REVIEWED, OR REMEDIATED WITHOUT A WRITTEN AND APPROVED PLAN.

Before any document creation (Phase 1), the following planning package MUST exist and be explicitly approved by the human:

Required Planning Artifacts

1. Planning Roadmap — plans/ROADMAP.md or governance/plans/ROADMAP.md listing all intended SDD layers and their dependencies
2. Planning Index — governance/plans/README.md or .hermes/plans/README.md listing required plan documents
3. Changelog Plan — Document tracking expected changes per layer
4. IPLAN or Development Plan — governance/plans/PLAN-NNN_{slug}.md (preferred) or .hermes/plans/YYYY-MM-DD_HHMMSS-{slug}.md per the plan skill

Planning Gate Checklist (Execute Before Phase 1)

• Planning roadmap exists for project scope
• Planning index lists required plan artifacts
• Changelog plan exists for issue scope
• Planning gap review completed (resolved or deferred with rationale)
• IPLAN or development plan exists and is explicitly approved by human
• Human has explicitly approved proceeding to document creation

If any checklist item is missing: STOP. Do not proceed to Phase 1. Create the missing artifact or ask the human for direction.

For a deeper, 10-category audit covering changelog plans, gap reviews, index registration, dependency completeness, roadmap timing, ADR topic coverage, scope boundaries, section outlines, CHG governance, and validation pre-checks, see references/plan-gap-review-checklist.md.

BRD-to-Source Coverage Audit (For BRD Layer Initialization)

When initializing a project's BRD layer from a large source document (rulebook, strategy doc, etc.):

1. Extract all section headers from the source document — use grep -n '^# ' for markdown, or equivalent for the format
2. Build a coverage matrix: each source section → proposed BRD assignment + rationale
3. Identify gaps: unassigned sections, vague assignments ("folded into BRD-X" without explicit rationale), content blocks between section boundaries not captured by any header
4. Verify 100% coverage — every source unit must have an explicit BRD home or a deliberate exclusion with rationale
5. Check for orphan content — sections with no natural BRD home may indicate missing BRDs in the architecture

This audit must complete and be approved before any BRD extraction begins. The output is a table in the planning roadmap showing source section → BRD mapping with line spans.

UCX Governance Compliance

This phase implements the UCX DEVELOPMENT_WORKFLOW_GUIDE.md §2 "Planning-First Requirement":

Before implementation starts, complete this sequence: create planning roadmap → create planning index → define changelog plan → run planning gap review → create and approve IPLAN.

Reference: governance/templates/PROJECT_KICKOFF_PLAN-TEMPLATE.md for project-level planning structure.

Batch ADR Generation from BDD

For the complete ADR generation pipeline across 19 documents (9 engine + 10 cross-cutting), see references/adr-generation-from-bdd.md. This reference captures:

• Pre-generation checklist (hash fixes, validation verification)
• Subagent timeout workaround (pre-extract upstream data, direct write_file, retry-on-timeout pattern)
• UCX sdd_validate template interference bug and workaround (moving 3 template files to /tmp)
• Benchmark-first strategy (ADR-01 + ADR-07 first, then batch engine ADRs, then cross-cutting)
• Cross-cutting ADR topics (Event Bus, Auth, Calendar, Idempotency, Regulatory/WORM, Observability, Alerting, Backpressure, Input Validation, Encryption)
• BDD deferred findings → ADR coverage matrix
• ADR numbering convention (ADR-01-09 = engines, ADR-10-19 = cross-cutting)

Broker Backend Integration Architecture (Two-Layer MCP Pattern)

For the complete broker backend integration architecture — Internal API + per-broker MCP servers with Interactive Brokers — see references/broker-mcp-architecture-pattern.md. This reference captures the reusable pattern for any broker API integration project: two-layer separation, MCP protocol selection, connection lifecycle, idempotency strategy, and cross-cutting ADR dependencies (ADR-10/13/17/18/19). Also covers the full SDD pipeline (BRD-10→PRD-10→EARS-10→BDD-10→ADR-20) with scenario counts and document references.

Cross-Document Registration Sweep (Layer Completion)

When a full pipeline (BRD→PRD→EARS→BDD→ADR) is completed for a document number NN, run a registration sweep across ALL index files:

1. plans/README.md — update plan status + add new rows in SDD Document Artifacts table for each layer
2. 01_BRD/BRD-00_index.md — add to document registry table
3. 02_PRD/PRD-00_index.md — add row after template row (format: | [PRD-NN](./PRD-NN.yaml) \| Title \| Status \| Related BRD \| Features \| Priority \| Date |)
4. 03_EARS/EARS-00_index.md — add row after template row
5. 04_BDD/BDD-00_index.md — add row after template row
6. 05_ADR/ADR-00_index.md — add row to architecture index table
7. CHANGELOG.md — add pipeline entry under [Unreleased] with all layer versions and scores
8. plans/BRD-PLANNING-ROADMAP.md — update status to COMPLETE
9. Each layer document: update downstream_expected to reference the actual downstream document IDs (e.g., "see PRD-10", "see EARS-10")
10. ADR cross-cutting: verify the new ADR references all relevant cross-cutting ADRs (idempotency, rate limiting, validation, secrets, event bus)

sdd_validate UCX Template Interference (ADR Layer)

The UCX validator discovers template files across the entire project tree AND framework directories. Templates containing id: ADR-NN (or _id: ADR-NN) collide with the parse stream and cause spurious validation failures even when the actual document is structurally valid.

Files that must be temporarily moved (4 locations):

• Project: UCX/templates/layers/05_ADR/ADR-TEMPLATE.yaml
• Framework: framework/layers/05_ADR/ADR-TEMPLATE.yaml
• MCP: ucx_hermes/templates/ADR-TEMPLATE.yaml AND mcp_ucx/templates/ADR-TEMPLATE.yaml
• Legacy: ai_dev_ssd_flow_v2/05_ADR/ADR-TEMPLATE.yaml

Workaround: Move all 4+ files to /tmp, validate, check score, restore. The document will show 1 error ("Missing canonical layer template") — this is a false positive. The actual document has 0 cross-section errors and 0 warnings.

Do NOT patch _id: ADR-NN to _id: ADR-00 — the validator still discovers framework-level templates that cannot be patched (read-only framework directories).

Restore immediately after validation — sdd_init regenerates any missing templates.

Inline ADR Review (No Executor Required)

When UCX sdd_review executors are unavailable (no API keys, auth failures) or the 48KB review prompt would time out subagent dispatch, run the 5-persona review inline in the main agent context by reading ADR sections and applying persona criteria directly.

See references/adr-review-inline-pattern.md for the full pattern, review template structure, metadata update conventions, and common P1 finding categories.

Subagent Timeout Recovery (Large Document Generation)

When subagent generation times out at 600s on large documents (>50KB output expected):

• Pre-extract upstream data into the subagent prompt (don't make subagent read 6 files)
• Retry solo on timeout — check file mtime; if advanced, subagent wrote before timing out
• Fall back: build YAML via execute_code and write_file directly
• ADR-04 needed 5 dispatch attempts; ADR-09 needed direct write_file after 3 timeouts

delegate_task Parameter Format

delegate_task has two modes. Do NOT mix them — the function rejects hybrid calls:

• Batch mode: delegate_task(tasks=[{context, goal, role, toolsets}, ...]) — passes a JSON array
• Single mode: delegate_task(context=..., goal=..., role=..., toolsets=[...]) — passes individual fields

Error symptom: "Provide either 'goal' (single task) or 'tasks' (batch)." This fires when you pass both tasks (array) AND individual task parameters in the same call. Fix: pick one mode and use it consistently. Batch mode is preferred for parallel dispatch. Single mode for targeted remediation.

Batch PRD Generation from BRDs

After all BRDs are validated and reviewed, generate PRDs for each BRD.

Quality Gate (from TradeGent CC 2026-05-07 Review)

5/5 persona reviewers independently rejected "lightweight" PRDs as unbuildable stubs. A feature PRD with one generic core capability (e.g., "Product delivers [feature] as specified in BRD-XX" with acceptance criterion "All BRD acceptance criteria met — target 100%") IS NOT A VALID PRD. It is a placeholder shell. The EARS layer 3 cannot formalize requirements from stubs. The entire SDD pipeline stalls.

Correct pattern: Decompose EVERY BRD functional requirement into a PRD core capability with:

• Hash-level BRD references: @brd: BRD.NN.07.xxxx (not document-level @brd: BRD-NN)
• Populated diagram_contract with containers + data_flows (not empty {})
• User journeys with alt/else error branches
• Feature-specific error messages with actionable guidance
• adr_topic_elaboration in traceability section
• 3-7 capabilities per feature PRD, 3-5 user stories, 370-450 lines

The umbrella PRD remains full-detail (500+ lines). Feature PRDs follow the same pattern at ~400 lines each.

For the complete batch generation script, see references/batch-prd-generation-from-brds.md.

Batch Pipeline Execution — Single Feature Branch (BRD→BDD)

When a single new feature BRD needs to be carried through all downstream layers in one session with inline review at each layer, use the sequence in references/batch-pipeline-execution.md. Covers per-layer persona assignments, common fix types, metadata update patterns, and cross-layer consistency checks.

EARS Generation from PRDs (Layer 3)

After all PRDs are validated, reviewed, and remediated, generate EARS documents.

EARS Syntax Enforcement (Critical — from TradeGent CC 2026-05-07)

PROHIBITED QUALIFIERS (replace with quantified targets): "real-time" → "WITHIN 60 seconds" | "immediate/immediately" → "WITHIN N seconds" "continuously" → "at each [event]" | "fast/quickly" → "p50 < Nms, p95 < Nms" "near X" → "within 0.0Y of X"

STRUCTURAL RULES:

1. No compound WHEN with AND — split into atomic requirements
2. No nested IF inside SHALL — each conditional path is a separate requirement
3. WITHIN must reference a specific event (not orphaned "WITHIN 5 minutes")
4. IF/WITHIN must reference the same event
5. No subjective criteria ("acceptable", "reasonable", "significant")
6. Atomicity: one testable concept per requirement
7. Quantify interval ranges (not "every 15-25 min")

STATE MACHINE: every EARS touching operational modes MUST include a state_machine section with AUTONOMOUS → WARNING → HALTED → MANUAL → RECONCILING states and full transition triggers.

For the complete EARS rules, state machine template, and batch generation script, see references/ears-generation-pattern.md.

Benchmarks-First Strategy

1. Generate 2 benchmark EARS from the strongest upstream sources (umbrella + core feature)
2. Validate both with sdd_validate
3. Review with the EARS crew (per REVIEW_CREWS.yaml): requirements_specialist (35), tech_lead (25), qa_lead (20), chaos_engineer (12), security_engineer (8)
4. Remediate findings
5. Once validated, batch-generate remaining 7 EARS with execute_code

Batch BDD Generation from EARS (Layer 4)

After all EARS are validated and reviewed, generate BDD acceptance scenarios with the same benchmarks-first strategy documented below. The full generation pattern — including the Python build_bdd() function, safe YAML serialization with comparison-operator quoting, and validation workflow — lives in references/batch-bdd-generation-from-ears.md. For the post-generation review, remediation, and deferral rules (5-persona parallel review, chairperson scoring, ADR-blocked deferrals), see references/bdd-batch-review-remediation.md. For the post-generation review, remediation, and deferral rules (5-persona parallel review, chairperson scoring, ADR-blocked deferrals), see references/bdd-batch-review-remediation.md.

After BDD layer completion (all docs health >= 8), plan the ADR layer before generation. references/adr-layer-planning-and-gap-review.md covers: topic inventory (BDD deferred findings + PRD adr_topics + BRD constraints), engine vs cross-cutting categorization, coverage matrix construction, gap review methodology, pre-generation checklist, and anti-patterns.

BDD Scenario Mapping Rules

Every BDD document must translate EARS requirements into executable Given-When-Then scenarios:

• Event-driven EARS → success scenarios: extract WHEN from statement as Given/When, THE-SHALL as Then
• State-driven EARS → success scenarios: WHILE condition as Given, monitoring cycle as When, behavioral outcome as Then
• Unwanted-behavior EARS → error scenarios: IF condition as Given, detection as When, escalation/logging as Then
• Ubiquitous EARS → dedicated success scenarios: verify completeness across all decision types (queryable, immutable, structured)
• At least 1 recovery scenario per BDD (state transition restoration, post-failure reconciliation, transient retry)
• Minimum 5 scenarios per BDD: 3-4 success, 1-2 error, 1 recovery
• Benchmark BDDs (umbrella + core engine) should reach 13-19 scenarios after review/remediation

Pragmatic Remediation Scope (What Belongs Where)

Not every finding from a persona review belongs at the BDD layer. Apply this triage:

Concrete ADR-deferral catalog (TradeGent CC batch proven):

The general rule: if a scenario requires mocking an external service, time-travel harness, or multi-system coordination to test, it likely belongs at SPEC (interface contracts) or TDD (integration test definitions), not BDD (user-facing acceptance criteria).

Batch Delegate Concurrency

The delegate_task function enforces max_concurrent_children (default 3). When dispatching 5-persona BDD reviews, split into two calls: first call dispatches 3 subagents, second call dispatches 2. Both calls run in parallel since they're separate delegate_task invocations. Total wall-clock time equals the slower batch, not the sum.

# Correct — two parallel delegate_task calls, 3+2 split
delegate_task(tasks=[qa-lead, technical-lead, chaos-engineer])  # batch 1
delegate_task(tasks=[sre, security-auditor])                    # batch 2

UCX Template Discovery for PRD Creation

The UCX sdd_create_build tool discovers available templates in the project tree:

# Try layer-specific template first
sdd_create_build(doc_type="prd", layer="02_PRD", template="02_PRD-TEMPLATE.yaml")
# Fall back to generic
sdd_create_build(doc_type="prd", layer="02_PRD", template="PRD-TEMPLATE.yaml")

If templates are not found, run sdd_init(project_path) to scaffold the project with template files. After init, re-run sdd_create_build to confirm template discovery.

Pre-flight checklist before PRD generation:

1. sdd_preflight(context="create") — confirms project state and next action
2. sdd_create_build — confirms template availability
3. If either fails, run sdd_init then retry
4. Generate plan in plans/PLAN-NNN_prd-generation.md and get human approval

PRD Diagram Section Placement

The UCX validator checks for diagrams.items at the top level of the PRD document, NOT nested under functional_requirements or other sections.

# WRONG — validator sees this as missing
diagram_contract:
  diagrams:
    items: [...]

# RIGHT — top-level diagrams section
diagrams:
  id: "PRD.01.diagrams.a1b2"
  directory: "diagrams/"
  format: "SVG from Mermaid"
  items:
    - id: "PRD.01.diagrams.c3d4"
      title: "Container Diagram"
      file: "diagrams/prd-01_containers.mmd"
      source: "C4-L2 description"
      scope: "container"

sdd_next_action Layer Gate

After all PRDs are generated and validated, call sdd_next_action(document="02_PRD") to confirm the layer's next stage. The response shows:

• current_stage: "created"
• existing_artifacts: list of all PRD files in the layer
• next_action: "validate" (or "review" if already validated)
• next_tool: "sdd_validate"

This gate confirms all documents are visible to the UCX tooling before proceeding to review or next layer (EARS).

PRD-to-BRD Traceability

Every PRD must reference its upstream BRD:

traceability:
  upstream:
    brd_references:
      - "@brd: BRD-01.04.78a9 (business_objectives.goals)"
      - "@brd: BRD-01.07.f79d (functional_requirements)"
  downstream_expected:
    - {type: "EARS", layer: 3, description: "Formal requirements"}
  cross_links:
    depends: ["@depends: BRD-01"]
    discoverability:
      - "@discoverability: PRD-02 (feature product requirements)"

For umbrella PRDs, populate discoverability with all 8 feature PRDs. For feature PRDs, reference the umbrella PRD and any directly related feature PRDs.

Phase 1: Document Creation (UCC)

Workflow

1. Receive the target document type and any reference/upstream materials
2. Load the appropriate YAML template from UCX (see Templates section below)
3. Dispatch the layer's author lens (the author: field of the layer's crew in REVIEW_CREWS.yaml) to draft the document following the template structure
4. Validate output against layer schema

Creation Author

Each layer's author is the single author: lens of its crew in framework/governance/REVIEW_CREWS.yaml (e.g., BRD → business_analyst, PRD → product_owner, EARS → requirements_specialist, ADR/SPEC → architect, BDD/TDD → qa_lead, IPLAN → tech_lead, CHG → integration_lead). Read the file for the current assignment rather than relying on a copy. The multi-lens crew reviews the draft in Phase 2.

Creation Prompt Rules

For BRD creation, enforce:

• All required sections present per the current framework/layers/01_BRD/BRD-TEMPLATE.yaml (that template is the authority for the section set — do not enumerate a fixed list here; it drifts from the schema)
• YAML frontmatter with doc_id: "BRD-{NN}"
• Element IDs: TYPE.NN.SS.xxxx (4-segment format per naming standards: e.g., BRD.01.07.a7f3)
• When uncertain about a requirement, DOCUMENT THE UNCERTAINTY rather than omit it
• No TBD/TODO items without explanation

For PRD creation, enforce:

• User stories with acceptance criteria
• Feature prioritization (MoSCoW)
• MVP scope boundary
• User personas and journeys

For ADR creation, enforce:

• Context-Decision-Consequences format
• Each decision has documented alternatives considered
• Trade-off analysis present

For TDD creation, enforce:

• Test pyramid: 70% unit / 20% integration / 10% e2e
• Every BDD scenario maps to one or more TDD test cases
• Test case format: inputs, expected outputs, edge cases
• Quality thresholds from SPEC must be reflected in test assertions
• Tests MUST be defined before implementation (test-first TDD)

For IPLAN creation, enforce:

• File manifest: one entry per deliverable file with status (NOT_STARTED/PARTIAL/COMPLETED)
• Bash commands: executable one-liners only, no interactive prompts
• Session handoff: sessions: [] at creation — the trail is appended by each session as it ends, never carried forward while authoring
• Execution order: test files FIRST, then implementation files
• Partial work tracking: description of in-progress work for resumption

Phase 2: Document Review (UCR)

Workflow

1. Receive the document to review
2. Dispatch ALL listed persona subagents in parallel
3. Collect all findings from each subagent
4. Dispatch fact-checker to cross-validate all P0/P1 findings
5. Dispatch board-chairperson to synthesize, de-duplicate, score, and produce final manifest

Review Persona Assignments (Dispatch Phase)

Dispatch the layer's crew from framework/governance/REVIEW_CREWS.yaml — one parallel subagent per review: lens, each injected with its framework/playbooks/<NN>_<LAYER>/<lens>.md playbook. Read REVIEW_CREWS.yaml for the current crew + weights; do not rely on a copy here. (Illustrative: the BRD crew is {architect: 30, business_analyst: 30, auditor: 20, chaos_engineer: 12, security_engineer: 8}.) The synthesizer lens plays the chairperson reduce (see "Chairperson Scoring").

Inline BRD Review (No Executor Required)

When UCX sdd_review executors are unavailable or the user prefers inline reviews, use the BRD crew's lenses (per REVIEW_CREWS.yaml) directly in the main agent context.

See references/brd-review-inline-pattern.md for the full pattern, review template structure, common P1 finding categories, and differences from the ADR inline review.

Review Post-Processing (Sequential, After Parallel Dispatch)

After ALL parallel subagents return findings:

1. fact-checker: Cross-validate all P0/P1 findings against the document. Remove false positives, correct categories.
2. board-chairperson (the synthesizer lens): Synthesize verified findings, de-duplicate, compute the weighted-average lens score, produce final manifest with readiness verdict.

Review Prompt Rules

• FALSE NEGATIVES ARE UNACCEPTABLE. When in doubt, FLAG IT.
• Every finding must include: Target File, Target Section, exact path
• Classify findings as P0 (critical/blocking), P1 (high), or P2 (medium)
• Pre-validation errors (YAML schema, missing fields) are infrastructure issues — report separately, do NOT count in P0 finding count

Chairperson Scoring

The readiness score is the weighted average of the crew's per-lens lens_scores, using the per-layer weights in framework/governance/REVIEW_CREWS.yaml (renormalised over the lenses that actually ran), then capped by unresolved blocking findings:

• Each dispatched lens returns a lens_score (0-100) for the document.
• score = Σ(lens_score × weight) / Σ(weight) over the lenses that ran.
• Cap: an unresolved P0 ⇒ fail (score 0); an unresolved P1 ⇒ score capped below the gate threshold.
• Coverage: if the lenses that ran fall below the crew's quorum, flag low-confidence → human review.

The numeric score is advisory; the deterministic gate (per REVIEW_TEAM.md) is the structural sdd_doc_lint floor plus "no unresolved P0/P1". Gate threshold: ≥90/100 readiness before generating the next layer (implemented in platforms/hermes/src/mcp_server/review/review_scoring.py).

Phase 3: Remediation (UCRem)

Workflow

1. Receive the UCR review report and target document
2. Pre-screen findings to determine which domain fixers are needed (adaptive loading)
3. Dispatch needed domaine fixers as parallel subagents
4. Dispatch board-chairperson to synthesize all fixes, resolve conflicts, produce final remediation report

Remediation Persona Assignments

Remediation Rules

• Complete llm_completion items FIRST
• Address llm_only items second
• Handle other findings third
• Verify but do NOT modify fixer_applied items
• The chairperson produces the final remediation manifest with execution order (auto-safe → auto-assisted → manual)

UCX sdd_remediate Limitation — Structural-Only Fixes

UCX sdd_remediate is a structural/schema fixer, not a content author. It detects:

• Placeholder tokens (xxxx, TBD without explanation)
• Invalid element ID formats
• Missing required sections

It does NOT:

• Add new scenarios to scenario_structure.scenarios
• Rewrite boilerplate Gherkin steps into domain-specific language
• Generate missing success/error/recovery/audit scenario blocks
• Apply findings from narrative markdown review reports (UCREM, chairperson manifests)

Observed behavior (TradeGent CC, 2026-05-08):

sdd_remediate(document=BDD-02.yaml, remediation_report=UCREM-REPORT.md)
→ findings: 2 tier2 (placeholder, element_id)
→ derived copy: BDD-02_remediate_v2.yaml
→ applied_changes: "none (copy-only deterministic baseline)"
→ md5sum(source) == md5sum(derived) — byte-for-byte identical

The UCREM report described 58 content-level findings (missing Gate 3 scenarios, audit logging, recovery paths, parameterized tables). sdd_remediate ignored all of them because they require semantic authoring, not structural repair.

Correct content-remediation path:

1. Parse chairperson manifest / UCREM report into a per-document fix list
2. Dispatch delegate_task fixer subagents (or scripted Python patching) to rewrite YAML content
3. Subagents must explicitly write scenario_structure.scenarios.{success,error,recovery,audit} blocks
4. After subagent writes, verify with yaml.safe_load() + scenario count diff
5. Run sdd_validate on the rewritten file for structural confirmation only

Never assume sdd_remediate with a markdown report will apply content fixes. It won't.

Subagent Content Remediation Pattern (BDD Layer)

When sdd_remediate is confirmed structural-only (see reproduction above), use delegate_task fixer subagents for semantic authoring. Proven at TradeGent CC 2026-05-08 for 7 BDDs.

Dispatcher setup:

• delegate_task enforces max_concurrent_children=3. Split docs into batches of 3 (or fewer).
• Each subagent receives: original BDD path, upstream EARS path, per-document fix list, YAML structure rules.

Fix list per document (example: BDD-02):

doc_path: /path/to/BDD-02.yaml
priority: P1| P2
cross_links: ["@depends: BDD-01"]
add_success:
  - "Gate 3 — Fundamental Health (ROE>10%, debt/equity<50%, FCF>0)"
  - "Gate 4 — Price Behavior (200-day MA proximity, no >10% gap in 90 days)"
  - "Composite Scoring (multi-factor ranking with min/max thresholds)"
add_error: []              # if none, omit
add_recovery: True         # "Recovery from Data Source Failed"
add_audit: True            # "Audit Logging for Screening Decisions"
rewrite_gherkin: True      # replace placeholders with concrete Given/When/Then
add_timing: True           # add WITHIN assertions per EARS
timing_assertions:         # exact thresholds from EARS
  - "WITHIN 5 minutes"
  - "WITHIN 10 seconds"
fix_spec_trace: True       # replace "5 (Behavior — X)" with actual EARS refs
health_score: "6/10"       # realistic, not fabricated

Subagent rules:

• Overwrite the original file; do NOT create a new path
• Scenario IDs: BDD.NN.SS.xxxx where xxxx = first 4 chars of SHA256("BDD.NN:{section}:{name}")
• After writing, verify with yaml.safe_load() and report scenario count breakdown
• Include upstream EARS requirement text in spec_trace entries (not placeholders)

Dispatcher verification (mandatory after each batch):

import os, yaml
for f in bdd_files:
    # Check modification time
    mtime = os.path.getmtime(f)
    # Check scenario count
    with open(f) as fh:
        data = yaml.safe_load(fh)
    sc = data.get("scenario_structure", {}).get("scenarios", {})
    total = sum(len(sc.get(k, [])) for k in ["success","error","recovery","audit","edge","performance","security"])
    print(f"{f}: modified={mtime} scenarios={total}")

• Reject any subagent result where mtime is unchanged or scenario count matches pre-remediation
• Re-dispatch timed-out subagents individually (common for complex docs like BDD-05 with pre-trade risk)

Post-remediation validation:

• Run sdd_validate on each rewritten file to confirm structural compliance
• Expected: PASS, 0 errors, 0 warnings
• Do NOT rely on the subagent's own "verification" claim — validate independently

Verification After Remediation — Disk State

Any claim that remediation is "applied" MUST be verified with a tool call in the same turn:

Anti-pattern: The UCREM report claimed BDD-02 went from 7 to 15 scenarios, but yaml.safe_load() on the original file still showed 7. The report described intended fixes; the files were untouched. Always verify the file, never the report.

See references/ucx-remediate-content-limitations.md for the full reproduction transcript, the expected-vs-actual comparison, and the scripted vs. subagent remediation paths.

Templates & Layer Assets

All templates are unified YAML files available as linked files in this skill:

• framework/layers/01_BRD/BRD-TEMPLATE.yaml
• framework/layers/02_PRD/PRD-TEMPLATE.yaml
• framework/layers/03_EARS/EARS-TEMPLATE.yaml
• framework/layers/04_BDD/BDD-TEMPLATE.yaml
• framework/layers/05_ADR/ADR-TEMPLATE.yaml
• framework/layers/06_SPEC/SPEC-TEMPLATE.yaml
• framework/layers/07_TDD/TDD-TEMPLATE.yaml
• framework/layers/08_IPLAN/IPLAN-TEMPLATE.yaml

Load the appropriate template from framework/layers/<NN>_<TYPE>/<TYPE>-TEMPLATE.yaml in the repository (e.g. framework/layers/01_BRD/BRD-TEMPLATE.yaml). Use the standard file-read mechanism — skill_view does not apply since templates live outside the skill (D-0013).

All documents use .yaml format. Markdown is for indexes and reference docs only. No subtypes — SPEC and TDD use unified templates (no CSPEC/DSPEC/UXSPEC/RISKSPEC/PROCSPEC; no UTEST/ITEST/STEST/FTEST/PTEST/SECTEST).

Load the appropriate template before beginning creation or review.

YAML Pitfalls and Safe Writing

Values Starting with Comparison Operators

YAML parsers choke on unquoted values that begin with >=, <=, >, or < because the leading >/< is interpreted as a block scalar chomping indicator. This hits frequently in SDD documents where target, criterion, and metric fields contain thresholds like target: >=90%.

Rule: quote any field value that starts with >=, <=, >, or <.

# WRONG — YAMLError: expected chomping or indentation indicators
target: >=90% of candidates remain qualified

# RIGHT
target: '>=90% of candidates remain qualified'

Inline Parentheses With Comparison Operators

Multi-line values with inline >= (e.g., beat rate >=60%)) also break parsing when spread across lines. Collapse into a single quoted string or use block scalar (|-) without the problematic inline operators on separate lines.

Programmatic Document Generation

When generating any SDD YAML document (BRD, PRD, etc.) programmatically via execute_code — including single documents with many element IDs — use the pattern documented in references/programmatic-sdd-generation.md. This covers: Python dict assembly from template structure, content-based element ID hashing, YAML quoting post-processing, and layer-specific quality

…(truncated)