luckiest-co 1.0.13 → 1.0.15

package/skills/luckiest-website-cloner-shaders/vendor/web-shader-extractor/references/capture-backends.md

@@ -0,0 +1,201 @@
+# Capture Backends
+
+Use after `TARGET_LOCKED`, or as a selected tactical probe while moving from `attributed` to `locked`. Capture only facts bound to the target surface group.
+
+## Common Rules
+
+- Prefer public source/config or runtime objects when they are target-bound.
+- Use preload hooks or frame capture when source does not expose the render graph.
+- Use bundle slices only when they resolve a named unknown.
+- Keep backend facts separate from replay implementation choices.
+- Record every hook result as evidence. Hook hits prove only that an API was used; they do not prove the target uses that API until tied to the target surface group, owner, frame, or call path.
+
+## WebGL / WebGL2
+
+Capture:
+
+- surface CSS size, backing size, DPR, and context attributes
+- vertex/fragment source or trusted source representation
+- attributes, buffers, indices, instancing, or fullscreen primitive
+- textures, samplers, formats, dimensions, and asset paths
+- pass order, FBOs, attachments, inputs, and outputs
+- viewport, scissor, clear, blend, depth, stencil, cull, alpha
+- time origin/unit/delta, random, uniform updates, pointer, scroll, resize
+- color space, tone mapping, premultiplied alpha, and DOM composite
+
+Common failure cases:
+
+- WebGL1 vs WebGL2 shader syntax
+- framebuffer orientation and texture coordinate flips
+- premultiplied alpha mismatch
+- renderer output color space vs shader internal color space
+- time measured in seconds, frames, or platform-specific increments
+- hidden parent DOM transforms changing canvas coordinates
+
+### WebGL Preload Hook Map
+
+Use this map when source or runtime objects do not expose enough facts. Hook only the minimum API set needed for the current unknown.
+
+Surface and owner:
+
+- `HTMLCanvasElement.prototype.getContext`
+- `OffscreenCanvas.prototype.getContext`
+- `HTMLCanvasElement.prototype.transferControlToOffscreen`
+
+Program and shader:
+
+- `createShader`
+- `shaderSource`
+- `compileShader`
+- `getShaderInfoLog`
+- `createProgram`
+- `attachShader`
+- `linkProgram`
+- `getProgramInfoLog`
+- `useProgram`
+
+Uniforms:
+
+- `getUniformLocation`
+- `uniform1f` / `uniform2f` / `uniform3f` / `uniform4f`
+- `uniform1i` / `uniform2i` / `uniform3i` / `uniform4i`
+- `uniformMatrix*`
+
+Geometry:
+
+- `createBuffer`
+- `bindBuffer`
+- `bufferData`
+- `bufferSubData`
+- `vertexAttribPointer`
+- `enableVertexAttribArray`
+- `bindVertexArray`
+
+Textures:
+
+- `createTexture`
+- `bindTexture`
+- `texImage2D`
+- `texSubImage2D`
+- `texParameteri`
+- `activeTexture`
+- `pixelStorei`
+
+Framebuffers:
+
+- `createFramebuffer`
+- `bindFramebuffer`
+- `framebufferTexture2D`
+- `createRenderbuffer`
+- `bindRenderbuffer`
+- `framebufferRenderbuffer`
+
+State:
+
+- `viewport`
+- `scissor`
+- `clearColor`
+- `clear`
+- `enable` / `disable`
+- `blendFunc` / `blendFuncSeparate`
+- `blendEquation`
+- `depthFunc`
+- `cullFace`
+- `colorMask`
+- `depthMask`
+
+Draw:
+
+- `drawArrays`
+- `drawElements`
+- `drawArraysInstanced`
+- `drawElementsInstanced`
+
+## WebGPU
+
+WebGPU targets do not pass through `gl.shaderSource()`. Treat them as a separate backend.
+
+Capture:
+
+- canvas configuration and preferred format
+- shader modules or trusted node/source definitions
+- render and compute pipeline descriptors
+- bind group layouts and bind groups
+- buffers, textures, samplers, and update cadence
+- render pass and compute pass order
+- command submission sequence
+- time, pointer, scroll, resize, random
+- output color, alpha, and canvas/DOM composite
+
+Prefer platform/source definitions, readable WGSL, or WebGPU capture tools.
+If the site uses Three.js TSL or another node system that targets WebGPU, capture the node definition and renderer route before translating to GLSL or WGSL.
+
+Do not declare WebGPU replay ready because a WebGL shader capture succeeded elsewhere on the page. Evidence must bind to the WebGPU target surface.
+
+### WebGPU Preload Hook Map
+
+- `navigator.gpu.requestAdapter`
+- `GPUAdapter.requestDevice`
+- `GPUCanvasContext.configure`
+- `GPUDevice.createShaderModule`
+- `GPUDevice.createRenderPipeline`
+- `GPUDevice.createComputePipeline`
+- `GPUDevice.createBindGroupLayout`
+- `GPUDevice.createBindGroup`
+- `GPUDevice.createBuffer`
+- `GPUDevice.createTexture`
+- `GPUCommandEncoder.beginRenderPass`
+- `GPUCommandEncoder.beginComputePass`
+- `GPURenderPassEncoder.setPipeline`
+- `GPURenderPassEncoder.setBindGroup`
+- `GPURenderPassEncoder.draw`
+- `GPURenderPassEncoder.drawIndexed`
+- `GPUQueue.writeBuffer`
+- `GPUQueue.writeTexture`
+- `GPUQueue.submit`
+
+## Canvas2D
+
+Canvas2D targets need command, asset, font, and timing facts rather than shader facts.
+
+Capture:
+
+- command stream or readable source
+- transforms and clipping
+- paths, text, image draws
+- gradients, patterns, filters
+- `globalCompositeOperation`
+- assets and fonts
+- timing, random, pointer, scroll, resize
+- canvas size, DPR, and DOM composite
+
+Use Vanilla JS for simple Canvas2D baselines. Keep static offscreen buffers when the source uses them. Match font loading and text metrics before tuning positions.
+
+Common failure cases:
+
+- font fallback changes glyph metrics
+- DPR scaling applied twice or not at all
+- filter/composite order differs from source
+- image smoothing settings change texture quality
+- random state is re-created every frame in the replay
+
+### Canvas2D Command Capture Map
+
+- `drawImage`
+- `fillRect` / `strokeRect` / `clearRect`
+- `beginPath` / `moveTo` / `lineTo` / `bezierCurveTo` / `arc` / `fill` / `stroke` / `clip`
+- `fillText` / `strokeText`
+- `setTransform` / `transform` / `translate` / `rotate` / `scale`
+- `save` / `restore`
+- `globalAlpha`
+- `globalCompositeOperation`
+- `filter`
+- `createLinearGradient` / `createRadialGradient` / `createPattern`
+- `imageSmoothingEnabled`
+
+## OffscreenCanvas And Worker Probes
+
+- Hook `transferControlToOffscreen` before page scripts run when worker ownership is suspected.
+- Record worker script URLs and message channels, but do not persist private message payloads unless they are public effect definitions needed for replay.
+- Bind OffscreenCanvas evidence back to the visible placeholder canvas or DOM layer before promoting owner or backend facts.
+- If worker source cannot be read, capture call timing, canvas dimensions, and message shapes as `PARTIAL` evidence and keep the missing source as a blocking or important unknown.

