@esoteric-logic/praxis-harness 2.10.0 → 2.11.0

package/base/CLAUDE.md

@@ -142,27 +142,42 @@ Kit manifests live in `~/.claude/kits/<name>/KIT.md`.
 
 ## Rules Registry — Load on Demand Only
 
-### Universal — always active (9 rules)
+### Universal — always active (12 rules)
+
+Quality is a generation-time constraint, not a post-hoc review. The rules below
+are the lens you write through — they shape every line of code produced.
+
 | File | Purpose |
 |------|---------|
 | `~/.claude/rules/profile.md` | Who the user is, identities, working style |
 | `~/.claude/rules/execution-loop.md` | SPEC/PLAN/VALIDATE loop enforcement |
 | `~/.claude/rules/coding.md` | Context7 mandate, tool preferences, quality architecture reference |
-| `~/.claude/rules/code-quality.md` | Layer 2: Active constraints — hard limits during generation |
+| `~/.claude/rules/code-quality.md` | Active constraints — hard limits during generation (30 lines, 3 nesting, 4 params) |
+| `~/.claude/rules/code-excellence.md` | Core principles — simplicity, correctness, naming, error design, dependency hygiene |
+| `~/.claude/rules/engineering-judgment.md` | Meta-reasoning — Five Questions, YAGNI, Rule of Three, reversibility test |
+| `~/.claude/rules/self-verify.md` | Self-verification — 24-check protocol before every commit |
 | `~/.claude/rules/git-workflow.md` | Commits, branches, identity verification, pre-commit checks |
 | `~/.claude/rules/vault.md` | Second brain integration — vault backend, file purposes |
 | `~/.claude/rules/context-management.md` | Context anti-rot, phase scoping, context reset protocol |
 | `~/.claude/rules/memory-boundary.md` | Auto-memory boundary, MEMORY.md cap, dream integration |
 | `~/.claude/rules/security-posture.md` | Sandbox model, credential protection, protected paths |
 
-### Skills — loaded at session start
-| File | Purpose |
-|------|---------|
-| `~/.claude/skills/code-excellence.md` | Layer 1: Principles — shapes reasoning about code |
-| `~/.claude/skills/engineering-judgment.md` | Layer 1: Meta-reasoning — principal engineer decision framework |
-| `~/.claude/skills/self-verify.md` | Layer 3: Self-verification protocol — proves correctness before commit |
-
 ### Scoped — load only when paths match
+
+#### Language quality (generation-time constraints per language)
+| File | Loads when |
+|------|------------|
+| `~/.claude/rules/python-quality.md` | `**/*.py` |
+| `~/.claude/rules/typescript-quality.md` | `**/*.ts`, `**/*.tsx` |
+| `~/.claude/rules/shell-quality.md` | `**/*.sh` |
+| `~/.claude/rules/go-quality.md` | `**/*.go` |
+| `~/.claude/rules/rust-quality.md` | `**/*.rs` |
+| `~/.claude/rules/java-quality.md` | `**/*.java` |
+| `~/.claude/rules/css-quality.md` | `**/*.css`, `**/*.scss`, `**/*.less` |
+| `~/.claude/rules/sql-quality.md` | `**/*.sql` |
+| `~/.claude/rules/api-quality.md` | `**/routes/**`, `**/api/**`, `**/controllers/**`, `**/handlers/**` |
+
+#### Infrastructure and tooling
 | File | Loads when |
 |------|------------|
 | `~/.claude/rules/azure.md` | `**/*.tf`, `**/*.bicep`, `**/*.azcli` |

package/base/rules/api-quality.md

@@ -0,0 +1,25 @@
+# API Quality — Generation Constraints
+# Scope: **/routes/**, **/api/**, **/controllers/**, **/handlers/**
+# Active during code generation, not post-hoc review
+
+## Invariants — BLOCK on violation
+
+- Validate all input before touching business logic — type, range, format, length.
+- Auth and permission checks execute before any data access — never after.
+- Every endpoint has an explicit error response shape — no raw stack traces to callers.
+- No raw database objects in responses — always project to a response type or DTO.
+- Parameterized queries only — never concatenate user input into SQL or query strings.
+- Rate limiting or pagination on any endpoint that returns unbounded collections.
+
+## Conventions — WARN on violation
+
+- Consistent error response format across all endpoints (status, code, message, details).
+- Idempotency keys on state-changing operations that clients may retry.
+- Request correlation IDs for tracing — propagate through the call chain.
+- CORS, CSRF, and security headers configured explicitly — not inherited from defaults.
+- Separate validation errors (400) from auth errors (401/403) from not-found (404) from server errors (500).
+- Log request context (method, path, status, duration) — never log request bodies containing PII.
+- API versioning strategy declared before first endpoint is written.
+
+## Removal Condition
+Remove when an API-specific linter rule engine replaces generation-time constraints.

