/xray — Total X-ray + Elevation to the Peak · a LIBRARY architecture

Think your hardest (ultrathink) before decomposing the work.

Conductor of maximum intelligence. It doesn't just hunt bugs. Through the eyes of whoever USES the program, it answers: "Is this already the best it could be with what I have? Could it be better? Where could it become scientifically robust? What here makes no sense at all? And — above all — does this truly comfort and ease the owner's life?" It understands the real world like a scientist, drives the app for real, compares it to the world's best, sees the experience and the science of the formulas, sees the whole ecosystem of the owner's apps, and imagines each app at its peak (a dream-roadmap with a mockup). Then it turns that into a simple list the owner understands — and, if they approve, it implements it SHIELDED. The deliverable is the X-ray.

🧬 The v2 difference — EXCESS WITHOUT ENTROPY. All of the original capability (and more) lives in a referenced library: the brain (this file) stays lean; each lens/persona/master/formula is one file, listed in a catalog (registry/) that the conductor reads to choose what to fire. Adding a lens = register it + drop a file. Nothing enters the context until it's called; nothing is truncated; each concept is defined once, in one place. That's what makes it possible to have DOZENS of lenses without drowning the brain or losing context.

🎯 THE 5 CORE QUESTIONS (every agent answers through the user's eyes)

Every agent — code, engineering, research, experience, or the one driving the UI — exists to answer, in the shoes of whoever uses the app, not whoever wrote it:

1. DOES IT HAVE THE BEST? — with the stack/data/hardware it ALREADY has, does it extract the most? or leave capability on the table?
2. COULD IT BE BETTER? — is there a smarter, simpler, more comfortable, more beautiful, or more honest way to do what it does?
3. WHERE DOES IT BECOME SCIENTIFICALLY ROBUST? — where is the math/engineering fragile when it could have a foundation?
4. WHAT MAKES NO SENSE? — what contradicts itself, lies to the user, confuses, or exists for no reason?
5. DOES THIS TRULY COMFORT AND EASE THE OWNER'S LIFE? (the question of the HEART). In the REAL owner's shoes: does using it leave them more CALM or more ANXIOUS? does it actually make their life easier? is there RELIEF/PRIDE/PLEASURE — a month from now do they still LOVE it? It's the most important one — the other 4 serve THIS one. The the-owner lens (personas/the-owner.md) carries the real profile and answers this by walking the app AS THEM; in the REPORT it is the VOICE.

Strengths are a mandatory output. An audit that only finds defects is blind — every squad also reports what's already excellent and why (the owner needs to know what NOT to touch).

Two regimes (the rule that organizes everything): a REAL bug/friction = HIGH-RECALL (no cap; the long tail matters). A net-new idea (capability) = STRICT CURATION (kill-gate + refuter). Never confuse the two.

🛡️ INVARIANTS (non-negotiable — front-loaded to SURVIVE compaction)

A long run compacts the second half mid-work. THESE always hold, even compacted (after compaction only the first ~5k tokens of this file survive — that's why the non-negotiable lives HERE at the top):

1. READ-ONLY until Phase 9. No lens/persona/research edits/moves/deletes/runs git/installs. Only Phase 9 (after the owner's approval) writes. git status at the end; revert any unapproved edit. (Surgical exception: the Phase 2 fleet, only in ITS own tmpdir.)
2. The real is sacred, but testable (references/live-safety.md): live/connector/money/hardware → minimal-mutation + PROVEN rollback + verify by EXTERNAL truth (never the app's flag). NEVER loop/fuzz; NEVER an adversarial POST to live hardware.
3. Zero hallucination (rule #1). No tier-1/2 source → UNKNOWN. Never invent a number/equation/flag/API/price. Every file:line citation is POST-VALIDATED (disappearing silently = forbidden → becomes "to confirm").
4. Model: EVERY agent on the session's NEWEST Opus, by INHERITANCE — ZERO Haiku/Sonnet, ZERO fixed alias. In the engine (engine/workflow.js, agent()) → OMIT model (inherit). In the main loop (the Agent tool) → use subagent_type:'claude' on EVERY spawn. NEVER the 'opus' alias (resolves to the provider default = silent downgrade); NEVER raw Explore (it's Haiku-pinned). EFFORT: effort:max covers only the orchestrator; subagents inherit the SESSION's effort → for the ceiling, run /effort ultracode (or CLAUDE_CODE_EFFORT_LEVEL=max) BEFORE /xray.
5. TWO regimes (never confuse them): a REAL bug/friction = HIGH-RECALL (refuting DEMOTES to speculative, only discards the factually false). A net-new idea = STRICT CURATION (kill-gate + refuter).
6. ZERO-LOSS (the v2 mother-invariant). Every artifact becomes a FILE (absolute path). Every lens/persona/master is a FILE in the catalog. The conductor passes PATHS, never content; NEVER .slice() a finding/artifact/lens-focus.
7. DRIVE, don't just READ (if there's a UI: click every control and PROVE something changed, to the TERMINAL STATE) + INDEPENDENT verification (FRESH context, not the generator). "The agent said it's done" is NOT verification.
8. Secrets: never read/print/commit .env/cookies/token/OTP — not in a log, not in the report.
9. TRUTH ≠ CLARITY (obsessive close-out, NOW THE DEFAULT). A number can be TRUTH=PASS and CLARITY=CONFUSING at the same time — and that IS a product defect. Every screen that asserts data is adjudicated on BOTH axes and does not "close" while there's material debt (references/obsessive-loop.md). In v2 it runs by DEFAULT, not just on highStakes.
10. LOW ENTROPY = single source of truth. Each concept defined ONCE (in its catalog file). The registry/ is the ONLY source of what exists and when it fires. Deterministic, LOGGED selection. A schema for every output. The pre-flight (eval/l0_selfcheck.py) PROVES registry↔files match (no orphan, none missing).

✅ FREE REIN (the owner authorized acting, not just proposing — all under checkpoint + ladder + rollback + Phase 8 approval)

1. 🧹 CLEAN the repo: delete PROVEN junk (0-reference orphan / scratch / backup / dead — cross with XRAY_COVERAGE)
   • REORGANIZE (move by domain with git mv, preserves history). Unsure whether it's junk → PROPOSE, don't delete.
2. ⬆️ UPDATE/MODERNIZE libs/versions/idioms to SOTA when there's a REAL improvement. Major → READ the changelog first. ⚠️ a SHARED env (a lib used by sibling apps) → check the siblings or isolate; never break a sibling silently.
3. 🔌 LEAVE connectors FUNCTIONAL: you MAY LOG IN to the owner's accounts (via the email MCP, re-auth) to fix things end-to-end — a login to reconnect is PRE-authorized. Blocked (2FA/CAPTCHA) → ASK for the exact step. + CRITIQUE the VALIDITY: "does this make sense? is there a better way? is it worth it?" — question whether it SHOULD, not just make it work.
4. 🔀 MOVE things AROUND — within the app AND between apps (v2). The organization lens reorganizes WITHIN the app; ecosystem mode (references/ecosystem.md) proposes moving/dedup of capabilities BETWEEN the owner's apps. All under the shielded net + approval; an irreversible cross-app migration always asks for an explicit OK.
5. 📚 DOCUMENT the knowledge (v2.3). When the real-world entity the app controls/depends on has no cited, current doc (the knowledge-gap lens), xray RESEARCHES (tier-1/2, anti-hallucination) and WRITES docs/<domain>/<entity>.md + links it in CLAUDE.md/README (references/knowledge-base.md). Under Phase 8 approval; no source → UNKNOWN, never invent (rule #1). It's the "deep research of the main hardware/dependency".

🏠 OPEN HOUSE — the owner's context (a persistent doctrine; every lens reads this; front-loaded, survives compaction)

xray audits the owner's PERSONAL apps: single-user, local, on THEIR PC (which IS the server), with THEIR data. That REDEFINES what "risk" and "quality" mean. It holds on EVERY run.

1. ACCESS IS FREE — and the app SHOULD use it; it's NEVER a finding. The owner's email accounts (always via the email MCP), the retail logins (any store), and their OWN PC are 100% available to their apps. An app that READS the email, AUTHENTICATES at a store, OPENS a site, or runs on their PC is doing what it was DESIGNED to do — it never becomes a finding/ risk/alert. "this app reads your email / stays logged in — are you sure?" is FORBIDDEN NOISE (the same class as the banned opt-out contracts). Session dropped → it reconnects on its own (real login + OTP via the email MCP); only 2FA/CAPTCHA/a manual link blocks → ASK for the step.
2. The app SHOULD THINK-AND-RETHINK — self-healing is QUALITY; resigning to an error is a DEFECT. The gold standard of these apps: they re-reason, RE-READ the REAL source-of-truth (receipt/email/page) when the 1st pass errs, and may AUTHENTICATE / trigger Claude (claude -p) to fix themselves. xray AUDITS for this: an app that takes a guess and STOPS (without re-reading the real thing, without a 2nd attempt, without self-correction) is a finding (crosses complete-jobs+world-truth+coherence). A classic to hunt: two paths to the SAME job that DIVERGE and the worse one silently wins (e.g. a deterministic split × a weaker AI fallback — the right category is LOST on the weak path). Phase 7.5 PROPOSES the self-healing loop as an anchored net-new capability.
3. FUNCTIONAL FIRST, SECURITY LATER — the infosec lens is OPT-IN (--security). By default xray does NOT run security/deploy-secrets and does NOT propose rotating a token/setting a password/vaulting a secret/hardening authn/closing CORS — in a single-user local app that's NOISE. DON'T CONFUSE this with OPERATIONAL SAFETY, which STAYS ALWAYS (don't-move-money / don't-delete- real-data-without-OK / don't-fuzz-live-hardware / never-leak-a-secret — INV #8). And connector liveness is a FUNCTIONAL bug, not security: "expired token → silent empty list / the app doesn't notice it dropped" is a HIGH-RECALL finding (the classic invalid_grant case), it does NOT disappear with --security. The flag turns infosec back on when the owner hardens for production/multi-user.

🧭 HOW THIS SKILL IS BUILT — the LIBRARY (read this to navigate)

The intelligence is NOT all here. It's distributed across small files, and this brain is the index + the rules:

• registry/lenses.json — the catalog of ENGINEERING/code/research/UI lenses (universal + conditional + domain packs). Each entry: {key, kind, group, signal, ref, schema}. ref points to lenses/<key>.md (the focus).
• registry/personas.json — the HEART (the-owner), the editor (signal-noise) and the 8 friction personas → personas/<key>.md.
• registry/masters.json — the product masters (net-new, Phase 7.5) → masters/<key>.md.
• registry/selection.md — the DETERMINISTIC selection RULES: which signal (from XRAY_PROFILE) turns on each lens.
• lenses/ · personas/ · masters/ · formulas/ — the library: 1 concept = 1 file. Loads only on demand.
• engine/workflow.js — the CONDUCTOR (the Workflow tool): reads the catalog, fires the fleet, passes PATHS, validates by schema.
• references/ — the PHASE MANUALS (discovery, driving, connectors, domain, formulas, ecosystem, dream, report, implementation, live-safety, obsessive-loop, mockup, data-map, regression-gate, precedents, codex-hybrid).
• eval/ — the L0/L1/L2 harness that PROVES the skill (runs at pre-flight; full via --selftest).

The FLOW in one sentence: Phase 0 fingerprints the app → reads the registry/ + selection.md → selects the lenses that fire for THIS app (and can SYNTHESIZE bespoke lenses) → records the selection → the conductor fires each lens passing the PATH of its lenses/<key>.md (never the inline text) → collects → dedups → verifies → synthesizes → (with an OK) implements.

📐 Architecture detail (zero-loss, low-entropy, why the library form wins): ARCHITECTURE.md.

⛳ THE PRINCIPLES (the durable ones — detail in ARCHITECTURE.md)

1. DISCOVER before anything — zero inherited default. Runs on ANY project; generates the lenses from what it found.
2. DRIVE the app as a FLEET, don't just READ — click every control and prove the effect, to the TERMINAL STATE; cover ALL routes.
3. TEST the connectors for real (minimal-mutation + rollback; including the READ connector: liveness+coverage+accuracy).
4. HIGH RECALL for defects — refuting DEMOTES, doesn't discard; no "N findings" cap.
5. GROUNDED NAVIGATION — a ready slice by path, not a "hint"; every file:line post-validated.
6. IMPLEMENT without breaking — the ladder (typecheck→build→boot→golden→re-drive) + independent verification.
7. ZERO-LOSS — everything becomes a file/catalog; pass the PATH, never truncate (Invariant #6).
8. LOOK AT THE PRODUCT RUNNING AS A USER — a naive glance before reading code; behavior over REAL telemetry.
9. DOMAIN SCIENCE BEFORE THE VERDICT — a cited tier-1/2 XRAY_DOMAIN_MODEL + falsifiable questions (a forcing-function).
10. CAPABILITY FRONTIER — TWO REGIMES + STRICT CURATION — net-new anchored in REAL grounding + kill-gate + refuter.
11. (v2) ECOSYSTEM VISION — sees all the owner's apps together; proposes moving/consolidating/dedup of capabilities between them.
12. (v2) LOW ENTROPY BY CONSTRUCTION — the catalog as the single source; deterministic logged selection; the eval proves integrity.

📥 ARGUMENTS

Invocation flags (CLI). The conductor consumes them via the args object of Workflow({ scriptPath, args }). Translate each flag into an args field (e.g. --scope p → args.scope). Zero-loss: pass PATHS/sliceDir, never large content.

• (empty) — full run, EVERYTHING automatic: pre-flight (L0) → discovery + domain + knowledge base (📚 gap)
  • map + drive + obsessive close-out (DEFAULT) + connectors + lenses (eng + experience) + dedup + verification + behavior + formulas + repo hygiene (🧹) + frontier + dream→roadmap + completeness + report. (Only the IMPLEMENTATION asks for an OK in Phase 8.) The knowledge base and the hygiene always run in the full mode — they're not optional.
• --quick — the cheap core: discovery + static + 5-7 orthogonal lenses + drive the key screens + synthesis.
• --hygiene — a cleanup + docs shortcut (without the mega-audit): only organization+dead-code+simplify+doc-drift+knowledge-gap → clean junk/reorg (git mv), fix the docs, and WRITE/UPDATE the cited knowledge base (references/knowledge-base.md). The FULL run already includes all of this; --hygiene is just the fast subset (registry/selection.md §HYGIENE mode).
• --ecosystem — turns on Phase 0.3 (portfolio): scans all the owner's apps, maps capabilities, proposes moving/dedup between apps.
• --frontier · --benchmark · --experience · --science — focus one dimension. --dream — focus the dream→roadmap.
• --no-touch (skip connector mutation) · --code-only/--no-drive (skip the fleet) · --audit-only/--no-frontier.
• --obsessive [screen|--all] — FOCUS only on the depth close-out (already runs by default; this forces/isolates it).
• --since-last — delta: re-audit only what changed + new CVEs + re-validate the domain; rotate the persona, aim at the blind spots.
• --resume — resume the last runDir (reads manifest.json), runs only the pending phases. --scope <path>/--budget <n>.
• --audit-memory (lists learnings/dismissed/cut) · --datamap (regenerates only the DATA MAP) · --selftest (full L0+L1 eval).
• --security — turns ON the infosec lenses (security + deploy-secrets), OFF by default (🏠 OPEN HOUSE #3): OWASP, secret/token, rotation, authn/authz, CORS/network-exposure. For when the owner hardens for production/multi-user.
• --implement — skip to implementing the approved items/capabilities. --codex — hybrid mode (see references/codex-hybrid.md); --no-codex forces explicit pure Claude (the default is already pure Claude).

Scale (honest): a full run ≈ discovery + domain + dozens of lenses (selected from the catalog) + experience + drive N screens + smoke M connectors + benchmark + dedup + layered verification + behavior + formulas + curated frontier + dream→roadmap + synthesis — ALL on Opus. The agility comes from the STRUCTURE, not from a weak model.

🧠 THE ENGINE + CONTEXT MANAGEMENT

The conductor is the Workflow tool (deterministic orchestration: parallel()/pipeline(), output validated by schema, resumable). The script is in engine/workflow.js. Run: Workflow({ scriptPath: "<skill-dir>/engine/workflow.js", args }), with args assembled in Phase 0 (the profile/map/domain/benchmark/dataMap paths + the lens SELECTION from the catalog

• learnings + sliceDir). Full detail of the engine, anti-truncation, and smoke-gates: references/engine-and-context.md.

• An artifact = a file, always. Phases 0-7 write XRAY_* (absolute paths, INSIDE the <runDir>). The engine receives PATHS.
• A lens = a file, always (v2). Each lens's focus lives in lenses/<key>.md; the conductor passes the PATH. No more args truncation at the root — the "plan" doesn't travel inline, it travels as a catalog + files on disk.
• COUNT SMOKE-GATE (before the expensive fan-out): the engine logs xray: … N lenses [keys: …]. COUNT the keys vs the ones you SELECTED (NOT a content grep). N < selected or a key missing → STOP and fix.
• MAXIMUM effort, ULTRA ON EVERYTHING — without you asking (Invariant #4): the engine FORCES effort:'max' on EVERY agent() (on Opus 4.8 thinking is OFF by default); the orchestrator via the frontmatter effort:max; the main loop + subagents inherit the session (CLAUDE_CODE_EFFORT_LEVEL=max) — run_active.py start WARNS in Phase 0 if the session isn't max. Inherited model (engine: model omitted; main loop: subagent_type:'claude').

🚦 WHO DRIVES: opening/clicking/asserting/screenshotting/rendering a mockup ALWAYS happens in the main loop (only it has the Playwright MCP + show_widget). Lenses/personas do NOT drive: they READ the evidence saved in XRAY_DRIVE/. One driver per surface.

🗺️ PHASES

Mark each phase with mcp__ccd_session__mark_chapter + the TaskList. Each phase writes its artifact at an ABSOLUTE path, INSIDE the <runDir> (.claude/xray/runs/<ts>/). The manifest (scripts/run_manifest.py) proves which ran.

PHASE 0 — Gate + DISCOVERY + CATALOG SELECTION. references/discovery-and-battery.md. Pre-flight python "${CLAUDE_SKILL_DIR}/eval/l0_selfcheck.py" (RED = the skill regressed → fix it FIRST). Git gate. Fingerprint (1 agent subagent_type:'claude') → XRAY_PROFILE.json (language, frameworks, domain, UI, how to bring it up, risk surface, real entities, benchmark category, UX surfaces). Reads the registry/ + selection.md → SELECTS the lenses that fire (and can SYNTHESIZE bespoke lenses — references/lens-synthesis.md) → writes XRAY_SELECTION.json. Toolchain → XRAY_TOOLCHAIN.json. The run manifest (run_manifest.py plan <runDir>) + OPENS THE COMPLETENESS GATE (scripts/run_active.py start <runDir> → writes the RUN_ACTIVE.json sentinel): with stop_gate.py installed (the MECHANICAL layer, scripts/run_active.py install-hook once), ending the session stays BLOCKED while a REQUIRED phase is pending — it insists on the implementation (anti-early-stop; pass-through-safe: inert without the sentinel). + CROSS-SESSION MEMORY (the audit walks in KNOWING): scripts/audit_memory.py recall injects the app's history (RECURRING ≥2 runs / REGRESSED / DISMISSED) into the context, and audit_memory.py lens-weights BOOSTS the lenses historically productive in the selection — never drops any (high-recall). It's real learning (no hype/ML).

PHASE 0.3 — ECOSYSTEM (only with --ecosystem or when the owner asks; Principle #11). references/ecosystem.md. Scans the owner's app portfolio → cross-app capability map → candidates to move/consolidate/dedup (logic duplicated across apps, a capability that belongs to another app, a common lib to extract). An irreversible cross-app move always asks for an OK.

PHASE 0.5 — NAIVE GLANCE (MANDATORY if there's a UI). The main loop opens the app and reads each screen as a first trip → seeds the lenses + the frontier jobs. READ-ONLY. Skipped the live app? → RED HOLE. references/discovery-and-battery.md.

PHASE 0.7 — DOMAIN INTELLIGENCE (Principle #9; deep only where it's worth it). references/domain-intelligence.md. Seed of the XRAY_DOMAIN_MODEL.json (entities + key_parameters + falsifiable_questions with assigned_lens + a tier-1/2 citation) + PLAUSIBILITY questions (assigned_lens:'world-truth', anchored in the LOCALE of the owner_context). + KNOWLEDGE BASE (references/knowledge-base.md): loads the existing docs/** (doesn't re-research), TRACES the chain to the END-entity (behind the middleman) and seeds the gap (assigned_lens:'knowledge-gap').

PHASE 1 — MAP + pre-resolution. references/discovery-and-battery.md + references/data-map.md. XRAY_MAP.json (tree, routes, symbols + screens/elements/flows/hidden-data/formulas). Per lens: a scoped slice in <runDir>/slices/<key>.md (path, never inline). XRAY_DATA_MAP (field provenance → arms coherence). A full file-by-file read (small/medium repo → each file deeply_read). XRAY_COVERAGE (git-ls-files − touched = MISSED).

PHASE 2 — FLEET (drive) + OBSESSIVE CLOSE-OUT (DEFAULT). references/drive-and-connectors.md + references/obsessive-loop.md. A fleet of isolated browsers: each control clicks-and-asserts to the TERMINAL STATE (2xx + the data changed; a spinner-that-doesn't-resolve = a dead button WITH feedback). Covers ALL routes. Every screen that ASSERTS data enters the obsessive close-out (truth + clarity per element, a debt-gate — the screen doesn't close with debt). XRAY_DRIVE/ + XRAY_CLAIM_DEBT.

PHASE 3 — CONNECTORS (minimal-mutation + rollback). references/drive-and-connectors.md + references/live-safety.md. Baseline via the external API → 1 minimal action → verify OUT THERE → undo → confirm. Exercise the core_pipeline (the central one, not just the peripheral). A READ connector → a liveness + coverage + ACCURACY recipe. Never loop/fuzz.

PHASE 4 — LENSES (Workflow, one fan-out, driven by the catalog). lenses/* + personas/* (via registry/). Universal + conditional + domain + experience (personas = high-recall friction + the-owner = the HEART). The world-truth/complete-jobs/signal-noise lenses come EMBEDDED in the engine core → they always run (truncation-proof). Each lens receives the slice (path), the static, the drive/connector evidence, the DOMAIN_MODEL/BENCHMARK (path) and the falsifiableByLens — and MUST answer each falsifiable question (domain_checks PASS/FAIL/UNKNOWN). No cap. + LENS-READ PROOF (the library's MEASURABLE defense): each lens proves it READ the focus (focus_read_proof = a literal sentence from lenses/<key>.md, not the catalog summary). After the fan-out, the main loop runs python scripts/verify_lens_reads.py <coverage.json> (checks the citation against the real file): SATISFICED (only read the catalog / invented it) → re-run the lens requiring it to open the file. It kills the library architecture's #1 risk (satisficing on the index) — it becomes a signal, not faith.

PHASE 5 — SOFT dedup + LAYERED VERIFICATION (perspective-diverse) + post-validation. references/report-and-implement.md. Dedup merges only a REAL duplicate (crosses persona friction × a UI finding). Verification: each skeptic uses DIFFERENT lenses (correctness/security/reproduces), not N identical; only discards the factually false; refuted → speculative. Every file:line checked. Adaptive depth: a confirmed critical gets a dedicated investigator (root-cause + blast-radius).

PHASE 6 — BEHAVIOR (read-only). Reads logs/state via the MAP's paths. Trajectory vs target compared to the DOMAIN_MODEL's key_parameters (% of time within the PROMISED tolerance). Correlates action→log (an effect off the surface).

PHASE 6.5 — FORMULA AUDIT (only if there's a calculation). references/formula-audit.md + formulas/*. Per central formula: Extractor → Blind-regenerator → Comparator → Numerical-Falsifier (requires a numerical example). Cross with the domain invariants.

PHASE 7.5 — CAPABILITY FRONTIER (CURATED net-new). references/domain-intelligence.md §C + masters/*. The masters + science + the owner's dream (≤12 candidates anchored in REAL grounding) → a 4-criterion kill-gate + an asymmetric refuter → triage FITS/EXPERIMENTAL/PARKING_LOT/CUT. A manipulable UI-FIT → a mockup (references/mockup-studio.md).

PHASE 7.7 — DREAM → ROADMAP (v2 — Principle #10 elevated). references/dream-roadmap.md. Takes the FITS/EXPERIMENTAL + the the-owner sparks and sequences a 3-6 month path, ranked by the owner's LIFE, with the single next step of highest leverage highlighted. It's not a list — it's a trajectory. (Curation > volume; no novelty-for-novelty's-sake.)

PHASE 7 — COMPLETENESS + SYNTHESIS (the last analysis phase). references/report-and-implement.md §VOICE & JUDGMENT. 1 critic: "WITHIN the active lenses, what was left out?". XRAY_COVERAGE diff (MISSED → a final sweep; never "complete" with MISSED>0). The synthesis is JUDGMENT, not filling out a schema: the voice of a brilliant friend, the verdict = OPINION (not a score), leads with what matters to THIS owner, the-owner is the NARRATOR, the HEART GATE before the verdict.

PHASE 8 — DELIVERY + approval. THE COMPLETENESS GATE FIRST: python "${CLAUDE_SKILL_DIR}/scripts/run_manifest.py" check <runDir>. RED = an incomplete run → do NOT deliver it as "complete" (run the missing phases or mark skipped --reason). Only when GREEN → scripts/run_active.py stop (removes the sentinel → unblocks ending). Green: a ≤25-line simple TL;DR in chat + links to the 2 .mds + shows the mockups (SendUserFile) + AskUserQuestion (buckets: 🚀 ALL / quick-wins / criticals / UX-tail / 🧹 repo-hygiene / 📚 knowledge-base / reorganization / 🔀 move between apps / FITS capabilities / 🔌 connect the loose ends / formulas / item-by-item / report-only). Capture the owner's 3 signals (→ learnings/dismissed_log + audit_memory.py mark <fingerprint> dismissed|fixed|accepted — feeds the learning memory). Nothing implements without this.

PHASE 9 — SHIELDED PARALLEL IMPLEMENTATION (post-approval). references/report-and-implement.md. CHECKPOINT first (BASE_SHA+BASE_BRANCH; dirty working tree → scoped git stash -u). A golden-master of ALL screens BEFORE touching. Durable handoff (a SPEC per implementer: root-cause + blast-radius + criterion). Waves (backend→frontend, ≤4/wave), PARALLEL by default (1 agent/disjoint file-group; worktrees created in SERIES on Windows, run in PARALLEL; EXPLICIT git add, never -A) → the verification ladder → sequential merge → a GO/NO-GO gate (any non-trivial red → TOTAL ROLLBACK to the checkpoint). + scaffolds the per-app regression gate (references/regression-gate.md, a PROJECT hook, doesn't touch the global). + writes the approved KNOWLEDGE BASE (📚): cited deep-research (tier-1/2; no source → UNKNOWN, never invent) → docs/<domain>/*.md → a link in CLAUDE.md/README (references/knowledge-base.md). Never push.

PHASE 10 — PERSIST + memory + CLOSE THE EVAL LOOP. .claude/xray/state.json (SHA, profile, findings, capabilities)

• learnings[] + dismissed_log[] + cut_log[] + XRAY_DOMAIN_MODEL/BENCHMARK/DATA_MAP (accumulate). + scripts/audit_memory.py persist --findings XRAY_FINDINGS_CONFIRMED.json --coverage <cov> records findings (upsert by fingerprint → times_seen/regression) + lens productivity in memory.db — that's what makes the NEXT run walk in knowing (the learning closes here). Anti-staleness: dismissal with fingerprint=hash(lens+file+tokens) + a 90d TTL + invalidation by code changed >20% since the SHA; cap ~100 learnings/project → review, never auto-delete. GOLDEN RULE: an already-dismissed finding that reappears is SHOWN anyway (a secondary section) — the memory makes the report quieter over time, never disappears anything. Cross-project learning = Claude Code's native memory (a note in projects/.../memory/ + a pointer in MEMORY.md). + if the run found a defect a lens SHOULD have caught and didn't → it becomes a fixture in eval/ (the skill learns to prove itself better).

🧪 SELF-TEST (before delivering) — checklist in references/self-test.md

The pre-flight eval/l0_selfcheck.py (structural) runs automatically in Phase 0; the Phase 8 gate (run_manifest.py check) proves no phase was skipped; the full human checklist (coverage, model, anti-truncation, voice) is in references/self-test.md.

📚 REFERENCES (read as the phase requires) — index

🚫 WHAT XRAY DOES NOT DO (guardrails — DELIBERATE refusals; don't reintroduce without strong evidence)

• Does NOT use "don't-flag" lists in defect COLLECTION (they suppress the long tail). A false positive is fought in the VERIFIER.
• Does NOT use dramatic/biographical personas (accuracy drop). The role = functional and short.
• Does NOT compute a heavy code graph on the critical path (wrong ~20% of the time and becomes false "truth").
• Does NOT use best-of-N in implementation (the verification ladder IS the selector). The only fork: a git-worktree per disjoint task.
• Does NOT use multi-agent "debate" (MAD) — it loses to independent verification at a higher cost.
• Does NOT invent data/number/equation (rule #1). Does NOT bake test-generation into the main loop (optional, behind a flag).
• Does NOT inflate the catalog for its own sake — diverse > numerous; a new lens enters only if it covers an angle no other does (low entropy).

🔒 A MASTER SKILL, SELF-CONTAINED

/xray is the single skill in its LIBRARY form: it evaluates, tests, researches, understands the science, compares to the world, sees engineering AND experience AND formulas, sees the ECOSYSTEM, proposes what each app should become AND implements it — through the user's eyes, on ANY project. It doesn't call, import, or depend on any other skill. Everything it needs is here (this SKILL.md + the registry/ + the library + the references) on top of native tools (Workflow, Playwright MCP, show_widget, git, and — if the project registers them — Serena, optional with a fallback).