@esoteric-logic/praxis-harness 2.8.0 → 2.9.1

package/base/CLAUDE.md

@@ -128,24 +128,33 @@ Kits activate via `/px-kit:<n>` slash command. Kits are idempotent — double-ac
 | infrastructure | `/px-kit:infrastructure` | Terraform → Azure → GitHub Actions → compliance |
 | api | `/px-kit:api` | RESTful conventions → OpenAPI specs → contract testing |
 | security | `/px-kit:security` | Threat modeling → IAM review → OWASP audit |
+| code-quality | `/px-kit:code-quality` | SAST + secrets + SCA + IaC gate → AI review (over-engineering, smells, structure) |
 | data | `/px-kit:data` | Schema design → migration planning → query optimization |
 
 Kit manifests live in `~/.claude/kits/<name>/KIT.md`.
 
 ## Rules Registry — Load on Demand Only
 
-### Universal — always active (8 rules)
+### Universal — always active (9 rules)
 | 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` | Code quality, security, complexity thresholds, Context7 mandate |
+| `~/.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/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
 | File | Loads when |
 |------|------------|

package/base/configs/ci/lint-stack.yml

@@ -1,7 +1,7 @@
-# Polyglot Lint Stack — 3-Layer CI Template
+# Lint Stack — CI Template
 # Copy to: .github/workflows/lint-stack.yml
-# Conditional: each tool runs only if its language files exist in the repo.
-# Pin actions to SHA — update hashes when upgrading versions.
+# DeepSource handles comprehensive analysis via GitHub app integration.
+# This workflow provides basic file hygiene checks only.
 
 name: Lint Stack
 on:
@@ -10,117 +10,27 @@ on:
 
 permissions:
   contents: read
-  pull-requests: write
 
 jobs:
-  # ─────────────────────────────────────────────
-  # LAYER 1: Fast Feedback (~10s per tool)
-  # ─────────────────────────────────────────────
-  lint:
-    name: L1 — Lint + Format
+  hygiene:
+    name: File Hygiene
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
 
-      # Python — Ruff
-      - name: Ruff check
-        if: hashFiles('**/*.py') != ''
-        uses: astral-sh/ruff-action@9700c1666704e06e2cf8f9046755e3dfc6297e40 # v3.2.1
-        with:
-          args: "check"
-      - name: Ruff format check
-        if: hashFiles('**/*.py') != ''
-        uses: astral-sh/ruff-action@9700c1666704e06e2cf8f9046755e3dfc6297e40 # v3.2.1
-        with:
-          args: "format --check"
-
-      # JS/TS — Biome
-      - name: Setup Biome
-        if: hashFiles('**/*.js', '**/*.ts', '**/*.jsx', '**/*.tsx') != ''
-        uses: biomejs/setup-biome@1cbe33ead22c7a2fded3b52fa2893611c815c3d2 # v2.5.0
-      - name: Biome CI
-        if: hashFiles('**/*.js', '**/*.ts', '**/*.jsx', '**/*.tsx') != ''
-        run: biome ci .
-
-      # Go — golangci-lint
-      - name: golangci-lint
-        if: hashFiles('go.mod') != ''
-        uses: golangci/golangci-lint-action@1481404843c368bc19ca9406f87d6e0fc97bdcfd # v7.0.0
-        with:
-          version: v2.1
-
-      # Rust — Clippy
-      - name: Setup Rust toolchain
-        if: hashFiles('Cargo.toml') != ''
-        uses: dtolnay/rust-toolchain@56f84321dbccf38fb67ce29ab63e4754056677e0 # stable
-        with:
-          toolchain: stable
-          components: clippy, rustfmt
-      - name: Clippy
-        if: hashFiles('Cargo.toml') != ''
-        run: cargo clippy --all-targets --all-features -- -D warnings
-      - name: rustfmt check
-        if: hashFiles('Cargo.toml') != ''
-        run: cargo fmt --all -- --check
-
-      # Shell — ShellCheck
-      - name: ShellCheck
-        if: hashFiles('**/*.sh') != ''
+      - name: Check for merge conflict markers
         run: |
