docs: define c0py engineering and evidence standards

2026-09-16 15:33:43 +02:00
parent 8e44be0b69
commit 982c7b19fc
1 changed files with 127 additions and 0 deletions
@@ -0,0 +1,127 @@
+# C0PY Standards
+
+## 1. Single-source-of-truth standard
+
+C0PY owns the canonical schemas for capture evidence, product topology, reconstruction specifications and fidelity verification. Other repositories may integrate with these contracts but may not create competing definitions.
+
+## 2. Evidence standard
+
+Every material claim about a source product must be represented with:
+
+- stable evidence id
+- evidence kind
+- source URL/route
+- capture profile
+- viewport/device context when relevant
+- timestamp
+- acquisition method
+- confidence class
+- provenance/source implementation
+- payload or durable object reference
+
+Confidence classes: `measured`, `observed`, `inferred`, `declared`, `unknown`.
+
+In `clone` mode synthetic/invented facts are forbidden. In `adapt` and `blend`, synthetic values must be explicitly labeled.
+
+## 3. Capture standard
+
+Deterministic capture has precedence over AI interpretation.
+
+Preferred order:
+
+1. browser/browser-protocol measurement
+2. runtime event/network observation
+3. structured source metadata
+4. semantic agent observation
+5. inference
+
+Playwright is the standard browser automation layer. Raw CDP is used for capabilities that require deeper browser instrumentation.
+
+## 4. Route and workflow standard
+
+Routes and workflows are graph data, not prose. Each discovered route/action/state transition is uniquely identifiable and links to its supporting evidence.
+
+A workflow is complete only when its required preconditions, actions, transitions, resulting states, error paths and relevant network contracts are represented.
+
+## 5. Reconstruction standard
+
+Builders consume frozen, versioned C0PY specifications. v0, Lovable, Codex and future builders are adapters, not authorities.
+
+Generated implementations must preserve:
+
+- component contracts
+- responsive contracts
+- interaction/state contracts
+- route contracts
+- network/domain contracts where reconstruction scope includes them
+- accessibility semantics
+- fidelity thresholds
+
+## 6. Upstream standard
+
+Every external capability is classified as `CORE`, `DEPENDENCY`, `CHERRY_PICK`, `ADAPTER`, `REIMPLEMENT`, `REFERENCE_ONLY` or `DROP`.
+
+Any source-derived code must preserve required copyright/license notices and record exact provenance.
+
+AGPL/copyleft systems such as SingleFile/Browsertrix remain isolated adapters/services unless C0PY deliberately changes licensing strategy.
+
+## 7. Verification standard
+
+Do not reduce fidelity to one number. Required dimensions include:
+
+- geometry
+- typography
+- color
+- assets
+- responsive behavior
+- route coverage
+- interactions and states
+- workflows
+- network contracts
+- motion
+- accessibility
+- runtime errors
+- build health
+
+Release gates are profile/version controlled. Critical route/workflow/state coverage defaults to 100%.
+
+## 8. Failure standard
+
+Failures are typed and machine-actionable. Minimum families:
+
+- `CaptureFailure`
+- `DiscoveryFailure`
+- `EvidenceGap`
+- `ReconstructionFailure`
+- `VerificationFailure`
+- `AuthorizationBoundary`
+- `UnsupportedSurface`
+- `DynamicContentVariance`
+- `NetworkReplayLimited`
+- `AuthSessionMissing`
+
+Every repair loop consumes typed failures rather than unstructured screenshots or generic prompts.
+
+## 9. Security and authorization standard
+
+Only capture resources and product states that the operator is authorized to access. Authentication state is supplied explicitly through capture profiles. Credentials and session material never enter source control.
+
+C0PY does not bypass access controls. Failed authorization is evidence and is represented as such.
+
+## 10. CI standard
+
+Changes to canonical schemas, evidence confidence semantics, capability taxonomy, release gates or adapter boundaries require:
+
+- schema/type checks
+- unit tests
+- provenance/license checks where applicable
+- documentation update
+- backward-compatibility note or explicit version bump
+
+## 11. Automation standard
+
+Automations must be idempotent, resumable and evidence-producing. A job may retry execution, but may not silently mutate evidence history or overwrite the lineage of an earlier capture.
+
+## 12. Cross-repo standard
+
+When another SIAX product wants website/product cloning, analysis or reconstruction, it must call/import C0PY instead of adding its own crawler/clone ontology. Shared automation and prompt systems reference this standard and the C0PY Masterplan.