@lvlup-sw/axiom 0.2.0

package/skills/distill/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: distill
+description: "Strip backend code to its essence by identifying dead code, vestigial patterns, and unnecessary complexity. Use when cleaning up after refactoring or reducing cognitive load. Triggers: 'simplify code', 'find dead code', 'clean up', or /axiom:distill. Do NOT use for error handling — use axiom:harden instead."
+user-invokable: true
+metadata:
+  author: lvlup-sw
+  version: 0.1.0
+  category: assessment
+  dimensions:
+    - hygiene
+    - topology
+---
+
+# Distill Skill
+
+## Overview
+
+Simplification skill for the axiom backend quality plugin. Covers DIM-5 (Hygiene) and DIM-1 (Topology) dimensions to strip code down to its essential form by identifying dead code, vestigial patterns, and unnecessary complexity.
+
+## Triggers
+
+Activate this skill when:
+- User says "simplify code", "find dead code", "clean up"
+- User runs `/axiom:distill`
+- Post-refactoring cleanup is needed
+- Reducing cognitive load in a module
+
+Do NOT activate when:
+- Error handling improvements are needed — use `axiom:harden` instead
+- Performance optimization is the goal — performance profiling is out of scope for axiom
+- Security hardening is required — use `axiom:harden` instead
+
+## Process
+
+### 1. Load Dimensions
+
+Load the relevant quality dimensions from `@skills/backend-quality/references/dimensions.md`:
+- **DIM-5 (Hygiene):** Dead code, commented-out code, unused imports/exports, vestigial patterns
+- **DIM-1 (Topology):** Module structure, dependency direction, wiring complexity
+
+### 2. Run Deterministic Checks
+
+Run `axiom:scan` for deterministic checks on Hygiene and Topology dimensions. This produces machine-verifiable findings for:
+- Unused exports and imports
+- Unreachable code paths
+- Circular dependencies
+- Excessive module fan-out
+
+### 3. Layer Qualitative Assessment
+
+Beyond deterministic checks, apply human-judgment analysis:
+
+#### Dead Code Identification
+Identify unreachable branches (code after `return`/`throw`), unused exports (exported but never imported elsewhere), commented-out code (version control exists for history), and feature-flagged-off code that shipped long ago.
+
+See `@skills/distill/references/dead-code-patterns.md` for detection heuristics and false positive guidance.
+
+#### Vestigial Pattern Detection
+Find evolutionary leftovers from previous designs. Look for divergent implementations that suggest a pattern was partially migrated, adapter layers wrapping things that no longer need adapting, and configuration for features that were removed.
+
+#### Wiring Simplification
+Identify manual DI that could be simpler, unnecessary indirection layers, over-abstracted factory/builder patterns where direct construction suffices, and registration ceremonies that add complexity without value.
+
+#### Abstraction Audit
+Flag premature abstractions, over-engineering, and single-use helpers. Ask: does this abstraction serve more than one caller? Would inlining it make the code clearer?
+
+#### Code Archaeology
+Identify patterns that were once necessary but no longer serve a purpose. Look for workarounds for bugs that have since been fixed, compatibility shims for deprecated APIs, and defensive code guarding against conditions that can no longer occur.
+
+### 4. Output Findings
+
+Format all findings per `@skills/backend-quality/references/findings-format.md`. Each finding includes:
+- Dimension (DIM-5 or DIM-1)
+- Severity (HIGH, MEDIUM, LOW)
+- Location (file, line range)
+- Description and recommended action
+
+See also `@skills/distill/references/simplification-guide.md` for guidance on when to simplify vs remove.
+
+## Error Handling
+
+- **Empty scope:** If no files match the target scope, output an informative message explaining that no files were found and suggesting the user verify the path or scope parameters.
+- **No findings:** If analysis completes with zero findings, report a clean result rather than failing silently.

package/skills/distill/references/dead-code-patterns.md