-          sudo apt-get install -y shellcheck
-          find . -name '*.sh' -not -path './node_modules/*' -not -path './vendor/*' | xargs shellcheck -s bash
-
-  # ─────────────────────────────────────────────
-  # LAYER 2: Quality Gates (~2min)
-  # ─────────────────────────────────────────────
-  security-scan:
-    name: L2 — Semgrep
-    runs-on: ubuntu-latest
-    needs: lint
-    steps:
-      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
-      - uses: semgrep/semgrep-action@713efdd345ae26c72e79b5b32927be8e0e6bab83 # v1
-        with:
-          config: >-
-            p/default
-            p/secrets
-            p/owasp-top-ten
-        env:
-          SEMGREP_APP_TOKEN: ${{ secrets.SEMGREP_APP_TOKEN }}
+          if git grep -rn '<<<<<<< \|>>>>>>> ' -- ':!*.yml' ':!*.yaml'; then
+            echo "::error::Merge conflict markers found"
+            exit 1
+          fi
 
-  # Uncomment to add SonarQube quality gate (requires self-hosted server)
-  # sonarqube:
-  #   name: L2 — SonarQube
-  #   runs-on: ubuntu-latest
-  #   needs: lint
-  #   steps:
-  #     - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
-  #       with:
-  #         fetch-depth: 0
-  #     - uses: SonarSource/sonarqube-scan-action@0e1a25e90571a34e2ec5c72ee40ba45cc73a1e6e # v4
-  #       env:
-  #         SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
-  #         SONAR_HOST_URL: ${{ secrets.SONAR_HOST_URL }}
-  #     - uses: SonarSource/sonarqube-quality-gate-action@dc2f7b0dd95544cd550de3066f25f47e3fc20894 # v1.1.0
-  #       timeout-minutes: 5
-  #       env:
-  #         SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
-
-  # ─────────────────────────────────────────────
-  # LAYER 3: AI Review (~2min, optional)
-  # ─────────────────────────────────────────────
-  # Uncomment to enable AI-powered PR review.
-  # Requires OPENAI_API_KEY secret or self-hosted Ollama.
-  #
-  # ai-review:
-  #   name: L3 — AI Review
-  #   runs-on: ubuntu-latest
-  #   needs: [security-scan]
-  #   steps:
-  #     - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
-  #     - uses: Codium-ai/pr-agent@main
-  #       env:
-  #         OPENAI_KEY: ${{ secrets.OPENAI_API_KEY }}
-  #         GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-  #       with:
-  #         command: review
+      - name: Check for large files
+        run: |
+          find . -type f -size +500k \
+            -not -path './.git/*' \
+            -not -path './node_modules/*' \
+            -not -path './vendor/*' \
+            -not -path './.terraform/*' | head -20 | while read -r f; do
+            echo "::warning file=$f::File exceeds 500KB"
+          done

package/base/configs/registry.json

