SDD Orchestrator — Specification-Driven Development Workflow Engine Overview You orchestrate the SDD v3.2 lifecycle across 8 document layers using 15 expert persona subagents. Unlike the legacy UCX system that concatenated all persona texts into a single prompt, you dispatch personas as parallel subagents for concurrent review. Mandatory Governance Load (Before Any SDD Work) Before creating, reviewing, or remediating ANY SDD document, load the governance protocol: This single file condenses the planning-first rules from GOVERANCE RULES.md §2b/§3, DEFINITION OF DONE.md plan/IPLAN review level,…

, line)\n if m:\n indent, key, op, rest = m.groups()\n if not rest.startswith(\"'\") and not rest.startswith('\"'):\n line = f\"{indent}{key}: '{op}{rest}'\"\n quoted.append(line)\n\nfinal_yaml = '\\n'.join(quoted) + '\\n'\n\nwith open(output_path, 'w') as f:\n f.write(final_yaml)\n\n# Verify\nimport subprocess\nr = subprocess.run([\"python3\", \"-c\", f\"import yaml; yaml.safe_load(open('{output_path}'))\"],\n capture_output=True, text=True)\nassert r.returncode == 0, f\"YAML invalid: {r.stderr}\"\n```\n\n### Step 4: UCX Validate\n\nAfter generation, run `sdd_validate` via MCP — never claim \"validated\" from `yaml.safe_load()` alone.\n\n```\nmcp_sdd_lifecycle_sdd_validate(doc_type=\"brd\", document=\"path/to/BRD-NN.yaml\", layer=\"01_BRD\")\n```\n\n## Phase 1: Structural Validation (for existing BRDs)\n\nUse `subprocess.run([\"cat\", path])` to get clean content — `read_file()` inside\nexecute_code returns line-numbered output that breaks YAML parsers.\n\n```python\nimport yaml, subprocess, re\n\nCANONICAL_SECTIONS = [\n \"id\", \"title\", \"metadata\", \"document_control\", \"executive_summary\",\n \"diagrams\", \"introduction\", \"business_objectives\", \"project_scope\",\n \"stakeholders\", \"functional_requirements\", \"adr_topics\",\n \"quality_expectations\", \"constraints_and_assumptions\",\n \"acceptance_criteria\", \"risk_management\", \"approval\",\n \"traceability\", \"glossary\", \"appendix\"\n]\n\nfor brd_id, filename in [(\"BRD-01\", \"BRD-01.yaml\"), ...]:\n path = f\"/opt/data/tradegent_covered_calls/01_BRD/{filename}\"\n r = subprocess.run([\"cat\", path], capture_output=True, text=True)\n doc = yaml.safe_load(r.stdout)\n\n present = set(doc.keys())\n missing = [k for k in CANONICAL_SECTIONS if k not in present]\n\n if missing:\n print(f\"❌ {brd_id} MISSING: {missing}\")\n else:\n print(f\"✅ {brd_id}: all 20 canonical sections present\")\n\n # Check server header\n server = doc[\"metadata\"][\"validation\"][\"server\"]\n needs_fix = (server != \"ucx_hermes\")\n\n # Scan for legacy IDs\n for line in r.stdout.splitlines():\n for pat in [\"REQ-001\", \"NFR-001\", \"SYS-0\", \"CTR-0\", \"TSPEC-\", \"TASK-0\"]:\n if pat in line:\n print(f\" LEGACY ID: {pat}\")\n\n # Count FRs and ADR topics\n fr_count = len(doc.get(\"functional_requirements\", {}).get(\"requirements\", []))\n adr_count = len(doc.get(\"adr_topics\", {}).get(\"topics\", []))\n print(f\" FRs: {fr_count}, ADR topics: {adr_count}\")\n```\n\n## Phase 2: Element ID Assignment\n\nGenerate deterministic SHA256 4-char hashes from content, assign to elements\nacross all sections, rewrite YAML, and post-process to quote comparison operators.\n\n```python\nimport yaml, hashlib, re, subprocess\n\ndef generate_hash(doc_id, section_id, title, description=\"\"):\n \"\"\"Deterministic 4-char SHA256 hash for element ID\"\"\"\n inp = f\"{doc_id}:{section_id}:{title}:{description}\"\n inp = re.sub(r'[^a-z0-9:]', '', inp.lower())[:200]\n return hashlib.sha256(inp.encode()).hexdigest()[:4]\n\n# Load document\ndoc = yaml.safe_load(r.stdout)\ndoc_num = brd_id_str.split(\"-\")[1]\n\n# Sections to process — assign IDs to every element in:\n# business_objectives.goals → BRD.NN.04.xxxx\n# business_objectives.success_metrics → BRD.NN.04.xxxx\n# functional_requirements.requirements → BRD.NN.07.xxxx\n# functional_requirements.requirements[].acceptance_criteria.items → BRD.NN.07.xxxx\n# adr_topics.topics → BRD.NN.08.xxxx\n# constraints_and_assumptions.constraints.items → BRD.NN.10.xxxx\n# constraints_and_assumptions.assumptions.items → BRD.NN.10.xxxx\n# risk_management.risks → BRD.NN.12.xxxx\n# diagrams.id → BRD.NN.diagrams.xxxx\n\n# For each section, iterate items and generate IDs:\nfor goal in doc[\"business_objectives\"][\"goals\"]:\n hid = generate_hash(doc_num, \"04\", goal[\"statement\"], goal.get(\"target\", \"\"))\n goal[\"id\"] = f\"BRD.{doc_num}.04.{hid}\"\n\n# ... repeat for all sections ...\n\n# Rewrite with post-processing\nnew_yaml = yaml.dump(doc, default_flow_style=False, sort_keys=False, allow_unicode=True, width=200)\n\n# Quote values starting with >=, \u003c=, >, \u003c\nimport io\nfixed_lines = []\nfor line in new_yaml.split('\\n'):\n m = re.match(r'^(\\s+)(\\w[\\w\\s]*):\\s*(>=|\u003c=|>|\u003c)(.*)', line)\n if m:\n indent, key, op, rest = m.groups()\n if not rest.strip().startswith('\"') and not rest.strip().startswith(\"'\"):\n line = f'{indent}{key}: \"{op}{rest.strip()}\"'\n fixed_lines.append(line)\n\nwith open(path, 'w') as f:\n f.write('\\n'.join(fixed_lines))\n\n# Verify\nyaml.safe_load('\\n'.join(fixed_lines))\n```\n\n## Phase 3: Post-Rewrite Integrity Checks\n\n```python\n# Count IDs by section\nfor line in lines:\n m = re.search(r'BRD\\.\\d{2}\\.\\w+\\.([a-f0-9]{4})', line)\n ...\n\n# Check for duplicate hashes\nall_hashes = [h for lst in ids.values() for h in lst]\ndupes = [h for h in all_hashes if all_hashes.count(h) > 1]\n\n# Verify server header\nassert doc[\"metadata\"][\"validation\"][\"server\"] == \"ucx_hermes\"\n```\n\n## Pitfalls\n\n- **Do NOT use `read_file()` inside execute_code** — returns line-numbered output (`1|content`). Use `subprocess.run([\"cat\", path])` instead.\n- **Programmatic parsing ≠ UCX validation.** `yaml.safe_load()` checks syntax and key presence, but `sdd_validate` (via `mcp_sdd_lifecycle_sdd_validate`) enforces cross-section rules, phase consistency, C4 compliance, and metadata limits. Documents must be tagged **PARSED (pending sdd_validate)** until UCX confirms zero errors.\n- **Check for hash collisions** — SHA256 4-char prefix has ~1/65K collision rate. Scan for duplicates before writing.\n- **`yaml.dump()` width** — set `width=200` to avoid auto-line-wrapping long values (which breaks quoted comparison operators).\n- **Keep existing IDs** — if an element already has a real hash (not `xxxx`), do NOT overwrite it. Preserve stability.\n- **`cwd` alone does NOT set `PYTHONPATH`** for stdio MCP servers. If the server imports sibling modules, add `env: {PYTHONPATH: \"/path/to/src\"}` to the Hermes `mcp_servers` config.\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":9163,"content_sha256":"ce7948369e6265ead23870406ec6ea97b39d79e7bc607311c58f68b3c4323516"},{"filename":"references/broker-mcp-architecture-pattern.md","content":"# Two-Layer Broker MCP Architecture Pattern\n\n## When to Use\n\nWhen building a trading system that needs to integrate with one or more broker APIs (Interactive Brokers, Schwab, Tastytrade, etc.) and wants broker portability without rewriting strategy code.\n\n## Pattern\n\n```\n┌─ Strategy Engines (in-process) ──────────────────────────┐\n│ import internal_api # broker-agnostic abstractions │\n│ internal_api.place_order(symbol, qty, price, action) │\n└──────────────────────┬────────────────────────────────────┘\n │ Python function calls (0ms IPC)\n┌──────────────────────▼────────────────────────────────────┐\n│ Internal API (Python library, broker-independent) │\n│ • Validation gates: market hours, idempotency, freshness │\n│ • Data sanity checks: position vs NAV, null greeks │\n│ • Typed return structures (Pydantic models) │\n│ • No broker-specific imports │\n└──────────────────────┬────────────────────────────────────┘\n │ MCP stdio (JSON-RPC, ~1-2ms)\n┌──────────────────────▼────────────────────────────────────┐\n│ Broker MCP Server (per-broker, stdio process) │\n│ • 11 MCP tools: 1:1 mapping to broker API calls │\n│ • Connection lifecycle: heartbeat, backoff, READY flag │\n│ • Rate limiting: token-bucket with CRITICAL tier │\n│ • Idempotency: SQLite WAL key → status store │\n│ • Paper/live isolation: port-based (7496 vs 7497) │\n│ • Watchdog: systemd auto-restart, 3-crash halt │\n└──────────────────────┬────────────────────────────────────┘\n │ IB API (TCP, TLS, ~5-10ms)\n┌──────────────────────▼────────────────────────────────────┐\n│ TWS/Gateway (External — Interactive Brokers) │\n└──────────────────────────────────────────────────────────┘\n```\n\n## Key Decisions\n\n| Decision | Choice | Alternatives Rejected |\n|----------|--------|----------------------|\n| Protocol | MCP stdio (JSON-RPC) | HTTP REST (higher latency), Direct monolith (broker lock-in) |\n| Broker library | ib_insync (sync, mature) | ib_async (async, no benefit for single-threaded IB API) |\n| Idempotency store | SQLite WAL (local, survives restart) | Redis (next cycle for multi-process) |\n| Rate limiter | Token-bucket 50/sec, 5 reserved for CRITICAL | Per-engine queues (ADR-17 cross-cutting standard) |\n| Credential encryption | AES-256-GCM (FIPS 140-2 path) | Fernet (ADR-19 standard, acceptable for non-FIPS) |\n| Process supervision | systemd watchdog, 2s restart, 3-crash halt | Supervisor (acceptable alternative) |\n\n## SDD Pipeline (BRD→IPLAN) for Broker Integration\n\n```\nL1 BRD-10: Business requirements — two-layer arch, 12 FRs, 11 ADR topics\nL2 PRD-10: Product specs — 7 capabilities, 5 stories, 3 containers, 6 data flows\nL3 EARS-10: Formal reqs — 30 requirements, 5-state FSM, 11 quality attributes\nL4 BDD-10: Acceptance — 19 scenarios (10 success + 6 error + 2 recovery + 1 audit)\nL5 ADR-20: Architecture — 5 decisions, 8 cross-cutting deps, 4 MVP phases\n```\n\n## ADR Cross-References for Broker ADR\n\nWhen creating a broker integration ADR, it must reference these existing cross-cutting ADRs:\n\n| ADR | Topic | Relationship |\n|-----|-------|-------------|\n| ADR-13 | Idempotency | Extends — reuse SQLite pattern, add broker reconciliation |\n| ADR-17 | Rate Limiting | Extends — reuse token-bucket, add IB pacing + CRITICAL tier |\n| ADR-18 | Input Validation | Implements — Pydantic at MCP boundary |\n| ADR-19 | Secrets | Extends — AES-256-GCM for broker creds (FIPS path) |\n| ADR-10 | Event Bus | Depends on — strategy engines communicate via event bus |\n\n## Pitfalls\n\n- **ADR ID collision**: ADR-10 is typically already taken (Event Bus). Use ADR-20 or next available number. Update all cross-references with batch replace.\n- **ib_insync vs ib_async**: ib_insync for MVP (sync, single-broker). ib_async reconsider for next cycle (async, multi-broker).\n- **TWS daily restart**: 11:45pm EST auto-restart. Suppress alerts during this window. Auto-reconnect handles it.\n- **IB API single-threaded**: Serialize all TWS calls. Rate limiter with priority queue is essential — time-critical orders must jump the queue.\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":5225,"content_sha256":"b6d94d02cce795cbd9c059f079cd72c8a4bee9a4700b0479a14609608f1b64a1"},{"filename":"references/cross-document-index-sweep.md","content":"# SDD Pipeline Cross-Document Index Sweep\n\n## When to Run\n\nAfter completing a full pipeline for a new document (any of BRD→PRD→EARS→BDD→ADR→SPEC→TDD→IPLAN), run a cross-document index sweep to register the new document across all project-level artifacts.\n\n## Files to Update (in order)\n\n| # | File | What to Add |\n|---|------|-------------|\n| 1 | `0N_TYPE/0N-00_index.md` | New document row in the Document Registry table |\n| 2 | `CHANGELOG.md` | Entry under latest `[Unreleased]` section with version, lines, status |\n| 3 | `plans/BRD-PLANNING-ROADMAP.md` | Update inventory table, architecture tree, status line |\n| 4 | `plans/README.md` | Update planning document statuses + SDD artifact table |\n| 5 | `plans/PLAN-NNN_*.md` | Mark plan status as COMPLETE when pipeline is done |\n| 6 | `0N_TYPE/README.md` | Update Files table if it lists individual documents |\n| 7 | Upstream documents | Update `downstream_expected` sections in all upstream docs |\n| 8 | Downstream documents | Update `upstream` references in all downstream docs |\n\n## Typical Execution Pattern\n\n```\n# After generating a full pipeline (BRD→PRD→EARS→BDD→ADR):\n# 1. Update each document's downstream_expected\n# 2. Batch-patch all 00_index.md files\n# 3. Update CHANGELOG, roadmap, and plans/README\n# 4. Verify YAML validity of all modified files\n```\n\n## Pitfalls\n\n- **Don't assume all 00_index files have the same format.** Each layer may have a different table structure. Read each one before patching.\n- **ADR numbering may not align with BRD numbering.** The project may have pre-existing ADRs with different IDs. Always check the directory for collisions.\n- **The `downstream_expected` section format varies between layers.** PRD has a flat list, BRD has nested descriptions. Match the existing format.\n- **plans/README.md is often stale.** It may still show old statuses. Update all related rows, not just the new document.\n\n## ADR ID Collision Resolution\n\nWhen `ADR-NN.yaml` already exists in the project with a different topic:\n\n1. Search for next available ADR number: `grep -r \"id: ADR-\" 05_ADR/*.yaml`\n2. Use next available number (e.g., ADR-20 if ADR-19 is last)\n3. Rename the file: `ADR-10_broker...yaml` → `ADR-20_broker...yaml`\n4. Replace all `ADR.10.xxx` element IDs to `ADR.20.xxx`\n5. Update cross-references in ALL upstream/downstream documents\n6. Add row to `ADR-00_index.md` with the new ADR number\n\nProven at TradeGent CC 2026-05-14: ADRs 01-19 pre-existing. Broker ADR assigned ADR-20. All 5 pipeline documents + 4 index files updated.\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":2548,"content_sha256":"f066462a8755895c4b9d61f0f5de823e2d41f43c9139a116794b2c47d23dd7f5"},{"filename":"references/data-consistency-report.json","content":"[\n {\n \"error_code\": \"COUNT_MISMATCH\",\n \"file\": \"framework/plans/CHG_MIGRATION_PLAN.md\",\n \"line_number\": 7,\n \"description\": \"States '7-layer v3 framework' but LAYER_REGISTRY.yaml defines 8 layers (BRD, PRD, EARS, BDD, ADR, SPEC, TDD, IPLAN) and README.md correctly states '8-layer documentation-to-code framework'\",\n \"severity\": \"ERROR\"\n },\n {\n \"error_code\": \"VERSION_INCONSISTENCY\",\n \"file\": \"framework/02_PRD/PRD-00_index.md\",\n \"line_number\": 189,\n \"description\": \"Index Version: 4.0 - inconsistent with other indexes (EARS/BDD/ADR use 3.0, SPEC/TDD use 2.0). Should be consistent, preferably matching framework version 3.2\",\n \"severity\": \"WARNING\"\n },\n {\n \"error_code\": \"VERSION_INCONSISTENCY\",\n \"file\": \"framework/03_EARS/EARS-00_index.md\",\n \"line_number\": 159,\n \"description\": \"Index Version: 3.0 - inconsistent with PRD (4.0) and SPEC/TDD (2.0). Should be consistent across all layer indexes\",\n \"severity\": \"WARNING\"\n },\n {\n \"error_code\": \"VERSION_INCONSISTENCY\",\n \"file\": \"framework/04_BDD/BDD-00_index.md\",\n \"line_number\": 183,\n \"description\": \"Index Version: 3.0 - inconsistent with PRD (4.0) and SPEC/TDD (2.0). Should be consistent across all layer indexes\",\n \"severity\": \"WARNING\"\n },\n {\n \"error_code\": \"VERSION_INCONSISTENCY\",\n \"file\": \"framework/05_ADR/ADR-00_index.md\",\n \"line_number\": 176,\n \"description\": \"Index Version: 3.0 - inconsistent with PRD (4.0) and SPEC/TDD (2.0). Should be consistent across all layer indexes\",\n \"severity\": \"WARNING\"\n },\n {\n \"error_code\": \"VERSION_INCONSISTENCY\",\n \"file\": \"framework/06_SPEC/SPEC-00_index.md\",\n \"line_number\": 71,\n \"description\": \"Index Version: 2.0 - inconsistent with PRD (4.0) and EARS/BDD/ADR (3.0). Should be consistent across all layer indexes\",\n \"severity\": \"WARNING\"\n },\n {\n \"error_code\": \"VERSION_INCONSISTENCY\",\n \"file\": \"framework/07_TDD/TDD-00_index.md\",\n \"line_number\": 87,\n \"description\": \"Index Version: 2.0 - inconsistent with PRD (4.0) and EARS/BDD/ADR (3.0). Should be consistent across all layer indexes\",\n \"severity\": \"WARNING\"\n },\n {\n \"error_code\": \"DATE_INCONSISTENCY\",\n \"file\": \"framework/01_BRD/BRD-TEMPLATE.yaml\",\n \"line_number\": 33,\n \"description\": \"Template has last_updated: '2026-03-29' while framework is version 3.2 dated 2026-04-29. LAYER_REGISTRY.yaml and most indexes use 2026-04-29\",\n \"severity\": \"WARNING\"\n },\n {\n \"error_code\": \"DATE_INCONSISTENCY\",\n \"file\": \"framework/02_PRD/PRD-TEMPLATE.yaml\",\n \"line_number\": 34,\n \"description\": \"Template has last_updated: '2026-03-29' while framework is version 3.2 dated 2026-04-29. LAYER_REGISTRY.yaml and most indexes use 2026-04-29\",\n \"severity\": \"WARNING\"\n },\n {\n \"error_code\": \"DATE_INCONSISTENCY\",\n \"file\": \"framework/03_EARS/EARS-TEMPLATE.yaml\",\n \"line_number\": 34,\n \"description\": \"Template has last_updated: '2026-03-29' while framework is version 3.2 dated 2026-04-29. LAYER_REGISTRY.yaml and most indexes use 2026-04-29\",\n \"severity\": \"WARNING\"\n },\n {\n \"error_code\": \"DATE_INCONSISTENCY\",\n \"file\": \"framework/04_BDD/BDD-TEMPLATE.yaml\",\n \"line_number\": 34,\n \"description\": \"Template has last_updated: '2026-03-29' while framework is version 3.2 dated 2026-04-29. LAYER_REGISTRY.yaml and most indexes use 2026-04-29\",\n \"severity\": \"WARNING\"\n },\n {\n \"error_code\": \"DATE_INCONSISTENCY\",\n \"file\": \"framework/05_ADR/ADR-TEMPLATE.yaml\",\n \"line_number\": 33,\n \"description\": \"Template has last_updated: '2026-03-29' while framework is version 3.2 dated 2026-04-29. LAYER_REGISTRY.yaml and most indexes use 2026-04-29\",\n \"severity\": \"WARNING\"\n },\n {\n \"error_code\": \"SPELLING_ERROR\",\n \"file\": \"framework/DIAGRAM_STANDARDS.md\",\n \"line_number\": 2,\n \"description\": \"Title misspells 'Requirement' as 'Requirement' in 'Mermaid-Only Requirement'\",\n \"severity\": \"ERROR\"\n },\n {\n \"error_code\": \"SPELLING_ERROR\",\n \"file\": \"framework/DIAGRAM_STANDARDS.md\",\n \"line_number\": 24,\n \"description\": \"Table header misspells 'Requirement' as 'Requirement' in '| Requirement | Description |'\",\n \"severity\": \"ERROR\"\n },\n {\n \"error_code\": \"SPELLING_ERROR\",\n \"file\": \"framework/DIAGRAM_STANDARDS.md\",\n \"line_number\": 36,\n \"description\": \"Table content misspells 'Prohibited' as 'Prohibited' in '| Format Type | Example | Prohibition Reason |'\",\n \"severity\": \"ERROR\"\n },\n {\n \"error_code\": \"SPELLING_ERROR\",\n \"file\": \"framework/DIAGRAM_STANDARDS.md\",\n \"line_number\": 47,\n \"description\": \"Table header misspells 'Permitted' as 'Permitted' in '| Exception | Permitted Use | Example |'\",\n \"severity\": \"ERROR\"\n },\n {\n \"error_code\": \"SPELLING_ERROR\",\n \"file\": \"framework/DIAGRAM_STANDARDS.md\",\n \"line_number\": 67,\n \"description\": \"Content misspells 'MVP' as 'MVP' and 'PROD' as 'PROD' in 'Use the following model across the MVP → PROD → NEW MVP lifecycle' - should be 'MVP → PROD → NEW MVP'\",\n \"severity\": \"WARNING\"\n },\n {\n \"error_code\": \"SPELLING_ERROR\",\n \"file\": \"framework/DOC_GOVERNANCE_CORE.md\",\n \"line_number\": 14,\n \"description\": \"Misspells 'Adopted' as 'Adopted' in 'Adopted 2026-04-29'\",\n \"severity\": \"ERROR\"\n },\n {\n \"error_code\": \"SPELLING_ERROR\",\n \"file\": \"framework/DOC_GOVERNANCE_CORE.md\",\n \"line_number\": 18,\n \"description\": \"Misspells 'authoring' as 'authoring' in 'anything that gets authored, committed, and shipped'\",\n \"severity\": \"ERROR\"\n },\n {\n \"error_code\": \"SPELLING_ERROR\",\n \"file\": \"framework/DOC_GOVERNANCE_CORE.md\",\n \"line_number\": 21,\n \"description\": \"Misspells 'authoring' as 'authoring' in 'The IPLAN status reflects authoring-completion'\",\n \"severity\": \"ERROR\"\n },\n {\n \"error_code\": \"SPELLING_ERROR\",\n \"file\": \"framework/DOC_GOVERNANCE_CORE.md\",\n \"line_number\": 28,\n \"description\": \"Misspells 'authoring' as 'authoring' in 'register the obligation in IPLAN registry's §deferred_items before flipping authoring-completion'\",\n \"severity\": \"ERROR\"\n },\n {\n \"error_code\": \"SPELLING_ERROR\",\n \"file\": \"framework/README.md\",\n \"line_number\": 165,\n \"description\": \"Misspells 'TASKS' as 'TASKS' in '| TASKS | IPLAN | Lighter-weight execution bridge with session handoff |'\",\n \"severity\": \"ERROR\"\n },\n {\n \"error_code\": \"SPELLING_ERROR\",\n \"file\": \"framework/SPEC_DRIVEN_DEVELOPMENT_GUIDE.md\",\n \"line_number\": 59,\n \"description\": \"Misspells 'TASKS' as 'TASKS' in '| TASKS (L11) | IPLAN (L8) execution bridge with session handoff |'\",\n \"severity\": \"ERROR\"\n },\n {\n \"error_code\": \"SPELLING_ERROR\",\n \"file\": \"framework/SPEC_DRIVEN_DEVELOPMENT_GUIDE.md\",\n \"line_number\": 78,\n \"description\": \"Misspells 'authoring' as 'authoring' in 'anything that gets authored, committed, shipped via git push'\",\n \"severity\": \"ERROR\"\n },\n {\n \"error_code\": \"SPELLING_ERROR\",\n \"file\": \"framework/SPEC_DRIVEN_DEVELOPMENT_GUIDE.md\",\n \"line_number\": 81,\n \"description\": \"Misspells 'authoring' as 'authoring' in 'The IPLAN status reflects authoring-completion'\",\n \"severity\": \"ERROR\"\n },\n {\n \"error_code\": \"SPELLING_ERROR\",\n \"file\": \"framework/CHG/CHG-00_index.md\",\n \"line_number\": 2,\n \"description\": \"Extra closing quote in title: 'CHG Index (v3.2)\\\"' - malformed YAML frontmatter value\",\n \"severity\": \"ERROR\"\n },\n {\n \"error_code\": \"SPELLING_ERROR\",\n \"file\": \"framework/CHG/gates/GATE-01_BUSINESS_PRODUCT.md\",\n \"line_number\": 19,\n \"description\": \"Misspells 'Layers' as 'Layers' in '> **Position**: Before Layers 1-2 (BRD, PRD)' - should be 'Layers' for consistency\",\n \"severity\": \"WARNING\"\n },\n {\n \"error_code\": \"SPELLING_ERROR\",\n \"file\": \"framework/CHG/gates/GATE-03_REQUIREMENTS_ARCHITECTURE.md\",\n \"line_number\": 20,\n \"description\": \"Misspells 'Layers' as 'Layers' in '> **Position**: Before Layers 3-5 (EARS, BDD, ADR)' - should be 'Layers' for consistency\",\n \"severity\": \"WARNING\"\n },\n {\n \"error_code\": \"SPELLING_ERROR\",\n \"file\": \"framework/CHG/gates/GATE-06_DESIGN_TEST.md\",\n \"line_number\": 19,\n \"description\": \"Misspells 'Layers' as 'Layers' in '> **Position**: Before Layers 6-7 (SPEC, TDD)' - should be 'Layers' for consistency\",\n \"severity\": \"WARNING\"\n },\n {\n \"error_code\": \"SPELLING_ERROR\",\n \"file\": \"framework/CHG/gates/GATE-CODE_IMPLEMENTATION.md\",\n \"line_number\": 19,\n \"description\": \"Misspells 'Layers' as 'Layers' in '> **Position**: Before Layers (Code)' - should be 'Layers' for consistency\",\n \"severity\": \"WARNING\"\n },\n {\n \"error_code\": \"DUPLICATE_CONTENT\",\n \"file\": \"framework/README.md\",\n \"line_number\": 8,\n \"description\": \"Traceability chain 'BRD → PRD → EARS → BDD → ADR → SPEC → TDD → IPLAN → Code' repeated at lines 8, 31, 39, 49, 55, 73, 152. Consider consolidating to a single definition with references\",\n \"severity\": \"INFO\"\n },\n {\n \"error_code\": \"DUPLICATE_CONTENT\",\n \"file\": \"framework/TRACEABILITY.md\",\n \"line_number\": 6,\n \"description\": \"Traceability chain 'BRD (L1) → PRD (L2) → EARS (L3) → BDD (L4) → ADR (L5) → SPEC (L6) → TDD (L7) → IPLAN (L8) → Code' is near-identical to README.md versions. Consider cross-referencing instead of duplicating\",\n \"severity\": \"INFO\"\n },\n {\n \"error_code\": \"DUPLICATE_CONTENT\",\n \"file\": \"framework/SPEC_DRIVEN_DEVELOPMENT_GUIDE.md\",\n \"line_number\": 8,\n \"description\": \"Traceability chain 'BRD (L1) → PRD (L2) → EARS (L3) → BDD (L4) → ADR (L5) → SPEC (L6) → TDD (L7) → IPLAN (L8) → Code' duplicated from TRACEABILITY.md\",\n \"severity\": \"INFO\"\n },\n {\n \"error_code\": \"LAYER_NUMBER_MISMATCH\",\n \"file\": \"framework/CHG/gates/GATE_INTERACTION_DIAGRAM.md\",\n \"line_number\": \"N/A\",\n \"description\": \"CHG_MIGRATION_PLAN.md states '7-layer v3 framework' at line 7, but all authoritative sources (LAYER_REGISTRY.yaml, README.md) define 8 layers. Likely typo for '8-layer'\",\n \"severity\": \"ERROR\"\n },\n {\n \"error_code\": \"DATE_INCONSISTENCY\",\n \"file\": \"framework/02_PRD/PRD-00_index.md\",\n \"line_number\": 45,\n \"description\": \"Template entry shows '2026-03-29' as Last Updated date, but PRD-TEMPLATE.yaml has last_updated: '2026-03-29'. If template was updated for v3.2, dates should be '2026-04-29'\",\n \"severity\": \"WARNING\"\n },\n {\n \"error_code\": \"DATE_INCONSISTENCY\",\n \"file\": \"framework/03_EARS/EARS-00_index.md\",\n \"line_number\": 45,\n \"description\": \"Template entry shows '2026-03-29' as Last Updated date, but EARS-TEMPLATE.yaml has last_updated: '2026-03-29'. If template was updated for v3.2, dates should be '2026-04-29'\",\n \"severity\": \"WARNING\"\n },\n {\n \"error_code\": \"DATE_INCONSISTENCY\",\n \"file\": \"framework/04_BDD/BDD-00_index.md\",\n \"line_number\": 69,\n \"description\": \"Template entry shows '2026-03-29' as Last Updated date, but BDD-TEMPLATE.yaml has last_updated: '2026-03-29'. If template was updated for v3.2, dates should be '2026-04-29'\",\n \"severity\": \"WARNING\"\n },\n {\n \"error_code\": \"DATE_INCONSISTENCY\",\n \"file\": \"framework/05_ADR/ADR-00_index.md\",\n \"line_number\": 45,\n \"description\": \"Template entry shows '2026-03-29' as Last Updated date, but ADR-TEMPLATE.yaml has last_updated: '2026-03-29'. If template was updated for v3.2, dates should be '2026-04-29'\",\n \"severity\": \"WARNING\"\n },\n {\n \"error_code\": \"METADATA_MISMATCH\",\n \"file\": \"framework/08_IPLAN/IPLAN-00_index.yaml\",\n \"line_number\": 1,\n \"description\": \"File starts with '# IPLAN-00_REGISTRY.yaml' but filename is 'IPLAN-00_index.yaml'. Comment inside (line 2) says 'SDD v3.2 Layer 8 — Execution tracking for all permanent IPLANs'. Inconsistent naming: REGISTRY vs index\",\n \"severity\": \"WARNING\"\n },\n {\n \"error_code\": \"SPELLING_ERROR\",\n \"file\": \"framework/08_IPLAN/IPLAN-00_index.yaml\",\n \"line_number\": 99,\n \"description\": \"Misspells 'introduced_by' as 'introduced_by' in '- introduced_by: \\\"IPLAN-02\\\"'\",\n \"severity\": \"ERROR\"\n },\n {\n \"error_code\": \"SPELLING_ERROR\",\n \"file\": \"framework/08_IPLAN/IPLAN-00_index.yaml\",\n \"line_number\": 165,\n \"description\": \"Misspells 'abandoned' as 'abandoned' in '- \\\"Set status: ABANDONED with date\\\"'\",\n \"severity\": \"ERROR\"\n },\n {\n \"error_code\": \"SPELLING_ERROR\",\n \"file\": \"framework/08_IPLAN/IPLAN-00_index.yaml\",\n \"line_number\": 170,\n \"description\": \"Misspells 'added' as 'added' in 'on_cross_plan_obligation_added:'\",\n \"severity\": \"ERROR\"\n },\n {\n \"error_code\": \"SPELLING_ERROR\",\n \"file\": \"framework/CHG/gates/GATE_ERROR_CATALOG.md\",\n \"line_number\": \"N/A\",\n \"description\": \"Referenced in CHG-00_index.md line 54 as 'GATE_ERROR_CATALOG.md' but actual filename needs verification for correct spelling of 'CATALOG'\",\n \"severity\": \"INFO\"\n },\n {\n \"error_code\": \"COUNT_MISMATCH\",\n \"file\": \"framework/README.md\",\n \"line_number\": 162,\n \"description\": \"Table states 'Cut SYS, REQ, CTR, TSPEC (42 files)' but CHG_MIGRATION_PLAN.md line 5 states '12 existing files' for CHG v2. Need to verify if 42 is accurate for TSPEC files alone or total cut\",\n \"severity\": \"WARNING\"\n },\n {\n \"error_code\": \"LAYER_NUMBER_MISMATCH\",\n \"file\": \"framework/LAYER_REGISTRY.yaml\",\n \"line_number\": 36,\n \"description\": \"Changelog (v3.0) states 'Collapsed from 14 layers to 7 (BRD→PRD→EARS→BDD→ADR→TDD→SPEC)' - says 7 layers but lists 7 items (BRD-PRD-EARS-BDD-ADR-TDD-SPEC). Current version has 8 layers (adds IPLAN). Inconsistent count\",\n \"severity\": \"WARNING\"\n },\n {\n \"error_code\": \"LAYER_NUMBER_MISMATCH\",\n \"file\": \"framework/LAYER_REGISTRY.yaml\",\n \"line_number\": 38,\n \"description\": \"Changelog (v3.0) states 'Added Layer 6 TDD' and 'SPEC promoted to Layer 7' but v3.2 now has SPEC as Layer 6 and TDD as Layer 7. The changelog is outdated relative to current structure\",\n \"severity\": \"WARNING\"\n }\n]\n","content_type":"application/json; charset=utf-8","language":"json","size":13876,"content_sha256":"1cbe809c3e12a2f3998f0819c61635820bd73bed7ee9d0d9955412edf96e53f7"},{"filename":"references/diagram-standards.md","content":"---\ntitle: \"Diagram Standards: Mermaid-Only Requirement\"\ntags:\n - framework-guide\n - shared-architecture\n - required-both-approaches\n - active\ncustom_fields:\n document_type: standards-guide\n priority: shared\n development_status: active\n applies_to: [all-artifacts, sdd-workflow]\n version: \"1.0\"\n---\n\n# Diagram Standards\n\n> **Authority:** `framework/governance/DIAGRAM_STANDARDS.md` is the source of\n> truth. This reference mirrors it for the orchestrator skill bundle; diagram\n> generation, validation, and SVG embedding are performed by the platform's own\n> diagram tooling.\n\n## Mandatory Format: Mermaid Only\n\nAll diagrams, charts, workflows, and visual representations in SDD framework artifacts MUST use Mermaid syntax.\n\n### Requirements\n\n| Requirement | Description |\n|-------------|-------------|\n| **Format** | Mermaid syntax (fenced code blocks with `mermaid` language tag) |\n| **Validation** | Diagrams must render without parse errors |\n| **Style** | Follow the platform's diagram tooling guidelines for syntax correctness |\n| **File Management** | Use the platform's diagram tooling for SVG generation and embedding |\n\n### Prohibited Formats\n\nThe following diagram formats are NOT permitted in any SDD artifact:\n\n| Format Type | Example | Prohibition Reason |\n|-------------|---------|-------------------|\n| ASCII art boxes | `+----+`, `| |`,`+----+` | Not renderable, inconsistent display |\n| Text-based flowcharts | `A --> B --> C` (outside Mermaid) | No semantic structure |\n| Unicode box-drawing | ``, ` `,`` | Font-dependent rendering |\n| Manual arrow diagrams | `==>`, `->`, `\u003c--` (outside Mermaid) | No styling or layout control |\n| Indented hierarchy text | Manual spacing alignment | Fragile, breaks with formatting |\n\n### Allowed Exceptions\n\n| Exception | Permitted Use | Example |\n|-----------|---------------|---------|\n| Directory trees | File/folder structure representation | `src/`, `tests/` |\n| Inline code references | Simple path or command notation | `src/main.py` |\n| Table-based data | Structured data display | Markdown tables |\n\n### Diagram Types Reference\n\nUse appropriate Mermaid diagram type for the content:\n\n| Content Type | Mermaid Diagram |\n|--------------|-----------------|\n| Process flows | `flowchart TD/LR` |\n| Sequences/interactions | `sequenceDiagram` |\n| State transitions | `stateDiagram-v2` |\n| Class relationships | `classDiagram` |\n| Entity relationships | `erDiagram` |\n| Timelines | `timeline` |\n| Mind maps | `mindmap` |\n\n## C4 + DFD + Sequence Ownership Model\n\nUse the following model across the MVP → PROD → NEW MVP lifecycle.\n\n| Layer Artifact | Required Model | Purpose |\n|----------------|----------------|---------|\n| BRD (L1) | C4 L1 (Context) + DFD L1 | Business/system boundary and top-level data movement |\n| PRD (L2) | C4 L2 (Container) + DFD L2 + key sequence | Product container interactions, data movement, temporal user/system flow |\n| ADR (L5) | Decision sequence (no C4 level — decision bridge) | Architecture decision rationale and alternatives |\n| SPEC (L6) | C4 L3 (Component) + DFD L3 | Component interfaces, data-flow constraints, behavior contracts |\n| Code | C4 L4 (Code) | Implementation-level class/package structure |\n\n### Diagram Intent Header (Mandatory)\n\nEach required diagram block MUST include an intent header immediately above the Mermaid block.\n\nRequired fields:\n\n- `diagram_type`: `c4` | `dfd` | `sequence`\n- `level`: `l1` | `l2` | `l3` | `l4` (as applicable, aligned: C4 level = DFD level)\n- `scope_boundary`: short boundary definition\n- `upstream_refs`: source requirement/decision references\n- `downstream_refs`: implementation or validation references\n\nRequired machine tags adjacent to diagram blocks:\n\n- `@diagram: c4-l1 | c4-l2 | c4-l3 | c4-l4`\n- `@diagram: dfd-l1 | dfd-l2 | dfd-l3`\n- `@diagram: sequence-sync | sequence-async | sequence-error`\n\nValidation severity defaults:\n\n- Error: missing mandatory diagram type for the layer/section\n- Warning: missing trust-boundary annotation or missing sequence exception-path branch\n- Info: optional enrichment gaps\n\n### SPEC Component Diagram Rule\n\n- SPEC MUST NOT require embedded C4 L4 code/class diagrams as mandatory content.\n- SPEC MUST reference downstream TDD/IPLAN location where C4 L4 ownership is implemented.\n\n### Component Diagram Contract (SPEC)\n\nRequired fields in SPEC diagram contract subsection:\n\n- `@diagram: c4-l3` component-level references\n- `@diagram: dfd-l3` data-flow boundary tags\n- Required sequence paths for critical integrations and error handling\n- Downstream TDD path for test case ownership\n\n### Layer Enforcement Summary\n\n| Layer | Mandatory Checks |\n|---|---|\n| BRD (L1) | `@diagram: c4-l1`, `@diagram: dfd-l1`; sequence optional for critical journeys |\n| PRD (L2) | `@diagram: c4-l2`, `@diagram: dfd-l2`, `@diagram: sequence-sync`; required sequence with explicit error path |\n| EARS (L3) | No diagrams required (refinement step; inherits upstream) |\n| BDD (L4) | Gherkin scenarios (no C4/DFD diagram requirements) |\n| ADR (L5) | Required decision sequence; no C4/DFD tags (decision bridge, not a C4 level) |\n| SPEC (L6) | `@diagram: c4-l3`, `@diagram: dfd-l3`, required Component Diagram Contract subsection, sequence-path constraints, downstream TDD ownership link |\n| TDD (L7) | No C4/DFD requirements (test case definitions) |\n| IPLAN (L8) | No C4/DFD requirements (execution plan) |\n| Code | C4 L4 ownership declarations aligned with SPEC references |\n\n### BRD Required Diagrams by Type\n\nBRD diagrams are scoped by `brd_type` (platform or feature). Required diagrams ensure consistent visual coverage across all BRDs.\n\n**Platform BRD (3 required)**:\n\n| # | Type | Description | Diagram Tag |\n|---|------|-------------|-------------|\n| 1 | `structure_overview` | Document section map with key metrics | `@diagram: c4-l1` |\n| 2 | `cross_brd_dependencies` | Upstream/downstream BRD dependency graph | `@diagram: c4-l1` |\n| 3 | `data_model` | Primary data model or entity hierarchy | `@diagram: dfd-l1` |\n\n**Feature BRD (2 required)**:\n\n| # | Type | Description | Diagram Tag |\n|---|------|-------------|-------------|\n| 1 | `user_journey` | Happy-path user flow | `@diagram: sequence-sync` |\n| 2 | `integration_points` | External system touchpoints | `@diagram: c4-l1` |\n\n**Optional (both types)**:\n\n- `implementation_phases` -- phase timeline or Gantt\n- `risk_summary` -- risk matrix visualization\n- `architecture_decisions` -- ADT decision tree\n- `key_flow_diagrams` -- domain-specific data or process flows\n\nAll diagrams follow the `diagrams` registry in BRD-TEMPLATE.yaml. Each item requires: `id`, `title`, `file`, `source`, `scope`.\n\n### Interactive Diagrams (RECOMMENDED)\n\nFor enhanced navigability, Mermaid diagrams MAY include click handlers to link nodes to related documents or sections. This is **optional but recommended** for traceability diagrams.\n\n**Basic Click Handler Syntax**:\n\n```mermaid\nflowchart LR\n BRD01[BRD-01: Platform]\n PRD01[PRD-01: Core]\n\n BRD01 --> PRD01\n\n click BRD01 \"../../01_BRD/BRD-01_platform/\" \"View BRD-01\"\n click PRD01 \"../PRD-01_core/\" \"View PRD-01\"\n```\n\n**Click Handler Format**:\n\n```\nclick \u003cnode_id> \"\u003crelative_path>\" \"\u003ctooltip_text>\"\n```\n\n**When to Use Interactive Diagrams**:\n\n| Use Case | Recommended | Example |\n|----------|-------------|---------|\n| Traceability diagrams | [PASS] Yes | Link BRD → PRD → EARS nodes |\n| Architecture overviews | [PASS] Yes | Link to component docs |\n| Workflow diagrams | [WARN] Optional | Link to process docs |\n| Simple concept diagrams | [FAIL] No | Static is sufficient |\n\n**Best Practices**:\n\n| Practice | Guidance |\n|----------|----------|\n| **Relative Paths** | Use `../` relative paths, not absolute URLs |\n| **Consistent Direction** | Link from diagram location to target |\n| **Tooltip Text** | Include descriptive tooltip (e.g., \"View PRD-01 Details\") |\n| **Fallback** | Diagrams must be readable without clicking |\n| **Validation** | Test links after file moves or renames |\n\n**Alternative: Inline Anchor Links**:\n\nFor HTML-rendered Markdown, anchor links can be embedded in node labels:\n\n```mermaid\nflowchart LR\n A[\"\u003ca href='#section-1'>Section 1\u003c/a>\"]\n B[\"\u003ca href='#section-2'>Section 2\u003c/a>\"]\n A --> B\n```\n\n**Note**: Anchor link syntax may not render in all Mermaid viewers. Use `click` handlers for broader compatibility.\n\n**Format Comparison**:\n\n| Aspect | Static Diagram | Click Handlers | Inline Anchors |\n|--------|---------------|----------------|----------------|\n| **Compatibility** | [PASS] All viewers | [PASS] Most viewers | [WARN] HTML only |\n| **Maintainability** | [PASS] No path updates | [FAIL] Path breakage risk | [FAIL] Path breakage risk |\n| **Navigation** | [FAIL] Manual | [PASS] One-click | [PASS] One-click |\n| **Recommended For** | Conceptual diagrams | Published traceability | In-document navigation |\n\n### Diagram Tooling\n\nThe platform supplies its own diagram tooling for Mermaid syntax generation,\nerror prevention, SVG conversion, and document embedding. This standard defines\nthe Mermaid-only requirement; the platform supplies the tools that enforce it.\n\n### Enforcement\n\n1. **Pre-commit validation**: Quality gates check for text-based diagram patterns\n2. **Workflow enforcement**: All document-generation workflows include the Mermaid-only requirement\n3. **Review checklist**: Diagram format verification during review\n\n### Traceability\n\nThis standard applies to all SDD artifacts across Layers 1-8.\n\n**Cross-references**:\n\n- Authority: `framework/governance/DIAGRAM_STANDARDS.md`\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":9537,"content_sha256":"d7519da278961f8b71f78e327a72ec9e423b7e7cdc38f32e4cd09bd9fa361fa4"},{"filename":"references/doc-governance-core.md","content":"# Document Governance — SDD v3.2\n\n## Principles\n\n1. **Single source of truth** — Each layer has one template. No duplicate representations.\n2. **YAML-first** — All templates are `.yaml`. MD is for indexes and reference docs only.\n3. **Cumulative traceability** — Each layer inherits all upstream tags; adds one.\n4. **Readiness gates** — Each layer must score >=90/100 before downstream generation.\n5. **No circular dependencies** — Downstream artifacts reference upstream, never the reverse.\n6. **Separation of development and deployment** — Development plans produce source code, Terraform modules, Helm charts, CI/CD workflow files, schema DDL, scripts — anything authored, committed, and shipped through version control. Deployment plans handle operator-only execution of those artifacts. A development plan is complete when its artifacts are authored, committed, and green — it does NOT wait for deployment.\n\n### Development vs Deployment Plans\n\nAdopted 2026-04-29. Permanent plans split into two roles:\n\n| Role | Owns | Done when |\n| ---- | ---- | --------- |\n| **Development plan (IPLAN)** | Source code, Terraform modules, Helm charts, CI/CD workflow files, schema DDL, scripts — anything that gets authored, committed, and shipped through `git push`. | Source code + Terraform modules + CI/CD scripts authored, committed, and green under `pre-commit run --all-files`; tests pass. |\n| **Deployment plan** | Operator-only execution of those artifacts: `terraform apply`, `atlas migrate apply`, Auth0 tenant config push, Secret Manager seeding, project provisioning, image build + deploy, environment activation, acceptance/soak runs. | Artifacts applied to the target environment; acceptance/soak gates green. |\n\n**Rule.** A development IPLAN flips to `Completed` once its source code + Terraform modules + CI/CD scripts are authored, committed, and green. **It does NOT wait for the artifacts to be deployed.** The deploy execution belongs to a separate deployment plan.\n\nPractical effect:\n\n- An IPLAN's validation_results entry like \"ready for deployment provisioning before IMPLEMENTED flip\" or \"`terraform apply` pending\" is **NOT** a gate on the IPLAN's status. Those gates belong on the deployment plan's phase markers.\n- An IPLAN that has shipped source code + Terraform module declarations + integration tests **IS** complete from the development side, even if no `terraform apply` has run.\n- Conversely, the deployment plan stays `In Progress` until the apply + acceptance steps actually execute against the target environment.\n\n**Cross-plan obligation handoff.** When closing a development IPLAN whose artifacts depend on a deployment-plan apply step, register the obligation in `IPLAN-00_index.yaml` §deferred_items before flipping `Completed`. The IPLAN's status reflects authoring-completion; the registry entry tracks the deploy-side handoff.\n\n## Immutability\n\n- Published artifacts (status: Approved) must not be modified.\n- Changes require a new document version or a new document ID.\n- Superseded documents are marked as Deprecated/Superseded in document_control.status.\n\n## Template Policy\n\n- **Unified YAML only** — No `.md` templates, no `.feature` templates.\n- Each layer has exactly one `{TYPE}-TEMPLATE.yaml`.\n- Template fields use `_guidance` prefix for authoring instructions (not validated).\n- Metadata block (`metadata:`) defines layer, schema version, and document type.\n\n## Validation\n\n- Layer entries must validate against `LAYER_REGISTRY.yaml`.\n- Required upstream tags must be present in traceability sections.\n- Element IDs must match the 4-segment hash format: `TYPE.NN.SS.xxxx`.\n- Document IDs must match the format: `TYPE-NN`.\n\n## v3.2 Governance Baseline\n\n| Governance Area | v3.2 Standard |\n|----|------|\n| Layer registry | 8-layer registry |\n| Lifecycle status field | `status` |\n| Template format | YAML-only templates |\n| Traceability depth | 8-depth chain |\n| Specification and testing | Unified SPEC (L6) + TDD with embedded test cases (L7) |\n| Change governance | CHG project-level overlay |\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":4065,"content_sha256":"98b52bc81b24bffe1042f033b4769ef3762ef2d2ee8600ec0126ef079a249ac3"},{"filename":"references/ears-generation-pattern.md","content":"# EARS Generation Pattern — SDD v3.2\n\n## Pattern: PRD Capabilities → EARS Statements\n\nEach PRD core capability maps to one or more EARS requirements, classified by pattern:\n\n| PRD Capability | Maps To | Pattern |\n|---------------|---------|---------|\n| User-initiated action | event_driven | WHEN-THE-SHALL-WITHIN |\n| Continuous monitoring | state_driven | WHILE-THE-SHALL-WITHIN |\n| Error handling | unwanted_behavior | IF-THE-SHALL-WITHIN |\n| Global invariants | ubiquitous | THE-SHALL |\n\n## Prohibited Qualifiers (replace with quantified targets)\n\n| Prohibited | Replacement |\n|-----------|-------------|\n| \"real-time\" | \"WITHIN 60 seconds\" or \"p50 \u003c 100ms, p95 \u003c 300ms\" |\n| \"immediate\" / \"immediately\" | \"WITHIN 30 seconds\" or specific duration |\n| \"continuously\" | \"at each [event]\" or specify periodicity |\n| \"fast\" / \"quickly\" | Specify exact latency numbers (p50/p95/p99) |\n| \"near X\" | \"within 0.0Y of X\" or explicit tolerance |\n\n## Structural Rules\n\n1. **No compound WHEN with AND** — Split into atomic requirements. \"WHEN A AND B\" becomes two separate WHEN requirements.\n\n2. **No nested IF inside SHALL** — Each conditional path is a separate requirement. \"SHALL escalate IF counter >= 3\" becomes a separate IF-THE-SHALL.\n\n3. **WITHIN must reference a specific event** — No orphaned reference points. \"WITHIN 5 minutes\" must be \"WITHIN 5 minutes of [event].\"\n\n4. **IF/WITHIN must reference the same event** — Don't mix trigger and reference. \"IF 3 failures... WITHIN 30 minutes of first failure\" is wrong. Fix to \"WITHIN 5 minutes of third failure.\"\n\n5. **No subjective criteria** — Replace \"acceptable\", \"reasonable\", \"significant\". \"assignment risk is unacceptable\" becomes \"ITM by >= 1% of underlying price.\"\n\n6. **Atomicity**: One testable concept per requirement. If a WHEN clause lists 3+ alternatives via OR, split into separate atomic requirements.\n\n7. **Quantify interval ranges**: \"every 15-25 min\" must specify configurable parameter or fixed value.\n\n## State Machine Pattern\n\nEvery EARS document that touches operational modes MUST include a state_machine section:\n\n```yaml\nstate_machine:\n description: 'Agent operational modes and transition rules.'\n states:\n AUTONOMOUS:\n description: Normal operation\n transitions:\n - to: WARNING\n trigger: Data staleness detected per thresholds\n - to: HALTED\n trigger: Critical dependency failure (3 consecutive failures)\n WARNING:\n description: Degraded — decisions suppressed, monitoring continues\n transitions:\n - to: AUTONOMOUS\n trigger: Recovery conditions met for 2 consecutive check windows\n - to: HALTED\n trigger: Failure escalates\n HALTED:\n description: All operations stopped\n transitions:\n - to: MANUAL\n trigger: Auto-escalates on HALTED entry\n MANUAL:\n description: Operator control — dashboard with one-click approvals\n transitions:\n - to: RECONCILING\n trigger: Operator initiates recovery sequence\n RECONCILING:\n description: State reconciliation with broker/external systems\n transitions:\n - to: AUTONOMOUS\n trigger: Reconciliation complete, broker API health passes 3 probes\n - to: MANUAL\n trigger: Unreconcilable state found (operator decides)\n```\n\n## Benchmarks-First Strategy\n\nFor EARS (and any SDD layer with 9+ documents):\n\n1. Generate 2 benchmark documents from the strongest upstream sources\n2. Validate both with sdd_validate\n3. Review with 4 personas in parallel (requirements-specialist, technical-lead, qa-lead, chaos-engineer)\n4. Remediate findings\n5. Once pattern validated, batch-generate remaining 7 using execute_code\n\n## Batch EARS Generation — Python Pattern\n\n```python\nimport subprocess, yaml, hashlib, re\n\ndef make_id(doc_type, doc_num, section_num, desc):\n inp = f\"{doc_type}:{doc_num}:{section_num}:{desc}\"[:200]\n h = hashlib.sha256(inp.encode()).hexdigest()[:4]\n return f\"{doc_type}.{doc_num:02d}.{section_num:02d}.{h}\"\n\ndef postprocess_yaml(yaml_str):\n \"\"\"Quote values starting with > \u003c comparison operators.\"\"\"\n lines = yaml_str.split('\\n')\n out = []\n for line in lines:\n if ':' in line and not line.strip().startswith('#'):\n idx = line.index(':')\n val = line[idx+1:].strip()\n if val and val[0] in '>\u003c':\n prefix = line[:idx+1]\n out.append(f'{prefix} \"{val}\"')\n continue\n out.append(line)\n return '\\n'.join(out)\n\n# Map PRD capabilities to EARS requirements\n# event-driven: WHEN [trigger], THE [component] SHALL [action] WITHIN [constraint]\n# state-driven: WHILE [state], THE [component] SHALL [behavior] WITHIN [context]\n# unwanted: IF [error], THE [component] SHALL [recovery] WITHIN [timing]\n# ubiquitous: THE [component] SHALL [invariant] for [scope]\n```\n\n## Dual-WITHIN Pitfall — Atomicity Violation (TradeGent CC 2026-05-14)\n\nA single EARS requirement with two WITHIN clauses violates atomicity. Each distinct timing\ntarget must be a separate requirement. This is a common generation error when a PRD capability\ndescribes two modes with different freshness targets (e.g., streaming vs snapshot).\n\n```yaml\n# WRONG — two WITHIN in one requirement (caught at review)\nstatement: |\n WHEN the Strategy Engine requests quote data, THE Internal API SHALL return\n quote stream WITHIN 1 second in streaming mode, WITHIN 30 seconds in snapshot mode.\n\n# RIGHT — split into two atomic requirements\n- name: Stream Real-Time Quotes in Streaming Mode\n statement: |\n WHEN the Strategy Engine requests streaming quote data, THE Internal API SHALL\n return quote stream WITHIN 1 second of broker event.\n- name: Query Quote Snapshot on Demand\n statement: |\n WHEN the Strategy Engine requests a quote snapshot, THE Internal API SHALL\n return most recent values WITHIN 30 seconds of broker snapshot timestamp.\n```\n\n**Detection rule**: grep for `WITHIN.*WITHIN` in EARS statements. Any match is a structural violation.\nAlso applies to: dual thresholds in one requirement, dual state transitions, OR-branched behavior\nwith different timing constraints.\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":6195,"content_sha256":"4498abede41e35bfe4d33a0b69c88c8f837aaceb0aaff8639fe0ad2e6f3deacf"},{"filename":"references/framework-location-and-quirks.md","content":"# SDD v3.2 Framework Location & Known Quirks\n\n## Framework Root\n\n```\nframework/\n```\n\n## Key Reference Files\n\n| File | Purpose |\n|------|---------|\n| LAYER_REGISTRY.yaml | Authoritative layer definitions, doc type metadata, c4 mapping |\n| ID_NAMING_STANDARDS.md | Document ID, element ID, tag, and file naming conventions |\n| TRACEABILITY.md | Cumulative tag chain, readiness gates, upstream/downstream rules |\n| THRESHOLD_NAMING_RULES.md | Threshold key format, category rules, boundary conventions (900+ lines) |\n| AI_ASSISTANT_RULES.md | Template usage rules, what NOT to reference (v2 cut layers), TDD enforcement |\n| QUICK_REFERENCE.md | One-page summary of layers, templates, gates |\n| TESTING_STRATEGY_TDD.md | TDD integration guidance |\n| DIAGRAM_STANDARDS.md | Mermaid diagram conventions |\n| README.md | Framework overview, directory structure, quick start |\n\n## Layer Folders\n\n```\n01_BRD/ 02_PRD/ 03_EARS/ 04_BDD/ 05_ADR/ 06_SPEC/ 07_TDD/ 08_IPLAN/ CHG/\n```\n\nTemplates: `0N_TYPE/TYPE-TEMPLATE.yaml` (e.g., `01_BRD/BRD-TEMPLATE.yaml`)\n\n## Known Framework Quirks (Discovered & Fixed)\n\n1. **Element ID regex was broken** — LAYER_REGISTRY.yaml pattern `^[A-Z]+\\.\\d{2,}\\.\\d{2,}\\.\\d{2,} sdd-orchestrator — Skillopedia rejected hex hashes (only accepted decimal digits). Fixed to `^[A-Z]+\\.\\d{2,}\\.\\d{2,}\\.[a-f0-9]{4,8} sdd-orchestrator — Skillopedia to accept valid IDs like `BRD.01.07.a7f3`.\n\n2. **BRD filename conflict** — ID_NAMING_STANDARDS.md said `BRD-01.yaml` but BRD-TEMPLATE.yaml says `BRD-01.yaml` is INVALID. Must use slug suffix: `BRD-01_kyc_onboarding.yaml` (feature) or `BRD-01_platform_architecture.yaml` (platform). Updated ID_NAMING_STANDARDS.md to document this. Non-BRD docs use plain `{TYPE}-NN.yaml`.\n\n3. **BDD-Ready gate** — QUICK_REFERENCE.md omits `spec_trace links` from the BDD-Ready criteria, but TRACEABILITY.md and the BDD-TEMPLATE.yaml both include it. The sdd-orchestrator skill correctly includes `spec_trace links` — trust the skill over QUICK_REFERENCE.md.\n\n## Threshold Tag Format\n\n`@threshold: {DOC_TYPE}.{DOC_NUM}.{category.subcategory.attribute}`\n\nExamples: `@threshold: PRD.01.kyc.l1.daily`, `@threshold: ADR.15.circuit.failure.count`\n\nDefined in source docs (BRD/PRD/ADR), referenced from downstream docs (EARS/BDD/SPEC/TDD/IPLAN).\n\n## ADR Dual Role\n\nADR can both DEFINE technical thresholds AND REFERENCE business/product thresholds from BRD/PRD. Documented in THRESHOLD_NAMING_RULES.md Section 1.2.\n\n## What NOT to Reference (per AI_ASSISTANT_RULES.md)\n\n- `framework/` — SDD v2, superseded\n- SYS, REQ, CTR layers — cut from v3\n- TSPEC subtypes (UTEST, ITEST, STEST, FTEST, PTEST, SECTEST) — replaced by TDD\n- TASKS — replaced by IPLAN\n- CHG/ gates — not a v3 concern for document creation/review\n\n## 4. UCX sdd_validate Template Collision Bug\n\nThe UCX `sdd_validate` tool discovers ALL YAML files in the project when scanning\nthe target layer directory and/or `UCX/templates/` tree. If any file contains\ntemplate placeholder data (e.g., `id: ADR-NN`, unquoted `>`, `>=`, broken block\nmappings), the validator WILL parse it and fail with a YAML error — even when\nthe target document itself is clean.\n\n**Symptoms**:\n\n```\nsdd_validate(document=ADR-01.yaml, layer=05_ADR)\n→ YAMLError: while parsing a block mapping\n in \"\u003cunicode string>\", line 20, column 1:\n id: ADR-NN\n ^\n expected \u003cblock end>, but found '\u003cblock mapping start>'\n```\n\n**Root cause**: The validator scans these locations:\n\n- The target layer directory (`0N_TYPE/`)\n- `UCX/templates/` (top-level template set)\n- `UCX/templates/layers/0N_TYPE/` (layer-specific templates)\n\nAny YAML file with `ADR-NN` or other template placeholders in any of these paths\nwill trigger false parse failures.\n\n**Workaround**: Before validation, move ALL ADR template files out of the\nproject tree entirely:\n\n```bash\n# Move all template copies to /tmp\nfind /opt/data/tradegent_covered_calls -name \"ADR-TEMPLATE*\" \\\n -exec mv {} /tmp/ \\; 2>/dev/null\n# Validate\nsdd_validate(document=ADR-01.yaml, layer=05_ADR)\n# Restore templates\nmv /tmp/ADR-TEMPLATE*.yaml /opt/data/tradegent_covered_calls/05_ADR/\n```\n\n**Note**: `yaml.safe_load()` on the target document will succeed while\n`sdd_validate` fails — this is the diagnostic signature. If the document parses\ncleanly in Python but the validator rejects it, check for template files in the\nproject tree with broken YAML.\n\nThis is distinct from the **filename heuristic bug** (quirk in main orchestrator\nSKILL.md) which misclassifies files as Markdown based on name patterns. The\ntemplate collision bug affects ANY valid YAML document if a template file exists\nnearby.\n\n## Development Completion Rule (from AI_ASSISTANT_RULES.md)\n\nIPLAN is Completed when: source code + CI/CD scripts authored, committed, tests pass, pre-commit passes.\nNOT blocked by: terraform apply, atlas migrate apply, acceptance/soak testing, image build/deploy.\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":4846,"content_sha256":"d66949f26dd5f724b96930e90358b2d37cdb6bf3fe5dd8f85f49c5b4da398d9a"},{"filename":"references/governance-load-protocol.md","content":"# Governance Load Protocol for sdd-orchestrator\n\n## Purpose\n\nThe governance tree (~130 files, synced to `sdd-orchestrator/governance/`) is NOT reachable via `skill_view()` unless files are explicitly declared in the skill's `linked_files` or loaded with `file_path` parameter. This protocol condenses the planning-first rules from three core governance documents so agents can apply them without loading the full tree.\n\n## When to Apply\n\nBefore ANY SDD document creation, review, or remediation — and before calling any UCX MCP tool (`sdd_init`, `sdd_validate`, `sdd_create_build`, `sdd_review`, `sdd_remediate`, `sdd_next_action`).\n\n## Condensed Rules (from GOVERANCE_RULES.md §2b, §3)\n\n### Plan Types and Storage (GOV §2b)\n\n| Plan Type | Location | Retention |\n|-----------|----------|-----------|\n| Document-layer IPLAN | `docs/IPLAN/` or `UCX/08_IPLAN/` | Permanent |\n| Permanent development plan | `plans/` or `governance/plans/` | Permanent |\n| Temporary plan | `tmp/` | Disposable |\n\n### Planning-First Sequence (GOV §3)\n\n1. Analyze provided information, constraints, dependencies, existing context\n2. Create planning roadmap for the target scope\n3. Create planning document index for required plan artifacts\n4. Define changelog plan for the scope\n5. Review planning artifacts for gaps — resolve or explicitly defer\n6. Create required execution plan artifact:\n - document-layer IPLAN (`IPLAN-NNN_{slug}.md`) for SDD layer delivery\n - permanent development plan (`PLAN-NNN_{slug}.md`, preferred) under `plans/`\n7. Record explicit plan approval (human reviewer or independent LLM-as-judge)\n\n### Hard Gates (GOV §3)\n\n- No document creation, testing, or coding begins before the planning gate is approved\n- No issue transitions to `ai:in-progress` before planning approval exists\n- **No completion claim without filesystem verification** — Plan ≠ Done. A written plan authorizes work; it does not constitute delivery. Before reporting any layer/document as complete, call sdd_next_action and verify existing_artifacts on disk. Never infer completion from pattern-matching across layers.\n\n### Definition of Done — Plan/IPLAN Review Level (DoD)\n\nA plan is Ready when:\n\n- [ ] Planning roadmap created for target scope\n- [ ] Planning index lists required planning documents\n- [ ] Changelog plan defined for target scope\n- [ ] Planning package gap review complete\n- [ ] Gaps resolved or explicitly deferred with rationale and owner\n- [ ] Solution addresses stated problem directly\n- [ ] Implementation approach practical and feasible\n- [ ] Edge cases and error handling considered\n- [ ] Plan reviewed (self-review for solo projects)\n- [ ] Approval record exists for both planning package and IPLAN\n\n### Depth Model (GOV §7)\n\n| Depth | Required Artifacts |\n|-------|-------------------|\n| Lite | BRD, PRD, IPLAN |\n| Standard | BRD, PRD, EARS, ADR, SPEC, TDD, IPLAN |\n| Full | BRD, PRD, EARS, BDD, ADR, SPEC, TDD, IPLAN + CHG gates |\n\n### Operational Steps from DEVELOPMENT_WORKFLOW_GUIDE.md §2\n\n1. Create planning roadmap for issue scope\n2. Create planning index listing required plan documents\n3. Define changelog plan for issue scope\n4. Run planning gap review and resolve or defer gaps with rationale\n5. Create and approve IPLAN\n\n## How to Load\n\nWhen loading `sdd-orchestrator` for SDD work:\n\n```\nskill_view(name='sdd-orchestrator', file_path='references/governance-load-protocol.md')\n```\n\nThis single file condenses the rules from all three governance documents.\n\nIf the full governance text is needed (rare), load individually:\n\n```\nskill_view(name='sdd-orchestrator', file_path='governance/GOVERNANCE_RULES.md')\nskill_view(name='sdd-orchestrator', file_path='governance/DEFINITION_OF_DONE.md')\nskill_view(name='sdd-orchestrator', file_path='governance/DEVELOPMENT_WORKFLOW_GUIDE.md')\n```\n\n## Maintenance\n\nAfter every UCX sync (`update-sdd-from-ucx`), review this file against the canonical governance documents. If upstream governance rules have changed, update this condensation.\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":4005,"content_sha256":"fa8d9f221e184b6810fa0c5a69038837bd819f5067ac3831b4f9b4b3ffe7f470"},{"filename":"references/hermes-agent-sdd-runtime-pattern.md","content":"# Hermes Agent as SDD Strategy Execution Runtime\n\n## Pattern\n\nWhen an SDD pipeline defines a strategy that must execute autonomously (trading agent, monitoring system, etc.), **Hermes Agent** can serve as the runtime orchestrator instead of building a custom execution engine. This pattern was proven with the TradeGent CC autonomous covered call trading agent (BRD-01 through BRD-10, ADR-21).\n\n## When to Use\n\n- SDD pipeline defines an autonomous strategy with scheduled check windows\n- Strategy requires external system integration (broker APIs, databases, webhooks)\n- MVP timeline is tight — building a custom orchestrator is too expensive\n- Strategy rules evolve over time — soft updates (skill patches) preferred over code deploys\n- Multi-platform operator alerting is needed (Telegram, Discord, etc.)\n\n## Architecture\n\n```\nHermes Agent (orchestration runtime)\n ├── cronjob: scheduled check windows (market hours, daily scans)\n ├── skills: SDD documents loaded as decision rules\n ├── memory: persistent state across sessions (positions, account, keys)\n ├── execute_code: apply strategy rules programmatically\n ├── MCP tools: broker/external system integration\n └── gateway: operator alerts via messaging platforms\n```\n\n## Implementation Steps\n\n### 1. Hermes Profile Setup\n\n```bash\nhermes profile create tradegent\nhermes -p tradegent config set agent.max_turns 120\nhermes -p tradegent tools enable cronjob memory delegation\n```\n\n### 2. Register External MCP Servers\n\n```bash\nhermes -p tradegent mcp add broker-ib \\\n --command \"/opt/data/tradegent/.venv/bin/python\" \\\n --args \"-m ib_mcp_server\" \\\n --cwd \"/opt/data/tradegent/\"\n```\n\n### 3. Create Strategy Skills from SDD Documents\n\nConvert each SDD document into a Hermes skill:\n\n- BRD → \"what to do\" (objectives, constraints)\n- PRD → \"how it works\" (features, capabilities)\n- EARS → \"formal rules\" (WHEN-THE-SHALL-WITHIN)\n- BDD → \"acceptance tests\" (Given-When-Then scenarios)\n\nSkills go in `~/.hermes/skills/tradegent/`.\n\n### 4. Schedule Cron Jobs\n\n```bash\n# Monday check window (9:30am EST)\nhermes -p tradegent cron create \"30 9 * * 1\" \\\n --prompt \"Run Monday morning check window per BRD-04. Fetch positions and quotes. Open new calls at delta-0.35. Load skills: brd-04, brd-03, prd-03, ears-04.\"\n\n# Wednesday afternoon check (3:00pm EST)\nhermes -p tradegent cron create \"0 15 * * 3\" \\\n --prompt \"Run Wednesday afternoon roll-out evaluation per BRD-04. Check DTE\u003c=2 positions. Evaluate net credit >= 0.80.\"\n```\n\n### 5. Configure Gateway for Alerts\n\n```bash\nhermes -p tradegent gateway setup # Configure Telegram/Discord\nhermes -p tradegent gateway install # Run as systemd service\n```\n\n## Advantages Over Custom Orchestrator\n\n| Aspect | Custom Orchestrator | Hermes Agent |\n|--------|-------------------|--------------|\n| Build time | 4-6 developer-weeks | ~1 developer-week |\n| Scheduling | Build cron + state machine | Built-in `cronjob` tool |\n| External APIs | Build integration layer | MCP servers (reusable) |\n| State persistence | Build database layer | Built-in `memory` tool |\n| Rule updates | Code redeploy | Skill patches (no deploy) |\n| Operator alerts | Build notification system | Built-in `gateway` (Telegram/Discord/etc.) |\n| Audit trail | Build logging pipeline | Session transcripts |\n| Multi-platform | N/A | 15+ messaging platforms |\n\n## Pitfalls\n\n- **LLM inference cost**: Each check window triggers a session (~5-10K tokens). At 5-10 checks/day, cost is ~$5-10/month. Acceptable for MVP; monitor for budget.\n- **Cron precision**: Minute-level, not sub-second. Acceptable for market-hour check windows (2-minute tolerance per EARS requirements).\n- **Single process**: Hermes crash during market hours requires watchdog. Configure systemd `Restart=always` with `RestartSec=2`.\n- **Strategy drift**: LLM may deviate from strict rulebook if skills are not sufficiently explicit. Write skills in imperative EARS syntax, not narrative.\n\n## Cost Comparison (TradeGent CC)\n\n| Item | Custom (ADR-01) | Hermes (ADR-21) |\n|------|----------------|-----------------|\n| Development | 6 developer-weeks | 1 developer-week |\n| Infrastructure | $200/month (Redis, etc.) | $0 (Hermes is open-source) |\n| LLM Inference | $0 | $5-10/month |\n| **Total MVP** | **6 weeks + $200/mo** | **1 week + $5-10/mo** |\n\n## Reference\n\nADR-21 documents this decision for the TradeGent CC project:\n`/opt/data/tradegent_covered_calls/05_ADR/ADR-21_hermes_orchestration_runtime.yaml`\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":4488,"content_sha256":"9717ea009f1c26858b5975fea8e22a7943d543b8d4764b326c25291373db5648"},{"filename":"references/id-naming-standards.md","content":"# ID Naming Standards — SDD v3.2\n\n## Document IDs\n\nFormat: `{TYPE}-{NN}` where TYPE is the artifact prefix and NN is a sequential two-digit number.\n\n| Artifact | Prefix | Example |\n|----------|--------|---------|\n| BRD | BRD | BRD-01 |\n| PRD | PRD | PRD-01 |\n| EARS | EARS | EARS-01 |\n| BDD | BDD | BDD-01 |\n| ADR | ADR | ADR-01 |\n| SPEC | SPEC | SPEC-01 |\n| TDD | TDD | TDD-01 |\n| IPLAN | IPLAN | IPLAN-01 |\n\n## Element IDs\n\nFormat: `{TYPE}.{doc_id}.{section_id}.{hash}`\n\n- `TYPE` — Upper case artifact prefix (e.g., BRD, SPEC)\n- `doc_id` — Two-digit document number (e.g., 01)\n- `section_id` — Two-digit section number (e.g., 03)\n- `hash` — 4-character hex content hash (SHA256, first 4 chars)\n\nExample: `BRD.01.07.a7f3`\n\n## Tag Format\n\n| Tag | Usage | Example |\n|-----|-------|---------|\n| `@brd: BRD.NN.SS.xxxx` | BRD references | `@brd: BRD.01.07.a7f3` |\n| `@prd: PRD.NN.SS.xxxx` | PRD references | `@prd: PRD.01.09.1dbc` |\n| `@ears: EARS.NN.SS.xxxx` | EARS references | `@ears: EARS.01.03.5e2a` |\n| `@bdd: BDD.NN.SS.xxxx` | BDD references | `@bdd: BDD.01.03.8f4c` |\n| `@adr: ADR.NN.SS.xxxx` | ADR references | `@adr: ADR.01.03.e5b1` |\n| `@spec: SPEC.NN` | SPEC references (document-level) | `@spec: SPEC-01` |\n| `@tdd: TDD.NN.SS.xxxx` | TDD references (test case level) | `@tdd: TDD.01.04.a3c1` |\n| `@iplan: IPLAN-NN` | IPLAN references (document-level) | `@iplan: IPLAN-01` |\n| `@threshold: TYPE.NN.key` | Performance thresholds | `@threshold: BRD.01.perf.p95_latency` |\n| `@depends: TYPE-NN` | Hard prerequisite | `@depends: BRD-01` |\n| `@discoverability: TYPE-NN` | Related document | `@discoverability: BRD-02` |\n\n## File Naming\n\n| File | Format | Example |\n|------|--------|---------|\n| Template | `{TYPE}-TEMPLATE.yaml` | `BRD-TEMPLATE.yaml` |\n| Index | `{TYPE}-00_index.md` (Layers 1-7) / `{TYPE}-00_index.yaml` (IPLAN) | `BRD-00_index.md` / `IPLAN-00_index.yaml` |\n| Document | `{TYPE}-NN.yaml` (BRD: `{TYPE}-NN_{slug}.yaml`) | `BRD-01_kyc_onboarding.yaml` |\n| README | `README.md` | — |\n| IPLAN Index | `{TYPE}-00_index.yaml` | `IPLAN-00_index.yaml` |\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":2079,"content_sha256":"24da0958d48b1bce29629f4bed4006ab689f9b633bc1b78242c81a5e8970057a"},{"filename":"references/layer-registry.yaml","content":"# SDD v3 Layer Registry\n# Single source of truth for all layer definitions\n# Version: 3.2\n# Last Updated: 2026-04-29\n\nversion: \"3.2\"\nmetadata:\n framework: \"Specification-Driven Development (SDD) v3 — Streamlined\"\n total_layers: 8\n maintainer: \"SDD Framework Team\"\n template_policy: unified_yaml\n changelog:\n - version: \"3.2-sec3\"\n date: \"2026-04-29\"\n changes:\n - \"Added CHG/ governance overlay: 5-gate change management system (GATE-01, GATE-03, GATE-06, GATE-08, GATE-CODE)\"\n - \"C1/C2/C3 change level naming (no collision with layer L1-L8 numbers)\"\n - \"12 files: template, index, README, 7 gate docs, 2 companion templates\"\n - version: \"3.2\"\n date: \"2026-04-29\"\n changes:\n - \"Swapped SPEC and TDD layer positions: ADR(L5) → SPEC(L6) → TDD(L7)\"\n - \"TDD now positioned after SPEC (logical: specify first, then define tests)\"\n - \"Expanded TDD template with test case definitions (inputs, outputs, edge cases)\"\n - \"Added spec_trace field to BDD for req-to-SPEC trace links\"\n - version: \"3.1\"\n date: \"2026-04-29\"\n changes:\n - \"Added Layer 8 IPLAN (optional implementation plan — bridges TDD to Code)\"\n - \"IPLAN solves Gap #4: execution bridge, session handoff, implementation contracts, audit trail\"\n - \"File manifest with test-first creation order\"\n - \"Stateless MCP executor session handoff protocol\"\n - version: \"3.0\"\n date: \"2026-04-28\"\n changes:\n - \"Established streamlined v3 baseline (BRD→PRD→EARS→BDD→ADR→TDD→SPEC)\"\n - \"Reduced documentation surface area and simplified layer responsibilities\"\n - \"Added Layer 6 TDD (lightweight test-driven development guide)\"\n - \"SPEC promoted to Layer 7 (unified, single template, no subtypes)\"\n - \"Maximum cumulative tags reduced to 6\"\n\nlayers:\n - number: 1\n artifact: BRD\n name: \"Business Requirements Document\"\n folder: 01_BRD/\n extensions: [.yaml]\n required_tags: []\n can_reference: []\n error_prefix: BRD\n optional: false\n description: \"Layer 1 — Business-level functional requirements and objectives\"\n template: \"BRD-TEMPLATE.yaml\"\n downstream: [PRD]\n\n - number: 2\n artifact: PRD\n name: \"Product Requirements Document\"\n folder: 02_PRD/\n extensions: [.yaml]\n required_tags: [brd]\n can_reference: [BRD]\n error_prefix: PRD\n optional: false\n description: \"Layer 2 — Product features and user stories derived from BRD\"\n template: \"PRD-TEMPLATE.yaml\"\n downstream: [EARS]\n\n - number: 3\n artifact: EARS\n name: \"Easy Approach to Requirements Syntax\"\n folder: 03_EARS/\n extensions: [.yaml]\n required_tags: [brd, prd]\n can_reference: [BRD, PRD]\n error_prefix: EARS\n optional: false\n description: \"Layer 3 — Formal requirements using WHEN-THE-SHALL-WITHIN syntax\"\n template: \"EARS-TEMPLATE.yaml\"\n downstream: [BDD]\n\n - number: 4\n artifact: BDD\n name: \"Behavior-Driven Development\"\n folder: 04_BDD/\n extensions: [.yaml]\n required_tags: [brd, prd, ears]\n can_reference: [BRD, PRD, EARS]\n error_prefix: BDD\n optional: false\n description: \"Layer 4 — Test scenarios using Given-When-Then format with req-to-SPEC trace links\"\n template: \"BDD-TEMPLATE.yaml\"\n downstream: [ADR]\n\n - number: 5\n artifact: ADR\n name: \"Architecture Decision Record\"\n folder: 05_ADR/\n extensions: [.yaml]\n required_tags: [brd, prd, ears, bdd]\n can_reference: [BRD, PRD, EARS, BDD]\n error_prefix: ADR\n optional: false\n description: \"Layer 5 — Architectural decisions with Context-Decision-Consequences\"\n template: \"ADR-TEMPLATE.yaml\"\n downstream: [SPEC]\n\n - number: 6\n artifact: SPEC\n name: \"Technical Specification\"\n folder: 06_SPEC/\n extensions: [.yaml]\n required_tags: [brd, prd, ears, bdd, adr]\n can_reference: [BRD, PRD, EARS, BDD, ADR]\n error_prefix: SPEC\n optional: false\n description: \"Layer 6 — Implementation-ready technical specification: interfaces, data models, behavior contracts\"\n template: \"SPEC-TEMPLATE.yaml\"\n downstream: [TDD]\n\n - number: 7\n artifact: TDD\n name: \"Test-Driven Development Guide\"\n folder: 07_TDD/\n extensions: [.yaml]\n required_tags: [brd, prd, ears, bdd, adr, spec]\n can_reference: [BRD, PRD, EARS, BDD, ADR, SPEC]\n error_prefix: TDD\n optional: false\n description: \"Layer 7 — Test case definitions, BDD-to-test mapping, quality thresholds, TDD execution order — defined from SPEC component contracts\"\n template: \"TDD-TEMPLATE.yaml\"\n downstream: [IPLAN]\n\n - number: 8\n artifact: IPLAN\n name: \"Implementation Plan\"\n folder: 08_IPLAN/\n extensions: [.yaml]\n required_tags: [brd, prd, ears, bdd, adr, spec, tdd]\n can_reference: [BRD, PRD, EARS, BDD, ADR, SPEC, TDD]\n error_prefix: IPLAN\n optional: false\n description: \"Layer 8 — Mandatory execution bridge: file manifest, bash commands, session handoff, code audit trail. One IPLAN per SPEC component. Temporary plans for bugfixes/corrections live in 08_IPLAN/tmp/.\"\n template: \"IPLAN-TEMPLATE.yaml\"\n downstream: [CODE]\n\nlayer_groups:\n business:\n layers: [1]\n description: \"Business requirements and objectives\"\n\n product:\n layers: [2, 3, 4]\n description: \"Product features, formal requirements, acceptance criteria\"\n\n architecture:\n layers: [5, 6]\n description: \"Architecture decisions and technical specification\"\n\n implementation:\n layers: [7, 8]\n description: \"Test definitions and execution planning\"\n\n# =============================================================================\n# C4 Architecture Model Mapping\n# =============================================================================\n# Maps the 4 C4 zoom levels to SDD v3.2 layers.\n#\n# | C4 Level | SDD Layers | Artifacts | Diagram Tags |\n# |-----------------|------------|---------------|----------------------------------|\n# | L1 Context | L1 | BRD | @diagram: c4-l1, @diagram: dfd-l1|\n# | L2 Container | L2 | PRD | @diagram: c4-l2, @diagram: dfd-l2|\n# | Decision Bridge | L3-L5 | EARS, BDD, ADR| none (decision sequence for ADR) |\n# | L3 Component | L6 | SPEC | @diagram: c4-l3, @diagram: dfd-l3|\n# | Implement Bridge| L7-L8 | TDD, IPLAN | none (test defs, execution plan) |\n# | L4 Code | Code | Source Code | @diagram: c4-l4 |\n#\n# Bridge layers (L3-L5, L7-L8) are SDD-specific refinements that don't\n# correspond directly to C4 zoom levels. They translate, validate, and\n# connect the C4 levels.\n\nc4_mapping:\n context:\n level: c4-l1\n sdd_layer: 1\n artifact: BRD\n diagram_tags: [\"@diagram: c4-l1\", \"@diagram: dfd-l1\"]\n description: \"System context — actors, external systems, business boundaries\"\n mandatory_purpose: \"Must describe the business environment, not product features\"\n\n container:\n level: c4-l2\n sdd_layer: 2\n artifact: PRD\n diagram_tags: [\"@diagram: c4-l2\", \"@diagram: dfd-l2\", \"@diagram: sequence-sync\"]\n description: \"Product containers — features, functional blocks, interactions\"\n mandatory_purpose: \"Must describe product-level interactions, not system internals\"\n\n decision_bridge:\n level: bridge\n sdd_layers: [3, 4, 5]\n artifacts: [EARS, BDD, ADR]\n description: \"Requirement formalization (EARS) → acceptance scenarios (BDD) → architecture decisions (ADR)\"\n note: \"Not a C4 level — bridges the transition from Container (PRD) to Component (SPEC)\"\n diagram_tags: [] # ADR uses decision sequence diagrams only; EARS/BDD none\n\n component:\n level: c4-l3\n sdd_layer: 6\n artifact: SPEC\n diagram_tags: [\"@diagram: c4-l3\", \"@diagram: dfd-l3\"]\n description: \"Component interfaces, data models, behavior contracts\"\n mandatory_purpose: \"Must define component boundaries — not architecture decisions or code\"\n\n implementation_bridge:\n level: bridge\n sdd_layers: [7, 8]\n artifacts: [TDD, IPLAN]\n description: \"Test case definitions (TDD) → execution planning (IPLAN)\"\n note: \"Not a C4 level — validates SPEC contracts and executes implementation\"\n diagram_tags: []\n\n code:\n level: c4-l4\n artifact: CODE\n diagram_tags: [\"@diagram: c4-l4\"]\n description: \"Source code class/package structure — C4-L4 ownership declared in code, referenced by IPLAN\"\n note: \"Not an SDD document layer — code is the output target\"\n\nid_patterns:\n document: \"^[A-Z]+-\\\\d{2,}$\"\n element: \"^[A-Z]+\\\\.\\\\d{2,}\\\\.\\\\d{2,}\\\\.[a-f0-9]{4,8}$\"\n","content_type":"application/yaml; charset=utf-8","language":"yaml","size":8649,"content_sha256":"f2de0e366e737eb32a30fd9a0de72c1f2c9b720f97ec96715724a0b497e9f45f"},{"filename":"references/plan-gap-review-checklist.md","content":"# Plan Gap Review Checklist\n\n**Purpose**: Concrete checklist for auditing a plan (PLAN-NNN or IPLAN-NNN) against SDD governance rules (GOVERNANCE_RULES.md §3) and Definition of Done (DEFINITION_OF_DONE.md — Plan/IPLAN Review Level).\n\n**When to use**: After writing a plan and before presenting it for approval. Run every gap item; resolve or explicitly defer each.\n\n---\n\n## Gap Categories (Audit Pass Order)\n\n### G1 — Changelog Plan\n\n- [ ] Does the plan define what changelog entries will be created?\n- [ ] Are the target files named (CHANGELOG.md, plans/CHANGELOG-PLAN.md, layer README)?\n- [ ] Are changelog entry formats consistent with project conventions?\n\n**GOV reference**: §3 step 4 — \"Define changelog plan for the scope\"\n**Common gap**: Plan has a \"Changelog Plan\" heading but only lists target documents, not actual entries.\n\n### G2 — Gap Review\n\n- [ ] Is there an explicit gap review section in the plan?\n- [ ] Are unknowns/unknowns enumerated (things not yet decided)?\n- [ ] Is each gap resolved or explicitly deferred with rationale?\n- [ ] Are deferred gaps assigned an owner (e.g., \"deferred to ADR\")?\n\n**GOV reference**: §3 step 5 — \"Review planning artifacts for gaps\"\n**Common gap**: Plan skips the gap review entirely — assumes everything is known.\n\n### G3 — Planning Index\n\n- [ ] Does `plans/README.md` or equivalent index this plan?\n- [ ] Is the plan's status column current?\n- [ ] Are downstream artifacts (e.g., new SDD document entries) reflected?\n\n**GOV reference**: §3 step 3 — \"Create planning document index\"\n**Common gap**: Plan written but never registered in the index — future sessions can't find it.\n\n### G4 — Upstream Dependencies\n\n- [ ] Are ALL upstream SDD artifacts that this work depends on listed?\n- [ ] Are cross-BRD dependencies complete (not just the obvious ones)?\n- [ ] Are data consumers listed (e.g., \"BRD-03 needs option chain from broker\")?\n\n**Common gap**: Feature BRD lists BRD-01 (umbrella) but misses the data-consumer BRDs that will use its output.\n\n### G5 — Roadmap Update Timing\n\n- [ ] Does the plan update the roadmap during planning, or defer to \"after creation\"?\n- [ ] If deferred, is there a clear handoff so the update doesn't get lost?\n\n**GOV reference**: §3 step 2 — \"Create planning roadmap for the target scope\"\n**Common gap**: Plan says \"update roadmap after document created\" but post-creation sessions forget.\n\n### G6 — ADR/Design Topics\n\n- [ ] Are architecture decision topics enumerated with sufficient coverage?\n- [ ] Are security, auth, credentials, isolation, and failover topics present?\n- [ ] Is there at least one topic per mandatory category (infrastructure, data, integration, security, observability)?\n\n**Common gap**: 7 ADR topics listed but auth/credentials, market data subscriptions, paper/live isolation, and order routing are missing.\n\n### G7 — Scope Boundary\n\n- [ ] Is there an explicit \"OUT of scope\" section?\n- [ ] Does it prevent the new artifact from absorbing content that belongs in existing artifacts?\n- [ ] Are deferred features listed with rationale?\n\n**Common gap**: Plan defines IN scope only — no boundary to prevent scope creep into adjacent BRDs.\n\n### G8 — Document Section Outline\n\n- [ ] Does the plan sketch what goes in each section of the target SDD document?\n- [ ] For BRDs: are all 18 sections accounted for with content expectations?\n- [ ] Is the outline detailed enough that generation won't miss sections?\n\n**Common gap**: Plan says \"generate BRD-10 per template\" without sketching section content.\n\n### G9 — CHG Governance\n\n- [ ] Is this a change to an existing layer? If so, is a CHG record included?\n- [ ] Does the plan document downstream impact (new PRD/EARS/BDD/etc. required)?\n- [ ] Is the change rationale documented?\n\n**Common gap**: Adding a BRD to a \"complete\" layer — no CHG record, no downstream impact analysis.\n\n### G10 — Validation Pre-Check\n\n- [ ] Does the plan verify that the new artifact won't conflict with existing artifacts?\n- [ ] Are cross-references to existing documents checked for accuracy before creation?\n- [ ] Is the target artifact numbered correctly (no collision with existing IDs)?\n\n**Common gap**: Plan doesn't check whether BRD-04 already covers the proposed BRD-10 scope.\n\n---\n\n## Quick Audit Commands\n\n```bash\n# G3: Check if plan is in index\ngrep -c \"PLAN-NNN\" plans/README.md\n\n# G4: Find all upstream BRD references\ngrep -oP 'BRD-\\d+' plans/PLAN-NNN_*.md | sort -u\n\n# G10: Check for scope overlap with existing documents\ngrep -l \"broker\\|order execution\\|position monitoring\" 01_BRD/BRD-*.yaml\n```\n\n---\n\n## TradeGent CC PLAN-009 Example (2026-05-14)\n\nInitial audit found 10 gaps across all 10 categories:\n\n- P0 (2): G1 (changelog plan missing), G2 (gap review missing)\n- P1 (5): G3, G4 (BRD-03/BRD-06 missing), G5, G6 (ADR topics incomplete), G7\n- P2 (3): G8, G9, G10\n\nAfter remediation: all 10 gaps resolved, plan approved, BRD-10 created and validated 100/100.\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":4953,"content_sha256":"d4e2549c4f4b631d598c77c25ecef73e8646614c822125f0027212a987871612"},{"filename":"references/programmatic-sdd-generation.md","content":"# Programmatic SDD Document Generation\n\n## When to Use\n\nGenerate a BRD, PRD, or other SDD YAML document programmatically via `execute_code` when:\n\n- The document has 500+ lines with many element IDs that need content-based hashing\n- You need deterministic hash generation (SHA256 first 4 chars) across many elements\n- YAML quoting edge cases (comparison operators, special chars) would cause iterative write/fail cycles\n- You're generating multiple documents from a common structure (batch)\n\n## Core Pattern\n\n```python\nimport hashlib, yaml, subprocess, datetime, re\n\ndef hash4(text):\n \"\"\"Produce 4-char hex hash for element IDs.\"\"\"\n clean = text.lower()[:100]\n return hashlib.sha256(clean.encode()).hexdigest()[:4]\n\ndef eid(section, title, desc=\"\"):\n \"\"\"Generate TYPE.NN.SS.xxxx element ID. Section can be int or string.\"\"\"\n if isinstance(section, int):\n sec_str = f\"{section:02d}\"\n else:\n sec_str = str(section)\n return f\"{doc_type}.{doc_id}.{sec_str}.{hash4(f'{doc_id}:{sec_str}:{title}:{desc}')}\"\n```\n\n## Document Assembly\n\nBuild the document as a Python dict following the template structure:\n\n```python\ndoc = {\n \"id\": \"BRD-10\",\n \"title\": \"Document Title\",\n \"metadata\": { ... }, # Schema version, layers, validation, C4 level, ID standard\n \"document_control\": { ... }, # Version, status, dates, revision_history\n \"executive_summary\": { ... },\n \"diagrams\": { ... }, # Required for PRD/BRD — must have items[]\n \"introduction\": { ... },\n \"business_objectives\": { ... }, # BRD only\n \"project_scope\": { ... }, # BRD only\n \"stakeholders\": { ... },\n \"functional_requirements\": {\n \"priority_definitions\": { \"P1\": \"...\", \"P2\": \"...\" },\n \"requirements\": [ ... ] # BRD format\n # OR\n \"core_capabilities\": [ ... ] # PRD format\n },\n \"adr_topics\": { ... }, # BRD only\n \"quality_expectations\": { ... },\n \"constraints_and_assumptions\": { ... },\n \"acceptance_criteria\": { ... }, # Different structure per layer\n \"risk_management\": { ... },\n \"approval\": { ... },\n \"traceability\": {\n \"tags\": [...],\n \"cross_links\": { \"depends\": [...], \"discoverability\": [...] },\n \"upstream\": { ... },\n \"downstream_expected\": [...],\n \"health_score\": { ... }\n },\n \"glossary\": { \"terms\": [...] },\n \"appendix\": { ... } # BRD only\n}\n```\n\n## Writing and Post-Processing\n\n```python\n# Dump YAML\nyaml_text = yaml.dump(doc, default_flow_style=False, allow_unicode=True, sort_keys=False, width=120)\n\n# Post-process: quote values starting with >=, \u003c=, >, \u003c\nlines = yaml_text.split('\\n')\nquoted = []\nfor line in lines:\n m = re.match(r'^(\\s+)(\\w[\\w\\s]*):\\s*(>=|\u003c=|>|\u003c)(.+)

SDD Orchestrator — Specification-Driven Development Workflow Engine Overview You orchestrate the SDD v3.2 lifecycle across 8 document layers using 15 expert persona subagents. Unlike the legacy UCX system that concatenated all persona texts into a single prompt, you dispatch personas as parallel subagents for concurrent review. Mandatory Governance Load (Before Any SDD Work) Before creating, reviewing, or remediating ANY SDD document, load the governance protocol: This single file condenses the planning-first rules from GOVERANCE RULES.md §2b/§3, DEFINITION OF DONE.md plan/IPLAN review level,…

, line)\n if m:\n indent, key, op, rest = m.groups()\n if not rest.startswith(\"'\") and not rest.startswith('\"'):\n line = f\"{indent}{key}: '{op}{rest}'\"\n quoted.append(line)\n\nfinal_yaml = '\\n'.join(quoted) + '\\n'\n\nwith open(output_path, 'w') as f:\n f.write(final_yaml)\n```\n\n## Verification\n\nAlways verify YAML validity immediately after writing:\n\n```python\nr = subprocess.run([\"python3\", \"-c\", f\"import yaml; d=yaml.safe_load(open('{output_path}')); print('YAML valid')\"],\n capture_output=True, text=True)\nif r.returncode != 0:\n print(f\"YAML ERROR: {r.stderr}\")\n```\n\n## Layer-Specific Requirements\n\n### BRD (Layer 1)\n\n- 18 top-level sections (template says 15, UCX validator accepts more)\n- Functional requirements use `requirements` list with `priority`, `complexity`, `business_needs`, `business_rules`, `acceptance_criteria`\n- Include `adr_topics` with 7+ topics\n- Include `appendix` with lifecycle and next_cycle_roadmap\n\n### PRD (Layer 2)\n\n- 15 top-level sections\n- `diagrams` section REQUIRED — must have `items[]` with at least 1 diagram entry\n- Functional requirements use `core_capabilities` with `brd_reference` hash links\n- Include `user_stories` with roles + stories in \"As a... I want... so that...\" format\n- Include `customer_facing_content` with positioning, key_messages, error_messages, success_messages\n- Include `diagram_contract` with containers + data_flows\n- User journey sequence diagram must include alt/else branches\n- ADR topic elaboration in traceability section\n\n## Quality Gate Checklist\n\nBefore calling generation complete, verify:\n\n- [ ] YAML parses cleanly\n- [ ] `sdd_validate` passes 0/0\n- [ ] Element IDs use content hashes (not sequential numbers)\n- [ ] BRD refs use hash-level `@brd: TYPE.NN.SS.xxxx` (not document-level `@brd: TYPE-NN`)\n- [ ] Diagram contract populated with containers + data_flows (PRD)\n- [ ] User journeys include alt/else error paths (PRD)\n- [ ] Customer-facing error messages have actionable guidance (PRD)\n- [ ] Traceability section has bidirectional cross-links\n\n## Pitfalls\n\n1. **read_file inside execute_code returns line-numbered output** — use `subprocess.run([\"cat\", path])` for clean YAML parsing\n2. **Comparison operators at line start** — quote `>=`, `\u003c=`, `>`, `\u003c` after yaml.dump()\n3. **Indentation errors from patch-based edits** — see `references/yaml-patch-indentation-fix.md`\n4. **sdd_validate template interference** — template files with `id: ADR-NN` collide with parse stream; move them aside\n5. **Filename heuristic bug** — long descriptive names like `BRD-08_performance_review_cadence.yaml` may be misclassified as Markdown; rename to `BRD-NN.yaml`\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":5440,"content_sha256":"1391183fefbf7362bda52aa14c2c18186c485799830d79439eea1840fe735aa8"},{"filename":"references/python-env-setup.md","content":"# Python Environment Setup on Systems with Conda\n\n## The Problem\n\nOn systems that have both `/opt/anaconda` (or any conda installation) and a\nsystem Python, `pyenv install` frequently fails when building Python 3.12+.\nThe build succeeds but the final `pip` bootstrap step dies:\n\n```\nInstalling pip from https://bootstrap.pypa.io/get-pip.py...\ncurl: /opt/anaconda/lib/libcurl.so.4: no version information available (required by curl)\nerror: failed to install pip via get-pip.py\n\nAttributeError: 'datetime.datetime' object has no attribute 'tb_frame'\n```\n\nRoot cause: conda's `libcurl.so.4` shadows the system curl, and the conda\nPython's `xmlrpc` module has an ABI mismatch with the freshly built 3.12\ninterpreter used to bootstrap pip.\n\n## The Solution\n\n**Use conda to create the environment directly** — it's already on the system\nand avoids the self-bootstrap problem entirely.\n\n```bash\n/opt/anaconda/bin/conda create -p /path/to/project/.venv python=3.12.13 -y\n```\n\nThe resulting environment lives at `\u003cproject>/.venv/bin/python` and works\nidentically to a venv or pyenv install.\n\n### Checking for Conda\n\n```bash\nls /opt/anaconda/bin/conda # most common location\nfind /opt -maxdepth 3 -name \"conda\" -type f 2>/dev/null\n```\n\n### Fallback If Conda Is Not Available\n\nInstall pyenv build dependencies first:\n\n```bash\nsudo apt-get install -y build-essential libssl-dev zlib1g-dev \\\n libbz2-dev libreadline-dev libsqlite3-dev libncursesw5-dev \\\n xz-utils tk-dev libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev\n```\n\nThen temporarily unset conda from PATH before building:\n\n```bash\nPATH=$(echo \"$PATH\" | tr ':' '\\n' | grep -v anaconda | tr '\\n' ':')\npyenv install 3.12.13\n```\n\n## When to Use Which\n\n| Project Type | Preferred Method |\n|-------------|-----------------|\n| SDD project (needs yaml, hashlib) | conda create (fast, no build) |\n| CI/CD container (no conda) | pyenv or apt install python3.12 |\n| User wants specific patch version | conda create with `python=3.12.13` |\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":1981,"content_sha256":"5c39f6aeff5500a082334e840f1bd2f46d5865e29b2f2774a0c1cf4fe8f6e45d"},{"filename":"references/quick-reference.md","content":"# Quick Reference — SDD v3.2\n\n## 8-Layer Chain\n\n```\nBRD → PRD → EARS → BDD → ADR → SPEC → TDD → IPLAN → Code\n```\n\n## Templates\n\n| Layer | Template | Upstream Tags |\n|-------|----------|---------------|\n| L1 BRD | [BRD-TEMPLATE.yaml](01_BRD/BRD-TEMPLATE.yaml) | — |\n| L2 PRD | [PRD-TEMPLATE.yaml](02_PRD/PRD-TEMPLATE.yaml) | @brd |\n| L3 EARS | [EARS-TEMPLATE.yaml](03_EARS/EARS-TEMPLATE.yaml) | @brd @prd |\n| L4 BDD | [BDD-TEMPLATE.yaml](04_BDD/BDD-TEMPLATE.yaml) | @brd @prd @ears |\n| L5 ADR | [ADR-TEMPLATE.yaml](05_ADR/ADR-TEMPLATE.yaml) | @brd @prd @ears @bdd |\n| L6 SPEC | [SPEC-TEMPLATE.yaml](06_SPEC/SPEC-TEMPLATE.yaml) | @brd @prd @ears @bdd @adr |\n| L7 TDD | [TDD-TEMPLATE.yaml](07_TDD/TDD-TEMPLATE.yaml) | @brd @prd @ears @bdd @adr @spec |\n| L8 IPLAN | [IPLAN-TEMPLATE.yaml](08_IPLAN/IPLAN-TEMPLATE.yaml) | @brd @prd @ears @bdd @adr @spec @tdd |\n\n## Key Files\n\n| File | Purpose |\n|------|---------|\n| [LAYER_REGISTRY.yaml](LAYER_REGISTRY.yaml) | Authoritative layer definitions |\n| [SPEC_DRIVEN_DEVELOPMENT_GUIDE.md](SPEC_DRIVEN_DEVELOPMENT_GUIDE.md) | SDD methodology |\n| [ID_NAMING_STANDARDS.md](ID_NAMING_STANDARDS.md) | Document and element ID formats |\n| [TRACEABILITY.md](TRACEABILITY.md) | Cross-layer traceability rules |\n| [DIAGRAM_STANDARDS.md](DIAGRAM_STANDARDS.md) | Mermaid diagram conventions |\n| [THRESHOLD_NAMING_RULES.md](THRESHOLD_NAMING_RULES.md) | Threshold key naming |\n| [TESTING_STRATEGY_TDD.md](TESTING_STRATEGY_TDD.md) | TDD integration |\n| [CHG_MIGRATION_PLAN.md](plans/CHG_MIGRATION_PLAN.md) | v2→v3 migration details |\n\n## Readiness Gates\n\n| Gate | Target | Check |\n|------|--------|-------|\n| PRD-Ready | >=90/100 | BRD objectives, requirements, scope complete |\n| EARS-Ready | >=90/100 | PRD features, user stories, domain clarity |\n| BDD-Ready | >=90/100 | EARS syntax, atomicity, testability |\n| ADR-Ready | >=90/100 | BDD scenarios, Gherkin quality, edge cases |\n| TDD-Ready | >=90/100 | SPEC interfaces, data models, behavior contracts |\n| IPLAN-Ready | >=90/100 | TDD test case coverage, threshold definitions |\n| EXEC-Ready | >=90/100 | IPLAN file manifest completeness, execution commands, contracts |\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":2170,"content_sha256":"a424d2c6fbaf70c98f137f221ce50b79340d616a7801912636049d054a593498"},{"filename":"references/traceability.md","content":"# Traceability — SDD v3.2\n\n## Traceability Chain\n\n```\nBRD (L1) → PRD (L2) → EARS (L3) → BDD (L4) → ADR (L5) → SPEC (L6) → TDD (L7) → IPLAN (L8) → Code\n```\n\n## Cumulative Tagging\n\nEach layer inherits and adds one tag:\n\n```\nLayer 1 (BRD): @brd\nLayer 2 (PRD): @brd @prd\nLayer 3 (EARS): @brd @prd @ears\nLayer 4 (BDD): @brd @prd @ears @bdd\nLayer 5 (ADR): @brd @prd @ears @bdd @adr\nLayer 6 (SPEC): @brd @prd @ears @bdd @adr @spec\nLayer 7 (TDD): @brd @prd @ears @bdd @adr @spec @tdd\nLayer 8 (IPLAN): @brd @prd @ears @bdd @adr @spec @tdd @iplan\n```\n\nMaximum 8 cumulative tags at IPLAN layer.\n\n## Upstream/Downstream Validation\n\n| Layer | Required Upstream Tags | Validated Downstream |\n|-------|----------------------|---------------------|\n| BRD | — | PRD |\n| PRD | @brd | EARS |\n| EARS | @brd, @prd | BDD |\n| BDD | @brd, @prd, @ears | ADR |\n| ADR | @brd, @prd, @ears, @bdd | SPEC |\n| SPEC | @brd, @prd, @ears, @bdd, @adr | TDD |\n| TDD | @brd, @prd, @ears, @bdd, @adr, @spec | IPLAN |\n| IPLAN | @brd, @prd, @ears, @bdd, @adr, @spec, @tdd | Code |\n\n## Layer Readiness Gates\n\nEach layer must achieve a readiness score >=90/100 before generating its immediate downstream artifact:\n\n| Gate | Score | Criteria |\n|------|-------|----------|\n| PRD-Ready | >=90 | BRD completeness in business objectives, requirements, scope |\n| EARS-Ready | >=90 | PRD completeness in features, user stories, domain clarity |\n| BDD-Ready | >=90 | EARS syntax compliance, atomicity, testability, spec_trace links |\n| ADR-Ready | >=90 | BDD scenario coverage, Gherkin quality, edge cases |\n| TDD-Ready | >=90 | SPEC interface clarity, data model, behavior contracts |\n| IPLAN-Ready | >=90 | TDD test case coverage, threshold definitions, execution order |\n| EXEC-Ready | >=90 | IPLAN file manifest completeness, execution commands, session handoff |\n\n## Cross-Document Dependencies\n\n- `@depends: TYPE-NN` — Hard prerequisite. Downstream cannot exist without upstream.\n- `@discoverability: TYPE-NN` — Related document for AI search context.\n- `@threshold: TYPE.NN.key` — Performance or quality threshold reference.\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":2119,"content_sha256":"60f0379389e44ad469f09adf0b191690d3206e7b4d0f49449b51796b06c06b53"}],"content_json":{"type":"doc","content":[{"type":"heading","attrs":{"level":1},"content":[{"text":"SDD Orchestrator — Specification-Driven Development Workflow Engine","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Overview","type":"text"}]},{"type":"paragraph","content":[{"text":"You orchestrate the SDD v3.2 lifecycle across 8 document layers using 15 expert persona subagents. Unlike the legacy UCX system that concatenated all persona texts into a single prompt, you dispatch personas as ","type":"text"},{"text":"parallel subagents","type":"text","marks":[{"type":"strong"}]},{"text":" for concurrent review.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Mandatory Governance Load (Before Any SDD Work)","type":"text"}]},{"type":"paragraph","content":[{"text":"Before creating, reviewing, or remediating ANY SDD document, load the governance protocol:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"skill_view(name='sdd-orchestrator', file_path='references/governance-load-protocol.md')","type":"text"}]},{"type":"paragraph","content":[{"text":"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. ","type":"text"},{"text":"Skip this load step = governance violation.","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"If the protocol file is missing or stale (after a UCX framework sync), fall back to loading the three governance docs individually via:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"skill_view(name='sdd-orchestrator', file_path='governance/GOVERNANCE_RULES.md')\nskill_view(name='sdd-orchestrator', file_path='governance/DEFINITION_OF_DONE.md')\nskill_view(name='sdd-orchestrator', file_path='governance/DEVELOPMENT_WORKFLOW_GUIDE.md')","type":"text"}]},{"type":"paragraph","content":[{"text":"These docs contain the planning-first gates (§3), Definition of Done for plan/IPLAN review level, depth model selection, plan types and storage rules (§2b), and the full agent operating model.","type":"text"}]},{"type":"paragraph","content":[{"text":"Governance docs are read ","type":"text"},{"text":"directly from the repository","type":"text","marks":[{"type":"strong"}]},{"text":" (","type":"text"},{"text":"framework/","type":"text","marks":[{"type":"code_inline"}]},{"text":" tree); per D-0013 (aidoc-flow migration), there is no local sync — re-stale-checks are not needed.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"SDD Layer Sequence (v3.2)","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"BRD (L1) → PRD (L2) → EARS (L3) → BDD (L4) → ADR (L5) → SPEC (L6) → TDD (L7) → IPLAN (L8) → Code","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Layer Descriptions","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Layer","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Artifact","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Purpose","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Upstream","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Downstream","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"L1","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"BRD","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Business requirements, objectives, scope","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"—","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"PRD","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"L2","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"PRD","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Product features, user stories, ADR topics","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"BRD","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"EARS","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"L3","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"EARS","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Formal requirements (WHEN-THE-SHALL-WITHIN)","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"BRD, PRD","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"BDD","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"L4","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"BDD","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Executable acceptance scenarios with spec_trace","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"BRD, PRD, EARS","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"ADR","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"L5","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"ADR","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Architecture decisions (Context-Decision-Consequences)","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"BRD, PRD, EARS, BDD","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"SPEC","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"L6","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"SPEC","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Component interfaces, data models, behavior contracts","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"BRD, PRD, EARS, BDD, ADR","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"TDD","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"L7","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"TDD","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Test case definitions, BDD-to-test mapping, quality thresholds","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"BRD through SPEC","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"IPLAN","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"L8","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"IPLAN","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Execution plan: file manifest, bash commands, session handoff","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"BRD through TDD","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Code","type":"text"}]}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"What Was Cut from v2","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Cut","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Replaced By","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"SYS (L6)","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"ADR captures architecture; PRD captures scope","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"REQ (L7)","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"EARS + BDD spec_trace provide requirement-to-spec links","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"CTR (L8)","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"SPEC interface contracts handled inline","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"TSPEC (L10)","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"TDD (L7) with embedded test case definitions","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"TASKS (L11)","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"IPLAN (L8) execution bridge with session handoff","type":"text"}]}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Persona Name Mapping (UCX → Hermes Skill)","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"UCX Name","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Hermes Skill Name","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"architect","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"system-architect","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"auditor","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"security-auditor","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"tech_lead","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"technical-lead","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"strategist","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"business-strategist","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"chaos_engineer","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"chaos-engineer","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"operator","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"site-reliability-engineer","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"integration_lead","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"integration-specialist","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"product_owner","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"product-owner","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"business_analyst","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"business-analyst","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"fact_checker","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"fact-checker","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"chairperson","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"board-chairperson","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"qa_lead","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"qa-lead","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"content_strategist","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"content-strategist","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"requirements_specialist","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"requirements-specialist","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"ux_strategist","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"ux-strategist","type":"text"}]}]}]}]},{"type":"hr","attrs":{"markup":"---"}},{"type":"hr","attrs":{"markup":"---"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"Hermes Agent as SDD Strategy Execution Runtime","type":"text"}]},{"type":"paragraph","content":[{"text":"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.","type":"text"}]},{"type":"paragraph","content":[{"text":"Pattern documented in: ","type":"text"},{"text":"references/hermes-agent-sdd-runtime-pattern.md","type":"text","marks":[{"type":"code_inline"}]}]},{"type":"paragraph","content":[{"text":"Key integration points:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"cronjob","type":"text","marks":[{"type":"strong"}]},{"text":": Schedule check windows at precise times (market hours, daily scans)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"skills","type":"text","marks":[{"type":"strong"}]},{"text":": Load SDD documents as decision rules — soft updates via skill patches","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"MCP servers","type":"text","marks":[{"type":"strong"}]},{"text":": Register broker/external system MCP servers as Hermes tools","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"memory","type":"text","marks":[{"type":"strong"}]},{"text":": Persist state across sessions (positions, account data, idempotency keys)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"gateway","type":"text","marks":[{"type":"strong"}]},{"text":": Multi-platform operator alerts (Telegram, Discord, etc.)","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Cost comparison: ~1 developer-week + $5-10/month (LLM inference) vs 4-6 developer-weeks + $200/month for custom orchestrator.","type":"text"}]},{"type":"paragraph","content":[{"text":"See ADR-21 for a complete implementation example (TradeGent CC).","type":"text"}]},{"type":"paragraph","content":[{"text":"NO SDD DOCUMENT MAY BE CREATED, REVIEWED, OR REMEDIATED WITHOUT A WRITTEN AND APPROVED PLAN.","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"Before any document creation (Phase 1), the following planning package MUST exist and be explicitly approved by the human:","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Required Planning Artifacts","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Planning Roadmap","type":"text","marks":[{"type":"strong"}]},{"text":" — ","type":"text"},{"text":"plans/ROADMAP.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" or ","type":"text"},{"text":"governance/plans/ROADMAP.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" listing all intended SDD layers and their dependencies","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Planning Index","type":"text","marks":[{"type":"strong"}]},{"text":" — ","type":"text"},{"text":"governance/plans/README.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" or ","type":"text"},{"text":".hermes/plans/README.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" listing required plan documents","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Changelog Plan","type":"text","marks":[{"type":"strong"}]},{"text":" — Document tracking expected changes per layer","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"IPLAN or Development Plan","type":"text","marks":[{"type":"strong"}]},{"text":" — ","type":"text"},{"text":"governance/plans/PLAN-NNN_{slug}.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" (preferred) or ","type":"text"},{"text":".hermes/plans/YYYY-MM-DD_HHMMSS-{slug}.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" per the ","type":"text"},{"text":"plan","type":"text","marks":[{"type":"code_inline"}]},{"text":" skill","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Planning Gate Checklist (Execute Before Phase 1)","type":"text"}]},{"type":"checkbox_list","attrs":{"id":null},"content":[{"type":"checkbox_item","attrs":{"checked":false},"content":[{"type":"paragraph","content":[{"text":"Planning roadmap exists for project scope","type":"text"}]}]},{"type":"checkbox_item","attrs":{"checked":false},"content":[{"type":"paragraph","content":[{"text":"Planning index lists required plan artifacts","type":"text"}]}]},{"type":"checkbox_item","attrs":{"checked":false},"content":[{"type":"paragraph","content":[{"text":"Changelog plan exists for issue scope","type":"text"}]}]},{"type":"checkbox_item","attrs":{"checked":false},"content":[{"type":"paragraph","content":[{"text":"Planning gap review completed (resolved or deferred with rationale)","type":"text"}]}]},{"type":"checkbox_item","attrs":{"checked":false},"content":[{"type":"paragraph","content":[{"text":"IPLAN or development plan exists and is explicitly approved by human","type":"text"}]}]},{"type":"checkbox_item","attrs":{"checked":false},"content":[{"type":"paragraph","content":[{"text":"Human has explicitly approved proceeding to document creation","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"If any checklist item is missing: STOP. Do not proceed to Phase 1. Create the missing artifact or ask the human for direction.","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"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 ","type":"text"},{"text":"references/plan-gap-review-checklist.md","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"BRD-to-Source Coverage Audit (For BRD Layer Initialization)","type":"text"}]},{"type":"paragraph","content":[{"text":"When initializing a project's BRD layer from a large source document (rulebook, strategy doc, etc.):","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Extract all section headers","type":"text","marks":[{"type":"strong"}]},{"text":" from the source document — use ","type":"text"},{"text":"grep -n '^# '","type":"text","marks":[{"type":"code_inline"}]},{"text":" for markdown, or equivalent for the format","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Build a coverage matrix","type":"text","marks":[{"type":"strong"}]},{"text":": each source section → proposed BRD assignment + rationale","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Identify gaps","type":"text","marks":[{"type":"strong"}]},{"text":": unassigned sections, vague assignments (\"folded into BRD-X\" without explicit rationale), content blocks between section boundaries not captured by any header","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Verify 100% coverage","type":"text","marks":[{"type":"strong"}]},{"text":" — every source unit must have an explicit BRD home or a deliberate exclusion with rationale","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Check for orphan content","type":"text","marks":[{"type":"strong"}]},{"text":" — sections with no natural BRD home may indicate missing BRDs in the architecture","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"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.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"UCX Governance Compliance","type":"text"}]},{"type":"paragraph","content":[{"text":"This phase implements the UCX ","type":"text"},{"text":"DEVELOPMENT_WORKFLOW_GUIDE.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" §2 \"Planning-First Requirement\":","type":"text"}]},{"type":"blockquote","content":[{"type":"paragraph","content":[{"text":"Before implementation starts, complete this sequence: create planning roadmap → create planning index → define changelog plan → run planning gap review → create and approve IPLAN.","type":"text"}]}]},{"type":"paragraph","content":[{"text":"Reference: ","type":"text"},{"text":"governance/templates/PROJECT_KICKOFF_PLAN-TEMPLATE.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" for project-level planning structure.","type":"text"}]},{"type":"hr","attrs":{"markup":"---"}},{"type":"heading","attrs":{"level":3},"content":[{"text":"Batch ADR Generation from BDD","type":"text"}]},{"type":"paragraph","content":[{"text":"For the complete ADR generation pipeline across 19 documents (9 engine + 10 cross-cutting), see ","type":"text"},{"text":"references/adr-generation-from-bdd.md","type":"text","marks":[{"type":"code_inline"}]},{"text":". This reference captures:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Pre-generation checklist (hash fixes, validation verification)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Subagent timeout workaround (pre-extract upstream data, direct write_file, retry-on-timeout pattern)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"UCX sdd_validate template interference bug and workaround (moving 3 template files to /tmp)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Benchmark-first strategy (ADR-01 + ADR-07 first, then batch engine ADRs, then cross-cutting)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Cross-cutting ADR topics (Event Bus, Auth, Calendar, Idempotency, Regulatory/WORM, Observability, Alerting, Backpressure, Input Validation, Encryption)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"BDD deferred findings → ADR coverage matrix","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"ADR numbering convention (ADR-01-09 = engines, ADR-10-19 = cross-cutting)","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Broker Backend Integration Architecture (Two-Layer MCP Pattern)","type":"text"}]},{"type":"paragraph","content":[{"text":"For the complete broker backend integration architecture — Internal API + per-broker MCP servers with Interactive Brokers — see ","type":"text"},{"text":"references/broker-mcp-architecture-pattern.md","type":"text","marks":[{"type":"code_inline"}]},{"text":". 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.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Cross-Document Registration Sweep (Layer Completion)","type":"text"}]},{"type":"paragraph","content":[{"text":"When a full pipeline (BRD→PRD→EARS→BDD→ADR) is completed for a document number NN, run a registration sweep across ALL index files:","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"plans/README.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" — update plan status + add new rows in SDD Document Artifacts table for each layer","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"01_BRD/BRD-00_index.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" — add to document registry table","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"02_PRD/PRD-00_index.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" — add row after template row (format: ","type":"text"},{"text":"| [PRD-NN](./PRD-NN.yaml) \\| Title \\| Status \\| Related BRD \\| Features \\| Priority \\| Date |","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"03_EARS/EARS-00_index.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" — add row after template row","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"04_BDD/BDD-00_index.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" — add row after template row","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"05_ADR/ADR-00_index.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" — add row to architecture index table","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"CHANGELOG.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" — add pipeline entry under [Unreleased] with all layer versions and scores","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"plans/BRD-PLANNING-ROADMAP.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" — update status to COMPLETE","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Each layer document: update ","type":"text"},{"text":"downstream_expected","type":"text","marks":[{"type":"code_inline"}]},{"text":" to reference the actual downstream document IDs (e.g., \"see PRD-10\", \"see EARS-10\")","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"ADR cross-cutting: verify the new ADR references all relevant cross-cutting ADRs (idempotency, rate limiting, validation, secrets, event bus)","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"sdd_validate UCX Template Interference (ADR Layer)","type":"text"}]},{"type":"paragraph","content":[{"text":"The UCX validator discovers template files across the entire project tree AND framework directories. Templates containing ","type":"text"},{"text":"id: ADR-NN","type":"text","marks":[{"type":"code_inline"}]},{"text":" (or ","type":"text"},{"text":"_id: ADR-NN","type":"text","marks":[{"type":"code_inline"}]},{"text":") collide with the parse stream and cause spurious validation failures even when the actual document is structurally valid.","type":"text"}]},{"type":"paragraph","content":[{"text":"Files that must be temporarily moved (4 locations):","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Project: ","type":"text"},{"text":"UCX/templates/layers/05_ADR/ADR-TEMPLATE.yaml","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Framework: ","type":"text"},{"text":"framework/layers/05_ADR/ADR-TEMPLATE.yaml","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"MCP: ","type":"text"},{"text":"ucx_hermes/templates/ADR-TEMPLATE.yaml","type":"text","marks":[{"type":"code_inline"}]},{"text":" AND ","type":"text"},{"text":"mcp_ucx/templates/ADR-TEMPLATE.yaml","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Legacy: ","type":"text"},{"text":"ai_dev_ssd_flow_v2/05_ADR/ADR-TEMPLATE.yaml","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"paragraph","content":[{"text":"Workaround","type":"text","marks":[{"type":"strong"}]},{"text":": 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.","type":"text"}]},{"type":"paragraph","content":[{"text":"Do NOT patch ","type":"text","marks":[{"type":"strong"}]},{"text":"_id: ADR-NN","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" to ","type":"text","marks":[{"type":"strong"}]},{"text":"_id: ADR-00","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" — the validator still discovers framework-level templates that cannot be patched (read-only framework directories).","type":"text"}]},{"type":"paragraph","content":[{"text":"Restore immediately after validation","type":"text","marks":[{"type":"strong"}]},{"text":" — ","type":"text"},{"text":"sdd_init","type":"text","marks":[{"type":"code_inline"}]},{"text":" regenerates any missing templates.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Inline ADR Review (No Executor Required)","type":"text"}]},{"type":"paragraph","content":[{"text":"When UCX ","type":"text"},{"text":"sdd_review","type":"text","marks":[{"type":"code_inline"}]},{"text":" executors are unavailable (no API keys, auth failures) or the 48KB review prompt would time out subagent dispatch, run the 5-persona review ","type":"text"},{"text":"inline","type":"text","marks":[{"type":"strong"}]},{"text":" in the main agent context by reading ADR sections and applying persona criteria directly.","type":"text"}]},{"type":"paragraph","content":[{"text":"See ","type":"text"},{"text":"references/adr-review-inline-pattern.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" for the full pattern, review template structure, metadata update conventions, and common P1 finding categories.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Subagent Timeout Recovery (Large Document Generation)","type":"text"}]},{"type":"paragraph","content":[{"text":"When subagent generation times out at 600s on large documents (>50KB output expected):","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Pre-extract upstream data into the subagent prompt (don't make subagent read 6 files)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Retry solo on timeout — check file mtime; if advanced, subagent wrote before timing out","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Fall back: build YAML via execute_code and write_file directly","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"ADR-04 needed 5 dispatch attempts; ADR-09 needed direct write_file after 3 timeouts","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"delegate_task Parameter Format","type":"text"}]},{"type":"paragraph","content":[{"text":"delegate_task","type":"text","marks":[{"type":"code_inline"}]},{"text":" has two modes. Do NOT mix them — the function rejects hybrid calls:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Batch mode","type":"text","marks":[{"type":"strong"}]},{"text":": ","type":"text"},{"text":"delegate_task(tasks=[{context, goal, role, toolsets}, ...])","type":"text","marks":[{"type":"code_inline"}]},{"text":" — passes a JSON array","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Single mode","type":"text","marks":[{"type":"strong"}]},{"text":": ","type":"text"},{"text":"delegate_task(context=..., goal=..., role=..., toolsets=[...])","type":"text","marks":[{"type":"code_inline"}]},{"text":" — passes individual fields","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Error symptom: \"Provide either 'goal' (single task) or 'tasks' (batch).\" This fires when you pass both ","type":"text"},{"text":"tasks","type":"text","marks":[{"type":"code_inline"}]},{"text":" (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.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Batch PRD Generation from BRDs","type":"text"}]},{"type":"paragraph","content":[{"text":"After all BRDs are validated and reviewed, generate PRDs for each BRD.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Quality Gate (from TradeGent CC 2026-05-07 Review)","type":"text"}]},{"type":"paragraph","content":[{"text":"5/5 persona reviewers independently rejected \"lightweight\" PRDs as unbuildable stubs.","type":"text","marks":[{"type":"strong"}]},{"text":" 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.","type":"text"}]},{"type":"paragraph","content":[{"text":"Correct pattern","type":"text","marks":[{"type":"strong"}]},{"text":": Decompose EVERY BRD functional requirement into a PRD core capability with:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Hash-level BRD references: ","type":"text"},{"text":"@brd: BRD.NN.07.xxxx","type":"text","marks":[{"type":"code_inline"}]},{"text":" (not document-level ","type":"text"},{"text":"@brd: BRD-NN","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Populated diagram_contract with containers + data_flows (not empty ","type":"text"},{"text":"{}","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"User journeys with alt/else error branches","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Feature-specific error messages with actionable guidance","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"adr_topic_elaboration in traceability section","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"3-7 capabilities per feature PRD, 3-5 user stories, 370-450 lines","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"The umbrella PRD remains full-detail (500+ lines). Feature PRDs follow the same pattern at ~400 lines each.","type":"text"}]},{"type":"paragraph","content":[{"text":"For the complete batch generation script, see ","type":"text"},{"text":"references/batch-prd-generation-from-brds.md","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Batch Pipeline Execution — Single Feature Branch (BRD→BDD)","type":"text"}]},{"type":"paragraph","content":[{"text":"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 ","type":"text"},{"text":"references/batch-pipeline-execution.md","type":"text","marks":[{"type":"code_inline"}]},{"text":". Covers per-layer persona assignments, common fix types, metadata update patterns, and cross-layer consistency checks.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"EARS Generation from PRDs (Layer 3)","type":"text"}]},{"type":"paragraph","content":[{"text":"After all PRDs are validated, reviewed, and remediated, generate EARS documents.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"EARS Syntax Enforcement (Critical — from TradeGent CC 2026-05-07)","type":"text"}]},{"type":"paragraph","content":[{"text":"PROHIBITED QUALIFIERS (replace with quantified targets): \"real-time\" → \"WITHIN 60 seconds\" | \"immediate/immediately\" → \"WITHIN N seconds\" \"continuously\" → \"at each [event]\" | \"fast/quickly\" → \"p50 \u003c Nms, p95 \u003c Nms\" \"near X\" → \"within 0.0Y of X\"","type":"text"}]},{"type":"paragraph","content":[{"text":"STRUCTURAL RULES:","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"No compound WHEN with AND — split into atomic requirements","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"No nested IF inside SHALL — each conditional path is a separate requirement","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"WITHIN must reference a specific event (not orphaned \"WITHIN 5 minutes\")","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"IF/WITHIN must reference the same event","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"No subjective criteria (\"acceptable\", \"reasonable\", \"significant\")","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Atomicity: one testable concept per requirement","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Quantify interval ranges (not \"every 15-25 min\")","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"STATE MACHINE: every EARS touching operational modes MUST include a state_machine section with AUTONOMOUS → WARNING → HALTED → MANUAL → RECONCILING states and full transition triggers.","type":"text"}]},{"type":"paragraph","content":[{"text":"For the complete EARS rules, state machine template, and batch generation script, see ","type":"text"},{"text":"references/ears-generation-pattern.md","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Benchmarks-First Strategy","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Generate 2 benchmark EARS from the strongest upstream sources (umbrella + core feature)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Validate both with sdd_validate","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Review with 4 personas: requirements-specialist, technical-lead, qa-lead, chaos-engineer","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Remediate findings","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Once validated, batch-generate remaining 7 EARS with execute_code","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Batch BDD Generation from EARS (Layer 4)","type":"text"}]},{"type":"paragraph","content":[{"text":"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 ","type":"text"},{"text":"references/batch-bdd-generation-from-ears.md","type":"text","marks":[{"type":"code_inline"}]},{"text":". For the post-generation review, remediation, and deferral rules (5-persona parallel review, chairperson scoring, ADR-blocked deferrals), see ","type":"text"},{"text":"references/bdd-batch-review-remediation.md","type":"text","marks":[{"type":"code_inline"}]},{"text":". For the post-generation review, remediation, and deferral rules (5-persona parallel review, chairperson scoring, ADR-blocked deferrals), see ","type":"text"},{"text":"references/bdd-batch-review-remediation.md","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"After BDD layer completion (all docs health >= 8), plan the ADR layer before generation. ","type":"text"},{"text":"references/adr-layer-planning-and-gap-review.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" 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.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"BDD Scenario Mapping Rules","type":"text"}]},{"type":"paragraph","content":[{"text":"Every BDD document must translate EARS requirements into executable Given-When-Then scenarios:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Event-driven EARS","type":"text","marks":[{"type":"strong"}]},{"text":" → success scenarios: extract WHEN from statement as Given/When, THE-SHALL as Then","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"State-driven EARS","type":"text","marks":[{"type":"strong"}]},{"text":" → success scenarios: WHILE condition as Given, monitoring cycle as When, behavioral outcome as Then","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Unwanted-behavior EARS","type":"text","marks":[{"type":"strong"}]},{"text":" → error scenarios: IF condition as Given, detection as When, escalation/logging as Then","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Ubiquitous EARS","type":"text","marks":[{"type":"strong"}]},{"text":" → dedicated success scenarios: verify completeness across all decision types (queryable, immutable, structured)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"At least 1 recovery scenario per BDD (state transition restoration, post-failure reconciliation, transient retry)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Minimum 5 scenarios per BDD: 3-4 success, 1-2 error, 1 recovery","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Benchmark BDDs (umbrella + core engine) should reach 13-19 scenarios after review/remediation","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Pragmatic Remediation Scope (What Belongs Where)","type":"text"}]},{"type":"paragraph","content":[{"text":"Not every finding from a persona review belongs at the BDD layer. Apply this triage:","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Finding Type","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Remediate In","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Rationale","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Missing EARS requirement coverage","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"BDD","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"BDD's job is to cover all formal requirements","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"State machine transition gaps","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"BDD","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Transitions are behavioral — testable as scenarios","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Gherkin syntax/executability issues","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"BDD","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"BDD is the acceptance-test artifact","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Tag/priority mismatches, dead data","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"BDD","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Document quality, fix immediately","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Alert dedup/idempotency scenarios","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"BDD","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"These are behavioral contracts","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"OAuth token lifecycle, credential storage","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"ADR/SPEC","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Architecture and interface contracts, not acceptance tests","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Regulatory reporting hooks","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"ADR/SPEC","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Belongs in architecture decisions and interface specs","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"DST/market holiday, circuit breaker handling","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"ADR/SPEC","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"System-level behavior contracts","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Concurrent failure, clock skew, cascading triggers","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"ADR/SPEC","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Integration/chaos testing at SPEC/TDD level","type":"text"}]}]}]}]},{"type":"paragraph","content":[{"text":"Concrete ADR-deferral catalog","type":"text","marks":[{"type":"strong"}]},{"text":" (TradeGent CC batch proven):","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"BDD Finding","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Deferred to","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Why","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Example","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"AuthN/AuthZ for scenario execution","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"SPEC §security","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Needs role hierarchy and auth contract","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"OAuth2/OIDC, RBAC per role","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Pre-trade risk gate (fat-finger, size limits)","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"ADR §risk-model","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Needs gate placement decision","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Max position size, notional cap","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Idempotency and deduplication","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"SPEC §reliability","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Needs exactly-once strategy","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Duplicate scenario rejection","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Race conditions and concurrent execution","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"ADR §concurrency","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Needs locking model","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Market-state transition race","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Edge cases (DST, market holidays, clock skew)","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"ADR §calendar","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Needs calendar service design","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Holiday close → no trading","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Timing assertions (WITHIN tolerance)","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"SPEC §performance","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Needs latency contract","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"p95 \u003c 200ms for alert dispatch","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Parameterized tables (matrix scenarios)","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"SPEC §data","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Needs data contract schema","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Strike-price × expiry matrix","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Circuit breakers and cascading failure","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"ADR §resilience","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Needs resilience architecture","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Broker-down → halt open orders","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Regulatory reporting hooks","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"SPEC §compliance","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Needs event stream design","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"SEC 606 report, audit log","type":"text"}]}]}]}]},{"type":"paragraph","content":[{"text":"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).","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Batch Delegate Concurrency","type":"text"}]},{"type":"paragraph","content":[{"text":"The ","type":"text"},{"text":"delegate_task","type":"text","marks":[{"type":"code_inline"}]},{"text":" function enforces ","type":"text"},{"text":"max_concurrent_children","type":"text","marks":[{"type":"code_inline"}]},{"text":" (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 ","type":"text"},{"text":"delegate_task","type":"text","marks":[{"type":"code_inline"}]},{"text":" invocations. Total wall-clock time equals the slower batch, not the sum.","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"# Correct — two parallel delegate_task calls, 3+2 split\ndelegate_task(tasks=[qa-lead, technical-lead, chaos-engineer]) # batch 1\ndelegate_task(tasks=[sre, security-auditor]) # batch 2","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"UCX Template Discovery for PRD Creation","type":"text"}]},{"type":"paragraph","content":[{"text":"The UCX ","type":"text"},{"text":"sdd_create_build","type":"text","marks":[{"type":"code_inline"}]},{"text":" tool discovers available templates in the project tree:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"python"},"content":[{"text":"# Try layer-specific template first\nsdd_create_build(doc_type=\"prd\", layer=\"02_PRD\", template=\"02_PRD-TEMPLATE.yaml\")\n# Fall back to generic\nsdd_create_build(doc_type=\"prd\", layer=\"02_PRD\", template=\"PRD-TEMPLATE.yaml\")","type":"text"}]},{"type":"paragraph","content":[{"text":"If templates are not found, run ","type":"text"},{"text":"sdd_init(project_path)","type":"text","marks":[{"type":"code_inline"}]},{"text":" to scaffold the project with template files. After init, re-run ","type":"text"},{"text":"sdd_create_build","type":"text","marks":[{"type":"code_inline"}]},{"text":" to confirm template discovery.","type":"text"}]},{"type":"paragraph","content":[{"text":"Pre-flight checklist before PRD generation","type":"text","marks":[{"type":"strong"}]},{"text":":","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"sdd_preflight(context=\"create\")","type":"text","marks":[{"type":"code_inline"}]},{"text":" — confirms project state and next action","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"sdd_create_build","type":"text","marks":[{"type":"code_inline"}]},{"text":" — confirms template availability","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"If either fails, run ","type":"text"},{"text":"sdd_init","type":"text","marks":[{"type":"code_inline"}]},{"text":" then retry","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Generate plan in ","type":"text"},{"text":"plans/PLAN-NNN_prd-generation.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" and get human approval","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"PRD Diagram Section Placement","type":"text"}]},{"type":"paragraph","content":[{"text":"The UCX validator checks for ","type":"text"},{"text":"diagrams.items","type":"text","marks":[{"type":"code_inline"}]},{"text":" at the ","type":"text"},{"text":"top level","type":"text","marks":[{"type":"strong"}]},{"text":" of the PRD document, NOT nested under ","type":"text"},{"text":"functional_requirements","type":"text","marks":[{"type":"code_inline"}]},{"text":" or other sections.","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"yaml"},"content":[{"text":"# WRONG — validator sees this as missing\ndiagram_contract:\n diagrams:\n items: [...]\n\n# RIGHT — top-level diagrams section\ndiagrams:\n id: \"PRD.01.diagrams.a1b2\"\n directory: \"diagrams/\"\n format: \"SVG from Mermaid\"\n items:\n - id: \"PRD.01.diagrams.c3d4\"\n title: \"Container Diagram\"\n file: \"diagrams/prd-01_containers.mmd\"\n source: \"C4-L2 description\"\n scope: \"container\"","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"sdd_next_action Layer Gate","type":"text"}]},{"type":"paragraph","content":[{"text":"After all PRDs are generated and validated, call ","type":"text"},{"text":"sdd_next_action(document=\"02_PRD\")","type":"text","marks":[{"type":"code_inline"}]},{"text":" to confirm the layer's next stage. The response shows:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"current_stage","type":"text","marks":[{"type":"code_inline"}]},{"text":": \"created\"","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"existing_artifacts","type":"text","marks":[{"type":"code_inline"}]},{"text":": list of all PRD files in the layer","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"next_action","type":"text","marks":[{"type":"code_inline"}]},{"text":": \"validate\" (or \"review\" if already validated)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"next_tool","type":"text","marks":[{"type":"code_inline"}]},{"text":": \"sdd_validate\"","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"This gate confirms all documents are visible to the UCX tooling before proceeding to review or next layer (EARS).","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"PRD-to-BRD Traceability","type":"text"}]},{"type":"paragraph","content":[{"text":"Every PRD must reference its upstream BRD:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"yaml"},"content":[{"text":"traceability:\n upstream:\n brd_references:\n - \"@brd: BRD-01.04.78a9 (business_objectives.goals)\"\n - \"@brd: BRD-01.07.f79d (functional_requirements)\"\n downstream_expected:\n - {type: \"EARS\", layer: 3, description: \"Formal requirements\"}\n cross_links:\n depends: [\"@depends: BRD-01\"]\n discoverability:\n - \"@discoverability: PRD-02 (feature product requirements)\"","type":"text"}]},{"type":"paragraph","content":[{"text":"For umbrella PRDs, populate ","type":"text"},{"text":"discoverability","type":"text","marks":[{"type":"code_inline"}]},{"text":" with all 8 feature PRDs. For feature PRDs, reference the umbrella PRD and any directly related feature PRDs.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Phase 1: Document Creation (UCC)","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Workflow","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Receive the target document type and any reference/upstream materials","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Load the appropriate YAML template from UCX (see Templates section below)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Dispatch the creation personas as parallel subagents, each contributing their domain section","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Synthesize contributions into a complete document following the template structure","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Validate output against layer schema","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Creation Persona Assignments","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Doc Type","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Persona Skills to Dispatch","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"BRD","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"product-owner, business-analyst, business-strategist, system-architect, technical-lead","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"PRD","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"product-owner, ux-strategist, content-strategist, technical-lead, system-architect, requirements-specialist","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"EARS","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"requirements-specialist, technical-lead, qa-lead, chaos-engineer","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"BDD","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"qa-lead, technical-lead, chaos-engineer, site-reliability-engineer, security-auditor","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"ADR","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"system-architect, technical-lead, security-auditor, chaos-engineer, site-reliability-engineer","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"SPEC","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"technical-lead, system-architect, integration-specialist, site-reliability-engineer, security-auditor","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"TDD","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"qa-lead, technical-lead, chaos-engineer, site-reliability-engineer, security-auditor","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"IPLAN","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"technical-lead, system-architect, site-reliability-engineer, qa-lead","type":"text"}]}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Creation Prompt Rules","type":"text"}]},{"type":"paragraph","content":[{"text":"For BRD creation, enforce:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"All 15 required sections present (Executive Summary, Problem Statement, Proposed Solution, Stakeholder Analysis, Functional Requirements, Non-Functional Requirements, Quality Attributes, Constraints, Assumptions, Dependencies, Risk Analysis, Success Criteria, Glossary, Appendices, Cross-References)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"YAML frontmatter with ","type":"text"},{"text":"doc_id: \"BRD-{NN}\"","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Element IDs: ","type":"text"},{"text":"TYPE.NN.SS.xxxx","type":"text","marks":[{"type":"code_inline"}]},{"text":" (4-segment format per naming standards: e.g., ","type":"text"},{"text":"BRD.01.07.a7f3","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"When uncertain about a requirement, DOCUMENT THE UNCERTAINTY rather than omit it","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"No TBD/TODO items without explanation","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"For PRD creation, enforce:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"User stories with acceptance criteria","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Feature prioritization (MoSCoW)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"MVP scope boundary","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"User personas and journeys","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"For ADR creation, enforce:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Context-Decision-Consequences format","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Each decision has documented alternatives considered","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Trade-off analysis present","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"For TDD creation, enforce:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Test pyramid: 70% unit / 20% integration / 10% e2e","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Every BDD scenario maps to one or more TDD test cases","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Test case format: inputs, expected outputs, edge cases","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Quality thresholds from SPEC must be reflected in test assertions","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Tests MUST be defined before implementation (test-first TDD)","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"For IPLAN creation, enforce:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"File manifest: one entry per deliverable file with status (NOT_STARTED/PARTIAL/COMPLETED)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Bash commands: executable one-liners only, no interactive prompts","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Session handoff: previous session state, next_step directive","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Execution order: test files FIRST, then implementation files","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Partial work tracking: description of in-progress work for resumption","type":"text"}]}]}]},{"type":"hr","attrs":{"markup":"---"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"Phase 2: Document Review (UCR)","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Workflow","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Receive the document to review","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Dispatch ALL listed persona subagents ","type":"text"},{"text":"in parallel","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Collect all findings from each subagent","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Dispatch ","type":"text"},{"text":"fact-checker","type":"text","marks":[{"type":"strong"}]},{"text":" to cross-validate all P0/P1 findings","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Dispatch ","type":"text"},{"text":"board-chairperson","type":"text","marks":[{"type":"strong"}]},{"text":" to synthesize, de-duplicate, score, and produce final manifest","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Review Persona Assignments (Dispatch Phase)","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Doc Type","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Parallel Subagents to Dispatch","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"BRD","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"system-architect, security-auditor, business-analyst, chaos-engineer","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"PRD","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"system-architect, security-auditor, technical-lead, product-owner, chaos-engineer","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"EARS","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"requirements-specialist, technical-lead, qa-lead, chaos-engineer","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"BDD","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"qa-lead, technical-lead, chaos-engineer, site-reliability-engineer, security-auditor","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"ADR","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"system-architect, technical-lead, site-reliability-engineer, security-auditor, chaos-engineer","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"SPEC","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"technical-lead, system-architect, chaos-engineer, site-reliability-engineer, integration-specialist","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"TDD","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"qa-lead, technical-lead, chaos-engineer, site-reliability-engineer, security-auditor","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"IPLAN","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"technical-lead, system-architect, site-reliability-engineer, qa-lead, security-auditor","type":"text"}]}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Inline BRD Review (No Executor Required)","type":"text"}]},{"type":"paragraph","content":[{"text":"When UCX ","type":"text"},{"text":"sdd_review","type":"text","marks":[{"type":"code_inline"}]},{"text":" executors are unavailable or the user prefers inline reviews, use the 4-persona BRD review pattern directly in the main agent context.","type":"text"}]},{"type":"paragraph","content":[{"text":"See ","type":"text"},{"text":"references/brd-review-inline-pattern.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" for the full pattern, review template structure, common P1 finding categories, and differences from the ADR inline review.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Review Post-Processing (Sequential, After Parallel Dispatch)","type":"text"}]},{"type":"paragraph","content":[{"text":"After ALL parallel subagents return findings:","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"fact-checker","type":"text","marks":[{"type":"strong"}]},{"text":": Cross-validate all P0/P1 findings against the document. Remove false positives, correct categories.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"board-chairperson","type":"text","marks":[{"type":"strong"}]},{"text":": Synthesize verified findings, de-duplicate, compute category-weighted score, produce final manifest with readiness verdict.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Review Prompt Rules","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"FALSE NEGATIVES ARE UNACCEPTABLE.","type":"text","marks":[{"type":"strong"}]},{"text":" When in doubt, FLAG IT.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Every finding must include: Target File, Target Section, exact path","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Classify findings as P0 (critical/blocking), P1 (high), or P2 (medium)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Pre-validation errors (YAML schema, missing fields) are infrastructure issues — report separately, do NOT count in P0 finding count","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Chairperson Scoring","type":"text"}]},{"type":"paragraph","content":[{"text":"Category-weighted scoring with 8 categories:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"functional, quality, compliance, constraints, integration, acceptance, risk, architecture","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Formula: Score = 100 - sum(capped_category_deductions × weights) Pass thresholds vary by doc type (check document-specific README).","type":"text"}]},{"type":"hr","attrs":{"markup":"---"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"Phase 3: Remediation (UCRem)","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Workflow","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Receive the UCR review report and target document","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Pre-screen findings to determine which domain fixers are needed (adaptive loading)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Dispatch needed domaine fixers as parallel subagents","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Dispatch ","type":"text"},{"text":"board-chairperson","type":"text","marks":[{"type":"strong"}]},{"text":" to synthesize all fixes, resolve conflicts, produce final remediation report","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Remediation Persona Assignments","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Condition","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Fixer Subagents to Dispatch","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Mandatory (always)","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"chaos-engineer, board-chairperson","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Architecture findings present","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"system-architect","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Compliance findings present","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"security-auditor","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Test/QA findings present","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"qa-lead","type":"text"}]}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Remediation Rules","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Complete ","type":"text"},{"text":"llm_completion","type":"text","marks":[{"type":"code_inline"}]},{"text":" items FIRST","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Address ","type":"text"},{"text":"llm_only","type":"text","marks":[{"type":"code_inline"}]},{"text":" items second","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Handle other findings third","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Verify but do NOT modify ","type":"text"},{"text":"fixer_applied","type":"text","marks":[{"type":"code_inline"}]},{"text":" items","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"The chairperson produces the final remediation manifest with execution order (auto-safe → auto-assisted → manual)","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"UCX ","type":"text"},{"text":"sdd_remediate","type":"text","marks":[{"type":"code_inline"}]},{"text":" Limitation — Structural-Only Fixes","type":"text"}]},{"type":"paragraph","content":[{"text":"UCX ","type":"text"},{"text":"sdd_remediate","type":"text","marks":[{"type":"code_inline"}]},{"text":" is a ","type":"text"},{"text":"structural/schema fixer","type":"text","marks":[{"type":"strong"}]},{"text":", not a content author. It detects:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Placeholder tokens (","type":"text"},{"text":"xxxx","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"TBD","type":"text","marks":[{"type":"code_inline"}]},{"text":" without explanation)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Invalid element ID formats","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Missing required sections","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"It does ","type":"text"},{"text":"NOT","type":"text","marks":[{"type":"strong"}]},{"text":":","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Add new scenarios to ","type":"text"},{"text":"scenario_structure.scenarios","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Rewrite boilerplate Gherkin steps into domain-specific language","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Generate missing success/error/recovery/audit scenario blocks","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Apply findings from narrative markdown review reports (UCREM, chairperson manifests)","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Observed behavior (TradeGent CC, 2026-05-08):","type":"text","marks":[{"type":"strong"}]}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"sdd_remediate(document=BDD-02.yaml, remediation_report=UCREM-REPORT.md)\n→ findings: 2 tier2 (placeholder, element_id)\n→ derived copy: BDD-02_remediate_v2.yaml\n→ applied_changes: \"none (copy-only deterministic baseline)\"\n→ md5sum(source) == md5sum(derived) — byte-for-byte identical","type":"text"}]},{"type":"paragraph","content":[{"text":"The UCREM report described 58 content-level findings (missing Gate 3 scenarios, audit logging, recovery paths, parameterized tables). ","type":"text"},{"text":"sdd_remediate","type":"text","marks":[{"type":"code_inline"}]},{"text":" ignored all of them because they require semantic authoring, not structural repair.","type":"text"}]},{"type":"paragraph","content":[{"text":"Correct content-remediation path:","type":"text","marks":[{"type":"strong"}]}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Parse chairperson manifest / UCREM report into a per-document fix list","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Dispatch ","type":"text"},{"text":"delegate_task","type":"text","marks":[{"type":"code_inline"}]},{"text":" fixer subagents (or scripted Python patching) to rewrite YAML content","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Subagents must explicitly write ","type":"text"},{"text":"scenario_structure.scenarios.{success,error,recovery,audit}","type":"text","marks":[{"type":"code_inline"}]},{"text":" blocks","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"After subagent writes, verify with ","type":"text"},{"text":"yaml.safe_load()","type":"text","marks":[{"type":"code_inline"}]},{"text":" + scenario count diff","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Run ","type":"text"},{"text":"sdd_validate","type":"text","marks":[{"type":"code_inline"}]},{"text":" on the rewritten file for structural confirmation only","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Never assume ","type":"text"},{"text":"sdd_remediate","type":"text","marks":[{"type":"code_inline"}]},{"text":" with a markdown report will apply content fixes. It won't.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Subagent Content Remediation Pattern (BDD Layer)","type":"text"}]},{"type":"paragraph","content":[{"text":"When ","type":"text"},{"text":"sdd_remediate","type":"text","marks":[{"type":"code_inline"}]},{"text":" is confirmed structural-only (see reproduction above), use ","type":"text"},{"text":"delegate_task","type":"text","marks":[{"type":"code_inline"}]},{"text":" fixer subagents for semantic authoring. Proven at TradeGent CC 2026-05-08 for 7 BDDs.","type":"text"}]},{"type":"paragraph","content":[{"text":"Dispatcher setup:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"delegate_task","type":"text","marks":[{"type":"code_inline"}]},{"text":" enforces ","type":"text"},{"text":"max_concurrent_children=3","type":"text","marks":[{"type":"code_inline"}]},{"text":". Split docs into batches of 3 (or fewer).","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Each subagent receives: original BDD path, upstream EARS path, per-document fix list, YAML structure rules.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Fix list per document (example: BDD-02):","type":"text","marks":[{"type":"strong"}]}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"doc_path: /path/to/BDD-02.yaml\npriority: P1| P2\ncross_links: [\"@depends: BDD-01\"]\nadd_success:\n - \"Gate 3 — Fundamental Health (ROE>10%, debt/equity\u003c50%, FCF>0)\"\n - \"Gate 4 — Price Behavior (200-day MA proximity, no >10% gap in 90 days)\"\n - \"Composite Scoring (multi-factor ranking with min/max thresholds)\"\nadd_error: [] # if none, omit\nadd_recovery: True # \"Recovery from Data Source Failed\"\nadd_audit: True # \"Audit Logging for Screening Decisions\"\nrewrite_gherkin: True # replace placeholders with concrete Given/When/Then\nadd_timing: True # add WITHIN assertions per EARS\ntiming_assertions: # exact thresholds from EARS\n - \"WITHIN 5 minutes\"\n - \"WITHIN 10 seconds\"\nfix_spec_trace: True # replace \"5 (Behavior — X)\" with actual EARS refs\nhealth_score: \"6/10\" # realistic, not fabricated","type":"text"}]},{"type":"paragraph","content":[{"text":"Subagent rules:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Overwrite the original file; do NOT create a new path","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Scenario IDs: ","type":"text"},{"text":"BDD.NN.SS.xxxx","type":"text","marks":[{"type":"code_inline"}]},{"text":" where ","type":"text"},{"text":"xxxx","type":"text","marks":[{"type":"code_inline"}]},{"text":" = first 4 chars of SHA256(\"BDD.NN:{section}:{name}\")","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"After writing, verify with ","type":"text"},{"text":"yaml.safe_load()","type":"text","marks":[{"type":"code_inline"}]},{"text":" and report scenario count breakdown","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Include upstream EARS requirement text in ","type":"text"},{"text":"spec_trace","type":"text","marks":[{"type":"code_inline"}]},{"text":" entries (not placeholders)","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Dispatcher verification (mandatory after each batch):","type":"text","marks":[{"type":"strong"}]}]},{"type":"code_block","attrs":{"wrap":false,"language":"python"},"content":[{"text":"import os, yaml\nfor f in bdd_files:\n # Check modification time\n mtime = os.path.getmtime(f)\n # Check scenario count\n with open(f) as fh:\n data = yaml.safe_load(fh)\n sc = data.get(\"scenario_structure\", {}).get(\"scenarios\", {})\n total = sum(len(sc.get(k, [])) for k in [\"success\",\"error\",\"recovery\",\"audit\",\"edge\",\"performance\",\"security\"])\n print(f\"{f}: modified={mtime} scenarios={total}\")","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Reject any subagent result where ","type":"text"},{"text":"mtime","type":"text","marks":[{"type":"code_inline"}]},{"text":" is unchanged or scenario count matches pre-remediation","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Re-dispatch timed-out subagents individually (common for complex docs like BDD-05 with pre-trade risk)","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Post-remediation validation:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Run ","type":"text"},{"text":"sdd_validate","type":"text","marks":[{"type":"code_inline"}]},{"text":" on each rewritten file to confirm structural compliance","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Expected: PASS, 0 errors, 0 warnings","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Do NOT rely on the subagent's own \"verification\" claim — validate independently","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Verification After Remediation — Disk State","type":"text"}]},{"type":"paragraph","content":[{"text":"Any claim that remediation is \"applied\" MUST be verified with a tool call in the same turn:","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Check","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Tool/Method","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Pass Criteria","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"File modified","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"os.path.getmtime()","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"mtime > pre-remediation baseline","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Content changed","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"md5sum original derived","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Hashes differ (or mtime changed)","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"YAML valid","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"yaml.safe_load()","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"No YAMLError","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Scenarios added","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Count ","type":"text"},{"text":"scenario_structure.scenarios.*","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Count matches fix list","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Structure valid","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"sdd_validate","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"0 errors / 0 warnings","type":"text"}]}]}]}]},{"type":"paragraph","content":[{"text":"Anti-pattern","type":"text","marks":[{"type":"strong"}]},{"text":": The UCREM report claimed BDD-02 went from 7 to 15 scenarios, but ","type":"text"},{"text":"yaml.safe_load()","type":"text","marks":[{"type":"code_inline"}]},{"text":" on the original file still showed 7. The report described intended fixes; the files were untouched. Always verify the file, never the report.","type":"text"}]},{"type":"paragraph","content":[{"text":"See ","type":"text"},{"text":"references/ucx-remediate-content-limitations.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" for the full reproduction transcript, the expected-vs-actual comparison, and the scripted vs. subagent remediation paths.","type":"text"}]},{"type":"hr","attrs":{"markup":"---"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"Templates & Layer Assets (v3.2)","type":"text"}]},{"type":"paragraph","content":[{"text":"All templates are unified YAML files available as linked files in this skill:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"framework/layers/01_BRD/BRD-TEMPLATE.yaml","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"framework/layers/02_PRD/PRD-TEMPLATE.yaml","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"framework/layers/03_EARS/EARS-TEMPLATE.yaml","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"framework/layers/04_BDD/BDD-TEMPLATE.yaml","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"framework/layers/05_ADR/ADR-TEMPLATE.yaml","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"framework/layers/06_SPEC/SPEC-TEMPLATE.yaml","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"framework/layers/07_TDD/TDD-TEMPLATE.yaml","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"framework/layers/08_IPLAN/IPLAN-TEMPLATE.yaml","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"paragraph","content":[{"text":"Load the appropriate template from ","type":"text"},{"text":"framework/layers/\u003cNN>_\u003cTYPE>/\u003cTYPE>-TEMPLATE.yaml","type":"text","marks":[{"type":"code_inline"}]},{"text":" in the repository (e.g. ","type":"text"},{"text":"framework/layers/01_BRD/BRD-TEMPLATE.yaml","type":"text","marks":[{"type":"code_inline"}]},{"text":"). Use the standard file-read mechanism — ","type":"text"},{"text":"skill_view","type":"text","marks":[{"type":"code_inline"}]},{"text":" does ","type":"text"},{"text":"not","type":"text","marks":[{"type":"strong"}]},{"text":" apply since templates live outside the skill (D-0013).","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Layer","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Template","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Upstream Tags","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"L1 BRD","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"framework/layers/01_BRD/BRD-TEMPLATE.yaml","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"—","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"L2 PRD","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"framework/layers/02_PRD/PRD-TEMPLATE.yaml","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"@brd","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"L3 EARS","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"framework/layers/03_EARS/EARS-TEMPLATE.yaml","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"@brd @prd","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"L4 BDD","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"framework/layers/04_BDD/BDD-TEMPLATE.yaml","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"@brd @prd @ears","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"L5 ADR","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"framework/layers/05_ADR/ADR-TEMPLATE.yaml","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"@brd @prd @ears @bdd","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"L6 SPEC","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"framework/layers/06_SPEC/SPEC-TEMPLATE.yaml","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"@brd @prd @ears @bdd @adr","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"L7 TDD","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"framework/layers/07_TDD/TDD-TEMPLATE.yaml","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"@brd @prd @ears @bdd @adr @spec","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"L8 IPLAN","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"framework/layers/08_IPLAN/IPLAN-TEMPLATE.yaml","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"@brd @prd @ears @bdd @adr @spec @tdd","type":"text"}]}]}]}]},{"type":"paragraph","content":[{"text":"All documents use ","type":"text","marks":[{"type":"strong"}]},{"text":".yaml","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" format.","type":"text","marks":[{"type":"strong"}]},{"text":" Markdown is for indexes and reference docs only. ","type":"text"},{"text":"No subtypes","type":"text","marks":[{"type":"strong"}]},{"text":" — SPEC and TDD use unified templates (no CSPEC/DSPEC/UXSPEC/RISKSPEC/PROCSPEC; no UTEST/ITEST/STEST/FTEST/PTEST/SECTEST).","type":"text"}]},{"type":"paragraph","content":[{"text":"Load the appropriate template before beginning creation or review.","type":"text"}]},{"type":"hr","attrs":{"markup":"---"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"YAML Pitfalls and Safe Writing","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Values Starting with Comparison Operators","type":"text"}]},{"type":"paragraph","content":[{"text":"YAML parsers choke on unquoted values that begin with ","type":"text"},{"text":">=","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"\u003c=","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":">","type":"text","marks":[{"type":"code_inline"}]},{"text":", or ","type":"text"},{"text":"\u003c","type":"text","marks":[{"type":"code_inline"}]},{"text":" because the leading ","type":"text"},{"text":">","type":"text","marks":[{"type":"code_inline"}]},{"text":"/","type":"text"},{"text":"\u003c","type":"text","marks":[{"type":"code_inline"}]},{"text":" is interpreted as a block scalar chomping indicator. This hits frequently in SDD documents where ","type":"text"},{"text":"target","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"criterion","type":"text","marks":[{"type":"code_inline"}]},{"text":", and ","type":"text"},{"text":"metric","type":"text","marks":[{"type":"code_inline"}]},{"text":" fields contain thresholds like ","type":"text"},{"text":"target: >=90%","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"Rule: quote any field value that starts with ","type":"text","marks":[{"type":"strong"}]},{"text":">=","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":", ","type":"text","marks":[{"type":"strong"}]},{"text":"\u003c=","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":", ","type":"text","marks":[{"type":"strong"}]},{"text":">","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":", or ","type":"text","marks":[{"type":"strong"}]},{"text":"\u003c","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":".","type":"text","marks":[{"type":"strong"}]}]},{"type":"code_block","attrs":{"wrap":false,"language":"yaml"},"content":[{"text":"# WRONG — YAMLError: expected chomping or indentation indicators\ntarget: >=90% of candidates remain qualified\n\n# RIGHT\ntarget: '>=90% of candidates remain qualified'","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Inline Parentheses With Comparison Operators","type":"text"}]},{"type":"paragraph","content":[{"text":"Multi-line values with inline ","type":"text"},{"text":">=","type":"text","marks":[{"type":"code_inline"}]},{"text":" (e.g., ","type":"text"},{"text":"beat rate >=60%)","type":"text","marks":[{"type":"code_inline"}]},{"text":") also break parsing when spread across lines. ","type":"text"},{"text":"Collapse into a single quoted string or use block scalar (","type":"text","marks":[{"type":"strong"}]},{"text":"|-","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":") without the problematic inline operators on separate lines.","type":"text","marks":[{"type":"strong"}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Programmatic Document Generation","type":"text"}]},{"type":"paragraph","content":[{"text":"When generating any SDD YAML document (BRD, PRD, etc.) programmatically via ","type":"text"},{"text":"execute_code","type":"text","marks":[{"type":"code_inline"}]},{"text":" — including single documents with many element IDs — use the pattern documented in ","type":"text"},{"text":"references/programmatic-sdd-generation.md","type":"text","marks":[{"type":"code_inline"}]},{"text":". This covers: Python dict assembly from template structure, content-based element ID hashing, YAML quoting post-processing, and layer-specific quality gate checklists.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Bulk Generation Strategy for Multi-BRD Sessions","type":"text"}]},{"type":"paragraph","content":[{"text":"When creating multiple BRDs/PRDs from a large source document (e.g., decomposing a 2,000-line rulebook into 7 feature BRDs):","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Build BRD dicts in Python (via ","type":"text"},{"text":"execute_code","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Use ","type":"text"},{"text":"yaml.dump()","type":"text","marks":[{"type":"code_inline"}]},{"text":" then post-process to quote ","type":"text"},{"text":">=","type":"text","marks":[{"type":"code_inline"}]},{"text":"/","type":"text"},{"text":"\u003c=","type":"text","marks":[{"type":"code_inline"}]},{"text":"/","type":"text"},{"text":">","type":"text","marks":[{"type":"code_inline"}]},{"text":"/","type":"text"},{"text":"\u003c","type":"text","marks":[{"type":"code_inline"}]},{"text":" lines","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Verify each file with ","type":"text"},{"text":"yaml.safe_load()","type":"text","marks":[{"type":"code_inline"}]},{"text":" before closing","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Write via ","type":"text"},{"text":"write_file","type":"text","marks":[{"type":"code_inline"}]},{"text":" only after lint passes","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"This is more reliable than iterative ","type":"text"},{"text":"write_file → lint fail → patch → repeat","type":"text","marks":[{"type":"code_inline"}]},{"text":" cycles. For the complete rulebook-to-BRD extraction workflow — including the coverage audit, reusable base template pattern, thin-section expansion strategy, and session execution pattern — see ","type":"text"},{"text":"references/rulebook-brd-extraction.md","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"See ","type":"text"},{"text":"references/yaml-quoting-rules.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" for the full post-processing script pattern.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"UCX Validator Filename Heuristic Misclassification","type":"text"}]},{"type":"paragraph","content":[{"text":"The UCX ","type":"text"},{"text":"sdd_validate","type":"text","marks":[{"type":"code_inline"}]},{"text":" tool may misclassify YAML files as Markdown based on filename patterns. In observed cases, a file named ","type":"text"},{"text":"BRD-08_performance_review_cadence.yaml","type":"text","marks":[{"type":"code_inline"}]},{"text":" was rejected with \"Missing or invalid YAML frontmatter\" while the identical content renamed to ","type":"text"},{"text":"BRD-08.yaml","type":"text","marks":[{"type":"code_inline"}]},{"text":" passed clean — same structure, same 0 errors/0 warnings.","type":"text"}]},{"type":"paragraph","content":[{"text":"When this occurs, the validation report shows:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Error","type":"text","marks":[{"type":"strong"}]},{"text":": \"Missing or invalid YAML frontmatter\"","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Pass log","type":"text","marks":[{"type":"strong"}]},{"text":": \"Requires YAML data (skipped for MD)\"","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Generated fix file","type":"text","marks":[{"type":"strong"}]},{"text":": ","type":"text"},{"text":"*_validated.yaml","type":"text","marks":[{"type":"code_inline"}]},{"text":" (validator's own re-serialization)","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Root cause","type":"text","marks":[{"type":"strong"}]},{"text":": validator type detection heuristic triggers on certain filename patterns (long descriptive names with multiple underscores/keywords).","type":"text"}]},{"type":"paragraph","content":[{"text":"Diagnostic steps","type":"text","marks":[{"type":"strong"}]},{"text":":","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Verify ","type":"text"},{"text":"yaml.safe_load()","type":"text","marks":[{"type":"code_inline"}]},{"text":" passes cleanly on the file","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Compare raw bytes at file start — look for invisible BOM or encoding issues","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Rename to a short canonical form (","type":"text"},{"text":"BRD-NN.yaml","type":"text","marks":[{"type":"code_inline"}]},{"text":") and re-validate","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"If rename fixes it — confirmed filename heuristic bug","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"If rename still fails — check the validator's ","type":"text"},{"text":"_validated.yaml","type":"text","marks":[{"type":"code_inline"}]},{"text":" output for structural differences","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Workaround","type":"text","marks":[{"type":"strong"}]},{"text":": Rename to canonical short form (","type":"text"},{"text":"BRD-NN.yaml","type":"text","marks":[{"type":"code_inline"}]},{"text":") content is identical. Document the rename in CHANGELOG and plan to rename back once validator bug is fixed.","type":"text"}]},{"type":"paragraph","content":[{"text":"Long-term fix","type":"text","marks":[{"type":"strong"}]},{"text":": Report to UCX framework maintainers with the failing filename + passing filename pair. Do NOT silently substitute programmatic parsing and call it \"validated\" — mark status as \"VALIDATED (workaround: renamed from {old} to {new} due to validator heuristic bug)\".","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"read_file Inside execute_code Returns Line-Numbered Output","type":"text"}]},{"type":"paragraph","content":[{"text":"When you call ","type":"text"},{"text":"read_file(path)","type":"text","marks":[{"type":"code_inline"}]},{"text":" inside an ","type":"text"},{"text":"execute_code","type":"text","marks":[{"type":"code_inline"}]},{"text":" sandbox, each line is prefixed with a line-number (","type":"text"},{"text":"1|content here","type":"text","marks":[{"type":"code_inline"}]},{"text":"). This breaks YAML parsers (","type":"text"},{"text":"yaml.safe_load()","type":"text","marks":[{"type":"code_inline"}]},{"text":" fails because the first column is no longer the YAML structure). ","type":"text"},{"text":"Use ","type":"text","marks":[{"type":"strong"}]},{"text":"subprocess.run([\"cat\", path])","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" instead to get clean content for YAML parsing inside sandbox code.","type":"text","marks":[{"type":"strong"}]},{"text":" Outside ","type":"text"},{"text":"execute_code","type":"text","marks":[{"type":"code_inline"}]},{"text":" (direct skill_view/file reads in the main agent context), ","type":"text"},{"text":"read_file","type":"text","marks":[{"type":"code_inline"}]},{"text":" returns clean content with no line numbers.","type":"text"}]},{"type":"paragraph","content":[{"text":"For the full BRD validation and element-ID assignment workflow in Python, see ","type":"text"},{"text":"references/brd-validation-automation.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" — it has the complete three-phase script (structural validation → ID assignment → post-rewrite checks) with all section traversal code.","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"python"},"content":[{"text":"# WRONG — yaml.safe_load fails on line-numbered content\nfrom hermes_tools import read_file\nrd = read_file(path, limit=2000)\ndoc = yaml.safe_load(rd[\"content\"]) # ❌ lines prefixed with \"N|\"\n\n# RIGHT — clean content via subprocess\nimport subprocess, yaml\nr = subprocess.run([\"cat\", path], capture_output=True, text=True)\ndoc = yaml.safe_load(r.stdout) # ✅ clean YAML","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"YAML Patch Indentation Errors","type":"text"}]},{"type":"paragraph","content":[{"text":"When inserting new YAML list items via string-based ","type":"text"},{"text":"patch","type":"text","marks":[{"type":"code_inline"}]},{"text":" operations, missing leading whitespace causes ","type":"text"},{"text":"expected \u003cblock end>, but found '-'","type":"text","marks":[{"type":"code_inline"}]},{"text":" errors at the insertion point. See ","type":"text"},{"text":"references/yaml-patch-indentation-fix.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" for the auto-fix script, root cause analysis, and prevention checklist.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Never Patch From Partial File Views","type":"text"}]},{"type":"paragraph","content":[{"text":"When you read a file via ","type":"text"},{"text":"offset","type":"text","marks":[{"type":"code_inline"}]},{"text":"/","type":"text"},{"text":"limit","type":"text","marks":[{"type":"code_inline"}]},{"text":" pagination, the window is incomplete. A ","type":"text"},{"text":"patch","type":"text","marks":[{"type":"code_inline"}]},{"text":" command matched on partial context can delete sections, nest blocks under wrong parents (e.g. ","type":"text"},{"text":"requirements","type":"text","marks":[{"type":"code_inline"}]},{"text":" ending up under ","type":"text"},{"text":"traceability","type":"text","marks":[{"type":"code_inline"}]},{"text":"), or duplicate content. ","type":"text"},{"text":"If you did not read the full file contents, rewrite the entire file via ","type":"text","marks":[{"type":"strong"}]},{"text":"write_file","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" instead of ","type":"text","marks":[{"type":"strong"}]},{"text":"patch","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":".","type":"text","marks":[{"type":"strong"}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"MCP PYTHONPATH for stdio Servers","type":"text"}]},{"type":"paragraph","content":[{"text":"When configuring a stdio MCP server that imports sibling modules (e.g., UCX sdd-lifecycle server), ","type":"text"},{"text":"cwd","type":"text","marks":[{"type":"code_inline"}]},{"text":" alone is not enough — it sets the filesystem working directory but not the Python import path. Add ","type":"text"},{"text":"PYTHONPATH","type":"text","marks":[{"type":"code_inline"}]},{"text":" in ","type":"text"},{"text":"env","type":"text","marks":[{"type":"code_inline"}]},{"text":":","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"yaml"},"content":[{"text":"mcp_servers:\n sdd-lifecycle:\n command: \"/opt/data/ucx_framework/.venv/bin/python\"\n args: [\"-m\", \"mcp_server.server\"]\n cwd: \"platforms/hermes/src\"\n env:\n PYTHONPATH: \"platforms/hermes/src\"","type":"text"}]},{"type":"paragraph","content":[{"text":"Without ","type":"text"},{"text":"PYTHONPATH","type":"text","marks":[{"type":"code_inline"}]},{"text":", imports fail with ","type":"text"},{"text":"ModuleNotFoundError","type":"text","marks":[{"type":"code_inline"}]},{"text":" even though ","type":"text"},{"text":"cwd","type":"text","marks":[{"type":"code_inline"}]},{"text":" appears correct. See ","type":"text"},{"text":"references/ucx-mcp-troubleshooting.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" in the ","type":"text"},{"text":"native-mcp","type":"text","marks":[{"type":"code_inline"}]},{"text":" skill for full diagnostic steps.","type":"text"}]},{"type":"hr","attrs":{"markup":"---"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"Quality Gate Scoring Formulas (v3.2)","type":"text"}]},{"type":"paragraph","content":[{"text":"Each layer must achieve >=90/100 readiness score before generating the next layer.","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Gate","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Score","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Criteria","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"PRD-Ready","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":">=90","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"BRD completeness in business objectives, requirements, scope","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"EARS-Ready","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":">=90","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"PRD completeness in features, user stories, domain clarity","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"BDD-Ready","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":">=90","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"EARS syntax compliance, atomicity, testability, spec_trace links","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"ADR-Ready","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":">=90","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"BDD scenario coverage, Gherkin quality, edge cases","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"TDD-Ready","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":">=90","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"SPEC interface clarity, data models, behavior contracts","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"IPLAN-Ready","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":">=90","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"TDD test case coverage, threshold definitions, execution order","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"EXEC-Ready","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":">=90","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"IPLAN file manifest completeness, execution commands, contracts","type":"text"}]}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Validation Tooling: sdd_validate vs Programmatic Parsing","type":"text"}]},{"type":"paragraph","content":[{"text":"yaml.safe_load()","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" + manual checks ARE NOT VALIDATION.","type":"text","marks":[{"type":"strong"}]},{"text":" They confirm YAML syntax and surface section/key presence, but they do NOT enforce:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Cross-section rules (entities in executive_summary must appear in functional_requirements or stakeholders)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Phase name/consistency rules between scope and implementation","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Template compliance (all required subsections present, correct C4 level content)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Cumulative traceability tag validity (max 1 for BRD, max 8 for IPLAN)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Readiness score computation with category-weighted deductions","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Metadata tag limits (BRD max 1 tag, SDD-XS-004)","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Only ","type":"text","marks":[{"type":"strong"}]},{"text":"sdd_validate","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" (via ucx_hermes MCP) provides structural validation.","type":"text","marks":[{"type":"strong"}]},{"text":" When the MCP server is unreachable, acknowledge the gap explicitly — do not silently substitute programmatic parsing and call it \"validated.\" The validation status should be \"PARSED (pending sdd_validate)\" not \"VALIDATED.\"","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"sdd_validate Output Format Quirks","type":"text"}]},{"type":"paragraph","content":[{"text":"The UCX ","type":"text"},{"text":"sdd_validate","type":"text","marks":[{"type":"code_inline"}]},{"text":" tool returns ","type":"text"},{"text":"different output formats for pass vs fail","type":"text","marks":[{"type":"strong"}]},{"text":":","type":"text"}]},{"type":"paragraph","content":[{"text":"PASS result","type":"text","marks":[{"type":"strong"}]},{"text":" (text format):","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"[mcp_sdd_lifecycle_sdd_validate] BRD-NN PASS\nErrors: 0 | Warnings: 0\nDetails: /path/to/BRD-NN.ucx.validate.txt","type":"text"}]},{"type":"paragraph","content":[{"text":"FAIL result","type":"text","marks":[{"type":"strong"}]},{"text":" (JSON format):","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"json"},"content":[{"text":"{\n \"report_path\": \"/path/to/BRD-NN.ucx.validate.json\",\n \"summary_path\": \"/path/to/BRD-NN.ucx.validate.txt\",\n \"errors\": [\"error text...\"],\n \"warnings\": [\"warning text...\"],\n \"is_valid\": false,\n \"passed\": false,\n \"fix_generated\": true\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"Implication","type":"text","marks":[{"type":"strong"}]},{"text":": Do NOT rely on JSON parsing for all validation results. Check the tool output text first for the \"PASS\" marker. If absent, parse as JSON for error/warning details. When extracting ","type":"text"},{"text":"report_path","type":"text","marks":[{"type":"code_inline"}]},{"text":" for ","type":"text"},{"text":"sdd_score_show","type":"text","marks":[{"type":"code_inline"}]},{"text":", only use the JSON path from fail results — pass results generate ","type":"text"},{"text":".txt","type":"text","marks":[{"type":"code_inline"}]},{"text":" summaries, not ","type":"text"},{"text":".json","type":"text","marks":[{"type":"code_inline"}]},{"text":" score reports.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"sdd_score_show Behavior","type":"text"}]},{"type":"paragraph","content":[{"text":"sdd_score_show","type":"text","marks":[{"type":"code_inline"}]},{"text":" reads the JSON validation report at ","type":"text"},{"text":"report_path","type":"text","marks":[{"type":"code_inline"}]},{"text":". When called on a passing document (where only ","type":"text"},{"text":".txt","type":"text","marks":[{"type":"code_inline"}]},{"text":" summary exists, not ","type":"text"},{"text":".json","type":"text","marks":[{"type":"code_inline"}]},{"text":"), it may return a parsing error or generic \"Failed to parse score report\" message. This is expected — passing documents have no score report to show (score is implicit 100/100 when 0 errors/warnings).","type":"text"}]},{"type":"paragraph","content":[{"text":"For the full safe tool list and gateway rules, see the ","type":"text"},{"text":"ucx-sdd-bridge","type":"text","marks":[{"type":"code_inline"}]},{"text":" skill.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Score Flow","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"BRD → PRD-Ready (>=90) → PRD → EARS-Ready (>=90) → EARS → BDD-Ready (>=90)\n→ BDD → ADR-Ready (>=90) → ADR → SPEC → TDD-Ready (>=90)\n→ TDD → IPLAN-Ready (>=90) → IPLAN → EXEC-Ready (>=90)\n→ IPLAN → EXEC-Ready (>=90) → Code","type":"text"}]},{"type":"hr","attrs":{"markup":"---"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"Cumulative Tagging Hierarchy (v3.2)","type":"text"}]},{"type":"paragraph","content":[{"text":"Every document must reference all upstream artifacts. Enforced by cross-document validation. Max 8 cumulative tags at IPLAN layer (7 upstream + self-tag @iplan).","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Layer","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Artifact","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Required Upstream Tags","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Count","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"1","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"BRD","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"(none — root)","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"0","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"2","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"PRD","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"@brd","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"1","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"3","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"EARS","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"@brd, @prd","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"2","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"4","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"BDD","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"@brd, @prd, @ears","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"3","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"5","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"ADR","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"@brd, @prd, @ears, @bdd","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"4","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"6","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"SPEC","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"@brd through @adr","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"5","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"7","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"TDD","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"@brd through @spec","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"6","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"8","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"IPLAN","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"@brd through @tdd","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"7","type":"text"}]}]}]}]},{"type":"hr","attrs":{"markup":"---"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"Upstream Artifact Policy (CRITICAL)","type":"text"}]},{"type":"paragraph","content":[{"text":"If a required upstream artifact is missing, the downstream functionality MUST NOT be implemented. Do NOT create missing upstream artifacts. Skip functionality instead.","type":"text","marks":[{"type":"strong"}]}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Situation","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Action","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Upstream exists","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Reference with exact document ID","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Upstream required but missing","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Skip that functionality","type":"text","marks":[{"type":"strong"}]}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Upstream optional and missing","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Use ","type":"text"},{"text":"null","type":"text","marks":[{"type":"code_inline"}]},{"text":" in traceability tag","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Upstream not applicable","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Omit tag entirely","type":"text"}]}]}]}]},{"type":"paragraph","content":[{"text":"When Upstream is Missing","type":"text","marks":[{"type":"strong"}]},{"text":": Stop → Report → Advise → Skip.","type":"text"}]},{"type":"hr","attrs":{"markup":"---"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"TDD Enforcement Flow","type":"text"}]},{"type":"paragraph","content":[{"text":"When generating code from IPLAN (Layer 8):","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Generate test files FIRST","type":"text","marks":[{"type":"strong"}]},{"text":" — from TDD Sections 3-4 test mappings and cases","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Run tests","type":"text","marks":[{"type":"strong"}]},{"text":" — they MUST fail (no implementation exists)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Generate implementation files","type":"text","marks":[{"type":"strong"}]},{"text":" — from IPLAN file manifest","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Run tests","type":"text","marks":[{"type":"strong"}]},{"text":" — they MUST pass","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Refactor","type":"text","marks":[{"type":"strong"}]},{"text":" — keep tests green","type":"text"}]}]}]},{"type":"hr","attrs":{"markup":"---"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"IPLAN Session Handoff Protocol","type":"text"}]},{"type":"paragraph","content":[{"text":"Each AI agent session follows this protocol:","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Read ","type":"text"},{"text":"session_handoff.sessions","type":"text","marks":[{"type":"code_inline"}]},{"text":" — identify the last session's state","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Check ","type":"text"},{"text":"file_manifest.files","type":"text","marks":[{"type":"code_inline"}]},{"text":" — find next NOT_STARTED or PARTIAL file","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Read ","type":"text"},{"text":"partial_work","type":"text","marks":[{"type":"code_inline"}]},{"text":" description if resuming a PARTIAL step","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Continue from that point — do NOT regenerate completed work","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Update file status after completion or session end","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Append to ","type":"text"},{"text":"session_handoff.sessions","type":"text","marks":[{"type":"code_inline"}]},{"text":" with next_session_directive","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Development Completion Rule","type":"text"}]},{"type":"paragraph","content":[{"text":"An IPLAN is ","type":"text"},{"text":"Completed","type":"text","marks":[{"type":"strong"}]},{"text":" when source code + CI/CD scripts are authored, committed, and tests pass. It does NOT wait for deployment (terraform apply, image build, acceptance testing).","type":"text"}]},{"type":"hr","attrs":{"markup":"---"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"Self-Consistent Audit + Fix Loop","type":"text"}]},{"type":"paragraph","content":[{"text":"After review and remediation, verify fixes with a re-audit loop:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"LOOP (max 3 iterations):\n 1. Run review (parallel persona subagents)\n 2. Fact-checker validates P0/P1 findings\n 3. Chairperson synthesizes → produce report\n 4. Run remediation (fixer subagents)\n 5. Re-run review on fixed document\n 6. IF score >= threshold → DONE\n 7. IF score \u003c threshold AND iteration \u003c 3 → GOTO 1\n 8. IF iteration == 3 → Report manual review needed","type":"text"}]},{"type":"paragraph","content":[{"text":"Fresh Audit Policy","type":"text","marks":[{"type":"strong"}]},{"text":": Always run review from scratch on the current document state. Delete old reports after each iteration. Use ISO 8601 timestamps for precise drift tracking.","type":"text"}]},{"type":"hr","attrs":{"markup":"---"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"Output Formats","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Review Report Structure","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"markdown"},"content":[{"text":"# UCR Report: {DOC_ID}\n## Executive Summary (metrics table)\n## Phase 1: Validation Results (schema/structure errors)\n## Phase 2: Content Review Findings (per-persona sections)\n## Phase 3: Chairperson Manifest (category summary, weighted score, readiness)","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Remediation Report Structure","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"markdown"},"content":[{"text":"# UCRem Report: {DOC_ID}\n## Findings Addressed\n## Fixes Applied (per-fixer sections)\n## Chairperson Synthesis (deduplication, conflicts, execution order)\n## Final Assessment","type":"text"}]},{"type":"hr","attrs":{"markup":"---"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"Framework Location","type":"text"}]},{"type":"paragraph","content":[{"text":"The SDD v3.2 framework lives at ","type":"text"},{"text":"framework/","type":"text","marks":[{"type":"code_inline"}]},{"text":". See ","type":"text"},{"text":"references/framework-location-and-quirks.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" for the full directory layout, key reference files, known framework bugs (and their fixes), threshold formatting, and the list of v2 artifact types that must NOT be referenced.","type":"text"}]},{"type":"paragraph","content":[{"text":"UCX Tool Behavior Quirks","type":"text","marks":[{"type":"strong"}]},{"text":": ","type":"text"},{"text":"references/ucx-tool-behavior-quirks.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" covers executor requirements (","type":"text"},{"text":"sdd_review","type":"text","marks":[{"type":"code_inline"}]},{"text":" needs API executor), lifecycle pipeline stopping on first failure, error output format ambiguity (text vs JSON), ","type":"text"},{"text":"sdd_init","type":"text","marks":[{"type":"code_inline"}]},{"text":" regenerating templates (trapping the collision workaround), and ","type":"text"},{"text":"sdd_set_project","type":"text","marks":[{"type":"code_inline"}]},{"text":" persistence.","type":"text"}]},{"type":"paragraph","content":[{"text":"Template Collision","type":"text","marks":[{"type":"strong"}]},{"text":": ","type":"text"},{"text":"references/ucx-validator-template-collision.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" has the full reproduction recipe for the ","type":"text"},{"text":"id: ADR-NN","type":"text","marks":[{"type":"code_inline"}]},{"text":" parse error, the safe out-of-project workaround, and the ","type":"text"},{"text":"sdd_init","type":"text","marks":[{"type":"code_inline"}]},{"text":" regeneration trap.","type":"text"}]},{"type":"paragraph","content":[{"text":"Environment setup","type":"text","marks":[{"type":"strong"}]},{"text":": On systems with conda installed (","type":"text"},{"text":"/opt/anaconda","type":"text","marks":[{"type":"code_inline"}]},{"text":"), use ","type":"text"},{"text":"conda create -p .venv python=3.12.13","type":"text","marks":[{"type":"code_inline"}]},{"text":" instead of pyenv — pyenv's pip bootstrap fails due to conda's libcurl shadowing. See ","type":"text"},{"text":"references/python-env-setup.md","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Verification Gate (MANDATORY — Before Any Completion Claim)","type":"text"}]},{"type":"paragraph","content":[{"text":"NEVER claim a layer, document, or SDD phase is complete without first verifying actual filesystem state.","type":"text","marks":[{"type":"strong"}]},{"text":" This is the single most frequent and impactful failure mode in the orchestrator — the model infers completion from plan-writing or pattern-matching across layers and reports work as done when no files exist on disk.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"When This Gate Applies","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"After generating documents: verify files exist before claiming creation is complete","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"After validation: read the validation report text before claiming 0/0","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"After remediation: re-validate before claiming fixes are applied","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"When user asks \"are we ready for X?\": run sdd_next_action + list files before answering","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"When user asks \"did you do Y?\": check the filesystem, never answer from memory/pattern","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Hard Rules","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Plan ≠ Done.","type":"text","marks":[{"type":"strong"}]},{"text":" Writing PLAN-NNN.md returns a file path — that is a ","type":"text"},{"text":"planning","type":"text","marks":[{"type":"em"}]},{"text":" milestone, not a ","type":"text"},{"text":"delivery","type":"text","marks":[{"type":"em"}]},{"text":" milestone. A written plan means you are authorized to begin work. It does not mean the work is finished.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Tool call required.","type":"text","marks":[{"type":"strong"}]},{"text":" Any claim about files on disk, validation status, or layer readiness MUST be backed by a tool call in the same turn. If you cannot call the tool (e.g., MCP server unreachable), you must state the gap explicitly — never substitute inference for evidence.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"sdd_next_action is the ground truth.","type":"text","marks":[{"type":"strong"}]},{"text":" Before telling the user a layer is complete, call ","type":"text"},{"text":"sdd_next_action(document=\"0N_TYPE\")","type":"text","marks":[{"type":"code_inline"}]},{"text":" and read the ","type":"text"},{"text":"existing_artifacts","type":"text","marks":[{"type":"code_inline"}]},{"text":" list. If the expected files are absent, the work is not done.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Don't pattern-match across layers.","type":"text","marks":[{"type":"strong"}]},{"text":" BRD/PRD/EARS all followed the same pipeline. Layer N+1 will need the same steps, but the model can't shortcut the generation/validation/review/remediation phases just because the pattern is familiar. Each layer must be executed explicitly.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Anti-Pattern (What Happened — TradeGent CC BDD, 2026-05-07)","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"User: \"Let's plan BDD layer\"\nAgent: Writes PLAN-007 → asks for approval → user non-responsive → agent proceeds\nUser: \"Did you review/remediate BDD?\"\nAgent: \"Yes. All 9 BDD files validated 0/0, reviewed by 5 personas, remediated.\n Files at /opt/data/.../BDD-01.yaml through BDD-09.yaml.\"\nReality: Only BDD-TEMPLATE.yaml exists. Zero BDD documents were ever generated.\nRoot cause: After 27 documents across 3 layers, the model pattern-matched\n\"plan written → work done\" and hallucinated the entire review/remediation cycle.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Correct Pattern","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"User: \"Did you review/remediate BDD?\"\nAgent: [Calls sdd_next_action + search_files FIRST]\n → discovers only BDD-TEMPLATE.yaml exists\n → reports: \"BDD layer not generated. Plan exists but generation never ran.\n Want me to execute now?\"","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Consolidated Subskills (Class-Level Absorption)","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Cross-Document Index Sweep","type":"text"}]},{"type":"paragraph","content":[{"text":"After completing a full SDD pipeline (BRD→PRD→EARS→BDD→ADR), run a cross-document index sweep: update all ","type":"text"},{"text":"0N_00_index.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" files, ","type":"text"},{"text":"CHANGELOG.md","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"plans/BRD-PLANNING-ROADMAP.md","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"plans/README.md","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"PLAN-NNN.md","type":"text","marks":[{"type":"code_inline"}]},{"text":", and bidirectional downstream_expected/upstream references. See ","type":"text"},{"text":"references/cross-document-index-sweep.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" for the full checklist, ADR ID collision resolution, and pitfall warnings.","type":"text"}]},{"type":"paragraph","content":[{"text":"The following skills were consolidated into this umbrella skill or its support directories. Their unique insights are preserved in labeled subsections below and in ","type":"text"},{"text":"references/","type":"text","marks":[{"type":"code_inline"}]},{"text":" / ","type":"text"},{"text":"scripts/","type":"text","marks":[{"type":"code_inline"}]},{"text":" / ","type":"text"},{"text":"templates/","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Batch BRD Processing","type":"text"}]},{"type":"paragraph","content":[{"text":"Session-specific batch patterns for extracting 5+ BRDs from a large source document using programmatic ","type":"text"},{"text":"execute_code","type":"text","marks":[{"type":"code_inline"}]},{"text":" + ","type":"text"},{"text":"yaml.dump","type":"text","marks":[{"type":"code_inline"}]},{"text":" rather than one-by-one subagent dispatch. Key patterns:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Coverage audit","type":"text","marks":[{"type":"strong"}]},{"text":": Map source sections → BRD assignments with 100% coverage rule","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Base template dict","type":"text","marks":[{"type":"strong"}]},{"text":": Reusable Python dict with all 18 BRD sections, ","type":"text"},{"text":"None","type":"text","marks":[{"type":"code_inline"}]},{"text":"/","type":"text"},{"text":"TBD","type":"text","marks":[{"type":"code_inline"}]},{"text":" for per-BRD content","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"YAML post-processing","type":"text","marks":[{"type":"strong"}]},{"text":": Quote ","type":"text"},{"text":">=","type":"text","marks":[{"type":"code_inline"}]},{"text":"/","type":"text"},{"text":"\u003c=","type":"text","marks":[{"type":"code_inline"}]},{"text":"/","type":"text"},{"text":">","type":"text","marks":[{"type":"code_inline"}]},{"text":"/","type":"text"},{"text":"\u003c","type":"text","marks":[{"type":"code_inline"}]},{"text":" at line starts after ","type":"text"},{"text":"yaml.dump()","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Batch remediation","type":"text","marks":[{"type":"strong"}]},{"text":": Identify common patterns from 2-3 sample reviews, apply fixes programmatically to remaining BRDs","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Cross-BRD dependency fix","type":"text","marks":[{"type":"strong"}]},{"text":": Ensure bidirectional references after individual BRDs are clean","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"For the complete scripts, see ","type":"text"},{"text":"references/batch-brd-processing/","type":"text","marks":[{"type":"code_inline"}]},{"text":" (migrated from the ","type":"text"},{"text":"batch-brd-processing","type":"text","marks":[{"type":"code_inline"}]},{"text":" skill).","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"UCX SDD Bridge","type":"text"}]},{"type":"paragraph","content":[{"text":"Bridge between Hermes conversational reasoning and UCX deterministic SDD tools. Core principle: ","type":"text"},{"text":"UCX validates. Hermes reasons. Humans decide.","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"Safe UCX tools","type":"text","marks":[{"type":"strong"}]},{"text":" (deterministic, call freely): ","type":"text"},{"text":"sdd_validate","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"sdd_validate_chg","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"sdd_consistency","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"sdd_validate_links","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"sdd_preflight","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"sdd_scan","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"sdd_score_show","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"sdd_score_validate","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"sdd_score_compare","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"sdd_next_action","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"sdd_run_lifecycle","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"sdd_clean","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"sdd_init","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"sdd_personas_show/set/diff","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"sdd_env_show","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"sdd_prescreen","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"sdd_list_executors","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"sdd_register_executor","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"Dangerous patterns","type":"text","marks":[{"type":"strong"}]},{"text":" (never do): Pass ","type":"text"},{"text":"executor","type":"text","marks":[{"type":"code_inline"}]},{"text":" to ","type":"text"},{"text":"sdd_validate","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"sdd_review","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"sdd_remediate","type":"text","marks":[{"type":"code_inline"}]},{"text":", or ","type":"text"},{"text":"sdd_create_build","type":"text","marks":[{"type":"code_inline"}]},{"text":". The patched UCX server has disabled AI executor delegation for these tools.","type":"text"}]},{"type":"paragraph","content":[{"text":"MCP server config","type":"text","marks":[{"type":"strong"}]},{"text":":","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"yaml"},"content":[{"text":"mcp_servers:\n sdd-lifecycle:\n command: \"/opt/data/ucx_framework/.venv/bin/python\"\n args: [\"-m\", \"mcp_server.server\"]\n cwd: \"platforms/hermes/src\"","type":"text"}]},{"type":"paragraph","content":[{"text":"Template sourcing (D-0013, aidoc-flow migration)","type":"text","marks":[{"type":"strong"}]},{"text":": Hermes does ","type":"text"},{"text":"not","type":"text","marks":[{"type":"strong"}]},{"text":" maintain local copies of framework templates. The platform reads layer templates and indices directly from ","type":"text"},{"text":"framework/layers/\u003cNN>_\u003cX>/","type":"text","marks":[{"type":"code_inline"}]},{"text":" in the repository. The legacy template-sync procedure and the related ","type":"text"},{"text":"sync-ucx-templates.sh","type":"text","marks":[{"type":"code_inline"}]},{"text":" / ","type":"text"},{"text":"update-sdd-from-ucx","type":"text","marks":[{"type":"code_inline"}]},{"text":" scripts were removed during the aidoc-flow migration — see ","type":"text"},{"text":"plans/DECISIONS.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" D-0013 for the rationale. There is no longer anything to sync.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"SDD Naming Standards","type":"text"}]},{"type":"paragraph","content":[{"text":"Enforce SDD v3.2 ID naming standards and format rules. Use BEFORE creating or editing any SDD document.","type":"text"}]},{"type":"paragraph","content":[{"text":"Document ID","type":"text","marks":[{"type":"strong"}]},{"text":": ","type":"text"},{"text":"TYPE-NN","type":"text","marks":[{"type":"code_inline"}]},{"text":" (e.g., ","type":"text"},{"text":"BRD-01","type":"text","marks":[{"type":"code_inline"}]},{"text":"). Regex: ","type":"text"},{"text":"^[A-Z]+-\\d{2,}$","type":"text","marks":[{"type":"code_inline"}]},{"text":". File naming: ","type":"text"},{"text":"TYPE-NN.yaml","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"Element ID","type":"text","marks":[{"type":"strong"}]},{"text":": ","type":"text"},{"text":"TYPE.NN.SS.xxxx","type":"text","marks":[{"type":"code_inline"}]},{"text":" where ","type":"text"},{"text":"xxxx","type":"text","marks":[{"type":"code_inline"}]},{"text":" = first 4 chars of SHA256 hash. Example: ","type":"text"},{"text":"BRD.01.07.a7f3","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"Tags","type":"text","marks":[{"type":"strong"}]},{"text":":","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Traceability: ","type":"text"},{"text":"@brd:","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"@prd:","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"@ears:","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"@bdd:","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"@adr:","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"@spec:","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"@tdd:","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"@iplan:","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Dependency: ","type":"text"},{"text":"@depends: TYPE-NN","type":"text","marks":[{"type":"code_inline"}]},{"text":" (hard prerequisite)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Discovery: ","type":"text"},{"text":"@discoverability: TYPE-NN","type":"text","marks":[{"type":"code_inline"}]},{"text":" (soft reference)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Threshold: ","type":"text"},{"text":"@threshold: TYPE.NN.key","type":"text","marks":[{"type":"code_inline"}]},{"text":" (e.g., ","type":"text"},{"text":"@threshold: PRD.01.kyc.l1.daily","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Threshold naming","type":"text","marks":[{"type":"strong"}]},{"text":": ","type":"text"},{"text":"{category}.{subcategory}.{attribute}[.{qualifier}]","type":"text","marks":[{"type":"code_inline"}]},{"text":". Universal categories: ","type":"text"},{"text":"perf","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"timeout","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"rate","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"retry","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"circuit","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"alert","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"cache","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"pool","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"queue","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"batch","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"Datetime","type":"text","marks":[{"type":"strong"}]},{"text":": ISO 8601 ","type":"text"},{"text":"YYYY-MM-DDTHH:MM:SS","type":"text","marks":[{"type":"code_inline"}]},{"text":". Date-only format deprecated.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"SDD Cross-Validation","type":"text"}]},{"type":"paragraph","content":[{"text":"Cross-document quality assurance: broken cross-references, orphaned artifacts, bidirectional link consistency, cumulative tag compliance, duplicate IDs, traceability matrix completeness.","type":"text"}]},{"type":"paragraph","content":[{"text":"Error codes (XDOC)","type":"text","marks":[{"type":"strong"}]},{"text":":","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"XDOC-001: Referenced requirement ID not found","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"XDOC-002: Missing cumulative tag","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"XDOC-003: Upstream document not found","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"XDOC-004–005: Link target/anchor missing","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"XDOC-006–010: Invalid tag format, gap in tag chain, circular reference, missing traceability, orphaned document","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Quality gates","type":"text","marks":[{"type":"strong"}]},{"text":":","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Zero cross-reference errors","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Zero orphaned artifacts","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"100% bidirectional link compliance","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"100% cumulative tag compliance","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Zero duplicate IDs","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Upstream artifact policy","type":"text","marks":[{"type":"strong"}]},{"text":": If a required upstream artifact is missing, the downstream functionality MUST NOT be implemented. Do NOT create missing upstream artifacts. Skip functionality instead.","type":"text"}]},{"type":"hr","attrs":{"markup":"---"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"Operation Modes","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Creating a Document","type":"text"}]},{"type":"paragraph","content":[{"text":"Say: \"Create a BRD for [project]\" — I will check for an approved plan first. If missing, STOP and create one before any document work.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Reviewing a Document","type":"text"}]},{"type":"paragraph","content":[{"text":"Say: \"Review [document path]\" — I will check for an approved plan first. If missing, STOP and create one before any review work.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Remediating a Document","type":"text"}]},{"type":"paragraph","content":[{"text":"Say: \"Fix findings in [document path] from [review report]\" — I will check for an approved plan first. If missing, STOP and create one before any remediation work.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Full Lifecycle","type":"text"}]},{"type":"paragraph","content":[{"text":"Say: \"Run full SDD lifecycle for [project]\" — I will FIRST create a planning package, get human approval, THEN orchestrate creation → review → remediation for each layer.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Planning-First Enforcement","type":"text"}]},{"type":"paragraph","content":[{"text":"For ALL modes above, execute this gate before any work:","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Check for existing plan in ","type":"text"},{"text":".hermes/plans/","type":"text","marks":[{"type":"code_inline"}]},{"text":" or ","type":"text"},{"text":"governance/plans/","type":"text","marks":[{"type":"code_inline"}]},{"text":" or ","type":"text"},{"text":"plans/","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"If plan exists: verify it covers the requested scope. If yes → proceed. If no → update plan first.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"If no plan exists: create plan per ","type":"text"},{"text":"plan","type":"text","marks":[{"type":"code_inline"}]},{"text":" skill, present to human, STOP until approval.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Record explicit human approval before transitioning to any document creation/review/remediation.","type":"text"}]}]}]},{"type":"hr","attrs":{"markup":"---"}}]},"metadata":{"date":"2026-06-05","name":"sdd-orchestrator","author":"@skillopedia","source":{"stars":15,"repo_name":"aidoc-flow-framework","origin_url":"https://github.com/vladm3105/aidoc-flow-framework/blob/HEAD/platforms/hermes/agent-skills/spec-driven-development/sdd-orchestrator/SKILL.md","repo_owner":"vladm3105","body_sha256":"2c8553a6907f1f83ded67a69f7744949eaeda57b7139870df7fda09a24cefd18","cluster_key":"024259469ee7a29fe005209de66cd2da0262875447bc605c530e00d2a2dae705","clean_bundle":{"format":"clean-skill-bundle-v1","source":"vladm3105/aidoc-flow-framework/platforms/hermes/agent-skills/spec-driven-development/sdd-orchestrator/SKILL.md","attachments":[{"id":"765a0c68-5dda-53b3-9b90-4c44928bdefd","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/765a0c68-5dda-53b3-9b90-4c44928bdefd/attachment.md","path":"governance/AI_AGENT_CAPACITY_PLANNING.md","size":55385,"sha256":"d3fb8284adb14345f4e570cdb84b7859065bdee28838e9d51ebf19e106199a33","contentType":"text/markdown; charset=utf-8"},{"id":"7989d392-dbf1-50fd-a4b6-da59b5ad0167","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/7989d392-dbf1-50fd-a4b6-da59b5ad0167/attachment.md","path":"governance/AI_AGENT_MEMORY.md","size":5894,"sha256":"eef39ad57d18a9dd9b009be493c4933e9eb68a1825077913608b255501f7c52d","contentType":"text/markdown; charset=utf-8"},{"id":"a5cc2c54-1c61-5881-8ae0-f3f93da25905","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/a5cc2c54-1c61-5881-8ae0-f3f93da25905/attachment.md","path":"governance/AI_ISSUE_LIFECYCLE.md","size":2439,"sha256":"e0d5d2d29edfc2b0ba0bc5c56f1f2228e6fac3ef559c1761913cf7852398b09f","contentType":"text/markdown; charset=utf-8"},{"id":"34c57fe2-db94-55cd-9d67-37e8627ddd64","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/34c57fe2-db94-55cd-9d67-37e8627ddd64/attachment.md","path":"governance/AI_PR_Review/AI_AGENT_REVIEW_WORKFLOW.md","size":28385,"sha256":"4672969f788f3931f87755dc66f241ab8469329a38a82847160b4d4d83f2982f","contentType":"text/markdown; charset=utf-8"},{"id":"3609aa5a-dd5a-56e2-ab70-87255a85da4c","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/3609aa5a-dd5a-56e2-ab70-87255a85da4c/attachment.md","path":"governance/AI_PR_Review/CLOUD_SETUP.md","size":2307,"sha256":"4466db73e64019c2d85822202b3749ada09e3185734ed5a33d317a2180dc72e2","contentType":"text/markdown; charset=utf-8"},{"id":"e78f5dd6-a9df-50fe-9dab-944cdfdd6554","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/e78f5dd6-a9df-50fe-9dab-944cdfdd6554/attachment.md","path":"governance/AI_PR_Review/FIX_INSTRUCTIONS.md","size":1960,"sha256":"d98e42c1815ccb603d0198bd0a574b004b8923efc70d08abfb26603768ec6b5b","contentType":"text/markdown; charset=utf-8"},{"id":"5d0c2d01-b783-5117-9c6e-29e9eb4921ff","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/5d0c2d01-b783-5117-9c6e-29e9eb4921ff/attachment.md","path":"governance/AI_PR_Review/IMPLEMENT_INSTRUCTIONS.md","size":4308,"sha256":"15516cdd22965415e204458849ef79796e6abd8f7d0df0cfcd3b4c3b5f914616","contentType":"text/markdown; charset=utf-8"},{"id":"281c90b5-85f9-580f-b3b2-b9d50e67ad3d","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/281c90b5-85f9-580f-b3b2-b9d50e67ad3d/attachment.md","path":"governance/AI_PR_Review/LOCAL_SETUP.md","size":5535,"sha256":"5a6528ff147e6d99ddee3b1593b4344dc208355021839c7c8cfc7b8276534855","contentType":"text/markdown; charset=utf-8"},{"id":"39b98bab-3b7e-52cf-a4cf-a19903fc0b2a","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/39b98bab-3b7e-52cf-a4cf-a19903fc0b2a/attachment.md","path":"governance/AI_PR_Review/MANUAL_REVIEW_GUIDE.md","size":9443,"sha256":"aa1cc26a15eb4e3a9b58fe984266944e2f874df681d90e820fb9861a3450b59b","contentType":"text/markdown; charset=utf-8"},{"id":"1a12b304-a7ef-5d29-a2c1-05512ae51198","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/1a12b304-a7ef-5d29-a2c1-05512ae51198/attachment.md","path":"governance/AI_PR_Review/ONBOARDING.md","size":5473,"sha256":"20774f308d86c660115f35ed2ac52aff41c5ae6cdf8c31f2cc38a0e600cab50c","contentType":"text/markdown; charset=utf-8"},{"id":"06ec0c37-1b18-5b78-8285-c8c18e3644ae","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/06ec0c37-1b18-5b78-8285-c8c18e3644ae/attachment.md","path":"governance/AI_PR_Review/README.md","size":14877,"sha256":"9919d6286ccc732f16813c2660456126028ce3acc80cfc4b36c99469823244b5","contentType":"text/markdown; charset=utf-8"},{"id":"7a988d82-a814-579c-8727-3c38a5d884d4","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/7a988d82-a814-579c-8727-3c38a5d884d4/attachment.md","path":"governance/AI_PR_Review/REVIEW_INSTRUCTIONS.md","size":9788,"sha256":"124d714e0f774a3dbb2318ac4df9159fc8eec9116fc35d36a406bfd8a9033b7b","contentType":"text/markdown; charset=utf-8"},{"id":"abf64bbe-9634-5378-b3e1-4fdd22efd5e1","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/abf64bbe-9634-5378-b3e1-4fdd22efd5e1/attachment.md","path":"governance/AI_TIME_ESTIMATION.md","size":18295,"sha256":"ba189721418cca3c0abc4d619b2f415cdcff251b751a3f788465af15d9ac21c0","contentType":"text/markdown; charset=utf-8"},{"id":"262b1340-db1e-5798-9000-4331fd71f7ee","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/262b1340-db1e-5798-9000-4331fd71f7ee/attachment.md","path":"governance/BRANCHING_STRATEGY.md","size":2435,"sha256":"b652e722e197c45fea6a5e848d8800e4773c8cce1d9790c4f2f7efe4b3c84b50","contentType":"text/markdown; charset=utf-8"},{"id":"409db5b1-a98c-574e-af63-9676da89ea54","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/409db5b1-a98c-574e-af63-9676da89ea54/attachment.md","path":"governance/CHG_GOVERNANCE_BRIDGE.md","size":794,"sha256":"d04f0d2716c56f299622aab49694644e671be38e5fbfa0c31ddd273487c868fe","contentType":"text/markdown; charset=utf-8"},{"id":"0a37fa4d-7a98-5ff4-a372-da87b211b3ff","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/0a37fa4d-7a98-5ff4-a372-da87b211b3ff/attachment.md","path":"governance/DEFINITION_OF_DONE.md","size":12626,"sha256":"54aca450d39755207726b6d5486ba61fdb7332145fc0cb84af38b63173b7f03c","contentType":"text/markdown; charset=utf-8"},{"id":"dc7d19da-4dcc-591b-bd4a-588162af2ed8","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/dc7d19da-4dcc-591b-bd4a-588162af2ed8/attachment.md","path":"governance/DEVELOPMENT_WORKFLOW_GUIDE.md","size":13742,"sha256":"b8e7e43cb474c93cfc56985dda279d9f84bc04d7579370c5bcee38ee806a9acf","contentType":"text/markdown; charset=utf-8"},{"id":"be125492-4c02-5e48-9247-ee8eee61d084","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/be125492-4c02-5e48-9247-ee8eee61d084/attachment.md","path":"governance/GOVERNANCE_RULES.md","size":7879,"sha256":"17166c35c7aeed6cac81104aba13087263f2bdf39f37507e9acbb47cc52daabc","contentType":"text/markdown; charset=utf-8"},{"id":"da764f07-e3ec-54a1-b414-5ec858f6f848","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/da764f07-e3ec-54a1-b414-5ec858f6f848/attachment.md","path":"governance/HOME_REPO.md","size":14262,"sha256":"24c4b9dd81b09761870c156928998db69c0a30900459b39511a12753953db1df","contentType":"text/markdown; charset=utf-8"},{"id":"4f3d27e6-f4a7-59e0-975b-01c1eda169f4","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/4f3d27e6-f4a7-59e0-975b-01c1eda169f4/attachment.md","path":"governance/README.md","size":5375,"sha256":"19cb1327a3642b45421e935c667c0a44b3e1c3a89ceb1a192ed7a90224effad3","contentType":"text/markdown; charset=utf-8"},{"id":"d885dfe9-b9a8-589e-b845-4a23f00be5f7","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/d885dfe9-b9a8-589e-b845-4a23f00be5f7/attachment.md","path":"governance/RELEASE_PROCESS.md","size":3484,"sha256":"e11a9fcce0ba44a28e8e38a99eecee1c31aed534bb6365c7483133d16a469e14","contentType":"text/markdown; charset=utf-8"},{"id":"37145a0b-88f3-5946-b29c-a75637247f25","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/37145a0b-88f3-5946-b29c-a75637247f25/attachment.md","path":"governance/REPOSITORY_STRATEGY.md","size":7259,"sha256":"70424c8a3da53dbbd884c12e6087184443a20ef748fb88bf05de2772476f3f28","contentType":"text/markdown; charset=utf-8"},{"id":"228b3ea7-10ae-518b-b5ce-c6af1a3f1e49","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/228b3ea7-10ae-518b-b5ce-c6af1a3f1e49/attachment.md","path":"governance/REPO_STRUCTURE_DECISION_MATRIX.md","size":3050,"sha256":"297c61bc88cee6290ead4f746171c45f7bdd2610fffe17b7ebb3f7d1fa4d2fdf","contentType":"text/markdown; charset=utf-8"},{"id":"dbcba9a7-c041-5d51-92c4-8c3a3326afce","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/dbcba9a7-c041-5d51-92c4-8c3a3326afce/attachment.md","path":"governance/ROLES_AND_TOOLS.md","size":15002,"sha256":"c5dad70cfd52be0b7c3029751493a8d416190a264a09a45ec89c3e3035b6ccac","contentType":"text/markdown; charset=utf-8"},{"id":"f6ffb022-ac79-5088-98ce-ab347883ca12","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/f6ffb022-ac79-5088-98ce-ab347883ca12/attachment.md","path":"governance/SDD_DEPTH_GUIDE.md","size":1740,"sha256":"433cb13683840fd5374bd0f35708468754cf63f3636dceb6d9d221ec7a0f6e99","contentType":"text/markdown; charset=utf-8"},{"id":"dfd2bc78-d297-5361-a5bf-9fc1f8293676","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/dfd2bc78-d297-5361-a5bf-9fc1f8293676/attachment.md","path":"governance/SECURITY_CHECKLIST.md","size":3187,"sha256":"d86a07e05ecc191e116b03d0ecf5ad8ddb35a5a71f497b3f388c8e9ca6f21346","contentType":"text/markdown; charset=utf-8"},{"id":"68a85452-9306-5cd0-8f58-5458587e5e9c","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/68a85452-9306-5cd0-8f58-5458587e5e9c/attachment.md","path":"governance/TASKS_IPLAN_BRIDGE.md","size":795,"sha256":"b0d55f9d4e9da8fbd653dde941f97cc45706d4ec90b8b9c5550ea708967f3fb2","contentType":"text/markdown; charset=utf-8"},{"id":"61a491df-cc98-5f72-93d6-504cb48dacff","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/61a491df-cc98-5f72-93d6-504cb48dacff/attachment.md","path":"governance/TROUBLESHOOTING.md","size":3806,"sha256":"59a6a84f44371acdfe525e4534e98fa04ace0e1a8b6f19a2c7ac6a9ee096f02b","contentType":"text/markdown; charset=utf-8"},{"id":"25f3805d-7ab6-585e-b478-b928391bc88b","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/25f3805d-7ab6-585e-b478-b928391bc88b/attachment.md","path":"governance/TSPEC_BDD_QA_BRIDGE.md","size":959,"sha256":"f87d43ecd040cb8f5aceb3e821c31b24ff21d357d880a0ef0858ae3022cbd054","contentType":"text/markdown; charset=utf-8"},{"id":"e02ff113-eb27-587e-b516-680353a80064","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/e02ff113-eb27-587e-b516-680353a80064/attachment.md","path":"governance/github/GITHUB_PROJECT_SETUP.md","size":53395,"sha256":"152d997c27dce1a2071b01bbe44c1821d0d4babedbc07cbbb657b6134eae57ea","contentType":"text/markdown; charset=utf-8"},{"id":"755a351c-e3a8-5062-8c05-23eba60044a8","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/755a351c-e3a8-5062-8c05-23eba60044a8/attachment.md","path":"governance/github/GITHUB_PROJECT_SETUP_AI_FIRST.md","size":2082,"sha256":"66e960f7fe936e6e8d4a6d18a0e33c631a747444adb82829ac0f90eb7db11ce0","contentType":"text/markdown; charset=utf-8"},{"id":"4a074930-dc37-537f-815c-57ec79b1beb2","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/4a074930-dc37-537f-815c-57ec79b1beb2/attachment.md","path":"governance/github/GITHUB_TOOLS_SETUP.md","size":30811,"sha256":"08524d3d61dc5f38617f198c4e1160f56916ac430f935797d7265ef2a792bddb","contentType":"text/markdown; charset=utf-8"},{"id":"e73a2f5d-c786-5bdb-a49c-4fb3766017c0","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/e73a2f5d-c786-5bdb-a49c-4fb3766017c0/attachment.md","path":"governance/github/GITHUB_WORKFLOWS.md","size":47622,"sha256":"50f933524d2c51222148d92272d02614f2c7d898788ab8cc73873ef5e47afc9f","contentType":"text/markdown; charset=utf-8"},{"id":"35f073a6-eba4-5923-8d05-d0a7d3d066e4","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/35f073a6-eba4-5923-8d05-d0a7d3d066e4/attachment.yaml","path":"governance/github/LABEL_REGISTRY.yaml","size":5376,"sha256":"596d8fab8f77e509d460f6c7cc915ebde8d1c99314a4421ff4daf31aa4c3807e","contentType":"application/yaml; charset=utf-8"},{"id":"96337eb1-1611-5960-aac7-9a6ba76cf0d0","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/96337eb1-1611-5960-aac7-9a6ba76cf0d0/attachment.md","path":"governance/github/WORKFLOW_INTEGRATION.md","size":664,"sha256":"8b6016145eb03a0b54a1b664afd523b422a528884ca9ca176a05557d2c5dbfdb","contentType":"text/markdown; charset=utf-8"},{"id":"ebb11ecf-6a75-56c0-a7fe-9e36f5c12a5e","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/ebb11ecf-6a75-56c0-a7fe-9e36f5c12a5e/attachment.md","path":"governance/memory/GLOBAL_LEARNINGS.md","size":581,"sha256":"67e3175a5f27449d1ae26701dd5d80ac96ab501dfdc3f3c9c583dfebb8784b4f","contentType":"text/markdown; charset=utf-8"},{"id":"cf57c755-3d87-53a0-9d15-f459910c77c1","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/cf57c755-3d87-53a0-9d15-f459910c77c1/attachment.md","path":"governance/plans/IPLAN-TEMPLATE.md","size":860,"sha256":"f3044d846a9187ad51ed8fadadbe49844cdc10106b3d4d1dd6a5649d617071cb","contentType":"text/markdown; charset=utf-8"},{"id":"7c4ae731-8474-58a2-9b8a-0b8d16fb84be","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/7c4ae731-8474-58a2-9b8a-0b8d16fb84be/attachment.md","path":"governance/plans/README.md","size":4959,"sha256":"ca981177bdd94ccf308e88e145ddcf63670ea57626a10d128c99b5840c3a0801","contentType":"text/markdown; charset=utf-8"},{"id":"6ea98794-e96f-5d69-a700-f814f63dc1c4","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/6ea98794-e96f-5d69-a700-f814f63dc1c4/attachment.py","path":"governance/scripts/apply_doc_path_aliases.py","size":7196,"sha256":"12092fb8a822e18f49413830d312f7e567588e95f5cb033d06e73eef1eee63b9","contentType":"text/x-python; charset=utf-8"},{"id":"b803fbd9-d748-5736-9da6-2824eee9af15","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/b803fbd9-d748-5736-9da6-2824eee9af15/attachment.json","path":"governance/scripts/cicd/phase-deployments.json","size":492,"sha256":"bc96319ac2c5e32d765ac5269a54ea5f999eae4ee82d485e9fb28a7a368e5a46","contentType":"application/json; charset=utf-8"},{"id":"151056fa-5c29-5c66-a176-b3e88b84271e","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/151056fa-5c29-5c66-a176-b3e88b84271e/attachment.md","path":"governance/scripts/ghes-runner/GHES_RUNNER_GUIDE.md","size":11525,"sha256":"d12c6d86bb8560d5ca51bab74e797d52dfc63dcdffd65f9923832fbeadd1d68b","contentType":"text/markdown; charset=utf-8"},{"id":"6a1e8a69-2ed0-548a-bf3b-157f9f0b2d7a","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/6a1e8a69-2ed0-548a-bf3b-157f9f0b2d7a/attachment.yml","path":"governance/scripts/ghes-runner/docker-compose.yml","size":848,"sha256":"50b43353bd94855503bbff941b13344d57564aced45e354706c5160dccf1e620","contentType":"application/yaml; charset=utf-8"},{"id":"75051789-a5c8-50dc-acec-6e4e67b5f09c","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/75051789-a5c8-50dc-acec-6e4e67b5f09c/attachment.sh","path":"governance/scripts/ghes-runner/setup-local-runner.sh","size":4443,"sha256":"ed3ac0b0a5ff9a6da11dd7127a2cca8eeb1d00ce21568a944f19d366fe823cc5","contentType":"application/x-sh; charset=utf-8"},{"id":"ae069675-05d6-5d24-bef2-4bf4efe13711","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/ae069675-05d6-5d24-bef2-4bf4efe13711/attachment.sh","path":"governance/scripts/ghes-runner/start.sh","size":2737,"sha256":"7414fb487777a4ab5b70eb1eb9b2bab9d2f77b09eed01843de61d99c25d4a842","contentType":"application/x-sh; charset=utf-8"},{"id":"181ece96-1e9a-55cc-a75f-2ece41584735","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/181ece96-1e9a-55cc-a75f-2ece41584735/attachment.md","path":"governance/scripts/project_setup/README.md","size":4232,"sha256":"9921295633b11c332a7338bd0019eae76948a1a1576fb4d642d112c4cc93aa5a","contentType":"text/markdown; charset=utf-8"},{"id":"227bd3b8-f3d0-56a8-bb47-2dccb48aad40","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/227bd3b8-f3d0-56a8-bb47-2dccb48aad40/attachment.md","path":"governance/scripts/project_setup/cloud/aws/README.md","size":2856,"sha256":"b02b558963ea32b4d4f502e281f86ac6f0781efd7f4ad889a1d7ed244ddc4933","contentType":"text/markdown; charset=utf-8"},{"id":"9bd41a3b-c517-52ce-9f34-224de23297df","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/9bd41a3b-c517-52ce-9f34-224de23297df/attachment.sh","path":"governance/scripts/project_setup/cloud/aws/setup-ecr.sh","size":2943,"sha256":"459215915c77836c5fa18247e258927b19e1f67f67047a6148bd51d3adc57cae","contentType":"application/x-sh; charset=utf-8"},{"id":"4172590c-4ef1-5b78-a73f-4e0bb684dbfd","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/4172590c-4ef1-5b78-a73f-4e0bb684dbfd/attachment.sh","path":"governance/scripts/project_setup/cloud/aws/setup-iam-oidc.sh","size":4477,"sha256":"9e302278bdc49e5fc72297b490f3455b8d881fcb62755ffdbc2a1a40f1ce8438","contentType":"application/x-sh; charset=utf-8"},{"id":"eaba26ec-a268-5ece-b9af-079b476112f8","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/eaba26ec-a268-5ece-b9af-079b476112f8/attachment.md","path":"governance/scripts/project_setup/cloud/azure/README.md","size":3458,"sha256":"e32f231d4f27538a3fbc71b3f2a03552c7ace2eb101e703a0a59d2c130f402f0","contentType":"text/markdown; charset=utf-8"},{"id":"422c057f-77c6-5ab8-9a04-989d974f9c86","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/422c057f-77c6-5ab8-9a04-989d974f9c86/attachment.sh","path":"governance/scripts/project_setup/cloud/azure/setup-acr.sh","size":3365,"sha256":"d34f0496d0737b146b13adb9ad39f45bf990ace1629f193918ddd1085d6ab757","contentType":"application/x-sh; charset=utf-8"},{"id":"6cdda75a-d5c4-5146-9e56-a2307d22ae97","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/6cdda75a-d5c4-5146-9e56-a2307d22ae97/attachment.sh","path":"governance/scripts/project_setup/cloud/azure/setup-managed-identity.sh","size":5144,"sha256":"63b22daeba0b7685da3b2add501023f372d4c4bcddb427ebaba46c77d06f867e","contentType":"application/x-sh; charset=utf-8"},{"id":"11256f06-197d-5420-9506-6459922fd363","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/11256f06-197d-5420-9506-6459922fd363/attachment.md","path":"governance/scripts/project_setup/cloud/gcp/README.md","size":4367,"sha256":"7df254b504898b30b9873264b4683ccceedef5f2f7370d3ccfc7ab0800dc00ea","contentType":"text/markdown; charset=utf-8"},{"id":"e665fa8e-3a62-555d-a836-2a6ee6b7f9ef","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/e665fa8e-3a62-555d-a836-2a6ee6b7f9ef/attachment.sh","path":"governance/scripts/project_setup/cloud/gcp/configure_revision_retention.sh","size":3708,"sha256":"9687fdf825d7daa8b21c39000f217ef1b14d62e814bd3d0f03f030f4dc9d2075","contentType":"application/x-sh; charset=utf-8"},{"id":"df40b7f4-eb9a-5800-aa9b-695321852649","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/df40b7f4-eb9a-5800-aa9b-695321852649/attachment.sh","path":"governance/scripts/project_setup/cloud/gcp/setup-ai-review-gcp.sh","size":17619,"sha256":"364d7b3f0a5246965d4b41015c2c1d6e280bfe6b2c0d65011bdb29b9b0d2befc","contentType":"application/x-sh; charset=utf-8"},{"id":"93edd79d-b89f-5009-abe1-e2f1307ded26","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/93edd79d-b89f-5009-abe1-e2f1307ded26/attachment.sh","path":"governance/scripts/project_setup/cloud/gcp/setup-environments.sh","size":9687,"sha256":"747d3d6b2f545085f08d6cf82318f7940cb4064b9111809c392fc3901a0b4607","contentType":"application/x-sh; charset=utf-8"},{"id":"ff427a36-d6bd-5950-8544-5fed84652839","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/ff427a36-d6bd-5950-8544-5fed84652839/attachment.sh","path":"governance/scripts/project_setup/cloud/gcp/setup-projects.sh","size":9483,"sha256":"1ef83b61041847746870702a0706fb773da18693a02133c627dabed50aa91ff6","contentType":"application/x-sh; charset=utf-8"},{"id":"f9a23c06-3f7d-51e6-9a77-0a4c7c9a60ab","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/f9a23c06-3f7d-51e6-9a77-0a4c7c9a60ab/attachment.sh","path":"governance/scripts/project_setup/cloud/gcp/setup-wif.sh","size":6589,"sha256":"eb3e8d416c570d7b5375264f6b5a04afe3ae36ac64d80b2985450c8d057fd052","contentType":"application/x-sh; charset=utf-8"},{"id":"ce3f10aa-49f1-5f39-b999-ba6f6abafe3c","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/ce3f10aa-49f1-5f39-b999-ba6f6abafe3c/attachment.sh","path":"governance/scripts/project_setup/cloud/gcp/setup_artifact_registry.sh","size":3650,"sha256":"4a47dbadf30683029583576ba8406fee90f8b7ee75ced033db553427ba09316e","contentType":"application/x-sh; charset=utf-8"},{"id":"503e76a1-fb07-5db4-88b0-3c029f8981f8","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/503e76a1-fb07-5db4-88b0-3c029f8981f8/attachment.sh","path":"governance/scripts/project_setup/setup_github_environments.sh","size":3382,"sha256":"e197d6084481111cc80580311455851c2254fa8ee6c161ef94a19b0cd77d2828","contentType":"application/x-sh; charset=utf-8"},{"id":"197926e5-f233-5cd9-bc9a-d8f244f16294","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/197926e5-f233-5cd9-bc9a-d8f244f16294/attachment.sh","path":"governance/scripts/project_setup/validate_configuration.sh","size":4859,"sha256":"70e8790e7b17f120c9b49fdcfc2b8a99f9dade53e7c3461fd247b4f8cc026e33","contentType":"application/x-sh; charset=utf-8"},{"id":"d4e933e1-36ce-5fbd-adcf-b201d4daa684","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/d4e933e1-36ce-5fbd-adcf-b201d4daa684/attachment.sh","path":"governance/scripts/setup-ai-pr-review-labels.sh","size":2850,"sha256":"e2e2da0ec7f39d44b56d3ed95a2defc0209ee047e7afce3feb9819f39c4c901a","contentType":"application/x-sh; charset=utf-8"},{"id":"8424296d-ad13-5572-abe0-47440ae9b5f7","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/8424296d-ad13-5572-abe0-47440ae9b5f7/attachment.sh","path":"governance/scripts/setup-all-labels.sh","size":3015,"sha256":"55e84152d9079978c156c95ce0de8fa1ac81f02fd314ec156d36b139342e03ce","contentType":"application/x-sh; charset=utf-8"},{"id":"f4e5afd4-4e87-5aaf-9e69-c725cb0fe687","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/f4e5afd4-4e87-5aaf-9e69-c725cb0fe687/attachment.sh","path":"governance/scripts/setup_project_hybrid.sh","size":8294,"sha256":"1959ff1382f52ce49e7cfef72ffb558a581821d964187f49ab932ee54f734d89","contentType":"application/x-sh; charset=utf-8"},{"id":"b5ad0820-ef74-5409-b475-dd79478a9857","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/b5ad0820-ef74-5409-b475-dd79478a9857/attachment.py","path":"governance/scripts/workflows/check_conflicts.py","size":2975,"sha256":"744d4dac0f00b269c7a0dfbf0d91338678bbc24e92cb9803bbc36a5587e8e25e","contentType":"text/x-python; charset=utf-8"},{"id":"6b5456ef-9623-5103-a843-f65ddb132fcf","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/6b5456ef-9623-5103-a843-f65ddb132fcf/attachment.py","path":"governance/scripts/workflows/check_error_rate.py","size":1733,"sha256":"9292499c4ebb905e3bd77aa01e4395962ab1439ddf1acdfb11520cc101acde2c","contentType":"text/x-python; charset=utf-8"},{"id":"0ca336b7-fdf0-5728-8ea8-ce5110a753e7","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/0ca336b7-fdf0-5728-8ea8-ce5110a753e7/attachment.py","path":"governance/scripts/workflows/check_iteration_limit.py","size":1430,"sha256":"8f8dcc51dc6c106a59f1e21e06893d0d8829123ffd42ba7eadb54669dd716af9","contentType":"text/x-python; charset=utf-8"},{"id":"72f45128-0d16-54aa-aca1-c67fb14cb6d7","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/72f45128-0d16-54aa-aca1-c67fb14cb6d7/attachment.py","path":"governance/scripts/workflows/check_phase_completion.py","size":7058,"sha256":"3eac2d9ed0f3d74f1491263a084d4c54e7f710a1e02e92b8b4048175984808ce","contentType":"text/x-python; charset=utf-8"},{"id":"be8067cb-839e-5531-a0cd-954958388a0f","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/be8067cb-839e-5531-a0cd-954958388a0f/attachment.py","path":"governance/scripts/workflows/check_qa_required.py","size":3546,"sha256":"bfc719a2d8db0e361acba9059addd07171ba2f581e13cabcac2d178bbdeeadfb","contentType":"text/x-python; charset=utf-8"},{"id":"25f252ae-303e-5f1d-83aa-2b91f56d0acc","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/25f252ae-303e-5f1d-83aa-2b91f56d0acc/attachment.py","path":"governance/scripts/workflows/check_staging_ready.py","size":7193,"sha256":"1a4ac3bb7c20e1237830d1c0b4ea9792b50d954e616c7fea9460b3ca1afd1d22","contentType":"text/x-python; charset=utf-8"},{"id":"b00ffd26-5a3f-5fa9-b8b6-44e37d249c6e","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/b00ffd26-5a3f-5fa9-b8b6-44e37d249c6e/attachment.py","path":"governance/scripts/workflows/create_bug_issues.py","size":3696,"sha256":"e6353bf248baffd7051d360a8f25f83087d4010f23d1847b4cb0886c69ba909f","contentType":"text/x-python; charset=utf-8"},{"id":"6575e5e6-177f-5096-a6cc-092514e26125","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/6575e5e6-177f-5096-a6cc-092514e26125/attachment.py","path":"governance/scripts/workflows/create_test_failure_issues.py","size":2663,"sha256":"5239f27e8542f4190ad5ca01168e8783b8b41e7539d4970e85522f8ca93d9a33","contentType":"text/x-python; charset=utf-8"},{"id":"9435d3b9-3a77-5773-b888-bf8663737fec","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/9435d3b9-3a77-5773-b888-bf8663737fec/attachment.py","path":"governance/scripts/workflows/execute_qa_tests.py","size":5536,"sha256":"3d128ef78e8c9cd321f785ce04cd73d327efa63c6baf0623b990a88178e9d964","contentType":"text/x-python; charset=utf-8"},{"id":"e5b3c536-5f56-53d5-a311-e0ac8ea52bfe","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/e5b3c536-5f56-53d5-a311-e0ac8ea52bfe/attachment.py","path":"governance/scripts/workflows/extract_test_plan.py","size":4132,"sha256":"683d1cf0741c852092461fc69a4747c25b4fba776802215041904a1537b90beb","contentType":"text/x-python; charset=utf-8"},{"id":"b43f079b-1f08-5d21-af6d-7e6061f07bb9","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/b43f079b-1f08-5d21-af6d-7e6061f07bb9/attachment.py","path":"governance/scripts/workflows/generate_deployment_plan.py","size":8295,"sha256":"5b8cb83725fc52b4e6ed171d144f2207ffbf3a1da33ce26c4c31b4ea14e67d9a","contentType":"text/x-python; charset=utf-8"},{"id":"17076fd2-73b1-536b-afff-7f97f4a3c14f","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/17076fd2-73b1-536b-afff-7f97f4a3c14f/attachment.py","path":"governance/scripts/workflows/generate_iplan_from_issue.py","size":11105,"sha256":"91c0475fac537e088869d12be17fb5516640e9a5d4ecce3fcfa5918cf6b52c6d","contentType":"text/x-python; charset=utf-8"},{"id":"1944f903-5e59-539e-b7c7-5573120631c3","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/1944f903-5e59-539e-b7c7-5573120631c3/attachment.py","path":"governance/scripts/workflows/generate_phase_summary.py","size":7399,"sha256":"d4374538f36f2326d42898814b7ae34fd0348628a18608a7f3d5b850efbd33c7","contentType":"text/x-python; charset=utf-8"},{"id":"2c9542a9-3fec-5e37-8648-d14ffef76c52","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/2c9542a9-3fec-5e37-8648-d14ffef76c52/attachment.py","path":"governance/scripts/workflows/handle_issue_reopen.py","size":2182,"sha256":"eaf679b2ea8679c06990cc3c4a745ef3438e5b225f42e88614c03beb14cac71c","contentType":"text/x-python; charset=utf-8"},{"id":"2f86709c-38d1-58a1-9369-c8f5c85c72e1","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/2f86709c-38d1-58a1-9369-c8f5c85c72e1/attachment.sh","path":"governance/scripts/workflows/smoke_test.sh","size":3470,"sha256":"6b1106d6dc407f05a972b81e792db1d918d32fecd6db95016fdcd0fb0a6affc5","contentType":"application/x-sh; charset=utf-8"},{"id":"26564086-80a0-526d-a52d-1cd88a00cbd2","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/26564086-80a0-526d-a52d-1cd88a00cbd2/attachment.py","path":"governance/scripts/workflows/sync_tasks_from_issues.py","size":1054,"sha256":"60ecde9e8493472aab22b04e81d100e67893e1c0fe2ddf1a691c7297ed026291","contentType":"text/x-python; charset=utf-8"},{"id":"a9e0d47f-accd-5ccd-ba96-18c8374a8163","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/a9e0d47f-accd-5ccd-ba96-18c8374a8163/attachment.py","path":"governance/scripts/workflows/update_phase_tracking.py","size":3908,"sha256":"56b725eaf92e903fcba6dd3352e9dd0a268fa90af1469204104c791feeb19a22","contentType":"text/x-python; charset=utf-8"},{"id":"8df721f5-c91a-59dc-909a-5440226fbf29","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/8df721f5-c91a-59dc-909a-5440226fbf29/attachment.py","path":"governance/scripts/workflows/update_prod_tracking.py","size":1266,"sha256":"4f128a3b9a632bc50013225af70792f2969d580eebd3aa1bec0252e365e781e8","contentType":"text/x-python; charset=utf-8"},{"id":"864c8b7a-5071-5df2-98f9-b3893c066b4b","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/864c8b7a-5071-5df2-98f9-b3893c066b4b/attachment.py","path":"governance/scripts/workflows/update_staging_tracking.py","size":2739,"sha256":"7937e271229f27e3ac8cb2f033d2f727390c61d06ec8d08557101fa8f560f60d","contentType":"text/x-python; charset=utf-8"},{"id":"df92cf71-2057-558a-8739-33fd3fa42ae9","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/df92cf71-2057-558a-8739-33fd3fa42ae9/attachment.py","path":"governance/scripts/workflows/validate_governance.py","size":6547,"sha256":"421f9e457bc7a44999f5f4a18155df9b60c83d21bac7d063056780c8527be3b7","contentType":"text/x-python; charset=utf-8"},{"id":"cd69a35f-2de6-5875-be9a-56025bbe7ba5","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/cd69a35f-2de6-5875-be9a-56025bbe7ba5/attachment.py","path":"governance/scripts/workflows/validate_project_setup.py","size":7492,"sha256":"0e1f4e707f31035f30a7e402826a699d149d0ba71b9eef99b0ea4d6098c643a4","contentType":"text/x-python; charset=utf-8"},{"id":"eee97492-89d0-5d42-a9f3-b99b57830552","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/eee97492-89d0-5d42-a9f3-b99b57830552/attachment.py","path":"governance/scripts/workflows/verify_acceptance_criteria.py","size":8773,"sha256":"d91def9380c90ac014ac372ca4d56c0606edc52303be16058cacd808572e6b5a","contentType":"text/x-python; charset=utf-8"},{"id":"25558c88-d0b0-59c5-84ca-9c146997510c","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/25558c88-d0b0-59c5-84ca-9c146997510c/attachment.py","path":"governance/scripts/workflows/verify_phase_prerequisites.py","size":2428,"sha256":"6d2f48db067f85e91355ac2a892de014010cf28b11cc4c2a4cd348bb2c340812","contentType":"text/x-python; charset=utf-8"},{"id":"0d288e78-d92b-5617-8a01-33b612cb5c9d","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/0d288e78-d92b-5617-8a01-33b612cb5c9d/attachment.py","path":"governance/scripts/workflows/verify_prod_readiness.py","size":1904,"sha256":"89733157cb6ff1192a02a2577d46df402906cccd641719c1ec16fc4e8f576898","contentType":"text/x-python; charset=utf-8"},{"id":"4ba3197c-2718-5eb0-91b9-cef9087b8903","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/4ba3197c-2718-5eb0-91b9-cef9087b8903/attachment.md","path":"governance/setup/CLOUD_GUIDE.md","size":10797,"sha256":"33f927f1972816e1acc8c610c22202c3eb9ebd2066ab6a44e31793ec2cabb18d","contentType":"text/markdown; charset=utf-8"},{"id":"9b7fcd6a-63b3-5b92-950f-d7619ffbbdf5","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/9b7fcd6a-63b3-5b92-950f-d7619ffbbdf5/attachment.md","path":"governance/setup/CONFIG.md","size":443,"sha256":"06b869da6121cdb70e1d99fad59aa58d6e9051783e4af0c2f599527454721dea","contentType":"text/markdown; charset=utf-8"},{"id":"7ea109d9-1d71-5250-a252-eb9a3565f169","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/7ea109d9-1d71-5250-a252-eb9a3565f169/attachment.md","path":"governance/setup/PRECOMMIT_HOOK_LIBRARY_CONSUMER_GUIDE.md","size":941,"sha256":"2c4676d1604f06c0189ca43df6b9ccc4ad4f94ae2e53ade47f4d854a2400aa56","contentType":"text/markdown; charset=utf-8"},{"id":"2d40c7d0-62c0-543b-b0f6-118228637fd8","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/2d40c7d0-62c0-543b-b0f6-118228637fd8/attachment.md","path":"governance/setup/SETUP_GUIDE.md","size":565,"sha256":"0672c688b9ef88331db091001ba7151c9b7140b1d3265231ba051ec1000203e4","contentType":"text/markdown; charset=utf-8"},{"id":"479c1c1b-4457-58ad-9be2-aa869140fc99","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/479c1c1b-4457-58ad-9be2-aa869140fc99/attachment.json","path":"governance/templates/.mcp.json","size":1223,"sha256":"c4e7807ea77616184f6d8b735dd39080bb3ea57875978db2492086bcb1bf2023","contentType":"application/json; charset=utf-8"},{"id":"cee0bb2d-3964-5899-bf36-8a25cb6dbfab","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/cee0bb2d-3964-5899-bf36-8a25cb6dbfab/attachment.md","path":"governance/templates/AWS-DEPLOYMENT.md","size":7241,"sha256":"cc796a3386024544b33973cd521b69b17561555e4ef9ea6923f35fef4ff2889b","contentType":"text/markdown; charset=utf-8"},{"id":"db3de1d9-9e7d-5e6c-9a17-92990c32cfa0","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/db3de1d9-9e7d-5e6c-9a17-92990c32cfa0/attachment.md","path":"governance/templates/AZURE-DEPLOYMENT.md","size":8768,"sha256":"57427daaac9d3327b2d6eb1a13f8af91d8ee81fc9257fac63db47673555d1e67","contentType":"text/markdown; charset=utf-8"},{"id":"3d1bab7d-0951-5e07-88bf-3d0ffc8f5aa4","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/3d1bab7d-0951-5e07-88bf-3d0ffc8f5aa4/attachment.md","path":"governance/templates/CLAUDE.md","size":11118,"sha256":"e3c47fa042506220488f20004256ef4ce935835e0b84242460ed1810e68fa058","contentType":"text/markdown; charset=utf-8"},{"id":"79d671e5-4202-523c-bace-eae221147692","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/79d671e5-4202-523c-bace-eae221147692/attachment.md","path":"governance/templates/CONTRIBUTING.md","size":9968,"sha256":"b96de547bc8cb0a6835076dfcf226164365ab799c9c60f4f5f44697493f3ece9","contentType":"text/markdown; charset=utf-8"},{"id":"79be7389-c477-561a-8653-f3e613f58413","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/79be7389-c477-561a-8653-f3e613f58413/attachment.md","path":"governance/templates/DEVELOPER_GUIDE.md","size":9267,"sha256":"c709c27a35fad402ed435fa47ece1b6a5853bbd544b86cb9e039b8d163c782a8","contentType":"text/markdown; charset=utf-8"},{"id":"a583eb8f-5abe-578f-961b-7109bf21f491","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/a583eb8f-5abe-578f-961b-7109bf21f491/attachment.md","path":"governance/templates/GCP-DEPLOYMENT.md","size":11189,"sha256":"63fdbe358e0d5a50421521268177f1520c826cecf79ff44bf79c871168b950f5","contentType":"text/markdown; charset=utf-8"},{"id":"3f34f0b5-18c6-5b43-846b-6a7e25f24d1a","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/3f34f0b5-18c6-5b43-846b-6a7e25f24d1a/attachment.md","path":"governance/templates/HANDOFF.md","size":6771,"sha256":"0e0aa5968f4034a5dc6e4a189d3bc4bf314a2451f2e646fd87aff9608cbd0e2b","contentType":"text/markdown; charset=utf-8"},{"id":"7de07fd4-36ea-5d6d-b433-fda5ad684d7d","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/7de07fd4-36ea-5d6d-b433-fda5ad684d7d/attachment.md","path":"governance/templates/IPLAN-TEMPLATE.md","size":860,"sha256":"f3044d846a9187ad51ed8fadadbe49844cdc10106b3d4d1dd6a5649d617071cb","contentType":"text/markdown; charset=utf-8"},{"id":"356039f1-4fd5-5765-b82f-330d11de8dc0","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/356039f1-4fd5-5765-b82f-330d11de8dc0/attachment.md","path":"governance/templates/MEMORY.md","size":1269,"sha256":"f2bfeb33f997e4aa4d9151ded47ee26b9c37e6defa1c6867ac3b0ffbf74b6ef2","contentType":"text/markdown; charset=utf-8"},{"id":"37fc77b3-f5e4-591a-819c-0e3224078bfc","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/37fc77b3-f5e4-591a-819c-0e3224078bfc/attachment.md","path":"governance/templates/PROJECT_DEFINITION.md","size":3917,"sha256":"9430473a490ea65b4d9d82de6c651f934ae34566f5d8c2fb3530749ed3011d22","contentType":"text/markdown; charset=utf-8"},{"id":"1abe437a-1d22-58f9-8c91-bb36ac121c8f","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/1abe437a-1d22-58f9-8c91-bb36ac121c8f/attachment.md","path":"governance/templates/PROJECT_KICKOFF_PLAN-TEMPLATE.md","size":5203,"sha256":"07df47b52cb5dfbbedf1e7520e02a7b14c13606eca2012da65eb17a9525f6749","contentType":"text/markdown; charset=utf-8"},{"id":"bd06b4c1-97ac-5c37-9e98-09e5d82b6180","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/bd06b4c1-97ac-5c37-9e98-09e5d82b6180/attachment.md","path":"governance/templates/PROJECT_PLAN-TEMPLATE.md","size":7540,"sha256":"9d932e38179ad1ac252ec6e5aa87bb6efeb8b04397c5689685d6122aa2a5c51b","contentType":"text/markdown; charset=utf-8"},{"id":"2da298bd-d4ed-538b-b71f-cee6198dee09","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/2da298bd-d4ed-538b-b71f-cee6198dee09/attachment.md","path":"governance/templates/README.md","size":14515,"sha256":"9d6e6b1cf5e228306eb1f824ac90550927f3d4ebc5d8691624ad78b1eadec91f","contentType":"text/markdown; charset=utf-8"},{"id":"cea2ac23-3248-5229-be96-5aa97093fa53","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/cea2ac23-3248-5229-be96-5aa97093fa53/attachment.md","path":"governance/templates/README_AIAGENT.md","size":18256,"sha256":"97e0f1be88a4dba9a60f7e549f702b7aa42fc44cf84bc0d87d26db6f23ea97a0","contentType":"text/markdown; charset=utf-8"},{"id":"8c32d908-5c20-5ca1-b003-6f5e2d75e559","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/8c32d908-5c20-5ca1-b003-6f5e2d75e559/attachment.md","path":"governance/templates/ROADMAP-TEMPLATE.md","size":7845,"sha256":"897f1e3b5403494f13563721b4263de7c62f3508252dc32db0127be52ae33c6a","contentType":"text/markdown; charset=utf-8"},{"id":"9168d84d-2018-55ab-8058-4e7f87715145","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/9168d84d-2018-55ab-8058-4e7f87715145/attachment.md","path":"governance/templates/SECURITY_CHECKLIST-TEMPLATE.md","size":993,"sha256":"a4426e3d194376f09a11fff8401366234c9ff39f1c9c3f13869ae5f4ccea8ac9","contentType":"text/markdown; charset=utf-8"},{"id":"f5781a78-9892-5dd3-a8c5-a047d5cb3318","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/f5781a78-9892-5dd3-a8c5-a047d5cb3318/attachment.md","path":"governance/templates/TROUBLESHOOTING-TEMPLATE.md","size":980,"sha256":"4cac8a818115a1184b12599c35cbc4babf40554d7d72426ba78f38e7afda3e02","contentType":"text/markdown; charset=utf-8"},{"id":"e3d2efaa-7cc6-5b00-ae30-c8076cd226c5","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/e3d2efaa-7cc6-5b00-ae30-c8076cd226c5/attachment.yml","path":"governance/templates/docker-compose.test.yml","size":1490,"sha256":"e1eecb3072980056eac9e7ae251b4fef8e3e5227944f2701554826de5938a773","contentType":"application/yaml; charset=utf-8"},{"id":"7052f6b9-620d-545a-bf64-29f921b78aff","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/7052f6b9-620d-545a-bf64-29f921b78aff/attachment.md","path":"governance/templates/plans-README.md","size":7564,"sha256":"cfaf9718b19c8c0431bf254003a878232c68ddb17d1fb154149daa5b26ef8b20","contentType":"text/markdown; charset=utf-8"},{"id":"379f8ee6-ea72-5fa2-8ec6-19c10eaf4b21","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/379f8ee6-ea72-5fa2-8ec6-19c10eaf4b21/attachment.yaml","path":"governance/templates/pre-commit-config.framework-library.yaml","size":929,"sha256":"38f556a6c8fa5d2b4d783119e9c822bc21344ffa6e96964d4276bababae0a314","contentType":"application/yaml; charset=utf-8"},{"id":"49c70689-e262-5acd-8a04-2ebc2c9b5ca9","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/49c70689-e262-5acd-8a04-2ebc2c9b5ca9/attachment.md","path":"governance/templates/qa/01-testing-strategy.md","size":479,"sha256":"8da20cd151a635bef72014b69ae7f7ad025b0f6f459329bc244971a0441ea05f","contentType":"text/markdown; charset=utf-8"},{"id":"be21abdd-3c65-5dae-807e-035af25e35eb","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/be21abdd-3c65-5dae-807e-035af25e35eb/attachment.md","path":"governance/templates/qa/02-test-standards.md","size":7005,"sha256":"c549e5bc77f5bfe3170343a5041203cd4a14e41a9fd478a27add5f48550f7b27","contentType":"text/markdown; charset=utf-8"},{"id":"d7a3fb50-1e38-5240-9544-7489f613278a","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/d7a3fb50-1e38-5240-9544-7489f613278a/attachment.md","path":"governance/templates/qa/03-ci-pipeline-spec.md","size":7556,"sha256":"e8e98d0befaa1a81a9603ed728a2cdfa646b919633efbb21e099d9790455cae3","contentType":"text/markdown; charset=utf-8"},{"id":"0a068e6e-80ec-5ea9-963e-dc567e6defb6","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/0a068e6e-80ec-5ea9-963e-dc567e6defb6/attachment.md","path":"governance/templates/qa/04-deployment-strategy.md","size":6799,"sha256":"ea8b0ebaac77716d75310264411f9eef76d7c9c05ff61f5fc7bcf180ccd86dca","contentType":"text/markdown; charset=utf-8"},{"id":"917826b5-1156-5888-8236-8bfae94c1dd9","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/917826b5-1156-5888-8236-8bfae94c1dd9/attachment.md","path":"governance/templates/qa/05-environment-spec.md","size":7852,"sha256":"1546bd37099b211d1116bf0d681c67768cfeca7905664b8e8aef8ff3e66389b8","contentType":"text/markdown; charset=utf-8"},{"id":"455a5946-22aa-53c7-979a-a771e593c1f6","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/455a5946-22aa-53c7-979a-a771e593c1f6/attachment.md","path":"governance/templates/qa/06-security-testing.md","size":6792,"sha256":"b5fbe95d31630cb18d59e4cf15452246767ed2c317a651f0af8cc7260d7e9ce9","contentType":"text/markdown; charset=utf-8"},{"id":"5316ea32-2ade-5182-8c8a-6f8a88e8c584","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/5316ea32-2ade-5182-8c8a-6f8a88e8c584/attachment.md","path":"governance/templates/qa/07-e2e-testing-guide.md","size":7709,"sha256":"a28da637379eea2c676c9f36296ffe08ed8167d77d35428f6bb428b5d5ddd478","contentType":"text/markdown; charset=utf-8"},{"id":"abcd34d7-0370-5328-9b7a-2ce11443bc3c","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/abcd34d7-0370-5328-9b7a-2ce11443bc3c/attachment.md","path":"governance/templates/qa/GCP_SECRETS_SETUP.md","size":13614,"sha256":"9f39ad5818fe519a5a7504b5de2a8fd9f4eae2cf36ba5b5d62d38f9ad6c08abb","contentType":"text/markdown; charset=utf-8"},{"id":"eca1829d-8246-51e2-b59a-e48f794e985b","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/eca1829d-8246-51e2-b59a-e48f794e985b/attachment.md","path":"governance/templates/qa/README.md","size":1945,"sha256":"43eff2d048d56861d9560aef32d19cba56166c87992c7f894dfc5ef1fbc7a231","contentType":"text/markdown; charset=utf-8"},{"id":"6d2969ab-7f21-5909-bc98-f27331913a05","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/6d2969ab-7f21-5909-bc98-f27331913a05/attachment.yaml","path":"governance/templates/sdd_config.yaml","size":724,"sha256":"db2f6b74e48b0569ad179a87891da957e7b0d1760a84a99c5a5534bf9f25d932","contentType":"application/yaml; charset=utf-8"},{"id":"7ec8f3f9-624d-5a62-b62c-67e5a6798df5","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/7ec8f3f9-624d-5a62-b62c-67e5a6798df5/attachment.md","path":"references/adr-generation-from-bdd.md","size":8447,"sha256":"ff3968c8b1dcb146c4bd9076f68f4b81fc804e5db6a537f260a66c1f29cbf353","contentType":"text/markdown; charset=utf-8"},{"id":"8519dafa-e68d-52c1-8b80-84e9dce2f6e4","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/8519dafa-e68d-52c1-8b80-84e9dce2f6e4/attachment.md","path":"references/adr-generation-subagent-pattern.md","size":3323,"sha256":"c9d3ed970d7df22f9caad8b840339d541b526cd825c2fb8ad0323d10f9dfcdd5","contentType":"text/markdown; charset=utf-8"},{"id":"5a1b5291-d5a8-597b-8812-2723b08dea58","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/5a1b5291-d5a8-597b-8812-2723b08dea58/attachment.md","path":"references/adr-layer-planning-and-gap-review.md","size":3407,"sha256":"bb033e8b7e737892f9c9888a33d88991ae8e27b30475af956968d2b0047177a8","contentType":"text/markdown; charset=utf-8"},{"id":"6b9b35b1-d22f-5e01-aa89-8a074f5f6f00","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/6b9b35b1-d22f-5e01-aa89-8a074f5f6f00/attachment.md","path":"references/adr-review-inline-pattern.md","size":8125,"sha256":"7de9c0383401382d384930e982763a56467f97e2060059bf143466cbb7ec4d4d","contentType":"text/markdown; charset=utf-8"},{"id":"40c34350-3eca-5b35-971a-b079cfdedc97","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/40c34350-3eca-5b35-971a-b079cfdedc97/attachment.md","path":"references/ai-assistant-rules.md","size":2951,"sha256":"d466185129feef9df6601900fd3f27eec355604ff38c7519db2f3eaca188eef2","contentType":"text/markdown; charset=utf-8"},{"id":"686fe9f3-8f0c-584b-b9cb-eef0cf69264b","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/686fe9f3-8f0c-584b-b9cb-eef0cf69264b/attachment.md","path":"references/batch-bdd-generation-from-ears.md","size":9464,"sha256":"2b479e404bdf113710660254eace077f8c9f9a6ee1c2cb7a410cab8491c3be0d","contentType":"text/markdown; charset=utf-8"},{"id":"d96e8490-84ba-521d-9869-3d660537c6a3","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/d96e8490-84ba-521d-9869-3d660537c6a3/attachment.md","path":"references/batch-brd-processing/batch-remediation-script.md","size":7190,"sha256":"77fa0396cf39eb55a612064e7db1a006089eb4d9c95c1e59b62c592799207b7f","contentType":"text/markdown; charset=utf-8"},{"id":"d53156b0-e1fc-5cf6-9fe6-2de78da34c98","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/d53156b0-e1fc-5cf6-9fe6-2de78da34c98/attachment.md","path":"references/batch-brd-processing/source-coverage-audit.md","size":3448,"sha256":"cf7cbb264dc6619a404564705633ec953fac91cf85b653e004da35b9860ffa6f","contentType":"text/markdown; charset=utf-8"},{"id":"3761b2c6-4944-5b8f-8530-bbc235793f24","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/3761b2c6-4944-5b8f-8530-bbc235793f24/attachment.md","path":"references/batch-brd-processing/validator-filename-bug-diagnostic.md","size":3225,"sha256":"abe8dc8d8631af2d8ff99829f38259c4d73449c4e10dca4045f314f60374b7b7","contentType":"text/markdown; charset=utf-8"},{"id":"e481f180-0667-51bf-be4c-c6366e564d18","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/e481f180-0667-51bf-be4c-c6366e564d18/attachment.md","path":"references/batch-brd-review-remediation.md","size":7587,"sha256":"3228ccc07475fa66b9a5314298e90bf45bca7944946797741e52f54be5521630","contentType":"text/markdown; charset=utf-8"},{"id":"e2fff4a8-0963-5c88-b8a6-0f39843b944d","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/e2fff4a8-0963-5c88-b8a6-0f39843b944d/attachment.md","path":"references/batch-pipeline-execution.md","size":3168,"sha256":"562ffab474f91e23677f183827ba0af69e3717504e49461d4682f412c5089cb3","contentType":"text/markdown; charset=utf-8"},{"id":"20712b31-b926-51ba-b8bf-3e5946c088db","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/20712b31-b926-51ba-b8bf-3e5946c088db/attachment.md","path":"references/batch-prd-generation-from-brds.md","size":8198,"sha256":"0a2d019998f9808bf68537fdb9eaf91df0dd14bb391512276b7bdb1a8e6c8cc0","contentType":"text/markdown; charset=utf-8"},{"id":"7d746722-a1ac-598c-8350-bf76f94f03d3","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/7d746722-a1ac-598c-8350-bf76f94f03d3/attachment.md","path":"references/bdd-batch-review-remediation.md","size":15341,"sha256":"cb5f4dc097ea5665b5b183c4606f96b2c3c86cfba4f46fa6e486f55772668252","contentType":"text/markdown; charset=utf-8"},{"id":"42800d80-9fd5-58c6-b45d-4ae836cc18d9","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/42800d80-9fd5-58c6-b45d-4ae836cc18d9/attachment.md","path":"references/benchmark-adr-generation.md","size":8623,"sha256":"f46eefd70938605570836931101cb449f825aa2988f53ac0c7e72896c234ba33","contentType":"text/markdown; charset=utf-8"},{"id":"1b4d4348-304f-5aae-a1ba-ad205de7e6a2","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/1b4d4348-304f-5aae-a1ba-ad205de7e6a2/attachment.md","path":"references/brd-review-inline-pattern.md","size":7410,"sha256":"7b1b1b1800660ce7407f015c1ec08aba5ba053508e85f0ac2de273d8ffc5a817","contentType":"text/markdown; charset=utf-8"},{"id":"cff7857c-702f-572e-8208-4215ab3c7229","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/cff7857c-702f-572e-8208-4215ab3c7229/attachment.md","path":"references/brd-validation-automation.md","size":9163,"sha256":"ce7948369e6265ead23870406ec6ea97b39d79e7bc607311c58f68b3c4323516","contentType":"text/markdown; charset=utf-8"},{"id":"7699ff9b-2b38-5052-9b15-e0d61cd44cfd","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/7699ff9b-2b38-5052-9b15-e0d61cd44cfd/attachment.md","path":"references/broker-mcp-architecture-pattern.md","size":5225,"sha256":"b6d94d02cce795cbd9c059f079cd72c8a4bee9a4700b0479a14609608f1b64a1","contentType":"text/markdown; charset=utf-8"},{"id":"880deab7-4233-583f-9756-aeb981ef484f","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/880deab7-4233-583f-9756-aeb981ef484f/attachment.md","path":"references/cross-document-index-sweep.md","size":2548,"sha256":"f066462a8755895c4b9d61f0f5de823e2d41f43c9139a116794b2c47d23dd7f5","contentType":"text/markdown; charset=utf-8"},{"id":"463fa71f-cbcb-5dad-b342-c30b1f68be3c","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/463fa71f-cbcb-5dad-b342-c30b1f68be3c/attachment.json","path":"references/data-consistency-report.json","size":13876,"sha256":"1cbe809c3e12a2f3998f0819c61635820bd73bed7ee9d0d9955412edf96e53f7","contentType":"application/json; charset=utf-8"},{"id":"922d24a1-2c97-56d8-b68c-abcaab2e52da","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/922d24a1-2c97-56d8-b68c-abcaab2e52da/attachment.md","path":"references/diagram-standards.md","size":9537,"sha256":"d7519da278961f8b71f78e327a72ec9e423b7e7cdc38f32e4cd09bd9fa361fa4","contentType":"text/markdown; charset=utf-8"},{"id":"7acd3597-36cd-53d2-9d4c-f774cfdcb717","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/7acd3597-36cd-53d2-9d4c-f774cfdcb717/attachment.md","path":"references/doc-governance-core.md","size":4065,"sha256":"98b52bc81b24bffe1042f033b4769ef3762ef2d2ee8600ec0126ef079a249ac3","contentType":"text/markdown; charset=utf-8"},{"id":"097fe5b2-fd93-5350-99f0-26a9a580ea84","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/097fe5b2-fd93-5350-99f0-26a9a580ea84/attachment.md","path":"references/ears-generation-pattern.md","size":6195,"sha256":"4498abede41e35bfe4d33a0b69c88c8f837aaceb0aaff8639fe0ad2e6f3deacf","contentType":"text/markdown; charset=utf-8"},{"id":"d8e4f12b-9f99-514d-86f0-d0259957ae4b","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/d8e4f12b-9f99-514d-86f0-d0259957ae4b/attachment.md","path":"references/framework-location-and-quirks.md","size":4846,"sha256":"d66949f26dd5f724b96930e90358b2d37cdb6bf3fe5dd8f85f49c5b4da398d9a","contentType":"text/markdown; charset=utf-8"},{"id":"3aa0c6f4-8664-5e65-a826-4d4ae98d6dab","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/3aa0c6f4-8664-5e65-a826-4d4ae98d6dab/attachment.md","path":"references/governance-load-protocol.md","size":4005,"sha256":"fa8d9f221e184b6810fa0c5a69038837bd819f5067ac3831b4f9b4b3ffe7f470","contentType":"text/markdown; charset=utf-8"},{"id":"f8c53359-b18c-5f16-8b5d-c7bad916bb1f","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/f8c53359-b18c-5f16-8b5d-c7bad916bb1f/attachment.md","path":"references/hermes-agent-sdd-runtime-pattern.md","size":4488,"sha256":"9717ea009f1c26858b5975fea8e22a7943d543b8d4764b326c25291373db5648","contentType":"text/markdown; charset=utf-8"},{"id":"ee3ebe75-e1f2-5ad4-9b4b-c9a5e6aa2501","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/ee3ebe75-e1f2-5ad4-9b4b-c9a5e6aa2501/attachment.md","path":"references/id-naming-standards.md","size":2079,"sha256":"24da0958d48b1bce29629f4bed4006ab689f9b633bc1b78242c81a5e8970057a","contentType":"text/markdown; charset=utf-8"},{"id":"c8e7f6a3-e16a-5a29-87cb-cb5e11176187","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/c8e7f6a3-e16a-5a29-87cb-cb5e11176187/attachment.yaml","path":"references/layer-registry.yaml","size":8649,"sha256":"f2de0e366e737eb32a30fd9a0de72c1f2c9b720f97ec96715724a0b497e9f45f","contentType":"application/yaml; charset=utf-8"},{"id":"4a891b49-2a7c-5570-8473-fd57e8aff083","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/4a891b49-2a7c-5570-8473-fd57e8aff083/attachment.md","path":"references/plan-gap-review-checklist.md","size":4953,"sha256":"d4e2549c4f4b631d598c77c25ecef73e8646614c822125f0027212a987871612","contentType":"text/markdown; charset=utf-8"},{"id":"b76d02c2-976a-541c-a2ec-afa4e37cea1a","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/b76d02c2-976a-541c-a2ec-afa4e37cea1a/attachment.md","path":"references/programmatic-sdd-generation.md","size":5440,"sha256":"1391183fefbf7362bda52aa14c2c18186c485799830d79439eea1840fe735aa8","contentType":"text/markdown; charset=utf-8"},{"id":"57766a88-162f-5ba0-b819-c69256def6cb","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/57766a88-162f-5ba0-b819-c69256def6cb/attachment.md","path":"references/python-env-setup.md","size":1981,"sha256":"5c39f6aeff5500a082334e840f1bd2f46d5865e29b2f2774a0c1cf4fe8f6e45d","contentType":"text/markdown; charset=utf-8"},{"id":"c035d2c2-9f2a-5237-a5d5-a705ede59526","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/c035d2c2-9f2a-5237-a5d5-a705ede59526/attachment.md","path":"references/quick-reference.md","size":2170,"sha256":"a424d2c6fbaf70c98f137f221ce50b79340d616a7801912636049d054a593498","contentType":"text/markdown; charset=utf-8"},{"id":"5fc05b1d-aa59-5c7e-9d40-3d5ca23dd01b","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/5fc05b1d-aa59-5c7e-9d40-3d5ca23dd01b/attachment.md","path":"references/rulebook-brd-extraction.md","size":4928,"sha256":"fc1eb9d2aebedd40796c06fddc953b4fc2979e40e171741770cb117da9b4d2b8","contentType":"text/markdown; charset=utf-8"},{"id":"402b9557-41ba-5f4e-a09f-721dfaacc708","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/402b9557-41ba-5f4e-a09f-721dfaacc708/attachment.md","path":"references/sdd-guide.md","size":4622,"sha256":"ed07915ce5930cf6b0905237ed6d003bac0c2be8eb3bb75e5fb9528aa79e7f32","contentType":"text/markdown; charset=utf-8"},{"id":"f92ef43b-6fb7-577c-8815-c44db530bea5","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/f92ef43b-6fb7-577c-8815-c44db530bea5/attachment.md","path":"references/sdd-workflow-quickstart.md","size":4140,"sha256":"cc21c5ca88d3a6222506e489a053ce8c2ee5a9cf5482ae8e33969bfb065e0f99","contentType":"text/markdown; charset=utf-8"},{"id":"be947260-e2e3-537f-976b-1747c3db65d9","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/be947260-e2e3-537f-976b-1747c3db65d9/attachment.md","path":"references/subagent-bdd-remediation-session-2026-05-08.md","size":8369,"sha256":"302a849097521297d3e5739603cd7f8f073c18094cf27aad19b5b1bb76269c86","contentType":"text/markdown; charset=utf-8"},{"id":"86db7226-4597-598f-a962-e9c5871f3a58","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/86db7226-4597-598f-a962-e9c5871f3a58/attachment.md","path":"references/testing-strategy-tdd.md","size":3264,"sha256":"bcadcd4c6b9cf6ecd9cf3843a0c2281b7670682d4f369f36a67bf89a5d99b713","contentType":"text/markdown; charset=utf-8"},{"id":"57c01e6f-4e0a-537a-a316-970b2a201964","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/57c01e6f-4e0a-537a-a316-970b2a201964/attachment.md","path":"references/threshold-naming-rules.md","size":31100,"sha256":"a55dea70cb5508a447a4fd5d18cd5fcf4184d7b77e284e073df50a2890483cc7","contentType":"text/markdown; charset=utf-8"},{"id":"a9a4886f-54c2-58fc-9b75-bf78f6118b3c","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/a9a4886f-54c2-58fc-9b75-bf78f6118b3c/attachment.md","path":"references/traceability.md","size":2119,"sha256":"60f0379389e44ad469f09adf0b191690d3206e7b4d0f49449b51796b06c06b53","contentType":"text/markdown; charset=utf-8"},{"id":"4654a686-b255-5422-9b69-e4e602291e64","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/4654a686-b255-5422-9b69-e4e602291e64/attachment.md","path":"references/ucx-readme.md","size":7837,"sha256":"c5f56c02eaa0903730b1915025b27838fe5ca5c23bfe55f764ce0cbdb81aee5a","contentType":"text/markdown; charset=utf-8"},{"id":"7fede4ec-3d31-5e1c-88c3-cc84860b01f7","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/7fede4ec-3d31-5e1c-88c3-cc84860b01f7/attachment.md","path":"references/ucx-remediate-content-limitations.md","size":5168,"sha256":"92130b5fba1f74e0d0ab1943ba061731cb1c9e57ed81ab57761039af5904d2d0","contentType":"text/markdown; charset=utf-8"},{"id":"26dd4de0-2c5b-58a3-8caf-d951c5ef6f4c","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/26dd4de0-2c5b-58a3-8caf-d951c5ef6f4c/attachment.md","path":"references/ucx-tool-behavior-quirks.md","size":2940,"sha256":"7393e0bd5b3b61c9ba94a0b960138080331b79fce8c033bb6eb895467019c4b2","contentType":"text/markdown; charset=utf-8"},{"id":"1fa8932f-82bf-515d-8de2-be9c09104874","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/1fa8932f-82bf-515d-8de2-be9c09104874/attachment.md","path":"references/ucx-validator-template-collision.md","size":3574,"sha256":"23a9184edf5e4c8002b251423c8c60c267d9d74c86b14c677f9028fdfbfc7260","contentType":"text/markdown; charset=utf-8"},{"id":"2a83f2b3-7ec2-5b59-bd44-7226143a5e7f","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/2a83f2b3-7ec2-5b59-bd44-7226143a5e7f/attachment.md","path":"references/yaml-patch-indentation-fix.md","size":3316,"sha256":"79c1d8bd30a013dfec65f55d0e86f463f7ee1a475b59d8c4f26eafa847ec99a5","contentType":"text/markdown; charset=utf-8"},{"id":"7792c389-1785-5da2-8801-4c019d14d795","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/7792c389-1785-5da2-8801-4c019d14d795/attachment.md","path":"references/yaml-quoting-rules.md","size":4069,"sha256":"355d8a1de801cd0a05d4c6422087691bfa7856276c29c670165fa6f7a1fc66b7","contentType":"text/markdown; charset=utf-8"},{"id":"747be60f-d9de-508f-8c01-dcf1d22c9532","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/747be60f-d9de-508f-8c01-dcf1d22c9532/attachment.md","path":"root-docs/HERMES_UCX_RUNTIME_ENVIRONMENT.md","size":6888,"sha256":"6017bad315cb16469e19f8c6786a818b9a646ff83a4a9ef36538d42f9e93d1fd","contentType":"text/markdown; charset=utf-8"},{"id":"bae841e7-e4cf-512b-b6cc-ae2a2eea412b","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/bae841e7-e4cf-512b-b6cc-ae2a2eea412b/attachment.md","path":"root-docs/MULTI_PROJECT_QUICK_REFERENCE.md","size":17331,"sha256":"ebd822953cac675e94e4768b8e7b4cf886436aa05e26d5d0d907771713f82dc1","contentType":"text/markdown; charset=utf-8"},{"id":"beaf742b-ef7e-5d90-ad88-384ff5be67e9","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/beaf742b-ef7e-5d90-ad88-384ff5be67e9/attachment.md","path":"root-docs/MULTI_PROJECT_SETUP_GUIDE.md","size":41411,"sha256":"56be55702193f943440d7a9c7d10c2d2ac014fe911427966285f72fb76c215d4","contentType":"text/markdown; charset=utf-8"},{"id":"da9e3f91-db76-5fa1-a308-d376e21bf72c","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/da9e3f91-db76-5fa1-a308-d376e21bf72c/attachment.md","path":"root-docs/README.md","size":14751,"sha256":"482e0f880c823152496358ff1be817b7aef81f26a615e61ed38db71cd0c94c12","contentType":"text/markdown; charset=utf-8"},{"id":"c88c88f4-b9d1-5c9a-8521-57e76a7637cf","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/c88c88f4-b9d1-5c9a-8521-57e76a7637cf/attachment.sh","path":"scripts/ucx-validation-gate.sh","size":1846,"sha256":"9d913738feffe25cf0faf2fcf76c7c967dd9c748f4bc9fc09bd180db085879a7","contentType":"application/x-sh; charset=utf-8"}],"bundle_sha256":"37cc9a149e86910353ff242f311d0991915e4264bb26a4d45619b33a9a965331","attachment_count":171,"text_attachments":171,"attachment_storage":"skillopedia-attachments-v1","binary_attachments":0,"excluded_attachments":[]},"cluster_size":1,"skill_md_path":"platforms/hermes/agent-skills/spec-driven-development/sdd-orchestrator/SKILL.md","import_metadata":{"date":"2026-06-05","author":"@skillopedia","version":"v1","category":"productivity-workflow","category_label":"Productivity"},"exact_dupes_collapsed_into_this":0},"version":"v1","category":"productivity-workflow","metadata":{"hermes":{"tags":["sdd","orchestration","workflow","review","creation","remediation"],"related_skills":["sdd-review-personas","sdd-naming-standards","sdd-cross-validation","hermes-agent"]}},"import_tag":"clean-skills-v1","description":"Orchestrate SDD v3.2 workflows across 8 layers (BRD→PRD→EARS→BDD→ADR→SPEC→TDD→IPLAN) using 15 specialized review personas dispatched as parallel subagents."}},"renderedAt":1782980997742}

SDD Orchestrator — Specification-Driven Development Workflow Engine Overview You orchestrate the SDD v3.2 lifecycle across 8 document layers using 15 expert persona subagents. Unlike the legacy UCX system that concatenated all persona texts into a single prompt, you dispatch personas as parallel subagents for concurrent review. Mandatory Governance Load (Before Any SDD Work) Before creating, reviewing, or remediating ANY SDD document, load the governance protocol: This single file condenses the planning-first rules from GOVERANCE RULES.md §2b/§3, DEFINITION OF DONE.md plan/IPLAN review level,…