@@ -0,0 +1,152 @@
+# Dead Code Patterns
+
+Reference guide for identifying, classifying, and triaging dead code in backend systems.
+
+## Dead Code Categories
+
+### 1. Unreachable Code
+
+Code that can never execute because control flow prevents reaching it.
+
+**Examples:**
+- Statements after unconditional `return`, `throw`, `break`, or `continue`
+- Branches guarded by conditions that are always false (e.g., `if (false)`, constant expressions)
+- `catch` blocks for exceptions that are never thrown by the `try` body
+- `switch` cases for enum values that no longer exist
+
+**Detection heuristics:**
+- Static analysis tools (TypeScript `--noUnusedLocals`, ESLint `no-unreachable`)
+- Grep for code after `return`/`throw` at the same indentation level
+- Analyze control flow graphs for unreachable nodes
+- Look for `if` conditions comparing against removed enum values or deleted constants
+
+### 2. Unused Exports
+
+Symbols that are exported from a module but never imported by any other module.
+
+**Examples:**
+- Functions exported from a utility module that no consumer calls
+- Types/interfaces exported but never referenced externally
+- Re-exports from barrel files (`index.ts`) where the re-exported symbol has no importers
+- Constants exported "just in case" during initial development
+
+**Detection heuristics:**
+- Grep for the export name across all importing files; zero hits means unused
+- Use `ts-prune`, `knip`, or similar tools to detect unused exports
+- Analyze barrel file re-exports: if the barrel is imported but only a subset of its exports are used, the rest are dead
+- Check test files separately — an export used only in tests may still be dead from a production perspective
+
+### 3. Commented-Out Code
+
+Code that has been commented out rather than deleted. Version control exists for history.
+
+**Examples:**
+- Block comments containing syntactically valid code
+- Lines prefixed with `//` that contain function calls, variable assignments, or imports
+- `/* ... */` blocks wrapping entire functions or class methods
+- TODO comments referencing code that should be "re-enabled" but never was
+
+**Detection heuristics:**
+- Grep for multi-line comments containing keywords like `function`, `const`, `import`, `export`, `class`, `return`
+- Look for `// ` followed by valid statement syntax (assignments, function calls)
+- Identify comments with version control references ("removed in v2", "old implementation")
+- Check git blame — if commented-out code has been that way for more than 2 sprints, it is dead
+
+### 4. Feature-Flagged-Off Code
+
+Code behind feature flags that have been permanently disabled or the flag has shipped long ago.
+
+**Examples:**
+- `if (featureFlags.enableNewParser)` where the flag has been `false` in all environments for months
+- A/B test branches where the experiment concluded and only one path is active
+- Migration code behind a flag that completed its rollout
+- Fallback paths for flags that have been `true` in production for multiple releases
+
+**Detection heuristics:**
+- Cross-reference feature flag names with the flag configuration store
+- Analyze flag usage: if a flag is always `true` or always `false` across all environments, the guarded code (or its inverse) is dead
+- Check flag creation dates — flags older than 90 days without recent changes are candidates
+- Look for TODO comments referencing flag cleanup
+
+## False Positive Guidance
+
+Not all apparently unused code is dead. Be cautious with:
+
+- **Intentional stubs:** Interface methods with empty bodies that exist to satisfy a contract, or template methods meant for subclass override
+- **Forward declarations:** Types or constants declared for planned but not-yet-implemented features (check the roadmap/backlog before flagging)
+- **Public API surface:** Libraries and packages intentionally export symbols for external consumers; check if the module is consumed outside the repository
+- **Plugin entry points:** Functions registered via reflection, dependency injection, or naming convention (e.g., `handle_*`, `on_*`) that are invoked dynamically
+- **Test helpers and fixtures:** Utility functions in test support files that may be imported conditionally or by test files not in the current scope
+- **Event handlers and callbacks:** Functions registered as listeners that are invoked indirectly through event dispatch
+
+**Verification steps before reporting:**
+1. Search the entire repository, not just the immediate module
+2. Check for dynamic invocation patterns (reflection, `eval`, dynamic imports)
+3. Look for references in configuration files, scripts, and documentation
+4. Verify whether the module is published as a package with external consumers
+
+## Severity Guide
+
+### HIGH Severity — Misleading Dead Code
+
+Dead code that actively misleads developers or creates risk:
+
+- Commented-out code that appears to be an alternative implementation, confusing future readers about which path is correct
+- Unreachable error handling that gives false confidence about fault tolerance
+- Unused exports that appear in IDE autocomplete, leading developers to use dead APIs
+- Feature-flagged code where the flag check masks a bug in the "live" path
+
+### MEDIUM Severity — Noise
+
+Dead code that adds cognitive load without active harm:
+
+- Unused utility functions that clutter the module
+- Old commented-out code that has been superseded by a different approach
+- Barrel file re-exports of symbols no one imports
+- Test helpers that are no longer called by any test
+
+### LOW Severity — Minor
+
+Dead code with minimal impact:
+
+- Single unused constants or type aliases
+- Commented-out log/debug statements
+- Unused function parameters (often enforced by interface contracts)
+- Empty catch blocks that were once meaningful but the try body changed
+
+## Examples
+
+### HIGH: Misleading unreachable error handler
+
+```typescript
+async function processOrder(order: Order): Promise<Result> {
+  const validated = validateOrder(order);
+  return submitOrder(validated);
+
+  // This catch-all never executes — gives false sense of error handling
+  try {
+    return submitOrder(validated);
+  } catch (error) {
+    await notifyOps(error);
+    return { status: 'failed', error };
+  }
+}
+```
+
+### MEDIUM: Unused export cluttering module
+
+```typescript
+// utils.ts
+export function formatDate(d: Date): string { /* ... */ }
+export function parseDate(s: string): Date { /* ... */ }
+export function dateToEpoch(d: Date): number { /* ... */ } // zero importers
+```
+
+### LOW: Commented-out debug logging
+
+```typescript
+function handleRequest(req: Request) {
+  // console.log('incoming request:', req.headers);
+  return processRequest(req);
+}
+```

