From 4a88f74627415097b8152ddfda16210b99f44ebd Mon Sep 17 00:00:00 2001
From: Simon Axelsson <simon@siax.io>
Date: Wed, 16 Sep 2026 15:34:03 +0200
Subject: [PATCH] docs: define c0py autonomous execution workflows

---
 docs/AUTOMATIONS.md | 98 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 98 insertions(+)
 create mode 100644 docs/AUTOMATIONS.md

diff --git a/docs/AUTOMATIONS.md b/docs/AUTOMATIONS.md
new file mode 100644
index 0000000..0539a78
--- /dev/null
+++ b/docs/AUTOMATIONS.md
@@ -0,0 +1,98 @@
+# C0PY Automations
+
+## Automation principles
+
+C0PY automations are resumable, idempotent, versioned and evidence-producing. Every run emits a manifest, provenance and machine-readable failures.
+
+## Canonical pipeline
+
+```text
+DISCOVER
+  -> CAPTURE
+  -> NORMALIZE TO IR
+  -> MODEL PRODUCT
+  -> FREEZE SPEC
+  -> RECONSTRUCT
+  -> DEPLOY PREVIEW
+  -> VERIFY
+  -> REPAIR (if failed)
+  -> VERIFY
+  -> RELEASE CANDIDATE
+```
+
+## Jobs
+
+### discover-target
+Inputs: target URL, capture profile, scope policy.
+Outputs: route graph, navigation graph, discovered workflows, crawl queue.
+
+### capture-target
+Uses Playwright/CDP and optional adapters. Captures DOM/runtime HTML, styles, accessibility, media/assets, screenshots, network/HAR, storage metadata, events and performance.
+
+### interaction-sweep
+Enumerates deterministic interactive states and records before/after deltas. Semantic agents may propose candidate flows; deterministic capture verifies them.
+
+### workflow-discovery
+Uses semantic browser adapters to discover product tasks and translates them into explicit action/state graphs with evidence links.
+
+### normalize-evidence
+Validates captured artifacts and writes the Canonical IR/Evidence Graph. Rejects untyped or provenance-free critical evidence.
+
+### generate-spec
+Creates frozen reconstruction contracts for routes, components, design tokens, responsive states, workflows and network/domain behavior.
+
+### reconstruct
+Dispatches versioned specs to selected builders (`v0`, `lovable`, `codex`, `generic`). Generated code is never treated as evidence about the source.
+
+### preview
+Builds and deploys a preview target. Vercel is a supported deployment adapter; SIAX/Coolify remains supported for controlled infrastructure.
+
+### verify
+Runs the fidelity vector: visual geometry/style, responsive, routes, interactions, workflows, network, motion, accessibility, runtime and build checks.
+
+### repair
+Turns verification failures into typed repair tasks, applies the smallest justified patch and sends the result back through verification. Repair may not relax gates without an explicit versioned policy change.
+
+### upstream-reconcile
+Scheduled/manual automation that checks registered upstream projects for high-value changes. It creates candidate capability records only; it never auto-merges foreign code without provenance/license/test gates.
+
+### schema-compatibility
+On every IR/schema change, validates backward compatibility and requires a version bump for incompatible changes.
+
+### license-provenance
+Checks all `CHERRY_PICK` and vendored/adapted source entries for repository, SHA, source path, classification and license/notice requirements.
+
+## Required run manifest
+
+Each automation run records at minimum:
+
+- run id
+- target id
+- C0PY commit/version
+- schema version
+- capture profile
+- started/completed timestamps
+- tool/adapter versions
+- evidence object ids
+- warnings and typed failures
+- retry lineage
+- output spec version
+- verification result
+
+## Failure policy
+
+No automation may convert a failed measurement into an inferred success. Failed or inaccessible states remain explicit evidence gaps.
+
+## CI/CD gates
+
+Pull requests touching capture, IR, product model, reconstruction contracts or fidelity rules must run:
+
+1. typecheck
+2. unit tests
+3. schema validation
+4. provenance validation
+5. license boundary validation
+6. representative deterministic fixture capture
+7. reconstruction fixture verification when affected
+
+Production promotion is blocked when critical route/workflow/state gates fail.