package/skills/luckiest-website-cloner-shaders/vendor/web-shader-extractor/references/evidence-policy.md

@@ -0,0 +1,93 @@
+# Evidence Policy
+
+Choose evidence by authority and collection cost.
+
+## Truth Labels
+
+Every implementation-critical fact needs a nearby truth label. If a fact has no label, treat it as `GUESS`.
+
+| Label | Meaning | Valid evidence |
+|---|---|---|
+| `SOURCE` | Direct target-bound evidence from implementation or runtime. | Public source, source map, runtime object dump, captured shader/WGSL, GPU frame capture, network body with hash, or authoritative API output. |
+| `PARTIAL` | Target-bound handle whose value, wiring, or replay role is not proven. | Symbol name, bundle slice, framework object, shader without draw/resource state, owner hint, or resource URL without use evidence. |
+| `GUESS` | No direct evidence for the fact. | Visual fit, naming inference, copied defaults, hand-tuned constants, approximate behavior rebuild, or unverified assumption. |
+
+Do not describe `PARTIAL` or `GUESS` facts as extracted source. A behavior rebuild can be used, but it stays approximate until promoted by evidence.
+
+## Leaf Facts vs Wiring Facts
+
+False conclusions often come from proving a leaf fact and guessing the wiring fact. Audit them separately:
+
+- Leaf facts: shader source, WGSL, constants, config values, asset URLs, resource dimensions, sampler settings, context attributes.
+- Wiring facts: target ownership, draw/pass order, FBO dependencies, coordinate transforms, time unit, delta rule, random source, input coupling, resize behavior, color/alpha/DOM composite.
+
+`SOURCE` leaf facts do not promote unproven wiring.
+A source shader string does not prove active pass order.
+A config field named `velocity` does not prove units.
+A framework signature does not prove the target canvas uses that framework.
+
+## Promotion Rules
+
+Promote a fact only when evidence improves:
+
+- `GUESS -> PARTIAL`: a target-bound handle exists, but the value or wiring is still missing.
+- `PARTIAL -> SOURCE`: direct source/runtime/frame evidence proves the value and its use in the target path.
+- `SOURCE` for gate-critical wiring should have corroboration when practical. Examples: source plus runtime object, runtime plus frame capture, or source plus local replay smoke.
+
+When evidence conflicts with the model, do not tune parameters to mask the conflict.
+Route the mismatch back to attribution, source trace, or replay readiness.
+Record the unresolved unknown.
+
+## Unknown Classes
+
+- `blocking`: cannot build a baseline that matches required evidence without resolving it
+- `important`: baseline can run, but QA must focus on it
+- `deferred`: affects projectization or polish, not baseline
+- `external`: blocked by access, authorization, or legal permission
+
+## Choosing The Next Action
+
+Prefer the action that resolves the most blocking unknowns while keeping authority high and cost low.
+
+Invalid action: "download every bundle and inspect everything."
+
+Valid action: "target context creation stack points into `hero-renderer.*.js`; fetch only that source-mapped module to resolve owner and shader source."
+
+## Evidence Ledger
+
+Use ledger entries for facts that influence implementation:
+
+```json
+{
+  "id": "ev-0042",
+  "fact": "target surface is created by THREE.WebGLRenderer",
+  "value": true,
+  "truth": "SOURCE",
+  "targetIds": ["surface-1"],
+  "source": {
+    "type": "runtime|api|source-map|frame-capture|bundle|dom|screenshot|inference",
+    "location": "evidence/runtime/renderer.json#0",
+    "hash": "sha256:..."
+  },
+  "authority": "direct|corroborated|indirect|inferred",
+  "confidence": 0.96,
+  "verifiedBy": ["runtime-owner", "call-stack"]
+}
+```
+
+Implementation-critical values should not rely only on `inferred` evidence unless the replay route is explicitly `BEHAVIOR_REBUILD`.
+
+## Pre-Delivery Honesty Check
+
+Before reporting completion, verify:
+
+- Every implementation-critical value has `SOURCE`, `PARTIAL`, or `GUESS` evidence.
+- No fitted value is labeled `SOURCE`.
+- Wiring facts are proven separately from leaf facts.
+- `REPLAY_READY` has no blocking unknowns without a documented fallback and fidelity downgrade.
+- Known gaps describe the blocking unknown and the evidence needed to resolve it. Do not replace missing evidence with assumptions.
+
+## Sensitive Data
+
+Do not persist cookies, Authorization headers, access tokens, private API keys, or private account data.
+When a browser session is already logged in, record only the minimum non-sensitive facts needed for target attribution and replay.