package/base/{skills → rules}/code-excellence.md

@@ -1,7 +1,7 @@
 # Code Excellence — Core Principles
 
-Load this skill at the start of every session. These principles shape how you reason about
-code before writing a single character. They are not a checklist — they are a worldview.
+These principles shape how you reason about code before writing a single character.
+They are not a checklist — they are a worldview. They are always active.
 
 ## The Prime Directive
 Write code that the next engineer will thank you for.
@@ -21,6 +21,13 @@ Before adding any abstraction, answer all three:
 - Would a new engineer understand the code FASTER with this abstraction than without it?
 If any answer is no — do not add it. Inline the logic.
 
+Over-engineering red flags — stop and simplify if you see yourself writing:
+- An interface/factory/strategy with exactly one implementation
+- A wrapper function whose entire body is a single delegating call
+- Unused type parameters, config options no caller sets, plugin systems with one plugin
+- Observer/EventEmitter with 2 listeners, Singleton for a module variable, Builder for 3 fields
+- A function with boolean flags that switch behavior — write two functions instead
+
 ## On Correctness
 Correctness means the code does exactly what its name promises. Not more. Not less.
 A function named `getUserById` returns a user by ID.

package/base/rules/css-quality.md

@@ -0,0 +1,25 @@
+# CSS Quality — Generation Constraints
+# Scope: **/*.css, **/*.scss, **/*.less
+# Active during code generation, not post-hoc review
+
+## Invariants — BLOCK on violation
+
+- No `!important` — fix the specificity problem instead.
+- No hardcoded color values — use design tokens or CSS custom properties.
+- No `px` for font sizes — use `rem` for scalability and accessibility.
+- No `z-index` without a comment and reference to the project's z-index scale.
+- No layout via `float` — use flexbox or grid.
+
+## Conventions — WARN on violation
+
+- CSS custom properties (`--var`) for all recurring values: spacing, colors, radii, shadows.
+- Mobile-first media queries (`min-width`) — never desktop-first (`max-width`).
+- Logical properties (`margin-inline`, `padding-block`) over physical (`margin-left`, `padding-top`).
+- `gap` for spacing between flex/grid items — not margin hacks on children.
+- Prefer `clamp()` for fluid typography and spacing over media query breakpoints.
+- `:focus-visible` over `:focus` for keyboard-only focus indicators.
+- `prefers-reduced-motion` media query wrapping any animation or transition.
+- BEM or utility-class convention — never bare tag selectors outside resets.
+
+## Removal Condition
+Remove when a CSS-specific linter rule engine replaces generation-time constraints.

package/base/rules/go-quality.md

@@ -0,0 +1,25 @@
+# Go Quality — Generation Constraints
+# Scope: **/*.go
+# Active during code generation, not post-hoc review
+
+## Invariants — BLOCK on violation
+
+- Every error return checked immediately — no `_` for error values.
+- No `panic` in library code — return errors. Reserve `panic` for truly unrecoverable states in `main`.
+- No `interface{}` or `any` without a comment explaining why a concrete type won't work.
+- Context (`context.Context`) as the first parameter of any function that does I/O or may be cancelled.
+- No goroutine without a clear ownership and shutdown path — leaked goroutines are memory leaks.
+
+## Conventions — WARN on violation
+
+- Table-driven tests for any function with more than 2 test cases.
+- `errors.Is` / `errors.As` for error comparison — never string matching on `err.Error()`.
+- `fmt.Errorf("context: %w", err)` to wrap errors with context — never lose the original.
+- Named return values only when they clarify the function signature — not as a substitute for declarations.
+- `sync.Mutex` fields placed immediately above the fields they protect, with a comment.
+- `defer` for cleanup — but never defer in a loop body.
+- Prefer `io.Reader` / `io.Writer` interfaces over concrete types in function signatures.
+- Struct field tags (`json`, `db`) on every field of a struct used for serialization.
+
+## Removal Condition
+Remove when golangci-lint rules replace generation-time constraints entirely.

