docs: establish canonical c0py reconstruction masterplan

docs/MASTERPLAN.md

@@ -0,0 +1,143 @@
+# C0PY Masterplan — Canonical Web Product Reconstruction Engine
+
+**Status:** canonical
+**Owner:** C0PY
+**Rule:** this document and the C0PY IR contracts are the single source of truth for web/product capture and reconstruction across SIAX.
+
+## Mission
+
+C0PY turns an observed web product into an evidence-backed digital twin specification that can be reconstructed, verified and repaired autonomously. The system must cover visual fidelity, responsive behavior, assets, interactions, workflows, network contracts, motion, accessibility and product topology.
+
+## Non-negotiable architecture
+
+```text
+Source product
+  -> discovery
+  -> deterministic capture
+  -> semantic exploration
+  -> Canonical Evidence Graph / IR
+  -> frozen reconstruction specs
+  -> builder adapters
+  -> preview deployment
+  -> multidimensional verification
+  -> repair loop
+  -> production candidate
+```
+
+No crawler, AI builder or upstream project owns the truth. The Canonical IR owns the truth.
+
+## Canonical layers
+
+1. **Discovery** — routes, sitemaps, links, navigation, semantic workflow discovery.
+2. **Capture** — Playwright + CDP as primary runtime; DOM, CSSOM, computed styles, accessibility tree, screenshots, storage, network, WebSocket/SSE, canvas/media and performance.
+3. **Evidence** — every assertion stores source, method, capture context, confidence and provenance.
+4. **Product model** — entities, relationships, capabilities, permissions, workflows and state machines inferred from observed behavior.
+5. **Specification** — deterministic page/component/workflow contracts generated from the evidence graph.
+6. **Reconstruction** — adapters for v0, Lovable, Codex and generic agents. Builders consume specs; they do not inspect the source as authority.
+7. **Verification** — geometry, typography, color, assets, routes, state, interaction, workflow, network, motion, accessibility and runtime health.
+8. **Repair** — failures become typed root-cause work items and are repaired iteratively.
+
+## Primary technology decisions
+
+- Browser runtime: Playwright.
+- Deep browser instrumentation: Chrome DevTools Protocol.
+- Crawl orchestration: Crawlee-compatible request graph.
+- Session/event replay: rrweb adapter.
+- Semantic exploration: Browser Use / Browser Harness adapters.
+- Visual comparison: pixelmatch-compatible deterministic diff plus computed-style root cause analysis.
+- Optional WebGL forensics: Spector.js adapter.
+- Optional archival: SingleFile and Browsertrix only behind process/service adapters due to copyleft boundaries.
+- Output target: clean SIAX architecture, normally Next.js + React + TypeScript, regardless of source framework.
+
+## Upstream capability policy
+
+Every borrowed idea or implementation MUST be classified as one of:
+
+- `CORE` — implemented and owned inside C0PY.
+- `DEPENDENCY` — consumed as a package/library.
+- `CHERRY_PICK` — imported/adapted source with exact provenance and license notice.
+- `ADAPTER` — isolated integration behind a C0PY contract.
+- `REIMPLEMENT` — behavior/specification reproduced without copying source.
+- `REFERENCE_ONLY` — studied, never included in runtime.
+- `DROP` — rejected duplicate or lower-value implementation.
+
+See `docs/UPSTREAM-CAPABILITY-MATRIX.md`.
+
+## Canonical package topology
+
+```text
+packages/
+  types/                 canonical shared contracts
+  c0py-core/
+    discovery/
+    capture/
+    evidence/
+    provenance/
+    product-model/
+    specification/
+    verification/
+    repair/
+    adapters/
+```
+
+As implementation grows, high-cohesion modules may graduate into their own workspace packages, but they must continue to consume the same IR contracts.
+
+## Evidence model
+
+Evidence confidence MUST use explicit semantics:
+
+- `measured`: deterministic machine measurement.
+- `observed`: directly observed behavior/state.
+- `inferred`: reasoned from evidence, not directly visible.
+- `declared`: supplied by an authorized configuration/specification.
+- `unknown`: insufficient evidence.
+
+`invented` is prohibited in clone mode. Adapt/blend mode may create new design/product choices, but they must be marked as synthetic and never confused with source evidence.
+
+## Operating modes
+
+- **clone** — maximize observable fidelity; no creative substitutions without an explicit evidence gap.
+- **adapt** — preserve approved product semantics while transforming brand/design/technology.
+- **blend** — combine explicitly selected capabilities/patterns from multiple references into a new product; every source lineage remains traceable.
+
+## Quality gates
+
+A single visual score is forbidden as the release criterion. C0PY uses a fidelity vector:
+
+- geometry
+- typography
+- colors
+- assets
+- responsive states
+- route coverage
+- interaction/state coverage
+- workflow coverage
+- network-contract parity
+- motion parity
+- accessibility semantics
+- console/runtime health
+- production build health
+
+Critical routes, contracted workflows and required interaction states must reach 100% coverage before a clone can be marked complete. Visual tolerances are profile-specific and recorded in the manifest.
+
+## Cross-repo rule
+
+Other SIAX repositories may consume C0PY capabilities, evidence and generated specs, but MUST NOT fork a parallel capture ontology, fidelity model or reconstruction masterplan. Cross-repo integrations point back to C0PY contracts/versioned schemas.
+
+## Delivery order
+
+1. Canonical IR + provenance.
+2. Playwright/CDP capture.
+3. route topology and deterministic extraction.
+4. HAR/network evidence and authenticated capture profiles.
+5. interaction/state delta engine.
+6. rrweb replay/event timeline.
+7. semantic workflow discovery adapters.
+8. design-system extraction.
+9. media/motion/WebGL adapters.
+10. specification generator.
+11. reconstruction adapters.
+12. multidimensional QA.
+13. autonomous repair loop.
+14. clone/adapt/blend orchestration.
+15. MCP/API contracts and fleet automations.