package/skills/distill/references/simplification-guide.md

@@ -0,0 +1,128 @@
+# Simplification Guide
+
+Reference guide for reducing code complexity, identifying vestigial patterns, and deciding when to simplify versus when to remove entirely.
+
+## Complexity Reduction Patterns
+
+### When to Inline vs Extract
+
+**Inline when:**
+- A function is called exactly once and its name does not add clarity beyond reading the body
+- A wrapper function merely delegates to another function without transformation
+- An abstraction layer adds indirection but no behavioral difference (pass-through adapters)
+- The extraction was premature — the "reusable" function is only used in one place
+
+**Extract when:**
+- The same logic appears in three or more locations (see "three uses" rule below)
+- A block of code has a clear name that communicates intent better than the implementation details
+- Testing the logic in isolation would significantly improve test coverage or clarity
+- The extracted function represents a domain concept that should be named
+
+**Decision heuristic:** If removing the function name forces the reader to re-derive the intent from the implementation, keep the extraction. If the name is just a restatement of the single line it wraps, inline it.
+
+### When Abstraction Helps vs Hurts
+
+**Abstraction helps when:**
+- Multiple concrete implementations exist and the abstraction captures their shared contract
+- The abstraction enables meaningful testability (swapping real for fake implementations)
+- Domain boundaries are clarified by the interface
+
+**Abstraction hurts when:**
+- Only one implementation exists and no second is planned or plausible
+- The abstraction mirrors the implementation 1:1 (an interface with the same shape as the single class)
+- Navigating through the abstraction layer requires more cognitive effort than understanding the concrete code
+- "Dependency injection" is really just passing a single concrete instance through extra layers
+
+### Reducing Conditional Complexity
+
+- **Collapse nested conditionals:** Replace `if (a) { if (b) { ... } }` with `if (a && b) { ... }` when the nesting adds no clarity
+- **Use early returns:** Convert deep nesting into guard clauses that return/throw early
+- **Replace flag variables:** When a boolean flag is set and then checked once, inline the condition
+- **Simplify boolean expressions:** `if (x === true)` becomes `if (x)`; `if (!x === false)` becomes `if (x)`
+
+## Vestigial Pattern Identification
+
+### Code Archaeology Approach
+
+Vestigial patterns are evolutionary leftovers — code structures that made sense in a previous design but persist after the design changed. To identify them:
+
+1. **Look for patterns that reference removed features:** Search for imports of deleted modules, references to renamed types, or configuration keys for features that no longer exist
+2. **Identify partial migrations:** When a codebase migrated from pattern A to pattern B, look for leftover pattern A code that was never converted
+3. **Check adapter layers:** If an adapter wraps a dependency that was replaced, and the adapter's interface matches the new dependency's interface directly, the adapter is vestigial
+4. **Examine defensive code:** Guards against conditions that were possible in a previous version but are now structurally impossible (e.g., null checks after a field became required)
+
+### Common Vestigial Pattern Types
+
+- **Dead adapters:** Wrapper classes that were introduced to bridge between two APIs, but one API was since removed or the wrapper now delegates directly
+- **Orphaned configuration:** Config keys, environment variables, or feature flags that no active code reads
+- **Compatibility shims:** Polyfills or compatibility layers for platform versions no longer supported
+- **Migration scaffolding:** Temporary code introduced to migrate data or APIs that was never removed after migration completed
+- **Defensive checks for impossible states:** Null checks, type guards, or fallback values for conditions that the current type system or architecture prevents
+
+## Wiring Simplification
+
+### From Manual Configure/Register to Simpler Patterns
+
+**Identify over-engineered wiring when:**
+- A registration function manually lists every dependency and wires them together, but the dependency graph is simple and linear
+- A factory creates objects by resolving dependencies one-by-one when direct construction with `new` would suffice
+- A configuration object has dozens of keys, most of which are always set to the same default value
+- A "plugin system" exists but there is only one plugin and no mechanism for external plugins
+
+**Simplification strategies:**
+- Replace manual DI containers with direct construction when there are fewer than 3 dependencies
+- Replace factory functions with constructors when the factory adds no logic beyond `new`
+- Replace configuration objects with sensible defaults and optional overrides
+- Replace event bus / pub-sub patterns with direct function calls when there is only one subscriber
+
+### Recognizing Unnecessary Indirection
+
+Indirection that does not serve a purpose:
+
+- **Pass-through functions:** `function doThing(x) { return actuallyDoThing(x); }` with no additional logic
+- **Single-method interfaces with one implementation:** The interface and class are isomorphic
+- **Manager/controller classes that only delegate:** A `FooManager` that holds a `Foo` and forwards all calls
+- **Middleware chains with one middleware:** The chain infrastructure adds complexity but only one handler exists
+
+## The "Three Uses" Rule
+
+Do not abstract until you have seen the pattern three times:
+
+1. **First occurrence:** Write the code inline. Do not extract.
+2. **Second occurrence:** Note the duplication but tolerate it. Copy-paste is acceptable.
+3. **Third occurrence:** Now extract. You have enough examples to see the true shape of the abstraction.
+
+**Why three?** Two occurrences often look similar by coincidence. The third occurrence confirms the pattern is real and reveals which parts vary (parameters) and which are fixed (the abstraction body). Abstracting after two uses risks creating an abstraction shaped for the wrong generalization.
+
+**Exception:** If the duplicated code is long (>20 lines) or contains complex logic with known bug risk, extract after two uses. The cost of a slightly wrong abstraction is lower than the cost of a bug fix applied to only one copy.
+
+## Simplification vs Deletion
+
+### When to Simplify
+
+Simplify (reduce complexity without removing) when:
+- The code serves a current purpose but is more complicated than necessary
+- The functionality is needed but the implementation has accumulated accidental complexity
+- A refactoring pass changed the surroundings but left this code with now-unnecessary guards or abstractions
+- The code works but is hard to understand — simplification improves readability without changing behavior
+
+### When to Remove Entirely
+
+Remove (delete the code) when:
+- The code is unreachable or provably never executed
+- The feature the code supports has been decommissioned
+- The code is commented out and has been for more than one release cycle
+- A replacement implementation exists and the old one is no longer used
+- The code is a workaround for a bug that has been fixed at its source
+
+### Decision Framework
+
+Ask these questions in order:
+
+1. **Is this code reachable?** If no, delete it.
+2. **Does this code serve an active feature?** If no, delete it.
+3. **Is this code more complex than it needs to be?** If yes, simplify it.
+4. **Is there a simpler way to achieve the same result?** If yes, simplify to that.
+5. **Would a reader understand this code without extra context?** If no, simplify for clarity.
+
+When in doubt, prefer deletion over simplification. Dead code that is simplified is still dead code. Version control preserves history — you can always retrieve deleted code if needed.