package/skills/luckiest-website-cloner-shaders/vendor/web-shader-extractor/references/operating-contract.md

@@ -0,0 +1,82 @@
+# Operating Contract
+
+This contract defines the behavior of the Web Shader Extractor skill before any focused workflow begins.
+
+## Objective
+
+Start from the visual effect the user points to.
+Lock the rendering surface, runtime, and source entry that produce it.
+Use the lowest-cost target-bound evidence path.
+Build a runnable and verifiable local baseline first.
+Perform cleanup, modularization, and editability work only after that baseline passes verification.
+
+This skill is not a general website cloner or a general JavaScript reverse-engineering workflow.
+The core completion state is a local, runnable, verified replay of the target visual.
+
+## Non-Negotiable Principles
+
+1. Start from the visual target, not from bundles, framework names, or project structure.
+2. Be canvas-first, not canvas-only: track iframes, OffscreenCanvas, workers, WebGPU, and DOM layers that participate in the effect.
+3. Attribute before locking: the largest, fullscreen, or continuously animated canvas is not automatically the target.
+4. Bind every conclusion to the target: a page-level Three.js, Babylon.js, or platform signature does not prove the target canvas uses it.
+5. Lock the target before deep analysis: do not deobfuscate full bundles before `TARGET_LOCKED`.
+6. Resolve one key unknown at a time: every action must state which unknown it resolves.
+7. Prefer evidence over inference: public definitions, source, source maps, runtime objects, and frame captures outrank minified guesses.
+8. Replay first: a runnable, verified local baseline is the core deliverable.
+9. Restore before refactoring: projectization, modularization, lite versions, and native WebGL conversions happen after the baseline.
+10. Choose the stack for evidence match: use native WebGL only when the scene is simple and conversion facts are complete.
+11. Do not compensate by tuning: never change brightness, speed, position, or noise values to mask timing, color, FBO, resource, coordinate, or state-model errors.
+12. Do not downgrade silently: if source replay falls back to pipeline replay or behavior rebuild, record it.
+13. A matching single frame is not dynamic correctness: verify time, input, scroll, and multi-pass behavior separately.
+14. Never overwrite the baseline: projectization and simplification happen in separate directories.
+15. Do not ask by default: ask only for product-level scope changes or external authorization blockers.
+16. Do not bypass access control: handle only public content or content the user is authorized to access and reproduce; do not save cookies, Authorization headers, tokens, or secrets.
+17. Label implementation-critical facts as `SOURCE`, `PARTIAL`, or `GUESS`; an unlabeled value is treated as `GUESS`.
+18. Separate leaf facts from wiring. Shader text, constants, asset URLs, and pass names can be source facts while render order, timing, input coupling, units, and ownership are still unproven.
+
+## False Conclusion Rules
+
+```text
+1. The largest or fullscreen canvas is not necessarily the target canvas.
+2. A framework existing on the page does not mean the target canvas uses it.
+3. A visible first frame does not prove the render graph, time, and inputs are correct.
+4. A similar screenshot does not prove the dynamic effect has been verified.
+5. A source constant does not prove the pipeline wiring that consumes it.
+6. A target-bound symbol name does not prove units, coordinate space, or timing semantics.
+7. A local fix that improves appearance is not evidence; it is a GUESS until traced or independently verified.
+```
+
+## Fact Labels
+
+Use truth labels close to facts that drive implementation:
+
+- `SOURCE`: direct target-bound evidence. Examples: public original source, source-mapped module, runtime object dump, captured shader/WGSL, frame capture, or network body with hash.
+- `PARTIAL`: a handle for the next probe. Examples: class/function/field name, target-bound bundle slice, framework object, or shader without state/pass/input facts.
+- `GUESS`: visual fitting, naming inference, copied defaults, hand-tuned constants, or any behavior rebuild value without direct evidence.
+
+Never upgrade a fact because output looks similar.
+If a value is fitted so the baseline resembles the source, keep it labeled `GUESS`.
+State which evidence would promote it.
+If direct source conflicts with runtime behavior, treat wiring, units, or target attribution as unresolved before tuning.
+
+Before declaring `TARGET_LOCKED`, `REPLAY_READY`, or `BASELINE_VERIFIED`, check both layers:
+
+- Leaf facts: shader/WGSL text, constants, config, asset paths, resource dimensions, context attributes.
+- Wiring facts: owner, pass order, FBO dependencies, coordinate transforms, time units, random rules, pointer/scroll/resize coupling, output composite.
+
+Read `references/evidence-policy.md` for the full labeling and audit rules.
+
+## External Blockers
+
+Ask separately only for login, CAPTCHA, private pages, paid resources, or permission/license uncertainty.
+Combine blockers into one note.
+
+If connecting to an existing logged-in browser, tell the user credentials or page data may be visible to the agent.
+Do not persist sensitive headers, cookies, tokens, or secrets.
+
+## Completion States
+
+- `DONE_BASELINE_VERIFIED`: baseline passed Source -> Baseline validation.
+- `DONE_PROJECTIZED`: editable project passed Baseline -> Editable regression.
+- `DONE_BASELINE_WITH_GAPS`: baseline runs, but differences or evidence gaps remain and are documented.
+- `BLOCKED_EXTERNAL`: legal access, authorization, or permission prevents progress.

