sela-core 0.1.0-alpha.2 → 0.1.0-alpha.31

package/README.md

@@ -1,103 +1,856 @@
-# Sela
+# Sela Documentation
 
-## Getting started
+> **Self-Healing Reliability Engine for Playwright**
+> _Version 1.0.8_
 
-To make it easy for you to get started with GitLab, here's a list of recommended next steps.
+---
+
+## Table of Contents
+
+1. [Introduction - The Problem & The Solution](#1-introduction)
+2. [The Safety-First Philosophy](#2-the-safety-first-philosophy)
+3. [Core Concepts](#3-core-concepts)
+4. [Quick Start](#4-quick-start)
+5. [CLI Reference](#5-cli-reference)
+6. [CI/CD Integration & Sharding](#6-cicd-integration--sharding)
+7. [Reporting & Insights](#7-reporting--insights)
+8. [Advanced Configuration](#8-advanced-configuration)
+9. [Error Reference](#9-error-reference)
+
+---
+
+## 1. Introduction
+
+### The Problem: Tests That Break Without Warning
+
+Selector fragility is the silent killer of test suite ROI. A frontend refactor ships on Friday, and by Monday your CI pipeline is red - not because the application broke, but because a `div` got an `id` rename, a class was reorganised, or a component hierarchy shifted by one level. Your engineers spend the morning triaging failures that have nothing to do with bugs.
+
+At scale, this compounds fast. A team with 2,000 end-to-end tests might absorb dozens of locator-maintenance hours per sprint - engineers doing rote, zero-insight work instead of shipping features.
+
+### What is Sela?
+
+Sela is a **Self-Healing Reliability Engine** for Playwright. It intercepts locator failures at runtime, uses a multi-stage AI pipeline to recover the correct selector, and - after passing a rigorous multi-gate safety review - surgically patches your source code. The broken test passes. Your spec file is updated. No human intervention required.
+
+Sela is **not** a test generator or a code scaffolding tool. It is a reliability layer that runs inside your existing Playwright setup, invisible during green runs, and active only when something breaks. Think of it as an immune system for your test suite.
+
+### Why Sela?
+
+Most "AI testing" tools either generate new tests from scratch or produce brittle selector suggestions you have to manually review. Sela is different in three fundamental ways:
+
+| Dimension           | Typical AI Tools           | Sela                                  |
+| ------------------- | -------------------------- | ------------------------------------- |
+| **When it acts**    | Test generation (pre-run)  | Failure recovery (runtime)            |
+| **What it changes** | Generates new files        | Surgically patches existing source    |
+| **Safety model**    | None / "review everything" | 8-gate automated safety pipeline      |
+| **CI integration**  | Standalone                 | Native Playwright Reporter & sharding |
+| **Source of truth** | The AI                     | Your codebase + DNA fingerprints      |
+
+The key differentiator is **safety with autonomy**. Sela is designed to touch your source code unattended in CI - which means its safety guarantees have to be enterprise-grade. Every heal goes through a multi-gate verification pipeline before a single byte is written to disk.
+
+---
+
+## 2. The Safety-First Philosophy
+
+> _Sela will never make your test suite less trustworthy in order to make it green._
+
+This is the core design constraint. A self-healing engine that silently swaps a **Login** button for a **Logout** button would be worse than no healing at all. Sela's entire architecture is built around preventing exactly this class of failure.
+
+### How Sela Verifies Every Fix Before Touching Your Codebase
+
+When a locator fails, Sela goes through the following sequence. Each stage is a gate - a failure at any gate stops the process and records the event for your review.
+
+```
+Locator Failure Detected
+        │
+        ▼
+┌───────────────────────┐
+│  1. AI Selector Fix   │  LLM proposes a candidate selector + confidence score
+└───────────┬───────────┘
+            │
+            ▼
+┌───────────────────────┐
+│  2. Live DOM Probe    │  Sela finds the element live on the page (1.5s timeout)
+└───────────┬───────────┘
+            │
+            ▼
+┌───────────────────────┐
+│  3. DNA Capture       │  Atomic snapshot of the candidate element's full identity
+└───────────┬───────────┘
+            │
+            ▼
+┌───────────────────────────────────────────────────────────────┐
+│                     SafetyGuard Pipeline                      │
+│  Gate 1: Visibility Check (ghost / occluded element?)         │
+│  Gate 2: Hard Confidence Stop (AI confidence < threshold?)    │
+│  Gate 3: Zero-Trust Content Verification                      │
+│  Gate 4: Structural-Only Change Check                         │
+│  Gate 5: Binary Semantic-Opposite Guard                       │
+│  Gate 6: Functional Role Classification                       │
+│  Gate 6.5: Dangerous-Sink Transition Rule                     │
+│  Gate 7: Intent Auditor (second AI model - haiku)             │
+│  Gate 8: Confidence Tier Decision                             │
+└───────────────────────────────────────────────────────────────┘
+            │
+            ▼
+     APPLY / HOLD / REJECT
+            │
+            ▼ (APPLY only)
+┌───────────────────────┐
+│  AST Source Mutation  │  Surgical, comment-preserving, type-checked write
+└───────────────────────┘
+```
+
+> 💡 **Suggested diagram:** Replace the ASCII art above with an interactive vertical flow diagram showing each gate as a coloured node (green = pass, red = reject, amber = hold).
+
+### The 8-Gate SafetyGuard Pipeline - In Detail
+
+#### Gate 1: Visibility Check
+
+Before anything else, Sela checks whether the candidate element is actually visible and interactive. Six "ghost conditions" are evaluated:
+
+- `G1` - `display: none`
+- `G2` - `visibility: hidden`
+- `G3` - `opacity < 0.05`
+- `G4` - `pointer-events: none` with no interactable child
+- `G5` - zero width and height
+- `G6` - `content-visibility: hidden`
+
+A ghost element results in an immediate `FAIL_HARD` - there is no scenario where healing to an invisible element is correct. Occlusion (another element covering the candidate at its centre point) is also checked: on `main`/`master` branches it is `FAIL_HARD`; on feature branches it is `REQUIRES_REVIEW`.
+
+#### Gate 2: Hard Confidence Stop
+
+The AI healing model returns a numeric confidence score (0–100). If this score falls below `confidenceHardStop` (default: **85**), the heal is blocked unconditionally. This gate is intentionally aggressive - a low-confidence suggestion should never reach your source.
+
+#### Gate 3: Zero-Trust Content Verification
+
+Sela compares the live `innerText` of the candidate element against the DNA baseline text captured during the original test run. If the AI omitted a `contentChange` assessment but the text has changed, Sela synthesises one and forces a full inversion check. Nothing is assumed correct.
+
+#### Gate 4: Structural-Only Change Check
+
+If the selector changed but no text content changed, the risk profile drops significantly. A purely structural heal (e.g., an `id` rename with identical label text) is fast-tracked to `SAFE` if confidence is high enough, or `REQUIRES_REVIEW` if it falls below `confidenceReviewThreshold`.
+
+#### Gate 5: Binary Semantic-Opposite Guard
+
+A hardcoded vocabulary of semantic antonym pairs - `welcome`/`denied`, `login`/`logout`, `enable`/`disable`, and others - is checked against the old and new element text. A match means the element's meaning has inverted. This results in `FAIL_HARD`, regardless of AI confidence.
+
+#### Gate 6: Functional Role Classification
+
+Sela classifies elements into functional roles using word-boundary regex matching:
+
+| Role              | Examples                       |
+| ----------------- | ------------------------------ |
+| `SUBMIT`          | Submit, Confirm, Save, Apply   |
+| `CANCEL`          | Cancel, Discard, Abort         |
+| `DELETE`          | Delete, Remove, Destroy        |
+| `NAVIGATE`        | Back, Next, Go to              |
+| `AUTH`            | Sign in, Log out, Authenticate |
+| `STATUS_POSITIVE` | Success, Approved, Active      |
+| `STATUS_NEGATIVE` | Error, Rejected, Inactive      |
+
+Cross-role swaps (e.g., healing from a `SUBMIT` button to a `CANCEL` button) trigger escalated responses:
+
+- In **assertion mode**: `BLOCKED`
+- In **action mode**: `REQUIRES_REVIEW`
+- `STATUS_POSITIVE` ↔ `STATUS_NEGATIVE`: always `FAIL_HARD`
+
+#### Gate 6.5: Dangerous-Sink Transition Rule
+
+A specialised rule that watches for dynamic role mutations. If the new element falls into the `DELETE` or `AUTH` role and the old element did not, the pipeline sets a `forceAudit` flag - bypassing all confidence-based shortcuts and forcing the Intent Auditor (Gate 7) to evaluate the change regardless of score.
+
+#### Gate 7: The Intent Auditor
+
+When a heal is flagged for deeper review, a second AI model (Claude Haiku) acts as an independent auditor. It receives the DNA before and after snapshots and evaluates whether the semantic intent of the locator is preserved. It returns one of three verdicts:
+
+- **`CONSISTENT`** - The element serves the same purpose. Proceed.
+- **`SUSPICIOUS`** - Intent is uncertain. Blocked in assertion mode; held for review in action mode.
+- **`INCONSISTENT`** - The element's role has changed. `FAIL_HARD`.
+
+The raw auditor confidence is then adjusted structurally:
+
+- **Ancestry drift penalty** (up to −30 pts): if the parent elements have changed significantly, confidence is penalised.
+- **Anchor bonus** (up to +15 pts): if the closest accessible label or row anchor text is an exact match, confidence is boosted.
+
+An adjusted `CONSISTENT` verdict below 50% is downgraded to `SUSPICIOUS`.
+
+#### Gate 8: Confidence Tier Decision
+
+With all gates passed, the final confidence score determines the outcome:
+
+- `≥ confidenceReviewThreshold` (default: **95**) → **`SAFE`** → heal is applied
+- `< confidenceReviewThreshold` → **`REQUIRES_REVIEW`** → heal is quarantined
+
+### The Three Dispositions
+
+Every heal exits the SafetyGuard with one of three dispositions:
+
+| Disposition  | Safety Level            | Behaviour                                                            |
+| ------------ | ----------------------- | -------------------------------------------------------------------- |
+| **`APPLY`**  | `SAFE`                  | Source mutation is written to disk                                   |
+| **`HOLD`**   | `REQUIRES_REVIEW`       | Heal is quarantined; source is untouched; `PROTECTED` event recorded |
+| **`REJECT`** | `BLOCKED` / `FAIL_HARD` | Change is refused; codebase is completely untouched                  |
+
+`PROTECTED` events surface prominently in the Sela Insights report, auto-expanded and annotated with the specific safety rule that blocked the change. This is a feature, not a failure - it means Sela caught a potential regression that would have silently corrupted your test suite.
+
+### The Internal-Selector Invariant
+
+Playwright uses `internal:` engine selectors (e.g., `internal:role=button[name="Submit"i]`) as a private serialisation format. Sela **never** writes these into your source code - they are fragile, undocumented, and produce poor developer experience.
+
+At every write-head, Sela intercepts internal selectors and translates them to idiomatic public Playwright methods:
+
+- `internal:role=…` → `getByRole(...)`
+- `internal:label=…` → `getByLabel(...)`
+
+When a constant (e.g., `const SEL = "#submit"`) is being updated and `getByRole(...)` would be out of scope at the declaration site, Sela writes a clean `role=button[name="Submit"]` public locator string instead, and surfaces a `SEMANTIC_UPGRADE_SUGGESTED` advisory recommending the full method refactor as an optional next step.
+
+### Outbound Data Sanitization
+
+Before any context is sent to an AI provider, Sela sanitises the payload. The following are detected and masked:
+
+- Email addresses
+- Access tokens, secrets, and credentials
+- Password-like values
+- Credit card numbers
+- Custom project-defined sensitive patterns
+
+Sanitisation is **enabled by default**, covers all DOM snapshots, DNA payloads, and healing context, and is fail-secure: if the sanitisation configuration fails to load, masking remains active. It can be disabled via configuration only if your project explicitly requires it.
+
+---
+
+## 3. Core Concepts
+
+### The DNA System - Element Fingerprints
+
+The foundation of Sela's healing intelligence is the **DNA snapshot** - a structured JSON fingerprint of each element captured at the moment it first passes a test. Stored in `sela-snapshots/<stableId>.json`, a DNA record contains:
+
+**Identity**
+
+- Tag name, `id`, `role`, class list, and all HTML attributes
+- `innerText` / `textContent` (trimmed)
+- Bounding rect (`x`, `y`, `width`, `height`)
+- Schema version (`v2`), timestamp
+
+**Ancestry (up to 5 levels)**
+
+- Each ancestor: tag, `id`, classes, and a structural fingerprint
+- Walk stops at Shadow DOM boundaries
+
+**Visibility State**
+
+- Ghost conditions (G1–G6)
+- Occlusion status
+- Opacity value
+
+**Contextual Anchors**
+
+- `closestLabel`: resolved via `aria-labelledby` → `aria-label` → `label[for]` → implicit wrapper → nearest visible sibling
+- `rowAnchor`: longest unique sibling cell text when the element lives in a table row
+- `neighborTexts`: up to five direct-sibling texts
+
+**Shadow DOM & Frame Awareness**
+
+- `isInShadowDom: boolean`
+- Frame traversal path for iframe-hosted elements
+
+The `stableId` is an MD5 hash of `file:line:action[:idx]` - stable across renames but unique per action, preventing cross-call-site poisoning.
+
+### The Heal Pipeline
+
+When a Playwright locator throws, Sela's `SelaEngine.heal()` runs the following sequence:
+
+1. Load the element's DNA snapshot (auto-migrates `v1` → `v2` on read)
+2. Extract an AI-optimised neighbourhood DOM via `DOMUtils.getNeighborhoodDom` (drills iframes and Shadow DOM, strips noise)
+3. Inject DNA context into the LLM prompt (text, role, anchor labels, row anchor, frame-path hint)
+4. Request a fix from the LLM - receives candidate selector chain + confidence + content-change assessment
+5. Live `innerText()` probe (1.5s timeout, frame-aware) - zero-trust verification baseline
+6. Atomic DNA capture of the candidate element
+7. SafetyGuard evaluation (8 gates - see §2)
+8. On `APPLY`: surgical AST source mutation via the Trace-Back Pipeline (primary) or regex fallback
+9. Capture `git diff --unified=1 HEAD` for the report
+10. Buffer `HealedEvent` / `ProtectedEvent` / `FailedEvent` for the end-of-run dashboard
+
+### The AST Trace-Back Pipeline
+
+Rather than blindly overwriting a call-site string, Sela traces a failing locator back to its **source declaration** and mutates it there - preserving your code architecture.
+
+**Example:** If `await hi.nth(3).click()` fails and `hi` was declared as `const hi = page.locator('#old-id')` in a `beforeEach`, Sela updates the declaration, not the call-site. Other tests consuming `hi` are untouched unless analysis proves the old selector is globally broken.
+
+The pipeline has four composable stages:
+
+| Stage | Component         | Purpose                                                                                                        |
+| ----- | ----------------- | -------------------------------------------------------------------------------------------------------------- |
+| 1     | `AnchorResolver`  | Identifies nodes by structural signature (not line numbers), surviving concurrent edits                        |
+| 2     | `TraceBackEngine` | Climbs the call chain to the source declaration; handles POM classes, `beforeEach` patterns, Shadow DOM chains |
+| 3     | `DecisionEngine`  | Chooses `MUTATE_IN_PLACE` (single consumer) vs. `FORK_AT_TEST` (multi-consumer) vs. `PROMPT_INTERACTIVE`       |
+| 4     | `MutationApplier` | Zero-layout-noise splice over exact character spans; type-safety gate with rollback                            |
+
+The `MutationApplier` re-parses the file after mutation and runs TypeScript's `getPreEmitDiagnostics`. If the change introduces a new type error, it rolls back automatically and leaves the file untouched.
+
+**Developer Opt-Out** - Pin any statement against Sela's pipeline with:
+
+```typescript
+// sela-fail-fast
+await page.locator("#legacy-broken").click();
+```
+
+Sela detects this directive before making any LLM call and records a `FailedEvent` with category `"Skipped by Developer"`.
+
+---
+
+## 4. Quick Start
+
+### Prerequisites
+
+- Node.js 18+
+- An existing Playwright project
+- An `ANTHROPIC_API_KEY` (set in your environment or `.env` file)
+
+### Installation
+
+```bash
+npm install sela-core --save-dev
+```
+
+### Time to Value: Under 5 Minutes
+
+**Step 1 - Initialise Sela**
+
+Run this from your project root:
+
+```bash
+npx sela init
+```
+
+This command:
+
+- Creates a `sela.config.ts` with sensible defaults
+- Verifies your `ANTHROPIC_API_KEY` is accessible
+- Rewrites `@playwright/test` imports to `sela-core` in your spec files
+
+> ⚠️ Sela replaces the `@playwright/test` import surface. The full Playwright API (`test`, `expect`, `defineConfig`, `chromium`, `firefox`, `webkit`, `devices`, `selectors`) is re-exported from `sela-core` unchanged - your tests require no further modification.
+
+**Step 2 - Add the Reporter**
+
+In your `playwright.config.ts`:
+
+```typescript
+import { defineConfig } from "sela-core";
+
+export default defineConfig({
+  reporter: [["sela-core/reporter"]],
+  // ... rest of your config
+});
+```
+
+**Step 3 - Run Your Tests**
+
+```bash
+npx playwright test
+```
 
-Already a pro? Just edit this README.md and make it your own. Want to make it easy? [Use the template at the bottom](#editing-this-readme)!
+When a locator failure occurs, Sela intercepts it automatically. At the end of the run, you'll see a summary table in your terminal:
 
-## Add your files
+```
+┌────────────────────┬───────┐
+│ 🔍 Tests Scanned   │  248  │
+│ ⚠️  Errors Detected │    3  │
+│ 🛠️  Successful Heals│    3  │
+│ ⏭️  Skipped Files   │    0  │
+└────────────────────┴───────┘
+```
 
-- [Create](https://docs.gitlab.com/user/project/repository/web_editor/#create-a-file) or [upload](https://docs.gitlab.com/user/project/repository/web_editor/#upload-a-file) files
-- [Add files using the command line](https://docs.gitlab.com/topics/git/add_files/#add-files-to-a-git-repository) or push an existing Git repository with the following command:
+**Step 4 - Review the Report**
 
+```bash
+npx sela show-report
 ```
-cd existing_repo
-git remote add origin https://gitlab.com/sela/Sela.git
-git branch -M main
-git push -uf origin main
+
+This opens `sela-report.html` in your default browser - an interactive dashboard showing healed selectors, safety verdicts, git diffs, and ROI metrics.
+
+---
+
+## 5. CLI Reference
+
+### Top-Level Commands
+
+#### `sela init`
+
+Bootstrap Sela in your project.
+
+```bash
+npx sela init
 ```
 
-## Integrate with your tools
+- Writes `sela.config.ts` to the project root
+- Validates `ANTHROPIC_API_KEY`
+- Migrates `@playwright/test` imports to `sela-core`
+
+---
+
+#### `sela status`
 
-- [Set up project integrations](https://gitlab.com/sela/Sela/-/settings/integrations)
+Print an ecosystem health report for your DNA index.
 
-## Collaborate with your team
+```bash
+npx sela status
+npx sela status --json     # Machine-readable JSON output
+```
 
-- [Invite team members and collaborators](https://docs.gitlab.com/user/project/members/)
-- [Create a new merge request](https://docs.gitlab.com/user/project/merge_requests/creating_merge_requests/)
-- [Automatically close issues from merge requests](https://docs.gitlab.com/user/project/issues/managing_issues/#closing-issues-automatically)
-- [Enable merge request approvals](https://docs.gitlab.com/user/project/merge_requests/approvals/)
-- [Set auto-merge](https://docs.gitlab.com/user/project/merge_requests/auto_merge/)
+Output includes: total DNA records, healed elements, unverified heals, orphaned snapshots (source file no longer exists), heal-to-record ratio, and top healed files.
 
-## Test and Deploy
+---
 
-Use the built-in continuous integration in GitLab.
+#### `sela list`
 
-- [Get started with GitLab CI/CD](https://docs.gitlab.com/ci/quick_start/)
-- [Analyze your code for known vulnerabilities with Static Application Security Testing (SAST)](https://docs.gitlab.com/user/application_security/sast/)
-- [Deploy to Kubernetes, Amazon EC2, or Amazon ECS using Auto Deploy](https://docs.gitlab.com/topics/autodevops/requirements/)
-- [Use pull-based deployments for improved Kubernetes management](https://docs.gitlab.com/user/clusters/agent/)
-- [Set up protected environments](https://docs.gitlab.com/ci/environments/protected_environments/)
+List DNA records with optional filters.
+
+```bash
+npx sela list
+npx sela list --filter "submit"       # Filter by text/selector substring
+npx sela list --source "checkout"     # Filter by source file path
+npx sela list --orphaned              # Show only orphaned DNA records
+npx sela list --limit 20 --json
+```
+
+| Flag              | Description                                     |
+| ----------------- | ----------------------------------------------- |
+| `--filter <text>` | Substring match on selector or element text     |
+| `--source <path>` | Filter by source file path                      |
+| `--orphaned`      | Show only records whose source no longer exists |
+| `--limit <n>`     | Limit output rows                               |
+| `--json`          | Emit structured JSON to stdout                  |
 
 ---
 
-# Editing this README
+#### `sela show-report`
 
-When you're ready to make this README your own, just edit this file and use the handy template below (or feel free to structure it however you want - this is just a starting point!). Thanks to [makeareadme.com](https://www.makeareadme.com/) for this template.
+Open the latest `sela-report.html` in your default browser, or print its absolute path.
 
-## Suggestions for a good README
+```bash
+npx sela show-report
+```
 
-Every project is different, so consider which of these sections apply to yours. The sections used in the template are suggestions for most open source projects. Also keep in mind that while a README can be too long and detailed, too long is better than too short. If you think your README is too long, consider utilizing another form of documentation rather than cutting out information.
+---
 
-## Name
+#### `sela merge <glob>`
 
-Choose a self-explaining name for your project.
+Aggregate sharded JSON payloads from parallel CI runners into a single unified report.
 
-## Description
+```bash
+npx sela merge ".sela/shard-outputs/*.json"
+```
 
-Let people know what your project can do specifically. Provide context and add a link to any reference visitors might be unfamiliar with. A list of Features or a Background subsection can also be added here. If there are alternatives to your project, this is a good place to list differentiating factors.
+Use this as the final step in a CI workflow after parallel shards complete. See [CI/CD Integration](#6-cicd-integration--sharding) for the full pattern.
 
-## Badges
+---
 
-On some READMEs, you may see small images that convey metadata, such as whether or not all the tests are passing for the project. You can use Shields to add some to your README. Many services also have instructions for adding a badge.
+### `sela dna` Subcommands
 
-## Visuals
+#### `sela dna find`
 
-Depending on what you are making, it can be a good idea to include screenshots or even a video (you'll frequently see GIFs rather than actual videos). Tools like ttygif can help, but check out Asciinema for a more sophisticated method.
+Search your DNA index by selector, text, or source file.
 
-## Installation
+```bash
+npx sela dna find --selector "#submit-btn"
+npx sela dna find --text "Add to Cart"
+npx sela dna find --source-file "checkout.spec.ts"
+npx sela dna find --json
+```
 
-Within a particular ecosystem, there may be a common way of installing things, such as using Yarn, NuGet, or Homebrew. However, consider the possibility that whoever is reading your README is a novice and would like more guidance. Listing specific steps helps remove ambiguity and gets people to using your project as quickly as possible. If it only runs in a specific context like a particular programming language version or operating system or has dependencies that have to be installed manually, also add a Requirements subsection.
+---
 
-## Usage
+#### `sela dna refactor [key]`
 
-Use examples liberally, and show the expected output if you can. It's helpful to have inline the smallest example of usage that you can demonstrate, while providing links to more sophisticated examples if they are too long to reasonably include in the README.
+Launch an interactive wizard to manually edit a DNA record, preview the diff, and commit the change to both the snapshot and the source file.
 
-## Support
+```bash
+npx sela dna refactor
+npx sela dna refactor <stableId>
+```
 
-Tell people where they can go to for help. It can be any combination of an issue tracker, a chat room, an email address, etc.
+---
 
-## Roadmap
+#### `sela dna bulk-update --old --new`
 
-If you have ideas for releases in the future, it is a good idea to list them in the README.
+Replace a selector string across all matching DNA records and their source files.
 
-## Contributing
+```bash
+npx sela dna bulk-update --old "#legacy-btn" --new "[data-testid='submit']"
+npx sela dna bulk-update --old "#legacy-btn" --new "[data-testid='submit']" --dry-run
+npx sela dna bulk-update --old "#legacy-btn" --new "[data-testid='submit']" --confirm
+```
 
-State if you are open to contributions and what your requirements are for accepting them.
+| Flag        | Description                              |
+| ----------- | ---------------------------------------- |
+| `--dry-run` | Preview changes without writing to disk  |
+| `--confirm` | Apply changes without interactive prompt |
 
-For people who want to make changes to your project, it's helpful to have some documentation on how to get started. Perhaps there is a script that they should run or some environment variables that they need to set. Make these steps explicit. These instructions could also be useful to your future self.
+---
 
-You can also document commands to lint the code or run tests. These steps help to ensure high code quality and reduce the likelihood that the changes inadvertently break something. Having instructions for running tests is especially helpful if it requires external setup, such as starting a Selenium server for testing in a browser.
+#### `sela dna sync-source <key>`
 
-## Authors and acknowledgment
+Rewrite the locator in a spec file at the exact line recorded in the DNA, to match the stored selector. Useful after manual DNA edits.
 
-Show your appreciation to those who have contributed to the project.
+```bash
+npx sela dna sync-source <stableId>
+```
 
-## License
+---
 
-For open source projects, say how it is licensed.
+### Global Flags
+
+| Flag        | Description                                                                             |
+| ----------- | --------------------------------------------------------------------------------------- |
+| `--json`    | Suppress spinners; redirect diagnostic output to stderr; emit structured JSON to stdout |
+| `--verbose` | Enable debug-level logging (raw LLM payloads, AST transformations, DOM extractions)     |
+
+**Environment variables:**
+
+| Variable          | Effect                                                                                               |
+| ----------------- | ---------------------------------------------------------------------------------------------------- |
+| `SELA_DEBUG=1`    | Equivalent to `--verbose`                                                                            |
+| `SELA_DRY_RUN=1`  | Full heal pipeline runs but no files are written to disk; report marks cards as "Dry Run · No Write" |
+| `SELA_NO_CACHE=1` | Bypass healing cache; every heal hits the LLM directly                                               |
+
+---
+
+## 6. CI/CD Integration & Sharding
+
+### The Playwright Reporter
+
+The `sela-core/reporter` integrates Sela's full heal-and-report pipeline at the Playwright reporter layer. It activates regardless of whether you are using the fixture-based `test` import.
+
+**Reporter lifecycle:**
+
+| Hook        | What Sela does                                                                                                                                        |
+| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `onBegin`   | Sets `SELA_REPORTER_ACTIVE=1`; clears stale shard files from prior crashed runs                                                                       |
+| `onTestEnd` | For `failed`/`timedOut` results: extracts the first PNG attachment, base64-encodes it into memory, and attaches it to the corresponding `FailedEvent` |
+| `onEnd`     | Flushes pending screenshots → compiles report → writes history → emits HTML + JSON                                                                    |
+
+### State Persistence in Ephemeral CI Environments
+
+Sela maintains a 14-run rolling history window in `.sela-history.json`. In ephemeral CI environments where the filesystem resets between runs, Sela implements an **Artifact-by-last-run** strategy: the history file is fetched from the previous run's artifacts before test execution begins.
+
+Add `.sela-history.json` to your CI artifact upload/download steps to preserve the historical trend across runs.
+
+`.sela-history.json` and report files should be excluded from git via `.gitignore`:
+
+```
+# .gitignore
+.sela-history.json
+sela-report.html
+sela-report.json
+.sela/
+sela-snapshots/
+```
+
+To remove any accidentally committed cache pointers:
+
+```bash
+git rm --cached .sela-history.json
+```
+
+### Parallel Sharding
+
+Sela supports Playwright's native `--shard=K/N` parallelism with no additional configuration.
+
+**How it works:**
+
+- Each shard runner writes an isolated payload file to `.sela/report-shards/sela-shard-<pid>-<ts>.json`. There is zero contention between runners.
+- The final CI step runs `sela merge` to aggregate all shards into one unified report and one historical row.
+
+**GitHub Actions example:**
+
+```yaml
+# .github/workflows/test.yml
+jobs:
+  test:
+    strategy:
+      matrix:
+        shard: [1, 2, 3, 4]
+    steps:
+      - run: npx playwright test --shard=${{ matrix.shard }}/4
+
+      - name: Upload shard output
+        uses: actions/upload-artifact@v4
+        with:
+          name: sela-shard-${{ matrix.shard }}
+          path: .sela/report-shards/
+
+  report:
+    needs: test
+    steps:
+      - name: Download all shard outputs
+        uses: actions/download-artifact@v4
+        with:
+          pattern: sela-shard-*
+          merge-multiple: true
+          path: .sela/report-shards/
+
+      - name: Merge Sela report
+        run: npx sela merge ".sela/report-shards/*.json"
+```
+
+**Shard merge guarantees:**
+
+- **Clock-skew immunity:** Event deduplication is keyed on `kind|stableId|normalizedPath|line|title` - timestamps are intentionally excluded, making the dedup safe across multi-region runners with clock drift.
+- **Partial-failure resilience:** If a subset of shards failed (e.g., a worker crash), `sela merge` aggregates the surviving data, produces the unified report, and surfaces a prominent diagnostic warning. It does not abort the reporting pipeline.
+
+### CI Deduplication
+
+When a CI job is retried (native Playwright retry or manual re-run), Sela detects the environment signature (`GITHUB_RUN_ID` or `CI_PIPELINE_ID`) and performs an **in-place overwrite** of the existing history entry for that run - preventing dataset inflation from retries.
+
+### Integrity Guard
+
+`ReportMergeService` validates the structure of `.sela-history.json` on read. If a corrupt or truncated state file is detected, it throws `HISTORY_CORRUPT` and aborts - preserving the last known good state. A corrupted history file will not silently clobber valid historical data.
+
+---
 
-## Project status
+## 7. Reporting & Insights
+
+### The Sela Insights Report
+
+`sela-report.html` is a self-contained, enterprise-grade dark-mode dashboard written to disk after every run (and accessible via `sela show-report`). It has two views toggled at the top of the page:
+
+#### The Management ROI Dashboard
+
+Designed for engineering leads and senior management:
+
+- **Status Donut Chart** - Live distribution of `Passed`, `Healed`, `Protected`, and `Failed` tests. Click any slice to jump to the Engineering Deep Dive, pre-filtered to that state.
+- **Executive KPI Cards** - Time saved today (12 min per heal, 18 min per project win, 4 min per detected failure), cumulative bugs prevented, suite success rate, and average AI healing confidence.
+- **14-Run Historical Trend Chart** - Area chart of cumulative developer hours recovered (cyan gradient) overlaid with a line tracking total self-healed selectors per run. Clean zero-heal runs appear as benchmark performance points, not gaps.
+- **Recent Runs Ledger** - Tabular audit trail of historical runs with confidence ratios and saved metrics.
+
+#### The Engineering Deep Dive
+
+Designed for the developers who own the specs:
+
+- **Dynamic filter chips** and a search bar supporting automated focus shortcuts
+- **Healing Cards** - When expanded, each healed test shows:
+  - A colour-coded git diff (`--unified=1`) with exact line numbers
+  - An Intent Auditor Gauge: circular progress UI with safety breakdown score, ancestry penalties, anchor bonuses, and the final verdict
+  - AI Chain-of-Thought: collapsible logical steps (DNA recovery, layout strategies, safety bounds)
+  - A DNA Evidence Table: old-vs-new attribute comparison with match/mismatch indicators
+  - **Action Panel:** one-click copy of rollback CLI script (`npx sela dna refactor --rollback`), copy of alternative candidate locators, and a VS Code deep-link (`vscode://file/path/to/spec.ts:42`) to jump directly to the mutated line
+- **Protected Event Cards** - Auto-expanded on load; annotated with the specific safety rule that blocked the change and the semantic inversion or role violation detected
+
+### Failure Screenshots
+
+The reporter automatically captures the first PNG screenshot from Playwright's test attachments on failure, base64-encodes it into memory (surviving Playwright's temp-folder cleanup), and embeds it inline in the failure card in the HTML report. No additional configuration is required.
+
+### PR Automation
+
+Sela can optionally open pull requests or commits for healed selectors. Configure via `sela.config.ts`:
+
+```typescript
+prAutomation: {
+  enabled: true,
+  strategy: 'PR',           // 'directCommit' | 'PR' | 'draftPR'
+  minAiConfidence: 90,
+  minAuditorConfidence: 80,
+  onBugDetected: true,      // Open separate issue/PR for PROTECTED events
+}
+```
+
+Sela evaluates the configured strategy at runtime and **downgrades** it automatically when constraints are not met (e.g., insufficient confidence, branch policy mismatch), logging the reason.
+
+---
+
+## 8. Advanced Configuration
+
+### `sela.config.ts` - Full Reference
+
+```typescript
+import { defineConfig } from "sela-core";
+
+export default defineConfig({
+  // 'balanced' | 'strict' | 'loose' - preset that sets threshold defaults
+  policy: "balanced",
+
+  // How Sela writes heals to disk
+  updateStrategy: "inPlace", // 'inPlace' | 'commentOnly' | 'branch'
+  autoCommit: false, // Commit to current branch after healing
+
+  // SafetyGuard thresholds
+  thresholds: {
+    confidenceHardStop: 85, // Below this → BLOCKED unconditionally
+    confidenceReviewThreshold: 95, // Below this → REQUIRES_REVIEW
+    auditorConfidenceMin: 75, // Minimum adjusted auditor confidence
+    allowSuspicious: false, // Allow SUSPICIOUS heals through in action mode
+    auditorStrictness: "balanced", // 'strict' | 'balanced' | 'loose'
+  },
+
+  // Per-branch threshold overrides
+  branchOverrides: {
+    main: {
+      policy: "strict",
+      thresholds: { confidenceHardStop: 90, confidenceReviewThreshold: 98 },
+    },
+  },
+
+  // Write-scope allowlist (glob patterns); empty = unrestricted
+  allowedPaths: ["tests/**/*.spec.ts", "e2e/**/*.ts"],
+
+  // Healing budget - null = unlimited
+  maxHealsPerRun: 50,
+
+  // Outbound data sanitisation
+  sanitization: {
+    enabled: true,
+    customPatterns: [
+      /ACME-[A-Z0-9]{16}/g, // Custom token format
+    ],
+  },
+
+  // PR automation
+  prAutomation: {
+    enabled: false,
+    strategy: "PR",
+    minAiConfidence: 90,
+    minAuditorConfidence: 80,
+    onBugDetected: true,
+  },
+});
+```
+
+### Update Strategy Modes
+
+| Mode          | Behaviour                                                                                |
+| ------------- | ---------------------------------------------------------------------------------------- |
+| `inPlace`     | Writes the healed selector directly to your spec (default)                               |
+| `commentOnly` | Inserts `// TODO [Sela]: <new selector>` above the failing line; source is never mutated |
+| `branch`      | Creates a `sela/heal-<timestamp>` git branch and commits the change there                |
+
+`commentOnly` is useful when you want Sela to analyse and propose fixes in CI, but reserve the actual write for a human review step.
+
+### Branch Overrides
+
+Apply tighter constraints on protected branches:
+
+```typescript
+branchOverrides: {
+  main: {
+    policy: 'strict',
+    thresholds: {
+      confidenceHardStop: 92,
+      confidenceReviewThreshold: 98,
+    },
+  },
+  'release/*': {
+    policy: 'strict',
+  },
+},
+```
+
+Sela detects the current branch via `git rev-parse --abbrev-ref HEAD` and merges the matching override at runtime.
+
+### Write Scope Protection
+
+Restrict which files Sela is permitted to modify using glob patterns:
+
+```typescript
+allowedPaths: [
+  'tests/**/*.spec.ts',
+  'e2e/pages/**/*.ts',
+],
+```
+
+- All write-heads (`SourceUpdater`, `ASTSourceUpdater`, `InitializerUpdater`, `MutationApplier`) validate the target path against this list before writing
+- Path traversal (`../`) and symlink escapes are blocked unless explicitly matched by an absolute pattern
+- An empty `allowedPaths` array means unrestricted writes (backward-compatible default)
+
+### Heal Budget
+
+Limit the number of AI-generated heals per run to control costs or enforce a gradual rollout:
+
+```typescript
+maxHealsPerRun: 25,
+```
+
+- Each AI heal consumes one budget slot
+- Cache hits do **not** consume budget
+- Once exhausted, additional heal attempts are skipped for that run
+- Budget state is process-safe and shared across all workers
+
+### Dry Run Mode
+
+Run the full healing pipeline - including LLM calls, SafetyGuard evaluation, and AST mutation - without writing anything to disk:
+
+```bash
+SELA_DRY_RUN=1 npx playwright test
+```
+
+The report marks healed cards as `"Dry Run · No Write"`. Use this to audit what Sela would change before enabling it in production CI.
+
+### The `sela-fail-fast` Directive
+
+Exempt individual statements from healing entirely:
+
+```typescript
+// sela-fail-fast
+await page.locator("#legacy-element").click();
+```
+
+Also accepted as `// @sela-fail-fast` or `/* sela-fail-fast */`. Sela detects this directive **before** making any LLM call - it never reaches the AI pipeline, so there is zero cost for opted-out selectors.
+
+---
+
+## 9. Error Reference
+
+All Sela errors follow a canonical structure:
+
+```typescript
+{
+  subsystem: string,   // e.g. "SafetyGuard", "ASTUpdater", "Report"
+  code: string,        // stable machine-readable code
+  reason: string,      // human-readable explanation
+  context: object,     // structured diagnostic context
+  message: string,
+  stack: string,
+}
+```
+
+### SafetyGuard Codes
+
+| Code                             | Trigger                                                 |
+| -------------------------------- | ------------------------------------------------------- |
+| `BLOCKED_LOW_CONFIDENCE`         | AI confidence below `confidenceHardStop`                |
+| `BLOCKED_AUDITOR_SUSPICIOUS`     | Intent Auditor returned `SUSPICIOUS` in assertion mode  |
+| `BLOCKED_ROLE_SWAP_ASSERTION`    | Cross-role swap detected in assertion mode              |
+| `FAIL_HARD_VISIBILITY_GHOST`     | Candidate element is invisible (G1–G6)                  |
+| `FAIL_HARD_VISIBILITY_OCCLUDED`  | Candidate element is covered on main/master             |
+| `FAIL_HARD_SEMANTIC_INVERSION`   | Binary semantic opposite detected                       |
+| `FAIL_HARD_STATUS_INVERSION`     | Status role inversion (POSITIVE ↔ NEGATIVE)             |
+| `FAIL_HARD_AUDITOR_INCONSISTENT` | Intent Auditor returned `INCONSISTENT`                  |
+| `FAIL_HARD_DANGEROUS_SINK`       | Dangerous-sink forced audit resulted in rejection       |
+| `SG_HELD_FOR_REVIEW`             | Heal quarantined (`REQUIRES_REVIEW`) - source untouched |
+| `GENERIC_REJECTION`              | Catch-all rejection                                     |
+
+### CI Integrity Codes
+
+| Code               | Trigger                                                                                                |
+| ------------------ | ------------------------------------------------------------------------------------------------------ |
+| `HISTORY_CORRUPT`  | `.sela-history.json` failed structural validation - pipeline aborted to preserve last-known-good state |
+| `SHARD_UNREADABLE` | A shard payload failed to parse - shard is skipped; aggregate-and-flag behaviour applies               |
+
+### Write-Scope & Budget Codes
+
+| Code                   | Trigger                                              |
+| ---------------------- | ---------------------------------------------------- |
+| `PATH_SCOPE_VIOLATION` | Attempted mutation outside configured `allowedPaths` |
+| `HEAL_BUDGET_EXCEEDED` | `maxHealsPerRun` limit reached for this execution    |
+
+### AST Codes
+
+| Code                             | Trigger                                                            |
+| -------------------------------- | ------------------------------------------------------------------ |
+| `AST_HEAL_DISABLED_BY_DIRECTIVE` | `// sela-fail-fast` directive detected above the failing statement |
+
+### Exit Code Policy
+
+- **Test runs** (`npx playwright test`): Playwright owns the exit code. A healed test passes → `0`. An unhealed genuine failure → `1`. Sela never converts a recoverable file-level failure into a worker crash.
+- **CLI subcommands**: Fatal infrastructure failures (missing config, history corruption) → non-zero exit. Recoverable file-level failures in batch commands → `0` (execution continued).
+
+---
 
-If you have run out of energy or time for your project, put a note at the top of the README saying that development has slowed down or stopped completely. Someone may choose to fork your project or volunteer to step in as a maintainer or owner, allowing your project to keep going. You can also make an explicit request for maintainers.
+_Sela is designed to earn your trust incrementally. Start with `commentOnly` mode, review a week of proposed heals in the Insights report, then graduate to `inPlace` when you are confident. The safety pipeline is always active regardless of write mode._