Iron Curtain — Design Documentation

UX Surface Gate Clusters (Cross-Check for Milestone Completeness)

These clusters are used to prevent milestone definitions from becoming backend-only.

Policy / External Gate Nodes

External Source Study Mappings (Confirmatory Research -> Overlay)

Use this section to record accepted takeaways from source studies that refine implementation emphasis, docs, or execution sequencing without necessarily creating a new Dxxx.

Mapping Rules (How to Keep This Page Useful)

1. Cluster-level, not bullet-level sprawl: map roadmap deliverables and exit criteria into stable feature clusters unless a bullet is itself a dependency boundary.
2. Dxxx ownership lives in 18-PROJECT-TRACKER.md: this page references decisions at cluster level for dependency reasoning.
3. Gameplay familiarity ordering follows 11-OPENRA-FEATURES.md: P0 gates M2, P1/P2 gate M3, P3 is explicitly deferred and tracked.
4. Mark policy/legal prerequisites as policy_gate nodes, not hidden assumptions.
5. Keep the “minimal online slice” narrow: M4 must not absorb browser/ranked/spectator requirements.
6. Keep “creator foundation” distinct from “full visual editor”: M8 is a parallel lane, M9 is the visual authoring platform milestone.
7. New features must be inserted in sequence, not appended as unsorted TODOs: every accepted feature proposal gets a milestone position and dependency edges in the same planning pass.
8. Priority is mandatory for placement decisions: new clusters should be classified (P-Core, P-Differentiator, P-Creator, P-Scale, P-Optional) and placed so higher-priority critical-path work is not silently displaced.
9. If a feature spans multiple milestones, split the cluster or add explicit validation_depends_on / integration_gate edges instead of hiding sequencing inside notes.
10. If non-indexed decision references reappear, normalize the decision index in the same planning pass and update tracker coverage.
11. When a source study yields accepted implementation refinements, map them here (cluster references + action type) so they influence execution planning instead of living only in research/*.md.
12. Future/deferred wording in canonical docs must map here when it implies accepted work. If a statement is a planned deferral, add/update the affected cluster row (or create one) in the same planning pass and update tracking/future-language-audit.md; if it cannot be placed, it is proposal-only or a Pxxx, not scheduled work.
13. If accepted work changes external implementation-repo onboarding or code navigation expectations, update the bootstrap and template docs (tracking/external-code-project-bootstrap.md, tracking/external-project-agents-template.md, tracking/source-code-index-template.md) in the same planning pass.

New Feature Intake (Dependency Map Workflow)

Use this workflow whenever a new feature/mode/tooling surface is added to the design:

1. Decide whether it is a Dxxx decision, a feature cluster, or both.
2. Assign a primary milestone (M0–M11) based on what must exist before the feature becomes implementable.
3. Add hard/soft/validation/policy/integration edges to existing milestones/clusters.
4. Record the canonical docs + roadmap phase mapping in the cluster row.
5. Check for milestone displacement: if the feature would delay a higher-priority milestone, mark it P-Optional/experimental or move it later.
6. Update 18-PROJECT-TRACKER.md in the same change set (milestone snapshot/risk/coverage impact and Dxxx row if applicable).
7. If the feature docs introduce future/deferred wording, classify it and update tracking/future-language-audit.md (and use tracking/deferral-wording-patterns.md for replacement wording where needed).
8. If the feature changes expected codebase structure or implementer routing, update the external bootstrap/AGENTS/code-index templates so external repos inherit the same assumptions.

Deferred Feature Placement Examples (Canonical Patterns)

• Good (planned deferral): “Deferred to M10 (P-Creator) after M9.SDK.D038_SCENARIO_EDITOR_CORE; not part of M9 exit criteria.” Result: add/update an M10.* cluster row with hard/soft edges and note the out-of-scope boundary.
• Good (north star): “Long-term vision only; depends on M7.NET.CROSS_ENGINE_BRIDGE_AND_TRUST + M11.VISUAL.D048_AND_RENDER_MOD_INFRA; trust-labeled and not a ranked promise.” Result: no new cluster if already covered, but add/update tracker risk/trust-label notes.
• Bad (ambiguous): “Could add later if players want it.” Result: rewrite into planned deferral + overlay mapping, or mark proposal-only / Pxxx.
• Good (external implementation handoff): “This introduces a new first-class subsystem boundary; update CODE-INDEX.md template examples and external AGENTS.md guidance in M0 tooling docs.” Result: preserve LLM/human navigation quality across implementation repos as the architecture grows.