@@ -26,16 +26,13 @@
       {"name": "gh", "minVersion": "2.0.0", "install": "brew install gh"}
     ],
     "optional": [
-      {"name": "trufflehog", "feature": "secret-scanning", "install": "brew install trufflehog"},
-      {"name": "gitleaks", "feature": "secret-scanning", "install": "brew install gitleaks"},
+      {"name": "deepsource", "feature": "code-analysis", "install": "curl -fsSL https://cli.deepsource.com/install | sh"},
       {"name": "osv-scanner", "feature": "dep-audit", "install": "go install github.com/google/osv-scanner/cmd/osv-scanner@latest"},
       {"name": "pip-audit", "feature": "dep-audit-python", "install": "pip install pip-audit"},
       {"name": "docker", "feature": "docker-sandbox", "install": "brew install --cask docker"},
       {"name": "biome", "feature": "lint-js", "install": "npm install -g @biomejs/biome"},
       {"name": "ruff", "feature": "lint-python", "install": "pip install ruff"},
-      {"name": "semgrep", "feature": "security-scan", "install": "pip install semgrep"},
       {"name": "markdownlint", "feature": "lint-markdown", "install": "npm install -g markdownlint-cli"},
-      {"name": "pre-commit", "feature": "pre-commit-hooks", "install": "pip install pre-commit"},
       {"name": "golangci-lint", "feature": "lint-go", "install": "brew install golangci-lint"},
       {"name": "rustfmt", "feature": "format-rust", "install": "rustup component add rustfmt"},
       {"name": "clippy", "feature": "lint-rust", "install": "rustup component add clippy"}
@@ -104,7 +101,6 @@
       {"path": "base/hooks/file-guard.sh", "event": "PreToolUse", "matcher": "Write|Edit|MultiEdit"},
       {"path": "base/hooks/identity-check.sh", "event": "PreToolUse", "matcher": "Bash"},
       {"path": "base/hooks/credential-guard.sh", "event": "PreToolUse", "matcher": "Bash"},
-      {"path": "base/hooks/quality-check.sh", "event": "PostToolUse", "matcher": "Write|Edit|MultiEdit"},
       {"path": "base/hooks/session-data-collect.sh", "event": "Stop", "matcher": ""}
     ],
     "optional": [

package/base/hooks/auto-format.sh

@@ -2,6 +2,7 @@
 # PostToolUse hook — auto-formats files after edit.
 # Always exits 0 (advisory, never blocks).
 set -uo pipefail
+trap 'exit 0' ERR
 
 INPUT=$(cat)
 FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // .tool_input.path // empty' 2>/dev/null)

package/base/hooks/dep-audit.sh

@@ -2,7 +2,8 @@
 # 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 -euo pipefail
+set -uo pipefail
+trap 'exit 0' ERR
 
 INPUT=$(cat)
 FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // .tool_input.path // empty' 2>/dev/null)
@@ -20,28 +21,40 @@ case "$BASENAME" in
   package.json)
     ECOSYSTEM="npm"
     if command -v npm &>/dev/null && [[ -f "$DIR/package-lock.json" || -f "$DIR/node_modules/.package-lock.json" ]]; then
-      AUDIT_RESULT=$(cd "$DIR" && npm audit --audit-level=high --json 2>/dev/null || true)
+      # npm audit exits non-zero when vulnerabilities exist — capture output regardless
+      AUDIT_RESULT=$(cd "$DIR" && npm audit --audit-level=high --json 2>/dev/null) || {
+        if [[ -n "$AUDIT_RESULT" ]]; then
+          : # non-zero with output = vulnerabilities found (expected)
+        else
+          echo "DEP-AUDIT (npm): audit command failed" >&2
+        fi
+      }
     fi
     ;;
   go.mod)
     ECOSYSTEM="go"
     if command -v govulncheck &>/dev/null; then
-      AUDIT_RESULT=$(cd "$DIR" && govulncheck -json ./... 2>/dev/null || true)
+      AUDIT_RESULT=$(cd "$DIR" && govulncheck -json ./... 2>/dev/null) || {
+        [[ -z "$AUDIT_RESULT" ]] && echo "DEP-AUDIT (go): govulncheck failed" >&2
+      }
     elif command -v go &>/dev/null; then
-      # Fallback: at least check for known issues via go list
-      AUDIT_RESULT=$(cd "$DIR" && go list -m -json all 2>/dev/null | head -c 5000 || true)
+      AUDIT_RESULT=$(cd "$DIR" && go list -m -json all 2>/dev/null | head -c 5000) || AUDIT_RESULT=""
     fi
     ;;
   requirements.txt|pyproject.toml)
     ECOSYSTEM="python"
     if command -v pip-audit &>/dev/null; then
