@esoteric-logic/praxis-harness 2.10.0 → 2.12.0

package/base/CLAUDE.md

@@ -125,6 +125,9 @@ Missing servers are non-blocking — features degrade gracefully.
 - Commit with wrong git identity
 - Write a file with unreplaced {placeholders}
 - Use vault search when Obsidian is not running (obsidian backend requires Obsidian open)
+- Mix refactoring and feature changes in one commit — commit refactor separately
+- Copy-paste 3+ lines instead of extracting a shared function
+- Use `console.log`/`fmt.Println`/`print()` for production logging — use the structured logger
 
 ## AI-Kit Registry
 Kits activate via `/px-kit:<n>` slash command. Kits are idempotent — double-activate is a no-op.
@@ -142,27 +145,44 @@ Kit manifests live in `~/.claude/kits/<name>/KIT.md`.
 
 ## Rules Registry — Load on Demand Only
 
-### Universal — always active (9 rules)
+### Universal — always active (14 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 |
+| `~/.claude/rules/writing-quality.md` | Prose constraints — sentence limits, fluff kill list, doc templates, voice rules |
+| `~/.claude/rules/refactor-triggers.md` | Pre-check protocol, commit refactor separately, QUALITY: comment convention |
 
 ### 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` |
@@ -173,11 +193,19 @@ Kit manifests live in `~/.claude/kits/<name>/KIT.md`.
 | `~/.claude/rules/live-docs-required.md` | Dependency manifests, files importing external packages |
 | `~/.claude/rules/desktop-protocol.md` | Claude Desktop ↔ Claude Code handoff sessions |
 
+#### Application observability
+
+| File | Loads when |
+|------|------------|
+| `~/.claude/rules/observable-code.md` | `**/services/**`, `**/handlers/**`, `**/workers/**`, `**/middleware/**`, `**/cmd/**` |
+
 ### Auto-invocable skills (replace former universal rules)
 | Skill | Triggers when |
 |-------|--------------|
 | `px-communication-standards` | Writing client-facing docs, proposals, status reports, commits, PRs |
 | `px-architecture-patterns` | Writing ADRs, specs, system design, risk docs, blocker reports |
+| `px-quality-gate` | Auto inside /px-verify (Step 1 item 5b) and before /px-ship — blocks on BLOCK findings |
+| `px-doc-lint` | Fast structural markdown check inside px-quality-gate for staged *.md files |
 
 ## Judgment & Research Commands
 

package/base/hooks/auto-format.sh

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 # PostToolUse hook — auto-formats files after edit.
 # Always exits 0 (advisory, never blocks).
-set -uo pipefail
+set -euo pipefail
 trap 'exit 0' ERR
 
 INPUT=$(cat)

package/base/hooks/dep-audit.sh

@@ -2,7 +2,7 @@
 # dep-audit.sh — PostToolUse:Write|Edit|MultiEdit hook
 # Runs dependency vulnerability checks when manifest files are modified.
 # Always exits 0 (advisory only — PostToolUse cannot hard-block).
-set -uo pipefail
+set -euo pipefail
 trap 'exit 0' ERR
 
 INPUT=$(cat)

package/base/hooks/file-guard.sh

@@ -6,7 +6,7 @@ set -euo pipefail
 INPUT=$(cat)
 FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // .tool_input.path // empty')
 
-if [ -z "$FILE_PATH" ]; then
+if [[ -z "$FILE_PATH" ]]; then
   exit 0
 fi
 
@@ -29,7 +29,7 @@ for pattern in "${PROTECTED_PATTERNS[@]}"; do
 done
 
 # Check project-level protected files from CLAUDE.md if it exists
-if [ -f "CLAUDE.md" ]; then
+if [[ -f "CLAUDE.md" ]]; then
   # Extract paths from ## Protected Files section
   IN_SECTION=false
   while IFS= read -r line; do
@@ -42,7 +42,7 @@ if [ -f "CLAUDE.md" ]; then
     fi
     if $IN_SECTION && echo "$line" | grep -qE "^- "; then
       PROTECTED=$(echo "$line" | sed 's/^- //' | sed 's/ *#.*//' | xargs)