package/skills/harden/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: harden
+description: "Strengthen backend resilience by finding silent catches, missing error context, resource leaks, and operational fragility. Use when hardening error handling or preparing for production deployment. Triggers: 'harden code', 'check error handling', 'resilience review', or /axiom:harden. Do NOT use for dead code — use axiom:distill instead."
+user-invokable: true
+metadata:
+  author: lvlup-sw
+  version: 0.1.0
+  category: assessment
+  dimensions:
+    - observability
+    - resilience
+---
+
+# Harden Skill
+
+## Overview
+
+Resilience-focused assessment skill covering DIM-2 (Observability) and DIM-7 (Resilience) from the backend quality dimension taxonomy. Finds error handling gaps, silent catches, resource leaks, and operational fragility that could cause cascading failures under stress.
+
+This skill combines deterministic pattern detection (via `axiom:scan`) with qualitative judgment to assess how well code handles failure, communicates errors, and manages resources.
+
+## Triggers
+
+### Positive Triggers
+
+Activate this skill when:
+- User says "harden code", "harden this", or "resilience review"
+- User says "check error handling" or "audit error handling"
+- User runs `/axiom:harden`
+- Preparing code for production deployment
+- After an incident exposed error handling gaps
+
+### Negative Triggers
+
+Do NOT use this skill when:
+- Looking for dead code or vestigial patterns — use `axiom:distill` instead
+- Reviewing architecture or SOLID compliance — use `axiom:critique` instead
+- Checking test quality or mock fidelity — use `axiom:verify` instead
+- Running a comprehensive audit — use `axiom:audit` instead
+
+## Process
+
+### Step 1: Load Dimension Definitions
+
+Load the relevant dimensions from the shared taxonomy:
+
+- `@skills/backend-quality/references/dimensions.md` — read the DIM-2 (Observability) and DIM-7 (Resilience) sections for invariants, signals, and severity guides.
+
+### Step 2: Run Deterministic Checks
+
+Invoke `axiom:scan` for mechanical pattern detection on the Observability and Resilience dimensions:
+
+- DIM-2 checks: empty catch blocks, log-only catches, swallowed promise rejections
+- DIM-7 checks: unbounded collections, missing timeouts, unbounded retry loops
+
+Collect all deterministic findings. These form the baseline that qualitative assessment builds upon.
+
+### Step 3: Qualitative Assessment
+
+Layer judgment-based analysis on top of the deterministic results. For each area, review the flagged code regions and nearby context:
+
+#### 3a. Empty Catch Audit
+
+Classify every catch block in scope into one of four categories:
+
+| Category | Definition | Action |
+|----------|-----------|--------|
+| **Silent** | Empty catch body, no logging, no recovery | HIGH — must add handling or documented rationale |
+| **Log-only** | Logs the error but takes no recovery action | MEDIUM — evaluate whether recovery is needed |
+| **Recovery** | Catches, logs, and takes corrective action | OK — verify recovery is correct |
+| **Intentional** | Documented rationale for swallowing (e.g., `// Intentional: probe-only, failure is expected`) | OK — verify comment is accurate |
+
+Consult `@skills/harden/references/error-patterns.md` for the full silent catch taxonomy and classification guidance.
+
+#### 3b. Error Context Propagation
+
+For each error path, evaluate whether errors include sufficient context:
+
+- **What** failed? (operation name, inputs, resource identifier)
+- **Why** did it fail? (root cause, constraint violation)
+- **How to fix?** (retry guidance, configuration check, escalation path)
+- **Cause chain?** (is the original error preserved via `{ cause: e }`?)
+
+Generic error messages like "Something went wrong" or "Operation failed" are a MEDIUM finding.
+
+#### 3c. Fallback Behavior Analysis
+
+Identify all fallback paths and evaluate visibility:
+
+- Are fallbacks logged or metriced so operators know degraded mode is active?
+- Do fallbacks silently switch behavior modes without signaling?
+- Is best-effort behavior clearly documented and visible in monitoring?
+
+Silent degradation — where the system quietly switches to a less capable mode — is a HIGH finding.
+
+#### 3d. Resource Lifecycle
+
+Verify open/close symmetry and acquire/release patterns:
+
+- File handles opened in try blocks — are they closed in finally?
+- Database connections — are they released on both success and error paths?
+- Event listeners — are they removed when no longer needed?
+- Streams — are they properly ended/destroyed on error?
+
+Consult `@skills/harden/references/resilience-checklist.md` for the full resource management checklist.
+
+#### 3e. Timeout and Retry Evaluation
+
+For every external call (HTTP, database, file system, IPC):
+
+- Is there a timeout? (missing timeout = MEDIUM)
+- Is the timeout reasonable for the operation? (60s for a health check = LOW)
+- Are retries bounded? (unbounded retry = HIGH)
+- Is there backoff? (no backoff = MEDIUM)
+
+#### 3f. Cache Bound Verification
+
+For every in-memory collection that persists beyond a single request:
+
+- Is there a maximum size? (unbounded Map/Set/Array = HIGH)
+- Is there an eviction policy? (LRU, TTL, or manual clear)
+- Do collections grow monotonically without cleanup?
+
+### Step 4: Output Findings
+
+Format all findings per the standard finding schema: `@skills/backend-quality/references/findings-format.md`
+
+Group findings by severity (HIGH, MEDIUM, LOW). Each finding must include:
+- Dimension (DIM-2 or DIM-7)
+- Evidence (file:line references)
+- Explanation (what is wrong and why it matters)
+- Suggestion (how to fix, when actionable)
+- Whether it was found deterministically or qualitatively
+
+## Error Handling
+
+### Empty Scope
+
+If the provided scope is empty or contains no files to analyze, return an informative message:
+
+> "No files found in the provided scope. Specify a file path, directory, or glob pattern. Example: `/axiom:harden src/` or `/axiom:harden src/events/`."
+
+Do not return an empty finding set without explanation.
+
+## Anti-Patterns
+
+| Don't | Do Instead |
+|-------|------------|
+| Flag every catch block as a problem | Classify — many catches are correct and intentional |
+| Ignore log-only catches | Evaluate whether the error needs recovery, not just logging |
+| Treat all fallbacks as bad | Evaluate whether degradation is visible and documented |
+| Skip resource lifecycle in test code | Test helpers leak resources too |
+| Assume timeouts are always present | Verify each external call individually |
+| Report cache concerns for request-scoped collections | Only flag persistent/growing collections |
+
+## References
+
+- `@skills/backend-quality/references/dimensions.md` — DIM-2 and DIM-7 definitions
+- `@skills/backend-quality/references/findings-format.md` — finding output schema
+- `@skills/harden/references/error-patterns.md` — silent catch taxonomy and error context checklist
+- `@skills/harden/references/resilience-checklist.md` — resource management, timeouts, retries, concurrency checklist