package/skills/luckiest-website-cloner-shaders/vendor/web-shader-extractor/references/qa-failure-policy.md

@@ -0,0 +1,100 @@
+# QA and Failure Policy
+
+Validation happens twice:
+
+1. Source -> Baseline: does the local baseline match the target evidence?
+2. Baseline -> Editable: did projectization avoid regression?
+
+## Fixed Conditions
+
+Keep these identical across comparisons:
+
+- viewport
+- DPR
+- browser/backend
+- fixed time or selected frame
+- pointer, scroll, resize, route state
+- random seed when controllable
+- background, alpha, and DOM composite
+- crop and time point
+
+## Validation Levels
+
+1. Build: dependencies and assets resolve
+2. GPU: shaders/pipelines compile and link
+3. Structural: pass, FBO, program, resource, and state match Manifest
+4. Visual: color, composition, alpha, edges
+5. Temporal: multi-frame rhythm, phase, randomness
+6. Interaction: pointer, scroll, resize, route
+7. Regression: editable project vs baseline
+
+## Minimum Source -> Baseline Protocol
+
+Minimum verification requires more than one static screenshot:
+
+1. Compare at the initial frame or a fixed time.
+2. Compare at a later frame.
+3. Compare after one relevant interaction if the target is interactive.
+4. For scroll-coupled effects, compare at top, middle, and target section.
+5. For route-coupled effects, compare at the route transition or persistent renderer state.
+6. Always record viewport, DPR, browser/backend, crop, time, pointer, scroll, and route state.
+
+Every comparison must save or reference:
+
+- source image or frame evidence
+- baseline image or frame evidence
+- diff image, numeric comparison, or written visual difference record
+
+If the environment cannot produce image diffs, write a structured visual difference record and keep that limitation in `known-gaps.md`. A single matching first frame is not enough for `BASELINE_VERIFIED`.
+
+## Truth Audit
+
+Run this audit before marking the final state:
+
+- Every implementation-critical fact in `replay-manifest.json` has direct evidence or a `PARTIAL` / `GUESS` label.
+- Leaf facts and wiring facts were checked separately. A verified shader or config value does not prove the active render graph, timing, coordinate space, or input route.
+- Any parameter changed to improve appearance is recorded as `GUESS` unless source/runtime/frame evidence proves it.
+- Any mismatch is routed to the upstream unknown that explains it. Do not cover mismatches with tuning.
+- Known gaps state the blocking unknown and the evidence needed to resolve it.
+
+The QA report is the gate artifact for `BASELINE_VERIFY` and `PROJECT_VERIFY`. Do not mark either gate passed while any required row is `pending`, any P0/P1/P2 issue is open, or the final status is absent.
+
+## Severity
+
+- `P0`: cannot run, cannot render, or route impossible
+- `P1`: wrong target, render graph, composition, or main interaction
+- `P2`: visible timing, color, alpha, responsive, or input drift
+- `P3`: polish or performance issue that does not block delivery
+
+Automatically loop only P0/P1/P2.
+
+## Failure Routing
+
+| Symptom | Category | Return |
+|---|---|---|
+| wrong canvas or missing shared surface | target | `SURFACE_ATTRIBUTION` |
+| missing shader/resource/input | evidence | `SOURCE_TRACE` |
+| wrong FBO, time, coordinates, color model | replay model | `CAPTURE_MINIMUM_TRUTH` |
+| dependency, path, or code error | implementation | `RAW_REPLAY` |
+| browser, GPU, CORS, or context issue | environment | `BASELINE_RUN` |
+| evidence complete but implementation visually wrong | fidelity implementation | `RAW_REPLAY` |
+
+Do not route all mismatches into parameter tuning.
+
+## Failure Signatures
+
+Use these signatures to classify mismatches before editing values.
+
+| Symptom | Likely Root Cause |
+|---|---|
+| overall too bright or color-shifted | color space, tone mapping, premultiplied alpha |
+| animation slowly drifts | seconds vs frames, delta, time origin |
+| vertical flip | UVs, render target orientation, SDF/image coordinate system |
+| black blocks or missing layers | FBO, clear, blend, depth, missing resources |
+| noise differs | RNG, precision, filtering, noise implementation |
+| edge softness differs | DPR, AA, derivatives, SDF smoothing |
+| scroll position drifts | DOM-canvas binding or scroll normalization |
+| route flicker | renderer lifecycle, resource cache, route persistence |
+| pointer response offset | canvas CSS transform, DPR, page scroll, coordinate normalization |
+
+Confirm the category with evidence before changing implementation constants.