-      if [ -n "$PROTECTED" ] && echo "$FILE_PATH" | grep -qE "$PROTECTED"; then
+      if [[ -n "$PROTECTED" ]] && echo "$FILE_PATH" | grep -qE "$PROTECTED"; then
         echo "BLOCKED: $FILE_PATH matches project-protected pattern '$PROTECTED'. Explain the intended change."
         exit 2
       fi

package/base/hooks/recursion-guard.sh

@@ -50,7 +50,13 @@ KEY="${KEY:0:300}"
 
 # ── Increment counter ──
 # Use a hash of the key for safe JSON field names
-KEY_HASH=$(echo -n "$KEY" | md5 2>/dev/null || echo -n "$KEY" | md5sum 2>/dev/null | cut -d' ' -f1 || echo "fallback")
+if command -v md5sum &>/dev/null; then
+  KEY_HASH=$(echo -n "$KEY" | md5sum | cut -d' ' -f1)
+elif command -v md5 &>/dev/null; then
+  KEY_HASH=$(echo -n "$KEY" | md5 -q)
+else
+  KEY_HASH="${KEY:0:32}"
+fi
 
 COUNT=$(jq -r --arg cat "$CATEGORY" --arg key "$KEY_HASH" \
   '.[$cat][$key] // 0' "$STATE_FILE" 2>/dev/null || echo "0")

package/base/hooks/session-data-collect.sh

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 # Stop hook — collects structured session data and stages it for the Stop prompt.
 # Always exits 0 (advisory, never blocks session end).
-set -uo pipefail
+set -euo pipefail
 trap 'exit 0' ERR
 
 CONFIG_FILE="$HOME/.claude/praxis.config.json"

package/base/hooks/vault-checkpoint.sh

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 # PreCompact hook — writes minimal checkpoint to vault before context compaction.
 # Always exits 0 (advisory, never blocks compaction).
-set -uo pipefail
+set -euo pipefail
 trap 'exit 0' ERR
 
 CONFIG_FILE="$HOME/.claude/praxis.config.json"
@@ -19,7 +19,7 @@ PLANS_DIR="$VAULT_PATH/plans"
 mkdir -p "$PLANS_DIR"
 
 DATE=$(date +%Y-%m-%d)
-TIMESTAMP=$(date +"%Y-%m-%d %H:%M:%S")
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
 CHECKPOINT_FILE="$PLANS_DIR/$DATE-compact-checkpoint.md"
 
 BRANCH=$(git --no-pager rev-parse --abbrev-ref HEAD 2>/dev/null || echo "unknown")
@@ -40,16 +40,16 @@ fi
 LINT_STATE="unknown"
 TEST_STATE="unknown"
 
-if [ -f "go.mod" ] && command -v golangci-lint &>/dev/null; then
+if [[ -f "go.mod" ]] && command -v golangci-lint &>/dev/null; then
   LINT_COUNT=$(golangci-lint run ./... 2>&1 | grep -c "^" || true)
-  if [ "$LINT_COUNT" -eq 0 ]; then
+  if [[ "$LINT_COUNT" -eq 0 ]]; then
     LINT_STATE="clean"
   else
     LINT_STATE="$LINT_COUNT findings"
   fi
 fi
 
-if [ -f "go.mod" ] && command -v go &>/dev/null; then
+if [[ -f "go.mod" ]] && command -v go &>/dev/null; then
   if go test ./... -short 2>&1 | grep -q "^ok"; then
     TEST_STATE="passing"
   else

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.
@@ -67,3 +74,25 @@ A comment that says `// increment counter` above `counter++` is noise.
 A comment that says `// retry three times because the upstream API returns 503 on cold start`
 is knowledge that cannot be inferred from the code alone.
 Delete the first kind. Write more of the second kind.
