@agentikos/omega-os 0.2.0 → 0.19.6

package/omega/Agentik_SSOT/docs/quality-arsenal/ARSENAL-ORCHESTRATION-PLAYBOOK.md

@@ -0,0 +1,364 @@
+---
+name: ARSENAL-ORCHESTRATION-PLAYBOOK
+description: >
+  Operational playbook for AISB (ORACLE-led orchestration) and project Oracles to
+  dispatch Quality Arsenal audits correctly. Translates user intent into specific
+  audit invocations with proper flags, ordering, and parallelism. Complements
+  ARSENAL-INTERCONNECTIONS.md (the what) with the how.
+  NOT a user-invokable skill — AISB/Oracle reference doc.
+---
+
+# Quality Arsenal — Orchestration Playbook v1.0
+
+> *"Given a mission, which audits fire, in what order, with what scope?"*
+
+---
+
+## 1. ORACLE'S AUDIT SELECTION ALGORITHM
+
+When Oracle receives a task (from AISB / direct user / rule 43 / godmode), it follows this decision tree:
+
+```
+1. Parse user intent. Extract:
+   - Action verb (fix / audit / verify / check / review / redesign / speed up / etc.)
+   - Target noun (page URL / file paths / module / feature / "everything")
+   - Domain signals (UI / code / perf / sec / a11y / SEO / data / API / flow / motion / copy / DX)
+
+2. Consult AUDIT KEYWORD DETECTION table in ~/.claude/CLAUDE.md §"AUDIT KEYWORD DETECTION":
+   - Each keyword maps to a specific /audit skill
+   - Multiple keywords = multiple audits in PARALLEL (rule 001 enforced)
+
+3. Consult ARSENAL-INTERCONNECTIONS.md §3 (dispatch order):
+   - If selected audits have ordering constraints (e.g., perfaudit → seoaudit):
+     batch by dependency group
+   - Within a group: dispatch in parallel
+
+4. Consult ARSENAL-INTERCONNECTIONS.md §5 (non-UI gates):
+   - If project is CLI/library/backend-only/headless:
+     remove incompatible audits (/uiuxaudit, /flowaudit, /motionaudit, /seoaudit)
+     emit "aborted — non-UI context" for user visibility
+     route to alternatives (/dxaudit, /copyaudit)
+
+5. Apply scoping flags based on signals:
+   - URL detected → --url=<URL>
+   - File paths detected → --files=<paths>
+   - Linear ticket ID (rule 43) → --ticket=<ID> + --url + --files
+   - "just this page" → --scope="single page"
+
+6. Enforce concurrency + locks (preamble §3):
+   - Check .{audit}/.lock for each selected audit before dispatch
+   - If lock held < 4h: wait or abort per user intent
+   - If stale > 4h: reclaim, proceed
+
+7. Dispatch via Agent() / TeamCreate() / direct Skill() per task complexity:
+   - SIMPLE (1 audit, single-file) → direct Skill()
+   - MEDIUM (2-3 audits, parallel, independent) → parallel Agent() calls
+   - COMPLEX (4+ audits, groups) → /team with tmux + dependency tracking
+   - EPIC (all 14) → /aisb full or /godmode orchestration
+
+8. Monitor progress via Telegram channel + .{audit}/progress.json files
+
+9. On completion:
+   - Verify all verdict.json files exist + preamble_version="1.0" (output gate)
+   - Aggregate findings by severity
+   - Run /metaudit IF any .md config file was edited during audits
+   - Report to user with cross-audit dedupe per INTERCONNECTIONS.md §5
+```
+
+---
+
+## 2. INTENT → AUDIT-SET TRANSLATION TABLE
+
+Machine-usable routing from natural language to dispatch:
+
+| User input (en/fr, case-insensitive substring match) | Dispatch plan |
+|------|---------------|
+| `audit complet`, `full audit`, `toutes les audits`, `all audits`, `tout auditer` | All 14 via the octad pattern (INTERCONNECTIONS §3). `/metaudit` as final step. |
+| `audit code`, `code audit`, `audit this code` | `/codeaudit --files=<detected>` solo |
+| `audit ui`, `audit ux`, `design audit`, `audit design`, `audit visuel` | `/uiuxaudit --url=<detected>` solo (add `/a11yaudit` if user says "accessible" too) |
+| `audit flow`, `user flow`, `audit parcours`, `workflow audit` | `/flowaudit --url=<detected>` solo |
+| `audit perf`, `performance audit`, `core web vitals`, `audit rapidité` | `/perfaudit --url=<detected>` solo |
+| `audit sec`, `security audit`, `owasp`, `audit sécurité` | `/apiaudit` (static auth) → `/secaudit` (exploit) — STRICT order |
+| `audit a11y`, `accessibility audit`, `wcag`, `audit accessibilité` | `/a11yaudit --url=<detected>` solo |
+| `audit seo`, `seo audit`, `audit référencement`, `crawlability` | `/perfaudit --url=<detected>` → `/seoaudit --url=<detected>` — STRICT order (CWV handoff) |
+| `audit api`, `api audit`, `audit contrats api` | `/dataaudit` → `/apiaudit` — STRICT order (schema → contract) |
+| `audit data`, `data audit`, `data integrity`, `audit données` | `/dataaudit` solo |
+| `audit feature`, `feature audit`, `audit complétude`, `prd gap` | `/featureaudit` solo |
+| `audit copy`, `copy audit`, `messaging audit`, `audit texte`, `audit messages` | `/copyaudit --url=<detected>` solo |
+| `audit dx`, `dx audit`, `developer experience`, `onboarding dev`, `audit dev` | `/dxaudit` solo |
+| `audit motion`, `motion audit`, `animation audit`, `audit animations` | `/motionaudit --url=<detected>` solo |
+| `debugaudit`, `hunt`, `runtime bug`, `chaos`, `audit bugs`, `find bugs` | `/codeaudit` → `/debugaudit` — STRICT order |
+| `meta audit`, `audit the audits`, `audit commands`, `quality arsenal compliance` | `/metaudit` solo |
+| `redesign dashboard`, `refonte dashboard`, `comme linear`, `comme vercel`, `dashboard senior` | `/refontaudit` (not Quality Arsenal, separate dashboard skill) |
+| Linear ticket phrase per rule 43 | QUADRUPLE: `/codeaudit` + `/uiuxaudit` + `/flowaudit` + `/debugaudit` all --ticket-scoped in parallel |
+| Vague (`review`, `check it out`) | ASK user which domain — do NOT pick arbitrarily |
+
+**Multiple keywords in one prompt** (e.g., "audit UX et code on /cases"):
+- Launch each matching audit in PARALLEL with the scope derived from the URL
+- Never combine into a single generic worker (rule 001, §AUDIT KEYWORD DETECTION)
+
+---
+
+## 3. SCOPE FLAGS — HOW TO APPLY THEM
+
+Per preamble §2 (scoped invocation flags), every audit accepts these flags uniformly:
+
+```
+--url={URL}          Apply URL-based walkthroughs to this page only.
+                     Required for: /uiuxaudit, /flowaudit, /debugaudit, /perfaudit,
+                     /a11yaudit, /seoaudit, /motionaudit, /copyaudit (for page-specific copy)
+                     when scope is specific.
+
+--files={paths}      Apply code-side checks to these files only.
+                     Required for: /codeaudit, /apiaudit, /dataaudit when targeting specific
+                     modules. Used by rule 43 (Linear pipeline) with git diff output.
+
+--scope={1-liner}    Free-text scope note in output.
+                     Always include for clarity. Example: --scope="checkout success page only".
+
+--ticket={ID}        Link audit to Linear ticket.
+                     Writes results to .linear-fix/{TICKET}/{audit}.json.
+                     MANDATORY for rule 43 pipeline (Step 8 dynamic chain).
+                     Requires --url and --files to be present.
+
+--no-fix             Dry-run scoring only; skip fix execution.
+                     Use when user wants to review the fix plan before authorize.
+
+--focus={area}       Per-audit narrower phase selection with FULL depth.
+                     Examples:
+                       /codeaudit --focus=security → phases 4+5+6+9+10 at full depth
+                       /uiuxaudit --focus=typography → phase 2 at full depth
+                     NOT a "quick mode". Full protocol, narrower surface.
+
+--set-baseline       Write current measurements as new baseline (regression comparison).
+                     Applies to /perfaudit, /debugaudit (visual), /seoaudit (rankings).
+                     Use sparingly — only for intentional baseline resets.
+```
+
+**FORBIDDEN flags** (rule 46): `--quick`, `--streamlined`, `--lightweight`, `--light`, `--fast`, `--custom`. If user requests, REFUSE with rule-46 explanation. Suggest `--focus <area>` for narrower scope at full depth.
+
+---
+
+## 4. PARALLELIZATION STRATEGY
+
+Multiple audits in the same dispatch:
+
+### Rule-43 Quadruple (Linear ticket)
+```
+Parallel dispatch (4 work sessions or Agent Teams):
+  /codeaudit  --files=$FILES --ticket=$T --url=$URL
+  /uiuxaudit  --files=$FILES --ticket=$T --url=$URL
+  /flowaudit  --files=$FILES --ticket=$T --url=$URL
+  /debugaudit --files=$FILES --ticket=$T --url=$URL
+
+Wait for all 4 to produce .linear-fix/$T/{audit}.json with score=100.
+If any < 100: fix-and-reaudit loop per rule 43 step 8b.
+```
+
+### Octad (full audit)
+```
+Phase A (parallel, no dependencies):
+  /codeaudit  — full run, produces audits/.codeaudit/verdict.json
+  /perfaudit  — full run, produces audits/.perfaudit/verdict.json (CWV measurements)
+  /a11yaudit  — full run
+  /dataaudit  — full run, produces audits/.dataaudit/verdict.json (schema types)
+
+Phase B (after Phase A completes — reads Phase A outputs):
+  /debugaudit   — reads audits/.codeaudit/ (skip phantom-covered findings)
+  /seoaudit     — reads audits/.perfaudit/verdict.json for CWV (skip re-measurement)
+  /apiaudit     — reads audits/.dataaudit/verdict.json for schema types, produces audits/.apiaudit/verdict.json
+  /secaudit     — reads audits/.apiaudit/verdict.json for auth surfaces to exploit
+
+NOTE: /apiaudit runs in Phase B (NOT Phase A) because it consumes /dataaudit output.
+      /secaudit also runs in Phase B because it consumes /apiaudit output.
+      This is a strict dependency chain: dataaudit → apiaudit → secaudit (sequential within Phase B).
+
+Phase C (parallel, independent of A+B, starts immediately with A):
+  /uiuxaudit /flowaudit /featureaudit /motionaudit /copyaudit /dxaudit
+
+Final: /metaudit (if any .md edited).
+```
+
+### Non-UI project audit
+```
+Parallel dispatch (only UI-compatible audits ABORT):
+  /codeaudit /dxaudit /copyaudit /perfaudit /secaudit /a11yaudit-partial
+  /apiaudit (if API project) /dataaudit (if DB project)
+
+ABORTED (emit graceful skip notices):
+  /uiuxaudit /flowaudit /motionaudit /seoaudit
+
+Inform user: "This is a {CLI/library/backend-only/headless} project.
+4 audits not applicable, skipped gracefully."
+```
+
+---
+
+## 5. AISB (ORACLE-led) FULL-PIPELINE TEMPLATE
+
+When `/aisb full <task>` is invoked:
+
+```
+STEP 0: kill-switch + state init (aisb.md)
+STEP 1: reformulate prompt (aisb.md §STEP 1)
+STEP 2: dispatch ORACLE (aisb.md §STEP 2)
+
+ORACLE then:
+  a. Classifies task (SIMPLE/MEDIUM/COMPLEX/EPIC)
+  b. Reads ARSENAL-ORCHESTRATION-PLAYBOOK.md §2 routing table
+  c. Reads ARSENAL-INTERCONNECTIONS.md §3 for dispatch order
+  d. Builds .orchestrator/dispatch-plan.json with:
+     - audits_to_run: [...]
+     - dispatch_groups: [[group_A], [group_B], [group_C]]
+     - scope_flags_per_audit: {...}
+     - wait_conditions: {...}
+  e. Creates TeamCreate + TaskCreate per audit
+  f. Dispatches per group, waiting on dependencies
+  g. Monitors .{audit}/progress.json + Telegram channel
+  h. On all complete: aggregates verdicts, dedupes per INTERCONNECTIONS §5, reports
+
+STEP 3: report results (aisb.md §STEP 3)
+POST-TASK: /debugaudit verification (aisb.md §POST-TASK)
+```
+
+---
+
+## 6. GODMODE AUDIT HANDLING
+
+`/godmode` is fully autonomous. When it spawns audits:
+
+```
+godmode Phase 2 cycle step 4 (EXECUTE):
+  - For each planned audit task:
+    - Pre-inline into the agent prompt:
+      - Audit name + scope flags
+      - References to preamble + interconnections
+      - Expected output path (.{audit}/verdict.json)
+      - Stop criteria: score >= 80 (solo) or 100 (rule 43)
+    - Spawn Agent(subagent_type=<specialist or generic>) or invoke Skill() directly
+  - Concurrent audits: use TeamCreate for visibility + SendMessage for coordination
+  - Track in ~/.godmode/audits-status.json
+
+godmode Phase 2 cycle step 8 (STUCK DETECTION):
+  - If same audit fails 3× with same finding pattern → root cause analysis,
+    not more retries (already enforced by 5-iter cap per preamble §4)
+
+godmode Phase 2 cycle step 10 (REPORT):
+  - Include audit scores in Telegram milestone updates
+  - Highlight any NEEDS_REVIEW items that hit the 5-iter cap
+```
+
+---
+
+## 7. METAUDIT INVOCATION TRIGGERS
+
+Run `/metaudit` automatically when:
+
+1. **After any `.md` file in `~/.claude/commands/` is edited** (drift prevention)
+2. **At the end of `/aisb full`** (final compliance check)
+3. **At rule 43 pipeline step 9** (before moving ticket to "In Review")
+4. **On-demand** when user invokes `/metaudit` directly
+
+Metaudit scope flags:
+- `/metaudit` — full 20-phase scan
+- `/metaudit --focus arsenal` — 14 audits compliance only (fast)
+- `/metaudit --focus preamble` — Phase 1 only (hinge point)
+- `/metaudit --focus deprecation` — stale refs only
+- `/metaudit --focus banned-phrases` — rule 46 scan
+- `/metaudit --focus skills` — Skill() call validity
+
+---
+
+## 8. ORACLE DISPATCH CONTRACT
+
+When Oracle dispatches an audit work session, the prompt MUST:
+
+1. **Start with the exact skill invocation on line 1**:
+   ```
+   /codeaudit --files=src/auth.ts,src/middleware.ts --url=https://example.com/dashboard --scope="auth flow regression" --ticket=DEN-42
+   ```
+2. **Never paraphrase the audit protocol** — rule 001 enforces this (AUDIT KEYWORD DETECTION).
+3. **Include expected output gate**: "On completion, verify `audits/.codeaudit/verdict.json` exists with `score >= 100` and `preamble_version: \"1.0\"`."
+4. **Include the interconnections context**: "See ARSENAL-INTERCONNECTIONS.md §1 for ownership boundaries. Do not duplicate findings owned by other audits."
+5. **Reference the preamble**: "All contracts in QUALITY-ARSENAL-PREAMBLE.md apply. Emit `preamble_version` in verdict.json."
+6. **Pass scope boundaries explicitly**: "Do not expand beyond the specified --files / --url / --scope."
+
+---
+
+## 9. USER COMMUNICATION TEMPLATES
+
+When Oracle reports audit results back to the user:
+
+### Success (single audit)
+```
+✅ /codeaudit complete — score 100/100 (S, Fortress)
+   Scope: 3 files, 1 page
+   Findings: 0 CRITICAL, 0 HIGH, 2 MEDIUM, 5 LOW (all auto-fixed)
+   Iterations: 2 (fix-and-reaudit loop)
+   Duration: 18min
+   Report: audits/.codeaudit/verdict.md
+   Next: /debugaudit for runtime verification (same scope)
+```
+
+### Partial (NEEDS_REVIEW)
+```
+⚠️ /flowaudit completed with 3 NEEDS_REVIEW items (hit 5-iter cap)
+   Score: 92/100 (A, solid)
+   Hinge flow intact. Remaining items need human decision:
+     1. Onboarding step 3 ambiguity (design choice, not fixable in code)
+     2. Payment retry UX (needs business policy)
+     3. Dead-end on /settings/advanced (intentional? confirm)
+   Report: audits/.flowaudit/verdict.md
+   Telegram SOS sent.
+```
+
+### Group dispatch (Linear DYNAMIC audit chain)
+```
+✅ Rule-43 DYNAMIC audit chain complete for DEN-42 (selector chose 5 of 16):
+   /codeaudit    100/100 (3 fixes applied)
+   /uiuxaudit    100/100 (1 fix applied)
+   /flowaudit    100/100 (0 fixes needed)
+   /debugaudit   100/100 (2 console warnings silenced)
+   /logicaudit   100/100 (1 redundant path removed)
+   Adversarial:  confirmed (5 attack attempts blocked)
+   Intent Q1-Q5: PASS
+   Gate passed:  ticket ready for "In Review: Gareth"
+   Comment posted with Before/After screenshots.
+```
+
+### Failure (ABORT)
+```
+🛑 /uiuxaudit aborted — non-UI context detected
+   Project type: CLI tool (no visual UI surface)
+   Alternatives dispatched automatically:
+     /dxaudit (primary for CLIs)
+     /copyaudit (help text, error messages)
+   Preamble §5 ABORT gate enforced per design.
+```
+
+---
+
+## 10. QUICK REFERENCE — "WHICH AUDIT FOR WHAT?"
+
+One-line answer per common question:
+
+| Question | Audit |
+|---------|-------|
+| "The button doesn't work" | `/debugaudit` + `/flowaudit` |
+| "The design looks off" | `/uiuxaudit` + `/a11yaudit` (if contrast/readability) |
+| "Site feels slow" | `/perfaudit` |
+| "Users can't find what they need" | `/flowaudit` + `/seoaudit` |
+| "Can someone hack us?" | `/secaudit` (must follow `/apiaudit` for auth surfaces) |
+| "Google isn't ranking us" | `/perfaudit` → `/seoaudit` |
+| "Form fields lost data" | `/flowaudit` (Phase 8 data integrity through flow) + `/dataaudit` |
+| "API returning wrong shape" | `/apiaudit` |
+| "Screen reader doesn't work" | `/a11yaudit` |
+| "This animation is distracting" | `/motionaudit` |
+| "Headline is unclear" | `/copyaudit` |
+| "New devs struggle to onboard" | `/dxaudit` |
+| "Database is corrupting" | `/dataaudit` |
+| "Is our command system healthy?" | `/metaudit` |
+
+---
+
+*v1.0 — 2026-04-14. Referenced by /aisb, /godmode, /team, rule 43, rule 001-smart-routing.md.*