package/skills/luckiest-website-cloner-shaders/vendor/web-shader-extractor/references/recon-kernel.md

@@ -0,0 +1,206 @@
+# Recon Kernel
+
+The Recon Kernel is the core workflow. It prevents scope drift into website cloning or unrelated bundle analysis.
+
+## Kernel Loop
+
+```text
+LIST        list candidate surfaces and rank them
+ATTRIBUTE   prove which surfaces contribute to the requested target visual
+LOCK        bind target surface group to context, owner, and source clues
+TRACE       choose the lowest-cost authoritative evidence route
+REPLAY      capture required facts and build a local baseline
+```
+
+## State Flow
+
+```text
+INTAKE
+-> CAPABILITY_SNAPSHOT
+-> QUICK_SCOUT
+-> SURFACE_ATTRIBUTION
+-> TARGET_LOCK_GATE
+-> SCOPE_CHECK
+-> TRACE_ROUTE_SELECT
+-> SOURCE_TRACE
+-> CAPTURE_MINIMUM_TRUTH
+-> REPLAY_READY_GATE
+-> RAW_REPLAY
+-> BASELINE_RUN
+-> BASELINE_VERIFY
+-> BASELINE_VERIFIED
+-> PROJECTIZE
+-> PROJECT_VERIFY
+-> OPTIONAL_LITE
+-> PACKAGE
+```
+
+Use these branches:
+
+```text
+TARGET_LOCK_GATE
+  - failed/provisional -> REFINE_SCOUT loop
+  - attributed -> owner/backend/source probe, then return to TARGET_LOCK_GATE
+  - locked -> SCOPE_CHECK
+
+REPLAY_READY_GATE
+  - blocking unknowns remain -> SOURCE_TRACE / CAPTURE_MINIMUM_TRUTH loop
+  - ready -> RAW_REPLAY
+
+BASELINE_VERIFY
+  - target error -> SURFACE_ATTRIBUTION
+  - evidence gap -> SOURCE_TRACE
+  - replay model error -> CAPTURE_MINIMUM_TRUTH / RAW_REPLAY
+  - implementation error -> RAW_REPLAY
+  - environment error -> BASELINE_RUN
+  - passed -> BASELINE_VERIFIED
+```
+
+Use `REFINE_SCOUT` when target lock fails or remains provisional. Use the failure routes in `references/qa-failure-policy.md` when verification fails.
+
+## Initial Protocol
+
+Perform these actions first and persist artifacts under the output directory:
+
+1. Record canonical URL, route, viewport, DPR, browser/backend, and a source screenshot.
+2. Enumerate visible canvases in the main page and iframes. Record OffscreenCanvas, Worker, WebGPU, video, and DOM mask/clip/sticky clues.
+3. Sample two or three frames per plausible surface; estimate visual coverage, temporal activity, z-order, and interaction response.
+4. For top candidates, run short reversible ablation tests: hide, opacity/freeze, transform, or output replacement. Record which target pixels or behaviors disappear.
+5. Probe minimal pointer, scroll, and resize interactions to identify coupling.
+6. Identify the target surface group context, owner thread/frame/worker, and creation source. If needed, reload once with a preload probe.
+7. Accept platform, framework, runtime, and source evidence only when it is bound to the target surface group.
+8. Select exactly one next evidence path and write `scout-card.json`.
+9. Before `TARGET_LOCKED`, do not download or deobfuscate full bundles. Use source maps, public structured definitions, or narrow bundle slices only when they resolve the next unknown.
+
+## Gate Semantics
+
+`TARGET_ATTRIBUTED` means visual causality is proven for a surface group.
+Context, owner, framework, or source may still be incomplete.
+Only owner/backend/source probes tied to `nextProbe` are allowed.
+
+`TARGET_LOCKED` means the target is a surface group.
+Visual attribution exists.
+Context and owner are known or reliably located.
+Source/framework evidence is target-bound.
+Effect boundary is known.
+One trace route is selected.
+Alternatives are recorded.
+
+`REPLAY_READY` means no blocking unknowns remain, or every remaining blocker has an explicit fallback and fidelity tier.
+Time/input rules, output color/alpha/composite, critical resources, and replay route are sufficient for the first local baseline.
+
+`BASELINE_VERIFIED` means the baseline starts independently.
+Main composition/layers are correct.
+Animation and key interactions are checked.
+Render graph/output composite has no P0/P1/P2 issue.
+Known gaps are documented instead of masked by manual tuning.
+
+## Gate Artifact Contract
+
+Gate artifacts are transition guards.
+A gate is not passed until the required artifact exists, uses the bundled template shape, has no placeholders in gate-critical fields, and points to persisted evidence or a documented external blocker.
+
+| Gate | Required artifact | Minimum pass condition |
+|---|---|---|
+| `TARGET_LOCK_GATE` | `scout-card.json` | `lockStatus=locked`; `targetSet` non-empty; attribution evidence referenced; context and owner known; alternatives recorded; primary trace route selected. |
+| `REPLAY_READY_GATE` | `replay-manifest.json` | replay route and fidelity tier set; target surfaces and runtime owner/backend recorded; facts labeled; no blocking unknowns without fallback and downgrade. |
+| `BASELINE_VERIFY` | `qa-report.md` plus `replay-manifest.json` | Source -> Baseline checks have evidence; P0/P1/P2 issues closed or routed back; fact audit complete; final status set. |
+| `PROJECT_VERIFY` | `qa-report.md` | Baseline -> Editable regression checks have evidence; P0/P1/P2 regressions closed; projectization did not change replay route or fidelity tier silently. |
+
+Evidence checklist entries must be structured objects, not prose strings:
+
+```json
+{
+  "status": "unknown",
+  "allowedStatus": ["passed", "blocked", "unknown"],
+  "evidenceId": "ev-001",
+  "path": "evidence/scout/ablation-surface-1.json",
+  "truth": "GUESS",
+  "allowedTruth": ["SOURCE", "PARTIAL", "GUESS"],
+  "notes": ""
+}
+```
+
+If a required artifact is missing or incomplete, keep the current state.
+Set `run-state.json.nextAction` to create or repair that artifact.
+Do not replace artifact fields with prose in the final answer.
+
+`run-state.json.gateStatus` copies the artifact status. It is not a separate evidence source. Update it only after the corresponding gate artifact passes.
+
+## Working Rule
+
+At every step, write down the unknown being reduced. A valid next action has this shape:
+
+```text
+state: SURFACE_ATTRIBUTION
+unknown: whether canvas#hero or iframe[0] owns the target distortion
+action: hide/freeze both candidates for one frame window and compare target crop
+expected evidence: ablation impact by surface
+```
+
+If the action has no target unknown, reject it.
+
+## Evidence Chain
+
+Prefer evidence in this order when it is target-bound:
+
+1. Public structured definition or source for the target embed/effect.
+2. Runtime object directly owning the target canvas/context.
+3. Source map or readable module that creates the target surface.
+4. GPU/frame capture tied to the target context.
+5. Narrow bundle slice selected by stack, call stack, or target IDs.
+6. Inference from minified code or visual behavior.
+
+Do not promote global framework hints to conclusions. They become conclusions only after `references/target-lock.md` criteria pass.
+
+## Artifact Discipline
+
+Keep large facts out of the conversation:
+
+- screenshots and crops under `evidence/screenshots/`
+- DOM and style snapshots under `evidence/dom/`
+- network index under `evidence/network/`
+- frame captures under `evidence/gpu/`
+- runtime probes under `evidence/runtime/`
+- source slices under `evidence/source/`
+
+Reference them from `scout-card.json`, `replay-manifest.json`, and `qa-report.md`.
+
+## Autonomy And State
+
+Default to autonomous execution. Ask only for product scope changes or external access/permission blockers.
+
+```text
+Observe
+-> Compare against current Gate / Manifest
+-> Classify failure or unknown
+-> Choose the lowest-cost action that reduces an unknown
+-> Execute
+-> Persist evidence and state
+-> Measure progress
+```
+
+"Try again" is not a valid action unless something changes.
+
+A retry must change at least one:
+
+- tool
+- injection timing
+- browser or GPU backend
+- target surface
+- interaction state
+- viewport
+- evidence source
+- bundle slice
+- root-cause hypothesis
+
+Default budgets:
+
+- same strategy: 2 attempts
+- capture strategy categories: 3
+- P0/P1/P2 repair rounds: 6
+- plateau: 2 consecutive rounds with no reduction in blocking unknowns and no QA improvement
+
+Persist `.web-shader-extractor/run-state.json`.
+Include state, gate status, strategy, attempts, target set, unknowns, evidence index, artifacts, budgets, plateau, next action, replay tier, and QA.
+Use `templates/run-state.json` as the starting schema.