-      AUDIT_RESULT=$(cd "$DIR" && pip-audit --format=json 2>/dev/null || true)
+      AUDIT_RESULT=$(cd "$DIR" && pip-audit --format=json 2>/dev/null) || {
+        [[ -z "$AUDIT_RESULT" ]] && echo "DEP-AUDIT (python): pip-audit failed" >&2
+      }
     fi
     ;;
   Cargo.toml)
     ECOSYSTEM="rust"
     if command -v cargo-audit &>/dev/null; then
-      AUDIT_RESULT=$(cd "$DIR" && cargo audit --json 2>/dev/null || true)
+      AUDIT_RESULT=$(cd "$DIR" && cargo audit --json 2>/dev/null) || {
+        [[ -z "$AUDIT_RESULT" ]] && echo "DEP-AUDIT (rust): cargo-audit failed" >&2
+      }
     fi
     ;;
   *)

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

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

package/base/hooks/settings-hooks.json

@@ -39,15 +39,6 @@
       }
     ],
     "PostToolUse": [
-      {
-        "matcher": "Write|Edit|MultiEdit",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "bash ~/.claude/hooks/quality-check.sh"
-          }
-        ]
-      },
       {
         "matcher": "Write|Edit|MultiEdit",
         "hooks": [
@@ -62,10 +53,6 @@
       {
         "matcher": "",
         "hooks": [
-          {
-            "type": "command",
-            "command": "bash ~/.claude/hooks/post-session-lint.sh"
-          },
           {
             "type": "prompt",
             "prompt": "Run the project test suite. Read CLAUDE.md ## Commands for the test command. If no test command defined, respond {ok:true}. Run tests. If all pass: respond {ok:true}. If tests fail: respond {ok:false, reason:'Tests failing: <summary>'}. Do not fix — only report."

package/base/hooks/vault-checkpoint.sh

@@ -2,6 +2,7 @@
 # PreCompact hook — writes minimal checkpoint to vault before context compaction.
 # Always exits 0 (advisory, never blocks compaction).
 set -uo pipefail
+trap 'exit 0' ERR
 
 CONFIG_FILE="$HOME/.claude/praxis.config.json"
 
@@ -23,8 +24,6 @@ CHECKPOINT_FILE="$PLANS_DIR/$DATE-compact-checkpoint.md"
 
 BRANCH=$(git --no-pager rev-parse --abbrev-ref HEAD 2>/dev/null || echo "unknown")
 LAST_COMMIT=$(git --no-pager log --oneline -1 2>/dev/null || echo "no commits")
-PROJECT_DIR=$(basename "$PWD")
-
 STATUS_FILE="$VAULT_PATH/status.md"
 PROGRESS_FILE="$VAULT_PATH/claude-progress.json"
 

package/base/lib/kit-check.sh

@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+# ════════════════════════════════════════════════════════════════
+#  Praxis — Shared Kit Install Check
+#  Source this file in kit install.sh scripts for consistent
+#  tool-checking output and counters.
+#
+#  Usage:
+#    source "$(dirname "$0")/../../base/lib/kit-check.sh"
+#    check "jq"      "brew install jq"
+#    check "curl"    "pre-installed on macOS/Linux"
+#    kit_check_summary
+# ════════════════════════════════════════════════════════════════
+
+KIT_CHECK_PASS=0
+KIT_CHECK_TOTAL=0
+
+check() {
+  local cmd="$1"
+  local install_hint="$2"
+  local optional="${3:-}"
+
+  KIT_CHECK_TOTAL=$((KIT_CHECK_TOTAL + 1))
+  if command -v "$cmd" &>/dev/null; then
+    echo "  ✓ $cmd found ($(command -v "$cmd"))"
+    KIT_CHECK_PASS=$((KIT_CHECK_PASS + 1))
+  else
+    if [[ "$optional" == "optional" ]]; then
+      echo "  ⚠ $cmd not found (optional)"
+    else
+      echo "  ✗ $cmd not found"
+    fi
+    echo "    Install: $install_hint"
+  fi
+}
+
+kit_check_summary() {
+  echo ""
+  echo "  $KIT_CHECK_PASS/$KIT_CHECK_TOTAL tools found"
+  if [[ $KIT_CHECK_PASS -lt $KIT_CHECK_TOTAL ]]; then
+    echo "  ⚠ Some tools missing. Install them before using kit commands."
+  fi
+}

package/base/lib/output.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+# ═══════��════════════════════════════════════════════════════════
+#  Praxis — Shared Output Helpers
+#  Source this file instead of defining colors/helpers inline.
+#
+#  Usage:
+#    source "$(dirname "$0")/../base/lib/output.sh"
+#    # or with absolute path:
+#    source "$HOME/.claude/lib/output.sh"
+#
+#  Safe to source multiple times — guards against redefinition.
+# ════��═══════════════════════════════════════════════════════════
+
+# ─── Colors (skip if already set) ───
+RED="${RED:-\033[0;31m}"
+GREEN="${GREEN:-\033[0;32m}"
+YELLOW="${YELLOW:-\033[0;33m}"
+CYAN="${CYAN:-\033[0;36m}"
+BOLD="${BOLD:-\033[1m}"
+DIM="${DIM:-\033[2m}"
+NC="${NC:-\033[0m}"
+
+# ─── Output helpers (skip if already defined) ───
+if ! declare -f ok &>/dev/null; then
+  ok()   { echo -e "  ${GREEN}✓${NC} $1"; }
+fi
+if ! declare -f warn &>/dev/null; then
+  warn() { echo -e "  ${YELLOW}⚠${NC} $1"; }
+fi
+if ! declare -f fail &>/dev/null; then
+  fail() { echo -e "  ${RED}✗${NC} $1"; }
+fi
+if ! declare -f step &>/dev/null; then
+  step() { echo -e "\n${CYAN}${BOLD}$1${NC}"; }
+fi
+if ! declare -f dim &>/dev/null; then
+  dim()  { echo -e "  ${DIM}$1${NC}"; }
+fi

package/base/rules/code-quality.md

@@ -0,0 +1,56 @@
+# Code Quality — Active Constraints
+
+These rules are active during code generation. They are not reviewed after writing —
+they shape what gets written in the first place.
+
+## Before writing any function
+State in a single-line comment what this function does.
+If you cannot write the comment in one sentence, split the function first.
+The function name must be derivable from that comment.
+
+## Hard limits — never violate without explicit documented exception
+- No function exceeds 30 lines of logic (blank lines and comments excluded)
+- No block nesting deeper than 3 levels
+- No function with more than 4 parameters — use an options/config object beyond 4
+- No class with more than 5 public methods — split the class first
+- No file with more than 300 lines — split the module first
+- No `TODO` or `FIXME` committed — resolve inline or create a tracked issue with link in comment
+
+## Before introducing any abstraction (interface, base class, factory, wrapper)
+Identify exactly 2 or more existing concrete use cases that require it.
+They must exist in the current codebase, not in anticipated future requirements.
+If only 1 use case exists, inline the logic and do not create the abstraction.
+
+## Before adding any new dependency
+- Verify the standard library does not provide equivalent functionality
+- Verify the package has had a commit within the last 6 months
+- Pin to exact version in package manifest
+- Add a comment above the import explaining why this dependency was chosen over alternatives
+
+## On every new public function or method
+Write the JSDoc/docstring before writing the implementation.
+The docstring must include: what it does, what each parameter is, what it returns, what it throws.
+If you cannot write the docstring, you do not yet understand what you are building.
+
+## On error handling — no exceptions
+- Every async function has explicit error handling (try/catch or .catch() or Result type)
+- Every function that receives external input validates type, range, and format before use
+- Every thrown error has a message that identifies: what failed, why it failed, what the caller should do
+- Errors are never caught and silently ignored — log at minimum, re-throw if unhandled
+
+## On tests
+- New public functions require tests before the PR is considered complete
+- Tests assert behavior (outputs and side effects), not implementation (which internal functions were called)
+- Each test covers exactly one scenario — no multi-scenario tests
+- Test files mirror source file structure — `src/auth/login.ts` → `tests/auth/login.test.ts`
+
+## On comments
+Write comments that explain WHY, not WHAT.
+Delete any comment that restates what the code already says.
+Write comments that capture: non-obvious decisions, external constraints, known limitations.
+
+## On naming
+- No single-letter variables except loop indices (`i`, `j`, `k`) in tight loops of ≤5 lines
+- No abbreviations unless they are universally understood domain terms (`id`, `url`, `api`)
+- No generic names: `data`, `info`, `temp`, `result`, `obj`, `val`, `res`, `thing`, `stuff`
+- Rename before committing. Names do not get "cleaned up later."

package/base/rules/coding.md

@@ -1,6 +1,5 @@
 # Coding — Universal Rules
 <!-- Universal — applies to ALL code regardless of language or stack -->
-<!-- Merged from coding.md + code-quality.md -->
 
 ---
 
@@ -9,132 +8,44 @@
 ### Documentation lookup before implementation
 - Before implementing anything that uses an external library, framework, or API:
   use Context7 to get current docs. Training data has a cutoff. Context7 does not.
-- Append "use context7" to any prompt involving a library not personally verified as current.
 - Never suggest a method, constructor, or API signature from memory for a library
   that releases frequently. Look it up first via Context7.
 - If Context7 is unavailable: state that docs could not be verified and flag the
   specific method/API as "unverified against current version."
 
-### Error handling
-- Never silently swallow exceptions. Every catch block must either re-throw,
-  log with context, or return a typed error.
-- No empty catch blocks. No fallback defaults unless explicitly asked.
-- Error messages MUST include context: request params, response body, status codes.
-- Use structured logging fields, not string interpolation.
-- External calls: retries with exponential backoff + warnings, then raise last error.
-- Validate response shape, not just status code — a 200 with error body is a silent failure.
-- Every function that can fail must have an explicit failure path.
-- Validate inputs at the boundary. Never assume callers pass correct data.
-
-### No hardcoded values
-- No credentials, tokens, connection strings, or API keys inline. Ever.
-  Use environment variables, Key Vault references, or parameter files.
-- No hardcoded paths specific to one machine. Use relative paths or env-derived roots.
-- No magic numbers without a named constant and a comment explaining the value.
-
-### State and side effects
-- Pure functions where possible. If a function mutates state, its name must signal that.
-- Never mutate input parameters. Return new values.
-- Write pure functions — only modify return values, never inputs or global state.
-
-### Typing
-- Strict typing everywhere: function signatures, variables, collections.
-- No implicit `any` or untyped parameters in typed languages.
-
-### No flag parameters
-- Never write a function with a boolean/enum parameter that switches behavior.
-  Write separate named functions instead.
-
-### Dead code
-- Delete dead code. Do not comment it out.
-  Commented-out code belongs in git history, not in files.
-- Check if logic already exists before writing new code: `rg` to search first.
-
----
-
-## Conventions — WARN on violation
-
-### Code structure
-- Functions do one thing. If you are writing "and" in a function description,
-  split it into two functions.
-- Prefer functional programming in greenfield code; classes only for connectors/interfaces.
-  Follow existing project conventions in established codebases.
-- All imports at the top of the file.
-- Follow DRY, KISS, YAGNI.
-
-### Naming
-- Variable names describe what they contain: `subscriptionIds` not `ids`,
-  `retryDelayMs` not `delay`.
-- Functions: verb-noun format. Name signals intent and side effects.
-
-### Testing
-- Write tests for ALL new code in production paths.
-- Spike/prototype carve-out: skip tests only if explicitly marked spike/prototype.
-  Flag test debt in `status.md` under `## Test Debt`.
-- Run tests before marking any task complete.
-- Mock external dependencies only — never mock the code under test.
-- Test edge cases and error paths, not just happy paths.
-- If existing tests break: fix them. Do not claim they are unrelated.
-- Never say "this should work" — demonstrate it with output, log line, or test result.
-
-### Dependency management
-Before adding any new package:
-1. Search first — check if functionality exists in codebase or stdlib (`rg`).
-2. Evaluate: maintenance status, last publish, open issues, bus factor.
-3. Minimize surface area — implement yourself if you only need one function.
-4. Pin versions — exact versions in lockfiles. No floating ranges in production deps.
-5. New production dependency requires explicit approval.
-
-### Documentation
-- Comments explain WHY, not WHAT. If the comment describes what the code does,
-  rewrite the code to be self-describing instead.
-- Update docs and comments when changing logic. Stale comments actively mislead.
-- Code is primary documentation — clear naming, types, docstrings.
-- YAML frontmatter on all markdown files:
-  ```yaml
-  ---
-  created: YYYY-MM-DD
-  status: draft|active|completed
-  tags: [relevant, tags]
-  source: agent
-  ---
-  ```
-
-### Scripts
-- Scripts that modify resources must have a dry-run or preview step before live run.
-
 ### Tool preferences
 - Use Read/Edit/Write tools instead of cat/sed/echo.
 - Use `rg` (ripgrep) for searching code, not grep.
 - Use `git --no-pager` for all git commands.
 - Use subagents for context-heavy research and code review.
 - Non-interactive commands only — no interactive prompts.
-- Prefer MCP tools for current documentation (context7, Playwright).
+- Prefer MCP tools for current documentation (context7).
+- YAML frontmatter on all markdown files.
 
 ---
 
-## Linter Delegation
+## Quality Architecture
 
-Style, formatting, import ordering, complexity thresholds, and security patterns
-are enforced by automated tooling (golangci-lint, shellcheck, hadolint, tflint,
-semgrep). Rules files cover ONLY:
-- Architecture decisions tooling cannot express
-- Permission boundaries and file-group scoping
-- Error learning from real session failures
-- Verification command references
+Code quality is enforced proactively, not reactively:
+- **Layer 1 (Principles)**: `code-excellence.md`, `engineering-judgment.md` — shape reasoning
+- **Layer 2 (Constraints)**: `code-quality.md` — hard limits during generation
+- **Layer 3 (Verification)**: `/px-self-verify` — prove correctness before commit
+- **Safety net**: DeepSource (cloud) — comprehensive analysis on push
 
-Do NOT duplicate in CLAUDE.md what hooks already enforce.
+Detailed rules: error handling, naming, testing, dependencies, simplicity, and
+judgment live in those files. This file covers only what they do not:
+Context7 mandate, tool preferences, and verification commands.
 
 ---
 
 ## Verification Commands
 
-Single-file (matches PostToolUse hooks):
+Single-file:
 - `go vet <file>` / `shellcheck <file>` / `hadolint Dockerfile` / `markdownlint <file>.md`
 
-Project-level (matches pre-commit + /verify):
-- `golangci-lint run`
-- `semgrep --config=auto --error .`
+Project-level:
+- `deepsource issues --path <file>` — query DeepSource findings
+- `deepsource repo status` — repo analysis status
 - `govulncheck ./...`
 - `trivy config .`
 
@@ -147,12 +58,6 @@ git diff --staged | grep -iE "(password|secret|token|key)\s*=\s*['\"][^'\"$]"
 
 # Find TODO/FIXME left in staged files
 git diff --staged | grep -E "(TODO|FIXME|HACK|XXX)"
-
-# Find commented-out code blocks (language-agnostic)
-git diff --staged | grep -E "^\+\s*(#|//|--|\*)\s*(def |function |class |var |const |let )"
-
-# Check for untyped any in TypeScript staged files
-git diff --staged -- '*.ts' | grep -E ": any"
 ```
 
 ---