package/omega/Agentik_SSOT/docs/quality-arsenal/AUDIT-VERIFICATION-CONTRACT.md

@@ -0,0 +1,272 @@
+---
+name: AUDIT-VERIFICATION-CONTRACT
+description: >
+  MANDATORY verification contract for all Quality Arsenal audits (/codeaudit, /flowaudit, /logicaudit,
+  /automationaudit, /debugaudit, /perfaudit, /secaudit, /a11yaudit, /seoaudit, /dataaudit, /apiaudit,
+  /copyaudit, /dxaudit, /motionaudit, /uiuxaudit, /featureaudit). Every audit MUST implement this
+  before/after verification protocol. An audit that cannot prove "100% functional before AND after"
+  is NOT complete. This is the "do no harm" contract.
+  NOT a user-invokable skill — this is a shared source of truth referenced by all audit skills.
+---
+
+# Audit Verification Contract v1.1 — "Do No Harm"
+
+> **An audit that breaks working functionality is a failure, regardless of score improvement.**
+> Before calling any fix "done", prove the thing you touched still works — AND wasn't broken before.
+
+> **v1.1 changelog (2026-04-17):** formalized the HINGE {DOMAIN} pattern,
+> documented mandatory minimums (phase count, score normalization, Phase N-1
+> / N+4), clarified the 16 Quality Arsenal skills the contract applies to.
+
+---
+
+## MANDATORY MINIMUMS (v1.1)
+
+Every Quality Arsenal skill MUST satisfy these structural invariants. A skill
+violating any of them is not compliant and fails `/metaudit`.
+
+| # | Invariant | Rationale |
+|---|---|---|
+| 1 | **At least 16 scored phases** (## headings counted as audit work, not doc) | Forensic depth — fewer phases = shallow audit |
+| 2 | **Phase N-1 (PRE-FIX BASELINE)** implemented before first fix | Hippocratic rule — can't prove "no regression" without baseline |
+| 3 | **Phase N+4 (before-after matrix)** produced to `.{audit}/before-after.md` | Proof-of-work artifact required for 100/100 verdict |
+| 4 | **Score normalized to /100** (raw may be /100, /320, /360, /420, /540 — must include normalization formula `raw / max * 100 = /100`) | Cross-skill comparison |
+| 5 | **HINGE {DOMAIN}** identification before Phase 1 (10× scrutiny on the one thing that dominates the domain's risk/value) | Gestalt clarity gate — not all phases equal |
+| 6 | **Popper falsification** in each scored item (how would you disprove this claim?) | Epistemic rigor — prevents confirmation bias |
+| 7 | **Fix → re-audit loop** with explicit max iterations (typically 5) | Bounded recovery, prevents infinite loops |
+| 8 | **Final verdict gate** blocks 100/100 claim unless `before-after.md` shows 0 regressions | Contract enforcement |
+
+### The HINGE {DOMAIN} Pattern (canonical)
+
+Each forensic audit identifies ONE element that deserves 10× scrutiny — the
+element whose quality dominates the entire domain. The term "hinge" means
+"everything pivots on this". The noun adapts to the domain:
+
+| Skill | Canonical hinge term | What it names |
+|---|---|---|
+| `/codeaudit` | **HINGE POINT** (module/function) | Single module where reliability pivots |
+| `/secaudit` | **SECURITY HINGE POINT** | Auth/authorization boundary |
+| `/uiuxaudit` | **HINGE COMPONENT** | Element that defines perceived quality |
+| `/a11yaudit` | **HINGE FLOW** | Primary accessible journey |
+| `/flowaudit` | **HINGE FLOW** | Journey that defines product's raison d'être |
+| `/perfaudit` | **HINGE PAGE** | Highest-traffic page |
+| `/motionaudit` | **HINGE PAGE** | Page defining kinetic identity |
+| `/seoaudit` | **HINGE PAGES** | Money/conversion pages |
+| `/copyaudit` | **HINGE PAGES** | Conversion-critical copy surfaces |
+| `/dataaudit` | **HINGE TABLES** | Core entities (users, orders, products) |
+| `/apiaudit` | **HINGE ENDPOINTS** | Money/auth/user-data endpoints |
+| `/debugaudit` | **HINGE FEATURE** | Feature whose breakage = product down |
+| `/featureaudit` | **HINGE CAPABILITY** | The one thing the product must do best |
+| `/dxaudit` | **HINGE EXPERIENCE** | First 30 min of a new developer |
+| `/automationaudit` | **HINGE AUTOMATION** | Script whose failure cascades most |
+| `/logicaudit` | **HINGE LOGIC** | Bottleneck decision/algorithm/pipeline |
+
+**Rule:** within a skill, use ONE canonical hinge term consistently. Do not
+mix "hinge point" with a domain-specific term in the same skill. The only
+skill using the generic "HINGE POINT" is `codeaudit` (because "code" has no
+more specific noun) and `secaudit` (which qualifies it with "SECURITY").
+
+When writing a new audit skill: pick the most specific noun for your domain,
+document it in the Gestalt section (Phase 0), and never drift from it.
+
+---
+
+## THE HIPPOCRATIC RULE
+
+**First, do no harm.** Every fix must pass 3 tests:
+
+1. **BEFORE test** — Capture baseline functional state. Does the thing currently work?
+2. **FIX** — Apply the change.
+3. **AFTER test** — Repeat the exact same capture. Does it still work?
+4. **DIFF** — Compare before vs after. Prove no regression.
+
+Without all 3, the fix is UNVERIFIED. Do NOT mark it done.
+
+---
+
+## MANDATORY PHASES FOR EVERY AUDIT
+
+Every audit (code/flow/logic/automation/debug/etc.) MUST add these phases AROUND its fix execution:
+
+### Phase N-1: PRE-FIX BASELINE CAPTURE
+
+Before touching ANY file, capture the current functional state of EVERYTHING the fix might affect.
+
+```
+For each file/resource about to be modified:
+  1. Identify direct dependents: who calls this? who reads this? who executes this?
+     Command: grep -rln "path/or/name" ~/.claude ~/.aisb ~/VibeCoding/work 2>/dev/null
+             | grep -v ".backup" | grep -v "/file-history/" | grep -v ".jsonl"
+  2. For each dependent, capture a "works check":
+     - Script: bash -n SCRIPT  (syntax check)
+     - Config: JSON parse / YAML parse
+     - Python: python3 -c "import ast; ast.parse(open('F').read())"
+     - Shell cron: validate expression
+     - TypeScript: tsc --noEmit PROJECT (if applicable)
+     - Skill: frontmatter present (head -3 | grep "^name:")
+  3. Save baseline to .{audit}/baseline/{file}.baseline
+  4. If ANY baseline check already fails → abort the fix, flag it as "pre-existing broken"
+     Do NOT fix unrelated broken things. Note and move on.
+```
+
+### Phase N: APPLY FIX (existing behavior)
+
+Normal fix execution. Nothing changes here.
+
+### Phase N+1: POST-FIX VERIFICATION
+
+Immediately after each fix, repeat EVERY baseline check from Phase N-1.
+
+```
+For each dependent captured at baseline:
+  1. Re-run the exact same "works check"
+  2. If check PASSES → record as OK
+  3. If check FAILS → this fix broke something that worked. REVERT immediately:
+     - For sed/Edit: restore from .bak
+     - For mv: mv back to original location
+     - For crontab: crontab /tmp/crontab.backup-*.txt
+  4. Mark fix as NEEDS_REVIEW in fix-plan.json
+  5. Continue to next fix (do NOT abort whole audit)
+```
+
+### Phase N+2: FUNCTIONAL SMOKE TEST
+
+Beyond syntax/parsing, verify the thing actually FUNCTIONS:
+
+```
+For every skill whose path changed:
+  - Read the skill file from its new location — does it exist?
+  - grep for all internal references (@-mentions, paths, links) — do they resolve?
+  - Check frontmatter is intact
+
+For every script whose behavior changed:
+  - Run with --help or --dry-run if supported
+  - Check it doesn't hang (timeout 10s)
+  - Check exit code
+
+For every rule whose content changed:
+  - Ensure it's still loadable (markdown syntax valid)
+  - Ensure no internal cross-references were broken
+
+For every cron that was modified:
+  - Validate cron expression with `cron-validator` or equivalent
+  - Confirm `crontab -l` shows expected output
+```
+
+### Phase N+3: BREAKAGE DETECTION REPORT
+
+After all fixes applied, run a full breakage scan:
+
+```bash
+# Find ALL stale references to moved/deleted paths
+echo "=== STALE REFERENCES CHECK ==="
+for old_path in "${MOVED_OR_DELETED[@]}"; do
+  BROKEN=$(grep -rln "$old_path" ~/.claude ~/.aisb ~/VibeCoding/work 2>/dev/null \
+           | grep -v ".backup" | grep -v "/file-history/" | grep -v ".jsonl" \
+           | grep -v ".{audit}/" | head -20)
+  if [ -n "$BROKEN" ]; then
+    echo "🔴 STALE REFERENCES to $old_path:"
+    echo "$BROKEN"
+    # Fix each one OR mark NEEDS_REVIEW
+  fi
+done
+
+# Exit 0 ONLY if zero stale references found
+```
+
+### Phase N+4: BEFORE/AFTER MATRIX (mandatory output)
+
+Every audit MUST produce `.{audit}/before-after.md`:
+
+```markdown
+# Before / After Verification Matrix
+
+## Functional checks
+
+| Item | Before | After | Status |
+|------|--------|-------|--------|
+| /linear skill loads | ✅ PASS | ✅ PASS | NO REGRESSION |
+| rule 43 referenced correctly | 🔴 needed fix | ✅ PASS | FIXED |
+| crontab validates | ✅ PASS | ✅ PASS | NO REGRESSION |
+| dispatch-to-session syntax | ✅ PASS | ✅ PASS | NO REGRESSION |
+| ... | ... | ... | ... |
+
+## Performance metrics
+
+| Metric | Before | After | Delta |
+|--------|--------|-------|-------|
+| Context tokens/session | 20,000 | 12,700 | -36% ✅ |
+| Rules loaded | 16 files | 12 files | -25% ✅ |
+| Dispatch wait time | 7s | 3-5s | -40% ✅ |
+| Minute-0 crons | 14 | 1 | -93% ✅ |
+
+## Regressions detected
+
+<list, or "NONE" if clean>
+
+## Status: {100/100 VERIFIED | NEEDS_REVIEW | FAILED}
+```
+
+If Status is NOT "100/100 VERIFIED" → the audit is NOT done. Do more work.
+
+---
+
+## THE "IT STILL WORKS" CHECKLIST
+
+Before marking ANY audit complete, tick every box:
+
+- [ ] Every file I moved has its new path referenced by every caller
+- [ ] Every file I deleted has no live references (only ephemeral logs OK)
+- [ ] Every script I modified passes `bash -n` (shell) or `python3 -c "import ast"` (Python)
+- [ ] Every cron I changed still passes cron-expression validation
+- [ ] Every skill file I changed still has valid frontmatter
+- [ ] Every rule I moved is accessible at its new path (file exists + readable)
+- [ ] I ran a FRESH grep for old paths across the full ecosystem — got 0 matches
+- [ ] For infrastructure changes (crons, live scripts): backups exist with timestamps
+- [ ] For each fix: before-check PASSED, fix applied, after-check PASSED
+- [ ] `before-after.md` produced with measurable deltas
+- [ ] Zero regressions claimed only if zero regressions actually found
+
+---
+
+## WHAT COUNTS AS "BROKEN" (revert immediately)
+
+- A skill file's path is referenced but target doesn't exist
+- A cron expression is invalid (cron validator fails)
+- A script has syntax errors (`bash -n` fails)
+- A Python module has import/parse errors
+- A rule references another rule that was deleted
+- A hook script points to a path that no longer exists AND the script is actively triggered
+
+---
+
+## WHAT DOESN'T COUNT AS BROKEN (OK to leave alone)
+
+- Reference in ephemeral log files (`tool-results/`, `file-history/`, `.jsonl` session files)
+- Reference in `.backup-*` files you created yourself
+- Reference in deprecated/archived scripts that aren't triggered
+- Reference in `shell-snapshots/` (autogenerated, rotates)
+
+Skip these by default in breakage scans.
+
+---
+
+## ENFORCEMENT
+
+Every audit skill's `## PHASE N+4: VERDICT & SCORING` section MUST end with:
+
+```
+## FINAL VERIFICATION GATE (MANDATORY before final verdict)
+
+1. Read AUDIT-VERIFICATION-CONTRACT.md fully
+2. Execute every check in the "IT STILL WORKS CHECKLIST"
+3. Produce .{audit}/before-after.md
+4. Grep for stale references — must be 0
+5. ONLY THEN write final verdict
+
+If ANY check fails → mark status as NEEDS_REVIEW and do NOT claim "done".
+```
+
+---
+
+*"An audit that breaks a single working thing is worse than no audit. Measure twice, fix once, verify thrice."*