+
+---
+
+## Reference Codebases — What Excellence Looks Like
+
+When you need a reference for what excellent code looks like, use these:
+
+| Domain | Reference | What to study |
+| ------ | --------- | ------------- |
+| C / systems | SQLite source (`sqlite.org/src`) | Discipline: 590x test-to-source ratio, 100% branch coverage, zero external deps |
+| C / network | Redis `src/ae.c`, `src/dict.c` | Naming, readability, data structures that document themselves |
+| Go | Go standard library (`pkg.go.dev/std`) | Idiomatic naming, error design, interface sizing — one method where possible |
+| Rust | `rustc_errors` crate | Error message design: what failed, where, what to do next |
+| Error messages | Elm compiler output | Kindest, most actionable errors in any compiled language |
+| API design | Stripe API (`docs.stripe.com`) | Naming consistency, versioning discipline, error schema |
+| Documentation | Go stdlib `net/http` package docs | Every exported symbol explained by what it does for the caller |
+
+When uncertain if code is good enough: "Would this survive a review from the SQLite team?"
+If the answer is no — simplify first.
+
+The SQLite standard: every line has a reason. Every function has one job.
+Every error has a message a human can act on.

package/base/rules/coding.md

@@ -13,6 +13,22 @@
 - If Context7 is unavailable: state that docs could not be verified and flag the
   specific method/API as "unverified against current version."
 
+### Import-trigger protocol
+
+Any commit diff that adds a new `import`, `require`, `using`, or `use` statement for an
+external package must have a corresponding Context7 lookup in the same session.
+
+Language-specific patterns matched:
+
+- JavaScript/TypeScript: `import ... from`, `require(...)`
+- Python: `import ...`, `from ... import`
+- Go: `import "..."` or `import (...)`
+- Rust: `use ...::...`
+- Java/C#: `import ...`, `using ...`
+
+Every new external import requires a Context7 verification before the gate clears.
+Internal packages (same repo, same module) are excluded.
+
 ### Tool preferences
 - Use Read/Edit/Write tools instead of cat/sed/echo.
 - Use `rg` (ripgrep) for searching code, not grep.

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/observable-code.md

@@ -0,0 +1,87 @@
+# Observable Code — Instrumentation Constraints
+# Scope: **/services/**, **/handlers/**, **/workers/**, **/middleware/**, **/cmd/**
+# Active during code generation for service-layer code
+# Cross-reference: api-quality.md covers request-level logging and correlation IDs.
+#   This rule covers application-level observability: structured logging, metrics, traces.
+
+Code is not production-ready if it cannot be debugged without attaching a debugger.
+Observable code tells you what happened, when, and why — from logs, metrics, and traces alone.
+
+## Invariants — BLOCK on violation
+
+### Structured logging only
+- All log statements use structured format (key-value pairs, not string interpolation)
+- No `fmt.Println` / `console.log` / `print()` in production code paths — use the structured logger
+- Log at the point of failure, not at the catch site (log once, propagate)
+
+### Log levels are semantic
+- ERROR: something failed and a human needs to know immediately
+- WARN: something unexpected happened but the system recovered
+- INFO: a significant state transition (service started, job completed, user authenticated)
+- DEBUG: internal detail useful during development — must not appear in production by default
+
+### Structured log format — mandatory fields
+```json
+{
+  "timestamp": "ISO-8601 UTC",
+  "level": "error|warn|info|debug",
+  "service": "service-name",
+  "correlation_id": "request or trace identifier",
+  "message": "what happened — actionable, not generic",
+  "context": { "relevant_key": "relevant_value" }
+}
+```
+
+### What NOT to log
+- Passwords, tokens, secrets, full credit card numbers
+- Full request/response bodies in production (may contain PII)
+- DEBUG logs in production services (log level must be configurable)
+- The same event more than once in the same request path
+
+### External call discipline
+- Every external call (HTTP, DB, queue) has a timeout
+- Every external call logs duration on completion
+- Failed external calls log: target, duration, error type, and whether retry will occur
+
+## Conventions — WARN on violation
+
+### Metrics naming
+Format: `{service}_{subsystem}_{name}_{unit}`
+All lowercase, underscores as separators.
+
+Mandatory metrics per service:
+- `{service}_requests_total` — counter, labeled by method and status code
+- `{service}_errors_total` — counter, labeled by error type
+- `{service}_latency_seconds` — histogram, labeled by operation
+- `{service}_active_connections` or `{service}_queue_depth` — gauge (if applicable)
+
+GOOD: `auth_login_attempts_total`, `cache_hit_ratio`, `queue_messages_pending`
+BAD: `loginAttempts`, `CacheHitRatio`, `queue-messages-pending`
+
+### Trace spans (OpenTelemetry)
+Span naming: `{service}/{operation}` — lowercase, slash separator
+GOOD: `auth/validate-token`, `db/query-users`, `cache/get`
+BAD: `validateToken`, `DB Query`, `GET /users`
+
+Mandatory span attributes:
+- `service.name`
+- `http.method` and `http.status_code` for HTTP operations
+- `db.system` and `db.operation` for database calls
+- `error.type` and `error.message` on error spans
+
+### Health endpoints
+- Liveness: `/healthz` — "is the process alive?"
+- Readiness: `/readyz` — "can the process serve traffic?"
+- Both return structured JSON with component status
+
+### The Observability Contract
+An error is only production-observable if ALL three are true:
+1. It appears in structured logs with correlation_id and context
+2. It increments an error metric labeled by error type
+3. It is captured in a trace span with error attributes
+
+If only one or two are true: the code is not fully observable. Fix before shipping.
+
+## Removal Condition
+Remove when an observability linter or OpenTelemetry SDK auto-instrumentation
+replaces these generation-time constraints entirely.

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/refactor-triggers.md

