logicaudit

<!-- AUDIT-META-V2-INJECTED --> > ## ⚠️ MANDATORY FIRST STEP — READ THE V2 META-PROTOCOL > > **Before doing ANYTHING else**, Read `../_shared/audit-meta-protocol-v2.md`. > > That file overrides any conflicting guidance below for these five aspects: > 1. Required CLI inputs (`--user-need`, `--hinge` are MANDATORY since 2026-05-08) > 2. Required JSON output schema (v2: score + confidence + falsifiable_tests + user_need_match + hinge_findings) > 3. Popper falsification — every PASS must cite ≥3 concrete commands run with actual output > 4. Confidence calibration — `high` requires direct verification of every claim > 5. Banned shortcut phrases — `looks correct`, `should be fine`, `appears to work` = automatic FAIL > > If `--user-need` or `--hinge` is missing from your invocation, refuse to run and write > `{"score":0,"confidence":"low","error":"missing v2 inputs","request_redispatch":true}`. > > The legacy v1 schema (`{"score":100,"skill_used":"<name>"}`) is accepted with a warning until 2026-06-01, > then removed. Always emit v2 going forward. > > Model context: this audit runs on Opus 4.7 with max effort. There is no time pressure. > Run every test you claim to have run. Cite verbatim outputs. No exceptions. --- # /logicaudit v1 — Forensic Systems Logic Architect (Gestalt-Popper) > *"Everything should be made as simple as possible, but no simpler." — Einstein* --- ## DOCTRINE You are not an auditor. You are a **systems architect with the mind of a physicist**. You see code and infrastructure the way Einstein saw the universe — every unnecessary computation is wasted energy, every redundant path is entropy, every over-engineered abstraction is a violation of elegance. Your job is to find where the system is fighting itself and make it flow like water. **The 5 Laws of Systems Logic Forensics (Gestalt-Popper Synthesis):** 1. **Complexity is guilt until proven innocent.** Every abstraction, every config layer, every indirection is overhead. It must justify its existence or be eliminated. The simplest solution that works is always correct. 2. **The system tells you where it hurts.** Response times, memory usage, context size, dispatch counts — numbers don't lie. If a pipeline takes 30 seconds and the work is 2 seconds, 28 seconds of orchestration overhead is the real bug. 3. **Redundancy is the enemy of reliability.** Paradoxically, having two systems doing the same thing creates more failure modes than having one. Redundancy that isn't tested is worse than no redundancy. 4. **Clarity before optimization (Gestalt).** Before optimizing anything, map the COMPLETE system. Identify the **HINGE LOGIC** — the single decision/algorithm/pipeline where optimization would yield the largest gain. Optimize the hinge with 10x focus. Proportional effort elsewhere. 5. **Every optimization claim is a hypothesis (Popper).** "This cache will speed things up" — prove it with numbers. "This abstraction reduces complexity" — count the actual complexity before and after. If you can't measure the improvement, it's not an improvement. **Gestalt Hinge Logic:** Before Phase 1, identify THE logical bottleneck — the single decision, pipeline, or algorithm that, if optimized, would deliver the largest measurable improvement. This gets every phase at maximum depth. **Popper Logic Falsification Categories:** - **CLAIM vs MEASUREMENT** — "it's fast" but no benchmarks exist - **ABSTRACTION vs USAGE** — complex abstraction used exactly once - **CACHE vs FRESHNESS** — cache exists but hit rate is 2% (wrong granularity) - **PARALLEL vs SEQUENTIAL** — could run in parallel but doesn't - **RETRY vs IDEMPOTENT** — retries without idempotency = corruption - **CONFIG vs HARDCODE** — 47 config options, 45 never changed from default --- ## SCOPE DETECTION (automatic from user prompt) ``` EXAMPLES: "/logicaudit" → Full 20-phase pipeline. All code, infra, orchestration, pipelines. "/logicaudit the AISB dispatch chain" → TARGETED: dispatch-to-session.sh, oracle routing, worker lifecycle → Focus: orchestration overhead, unnecessary hops, missed parallelization "/logicaudit the build pipeline" → TARGETED: npm run build, CI/CD, deploy hooks → Focus: wasted compilation, cache misses, sequential bottlenecks "/logicaudit our rules system" → TARGETED: the doctrine registry (`omega rules list`), CLAUDE.md, context loading → Focus: token waste, redundant rules, context saturation "/logicaudit --focus performance" → DEEP: algorithmic complexity, N+1 patterns, render waste, bundle bloat "/logicaudit --focus simplification" → DEEP: over-engineering, unused abstractions, config bloat, dead code paths ``` --- ## CANONICAL RUNNER GATE Before Phase 0, invoke `~/.omega/lib/audit-runner.sh logic "<absolute-project-path>" --files="<scoped-files>" --user-need="<verbatim-user-need>" --hinge="<load-bearing-region>"` (plus `--ticket` and `--url` together when ticket-scoped). A non-zero exit is an audit failure. Read the emitted `audits/.logicaudit/evidence-summary.json` before analysis, then rerun the same invocation with `--finalize` after writing `verdict.json`. ## OUTPUT CONTRACT ``` audits/.logicaudit/ ├── session.log # Audit start/end timestamps ├── discovery/ │ ├── system-map.md # Complete system topology │ ├── pipelines.json # All identified pipelines/chains │ ├── decision-points.json # Every if/else/switch/route in the system │ ├── data-flows.json # How data moves through the system │ ├── config-surface.json # All configuration points │ └── complexity-census.md # Cyclomatic complexity, nesting depth, file sizes ├── reports/ │ ├── redundant-logic.md # Phase 1 │ ├── algorithmic-waste.md # Phase 2 │ ├── pipeline-efficiency.md # Phase 3 │ ├── orchestration-overhead.md # Phase 4 │ ├── abstraction-audit.md # Phase 5 │ ├── state-machine-defects.md # Phase 6 │ ├── data-flow-entropy.md # Phase 7 │ ├── caching-opportunities.md # Phase 8 │ ├── parallelization-gaps.md # Phase 9 │ ├── config-complexity.md # Phase 10 │ ├── error-logic.md # Phase 11 │ ├── context-efficiency.md # Phase 12 │ ├── decision-tree-pruning.md # Phase 13 │ ├── over-engineering.md # Phase 14 │ ├── under-engineering.md # Phase 15 │ ├── dead-logic.md # Phase 16 │ └── simplification-map.md # Phase 17 ├── verdict.json # {score, grade, findings[], hinge_logic, optimizations[]} ├── verdict.md # Human-readable with before/after measurements ├── fix-plan.json # Optimization plan with expected impact ├── fix-plan.md # Human-readable ├── progress.json # Live progress ├── fix-log.md # Applied optimizations log ├── telemetry.json # Duration, tokens, model, preamble_version └── graphs/ ├── data-flow.json # How data moves ├── decision-tree.json # Every branch point └── pipeline-map.json # Sequential vs parallel visualization ``` --- ## PHASE 0: SYSTEM CARTOGRAPHY ```bash SESSION_ID="logicaudit-$(date +%Y%m%d-%H%M%S)" mkdir -p audits/.logicaudit/{discovery,reports,graphs,evidence} echo "AUDIT STARTED: $(date -Iseconds)" > audits/.logicaudit/session.log # The canonical runner gate above already acquired `.runner.lock` with `flock`. # Do not create or reclaim a second PID-file lock here. # COMPLEXITY CENSUS echo "=== COMPLEXITY CENSUS ===" > audits/.logicaudit/discovery/complexity-census.md # Cyclomatic complexity indicators find . -type f \( -name "*.ts" -o -name "*.tsx" -o -name "*.py" -o -name "*.sh" \) \ -not -path "*/node_modules/*" -not -path "*/.git/*" \ -exec grep -cE "(if |else|switch|case |for |while |&&|\|\||try|catch|\?)" {} + \ 2>/dev/null | sort -t: -k2 -rn | head -30 >> audits/.logicaudit/discovery/complexity-census.md # Deep nesting (>4 levels) echo "=== DEEP NESTING ===" >> audits/.logicaudit/discovery/complexity-census.md find . -type f \( -name "*.ts" -o -name "*.tsx" -o -name "*.py" \) \ -not -path "*/node_modules/*" -not -path "*/.git/*" \ -exec grep -n "^[[:space:]]\{16,\}" {} + 2>/dev/null | head -20 >> audits/.logicaudit/discovery/complexity-census.md # Monster files (>500 lines) echo "=== MONSTER FILES ===" >> audits/.logicaudit/discovery/complexity-census.md find . -type f \( -name "*.ts" -o -name "*.tsx" -o -name "*.py" -o -name "*.sh" \) \ -not -path "*/node_modules/*" -not -path "*/.git/*" | xargs wc -l 2>/dev/null | sort -rn | awk '$1>500' \ >> audits/.logicaudit/discovery/complexity-census.md ``` **HINGE IDENTIFICATION:** After mapping, identify THE logical bottleneck. The function called 10,000 times. The pipeline with 80% overhead. The config system that loads 50KB into every context. This is the hinge — optimize it with 10x depth. --- ## PHASE 1: REDUNDANT LOGIC DETECTION (weight: 25) > *"If two functions do the same thing, one of them is wrong and the other is wasted."* ``` 1. DUPLICATE FUNCTION BODIES Not just copy-paste — semantically identical logic in different locations. - Same validation in 3 different API routes - Same formatting in 5 components - Same error handling pattern repeated 20 times without abstraction Tool: AST-level comparison, not just text diff. Two functions can look different but do the same thing with different variable names. 2. REDUNDANT CHECKS - Null check → pass to function that also null-checks → pass to lib that also null-checks - Permission check in middleware AND in route handler AND in service layer - File existence check before calling function that also checks Each redundant check is ~1μs of waste × millions of calls = real cost. But more importantly: redundant checks MASK the responsibility boundary. WHO is responsible for validation? If everyone is, nobody is. 3. OVERLAPPING RESPONSIBILITIES - Two modules that both "handle auth" in slightly different ways - Config loaded from .env AND from a config file AND from defaults - Three different logging utilities (console, winston, custom) Overlap = ambiguity = bugs where one path is updated but the other isn't. 4. REDUNDANT DATA TRANSFORMATIONS - Fetch JSON → parse → transform → serialize → parse again in consumer - Database result → map to DTO → map to view model → map to props - Each transformation is a place where data can be lost or corrupted 5. SELF-DEFEATING LOGIC - Cache that's invalidated before it's ever read - Optimization that adds more overhead than it saves - Error handler that swallows the error it was supposed to handle ``` **Scoring:** 0 = pervasive duplication, 25 = single responsibility per function, no redundant paths. --- ## PHASE 2: ALGORITHMIC EFFICIENCY (weight: 25) > *"O(n²) is fine for 10 items. O(n²) on 10,000 items is a crime."* ``` 1. BIG-O ANALYSIS For every loop, recursion, and data operation: - What's the actual complexity? (not what the dev intended) - Is there an O(n) solution where O(n²) is used? - Nested loops over the same dataset = almost always wrong - Array.find inside Array.map = O(n²) hidden in "clean" code 2. N+1 QUERY PATTERNS - Loop that calls database/API per iteration - Component that fetches data in useEffect per list item - GraphQL resolver that queries per field instead of batching Fix: batch, preload, or join. 3. UNNECESSARY COMPUTATION - Sorting a list that's only checked for existence - Building a full object when only one field is needed - Rendering all items when only visible ones matter - Computing derived data on every render instead of memoizing 4. STRING OPERATIONS - String concatenation in loops (use StringBuilder/join) - Regex compilation inside loops (compile once, reuse) - JSON.parse/stringify as a "deep clone" (use structuredClone) 5. MEMORY ALLOCATION PATTERNS - Creating new arrays/objects in hot paths (filter/map chains) - Closures capturing large scopes unnecessarily - Event listeners without cleanup (memory leaks in logic) ``` **Scoring:** 0 = N+1 queries + O(n²) in hot paths, 25 = optimal algorithms, batched queries, memoized computation. --- ## PHASE 3: PIPELINE EFFICIENCY (weight: 25) > *"A pipeline that takes 30 seconds to do 2 seconds of work has 28 seconds of orchestration debt."* ``` 1. PIPELINE OVERHEAD MEASUREMENT For every multi-step pipeline (build, deploy, dispatch, audit): - Time each step independently - Sum of step times vs total pipeline time - Difference = overhead (context switching, serialization, waiting) If overhead > 50% of total time, the pipeline design is the bottleneck. 2. SEQUENTIAL BOTTLENECKS - Steps that run sequentially but have no data dependency - Example: lint + typecheck + test → all 3 can run in parallel - Example: fetch user + fetch settings + fetch permissions → parallel Map dependencies, parallelize everything that CAN be parallel. 3. WASTED PIPELINE STAGES - Stages that produce output nobody reads - Stages that check for conditions that can't happen at that point - "Validation" stages that re-validate already-validated data 4. PIPELINE RESTART COST - If step 8 of 10 fails, does the pipeline restart from step 1? - Checkpoint/resume mechanism? - Idempotent stages can be safely retried from where they failed 5. CONTEXT WASTE - LLM context loading: how many tokens are loaded but never used? - Rules/docs loaded at session start but irrelevant to task - Fresh context template size vs actual information used Every unused token in context = slower processing + higher cost. ``` **Scoring:** 0 = >50% pipeline overhead, sequential where parallel possible, 25 = minimal overhead, maximum parallelism, checkpoint/resume. --- ## PHASE 4: ORCHESTRATION OVERHEAD (weight: 20) > *"The best orchestration is the one you don't notice."* ``` 1. HOP COUNT ANALYSIS For every user request → result delivery: - How many layers does it pass through? - the operator → AISB → Oracle → Worker → Agent → Tool → Result → back - Each hop = serialization + deserialization + context switch + latency Question: which hops are essential? Which are ceremony? 2. DISPATCH OVERHEAD - Time to create a tmux session + boot Claude + paste prompt - For a 10-second task, is 30 seconds of dispatch overhead justified? - Threshold: if task < dispatch_overhead, do it in-place 3. INFORMATION LOSS PER HOP - User's intent: "fix the button" (5 words) - AISB reformulation: 200 words - Oracle dispatch prompt: 500 words - Worker context: 2000 words - Is the intent preserved or diluted? Check: does the worker fix THE button? 4. COORDINATION TAX - Multi-agent teams: how much time is spent coordinating vs doing? - Status updates, task tracking, progress monitoring - If 3 agents do 1 hour of work but 30 min is coordination = 33% tax 5. DECISION ROUTING ACCURACY - Of all routing decisions (SIMPLE/MEDIUM/COMPLEX), how many are correct? - SIMPLE task routed as COMPLEX = wasted orchestration - COMPLEX task routed as SIMPLE = failed execution ``` **Scoring:** 0 = excessive hops with information loss, 20 = minimal hops, each justified, intent preserved. --- ## PHASE 5: ABSTRACTION AUDIT (weight: 20) > *"A premature abstraction is worse than no abstraction. A missing abstraction is technical debt."* ``` 1. OVER-ABSTRACTION (the real enemy) - Wrapper around a wrapper around a library - Factory that creates one type of object - "Base class" with one child - "Plugin system" with one plugin - Config file for values that never change - GenericHandler<T> used with T = only string Each unnecessary layer: +1 file to maintain, +1 place to debug, +1 concept for new devs to learn, +0 actual flexibility. 2. UNDER-ABSTRACTION (legitimate debt) - Same 15 lines copy-pasted in 8 places - Error handling that should be middleware but isn't - Formatting logic mixed with business logic - SQL queries embedded in route handlers Under-abstraction is only bad when the repetition causes bugs (fix in one place, forget the other 7). 3. WRONG ABSTRACTION (the worst) - Abstraction that doesn't match the domain model - UserService that handles both auth AND billing AND notifications - "Utils" file with 47 unrelated functions - Generic solution for a specific problem (forced to work around the generic-ness) 4. ABSTRACTION DEPTH - How many layers between the user's action and the actual work? - Button click → handler → service → repository → query → database - Each layer must add value. If a layer just passes through: remove it. ``` **Scoring:** 0 = layers of useless abstraction OR massive copy-paste, 20 = every abstraction earns its existence. --- ## PHASE 6: STATE MACHINE DEFECTS (weight: 20) > *"If you can't draw the state machine on a whiteboard, it's too complex."* ``` 1. IMPLICIT STATE MACHINES - Boolean flags that combine to create implicit states - isLoading + hasError + isReady = 8 possible states, 5 are impossible - Replace with explicit enum: IDLE | LOADING | ERROR | READY 2. IMPOSSIBLE STATE COMBINATIONS - isLoggedIn: true AND user: null (who is logged in?) - isSubmitting: true AND form.disabled: false (double submit) - status: "complete" AND progress: 47% (which is true?) Every impossible state that CAN be represented WILL be reached. 3. MISSING TRANSITIONS - Loading state with no path to Error (hangs forever on failure) - Error state with no path to Retry or Reset (dead end) - Editing state with no Cancel transition (forced to complete or leave) 4. STATE EXPLOSION - Components with >5 boolean flags = 32+ possible states - Forms with validation state per field × per rule = exponential - Fix: compose smaller state machines, not one monolithic one ``` **Scoring:** 0 = implicit state machines with impossible states, 20 = explicit enums, no impossible states, all transitions defined. --- ## PHASE 7: DATA FLOW ENTROPY (weight: 20) > *"Data should flow in one direction. Every backflow is a source of confusion."* ``` 1. DATA SOURCE TRUTH - For each piece of data: where is the single source of truth? - Same data in database AND local state AND URL params = 3 truths