Known failure modes, doc drift risks, and mitigation for the harness and docs site.
Active risks
Section titled “Active risks”| Risk | Impact | Mitigation |
|---|---|---|
| Broken doc assets | Illustrations 404; reader trust erodes | gpt-image-2 generation with light-blueprint contract; e2e asserts naturalWidth > 0 |
| ADR index drift | Docs cite stale decision state | decisions.md synced from INDEX; PENDING_CREATION ADRs flagged |
| Content duplication | Three-layer thesis in 4 files diverges | Canonical pages: architecture vs Workflow vs Runtime |
| Stub pages in nav | cognitive-layer redirect confuses readers | Removed from sidebar; redirect URL preserved |
| Context explosion | Long sessions collapse | Context Economics; hydration scope mandate |
| Playbook contamination | Learn output injected into agents/rules | ADR-010 contamination-check gate |
| mmdc CI sandbox | Diagram render fails on hardened Linux | puppeteer-config.json with --no-sandbox in evidence pipeline |
Doc site debt (docs-artistry-20260530)
Section titled “Doc site debt (docs-artistry-20260530)”| Item | Priority | Status |
|---|---|---|
| Remotion tours (materialization, lifecycle) | P2 | Deferred |
| Deployment view depth (arc42 ch7) | P2 | Open |
Component-level C4 for .sdlc/bin/* | P2 | Open |
Evidence and reviewer plan: .sdlc/evidence/architecture-artistry-20260530/