package/base/rules/java-quality.md

@@ -0,0 +1,25 @@
+# Java Quality — Generation Constraints
+# Scope: **/*.java
+# Active during code generation, not post-hoc review
+
+## Invariants — BLOCK on violation
+
+- No raw types — always use parameterized generics (`List<String>`, not `List`).
+- No empty catch blocks — handle, re-throw with context, or log with severity.
+- No `null` returns from public methods without `@Nullable` annotation and documented behavior.
+- All public API methods have Javadoc with `@param`, `@return`, and `@throws`.
+- Resources (streams, connections) use try-with-resources — never manual `finally` close.
+
+## Conventions — WARN on violation
+
+- Records over classes for immutable data carriers (Java 16+).
+- `Optional` return type over nullable for methods that may not produce a result.
+- `var` for local variables only when the type is obvious from the right-hand side.
+- `sealed` interfaces/classes for closed hierarchies with pattern matching.
+- Builder pattern only for objects with 5+ fields — constructors or factories for fewer.
+- Prefer `List.of()`, `Map.of()` for immutable collections — not `Collections.unmodifiable*`.
+- `@Override` on every overriding method — let the compiler catch signature drift.
+- Stream operations only when they improve readability — explicit loops for complex logic.
+
+## Removal Condition
+Remove when a Java-specific linter rule engine replaces generation-time constraints.

package/base/rules/python-quality.md

@@ -0,0 +1,25 @@
+# Python Quality — Generation Constraints
+# Scope: **/*.py
+# Active during code generation, not post-hoc review
+
+## Invariants — BLOCK on violation
+
+- Type hints on every function signature — parameters and return type. No exceptions.
+- No bare `except:` — always catch a specific exception type.
+- No mutable default arguments (`def f(x=[])`) — use `None` and assign inside.
+- No `import *` — explicit imports only.
+- No `type: ignore` without an inline comment explaining why it's safe.
+- f-strings only for string formatting — never `%` or `.format()`.
+
+## Conventions — WARN on violation
+
+- `dataclass` or `TypedDict` over raw dicts for structured data with 3+ fields.
+- `pathlib.Path` over `os.path` for path manipulation.
+- Context managers (`with`) for all resource handling (files, connections, locks).
+- Comprehensions only when they fit one line — explicit loops otherwise.
+- `enum.Enum` or `Literal` for fixed sets of values — never raw strings.
+- `logging` module over `print()` in anything that isn't a CLI script.
+- Async functions: every `await` in a try/except or the caller handles the exception.
+
+## Removal Condition
+Remove when a Python-specific linter rule engine replaces generation-time constraints.

package/base/rules/rust-quality.md

@@ -0,0 +1,25 @@
+# Rust Quality — Generation Constraints
+# Scope: **/*.rs
+# Active during code generation, not post-hoc review
+
+## Invariants — BLOCK on violation
+
+- No `.unwrap()` or `.expect()` in library code — propagate errors with `?`.
+- No `unsafe` blocks without an inline `// SAFETY:` comment explaining the invariant.
+- No `.clone()` to silence the borrow checker — restructure ownership instead.
+- All public items have doc comments (`///`) — the API is the documentation.
+- Error types implement `std::error::Error` and provide context via `Display`.
+
+## Conventions — WARN on violation
+
+- `thiserror` for library error types, `anyhow` for application error types.
+- Prefer `&str` over `String` in function parameters — take ownership only when needed.
+- Prefer iterators and combinators over manual loops where they improve readability.
+- `#[must_use]` on functions whose return value should not be silently ignored.
+- Derive `Debug` on all public structs and enums.
+- `#[non_exhaustive]` on public enums that may gain variants.
+- Prefer `impl Trait` in argument position over generic type parameters when the type is used once.
+- Integration tests in `tests/` directory — unit tests in the same file with `#[cfg(test)]`.
+
+## Removal Condition
+Remove when clippy rules replace generation-time constraints entirely.

package/base/rules/shell-quality.md

