diff --git a/docs/STANDARDS.md b/docs/STANDARDS.md new file mode 100644 index 0000000..980f0e4 --- /dev/null +++ b/docs/STANDARDS.md @@ -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.