@@ -0,0 +1,59 @@
+# Refactor Triggers — Pre-Check Protocol
+# Scope: All code modifications
+# Always active during code generation
+# Cross-reference: code-quality.md defines the hard limits (30 lines, 3 nesting,
+#   4 params, 300-line files, no TODO/FIXME). This file defines WHEN and HOW
+#   to refactor — not the thresholds themselves.
+
+## Invariants — BLOCK on violation
+
+### Before touching any existing file
+Check the file against `code-quality.md` hard limits before adding code.
+If the file already violates limits:
+1. Do NOT add new code to it
+2. Refactor the file to compliance first
+3. THEN make the intended change
+4. Commit the refactor separately from the feature
+
+This is mandatory. Adding to an already-broken file compounds debt exponentially.
+
+### Commit refactor separately from feature
+- Refactoring commits use `refactor(scope):` prefix
+- Feature commits use `feat(scope):` prefix
+- Never mix structural changes and behavior changes in one commit
+- Rationale: reviewers cannot distinguish "moved code" from "changed behavior" in a mixed diff
+
+### Copy-paste detection
+If you find yourself copying 3+ lines from elsewhere in the same codebase: stop.
+Extract a shared function in a common location.
+Duplication is the root of divergent behavior bugs.
+
+## Conventions — WARN on violation
+
+### The QUALITY comment convention
+When you encounter a known violation in code you are NOT tasked with fixing:
+```
+// QUALITY: function exceeds 30 lines — refactor tracked in #123
+```
+
+Rules for QUALITY comments:
+- QUALITY: is the ONLY allowed debt marker. `TODO`, `FIXME`, and `HACK` are banned (see `code-quality.md`).
+- Every QUALITY comment MUST include a tracking reference (issue number, ADR, or ticket).
+- QUALITY comments are allowed in commits — unlike TODO/FIXME which are not.
+- A QUALITY comment is NOT a license to defer indefinitely. It is a documented acknowledgment.
+
+### Refactor vs rewrite decision gate
+- **Refactor** (preferred): same behavior, improved structure. Small, safe, incremental.
+- **Rewrite**: new behavior or complete structural replacement.
+
+If >50% of a file needs changing during a feature task:
+1. Stop. Do not incrementally refactor to the point of a full rewrite.
+2. File an issue for the rewrite.
+3. Complete the minimum viable refactor for the current feature.
+4. Propose the rewrite as a separate milestone with its own plan.
+
+Never rewrite during a feature task without an explicit plan.
+
+## Removal Condition
+Remove when automated refactoring tools (e.g., language-specific AST transforms)
+handle pre-check validation and commit separation automatically.

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.