@@ -0,0 +1,26 @@
+# Shell Quality — Generation Constraints
+# Scope: **/*.sh
+# Active during code generation, not post-hoc review
+
+## Invariants — BLOCK on violation
+
+- Every script starts with `#!/usr/bin/env bash` and `set -euo pipefail`.
+- All variable expansions quoted: `"$VAR"`, never bare `$VAR`.
+- No `eval` — ever. Use arrays for dynamic command construction.
+- `[[ ]]` for conditionals — never `[ ]` (no word splitting, no glob expansion).
+- No inline credentials or tokens — use environment variables.
+- Exit codes: 0 for success, 1 for general failure, 2 for hard block (Praxis convention).
+
+## Conventions — WARN on violation
+
+- Heredocs or `printf` for multi-line output — never multi-line `echo`.
+- `local` keyword for all variables inside functions.
+- `command -v` for tool detection — never `which`.
+- `mktemp` for temporary files — never hardcoded `/tmp/myfile`.
+- Trap `ERR` or use explicit error handling — don't rely solely on `set -e`.
+- Use `jq` with `--arg` / `--argjson` for JSON — never interpolate variables into JSON strings.
+- Prefer `$(...)` over backticks for command substitution.
+- Group related options into functions — no scripts longer than 100 lines without functions.
+
+## Removal Condition
+Remove when a shell-specific linter rule engine replaces generation-time constraints.

package/base/rules/sql-quality.md

@@ -0,0 +1,25 @@
+# SQL Quality — Generation Constraints
+# Scope: **/*.sql
+# Active during code generation, not post-hoc review
+
+## Invariants — BLOCK on violation
+
+- Parameterized queries only — never concatenate user input into SQL strings.
+- Every `SELECT` on user-generated data has a `LIMIT` — no unbounded result sets.
+- Every migration is reversible — include both `UP` and `DOWN` in every migration file.
+- No `SELECT *` — explicitly list columns. Schema changes should not silently alter query results.
+- No `DROP TABLE` or `DROP COLUMN` without a preceding data migration or explicit confirmation.
+
+## Conventions — WARN on violation
+
+- Uppercase SQL keywords (`SELECT`, `FROM`, `WHERE`) — lowercase for identifiers.
+- `snake_case` for all table and column names.
+- Foreign keys have explicit `ON DELETE` and `ON UPDATE` behavior — never rely on defaults.
+- Indexes on all columns used in `WHERE`, `JOIN`, and `ORDER BY` on tables >1000 rows.
+- `NOT NULL` by default — nullable columns require a comment explaining why null is valid.
+- `TIMESTAMP WITH TIME ZONE` for all temporal columns — never naive timestamps.
+- `CHECK` constraints for domain validation at the database level — don't rely solely on application code.
+- CTEs (`WITH`) for readability over nested subqueries beyond 2 levels.
+
+## Removal Condition
+Remove when a SQL-specific linter rule engine replaces generation-time constraints.

package/base/rules/typescript-quality.md

@@ -0,0 +1,26 @@
+# TypeScript Quality — Generation Constraints
+# Scope: **/*.ts, **/*.tsx
+# Active during code generation, not post-hoc review
+
+## Invariants — BLOCK on violation
+
+- No `any` type — ever. Use `unknown` and narrow, or define the actual type.
+- Explicit return types on all exported functions.
+- No non-null assertion (`!`) without an inline comment explaining why it's safe.
+- No `@ts-ignore` or `@ts-expect-error` without an inline comment explaining why.
+- No `as` type assertions unless narrowing from `unknown` — prefer type guards.
+- Strict null checks: handle `null` and `undefined` explicitly, never assume presence.
+
+## Conventions — WARN on violation
+
+- `const` by default — `let` only when reassignment is necessary. Never `var`.
+- Discriminated unions over optional fields for modeling distinct states.
+- `readonly` on properties that should not be mutated after construction.
+- `interface` for object shapes, `type` for unions, intersections, and computed types.
+- Named exports over default exports — better refactoring support and tree-shaking.
+- `Promise.all` for independent async operations — never sequential awaits for parallel work.
+- Error boundaries in React components that render user-generated or external data.
+- `satisfies` operator over `as` for type validation without widening.
+
+## Removal Condition
+Remove when a TypeScript-specific linter rule engine replaces generation-time constraints.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@esoteric-logic/praxis-harness",
-  "version": "2.10.0",
+  "version": "2.11.0",
   "description": "Layered Claude Code harness — workflow discipline, AI-Kits, persistent vault integration",
   "bin": {
     "praxis-harness": "./bin/praxis.js"