@esoteric-logic/praxis-harness 2.8.0 → 2.9.0

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/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

@@ -23,8 +23,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/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"
 ```
 
 ---

package/base/skills/code-excellence.md

@@ -0,0 +1,69 @@
+# 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.
+
+## The Prime Directive
+Write code that the next engineer will thank you for.
+That engineer is you, six months from now, at 2am with a production incident.
+Optimize for that moment.
+
+## On Simplicity
+The simplest solution that correctly solves the stated problem is always right.
+Not the solution that solves the *anticipated* problem.
+Not the solution that would *scale* if requirements changed.
+Not the solution that demonstrates *skill*.
+The solution to the problem in front of you, right now.
+
+Before adding any abstraction, answer all three:
+- Does this abstraction already have 2+ concrete use cases that exist TODAY?
+- If removed, does anything break that exists today?
+- 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.
+
+## 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.
+It does not log. It does not cache. It does not validate sessions. It does not send metrics.
+If it does those things, rename it or split it.
+Side effects that aren't in the name are the leading cause of bugs that take hours to find.
+
+## On Naming
+Names are the primary interface between code and the human reading it.
+A name that requires a comment to explain has failed.
+- Functions are named for what they DO (verb phrase): `validateEmailFormat`, `fetchOrderById`
+- Variables are named for what they CONTAIN (noun phrase): `userRecord`, `retryCount`
+- Booleans are named as assertions: `isValid`, `hasPermission`, `canRetry`
+- Avoid: `data`, `info`, `temp`, `result`, `obj`, `val`, `x`
+If you cannot name something clearly, you do not understand it well enough to write it yet.
+
+## On Error Handling
+Every function that can fail has two paths: success and failure. Both are designed.
+Neither is an afterthought.
+- Errors are never swallowed silently. Silent failures are the worst kind.
+- Error messages tell the caller what happened AND what to do about it.
+- Errors surface at the right level — don't catch what you can't handle.
+- External input is always validated before use. Always.
+
+## On Tests
+Tests are the second consumer of your API. If the test is hard to write, the API is wrong.
+Test behavior, not implementation:
+- WRONG: "calls the repository with the user id"
+- RIGHT: "returns null when the user does not exist in the database"
+The test name is documentation. Write it first. Then write the code that makes it pass.
+A test that can never fail is not a test — it's a ceremony.
+
+## On Dependencies
+Every dependency is a liability you will maintain forever.
+Before adding one, answer:
+- Can this be done in 10 lines with the standard library?
+- Has this package had a commit in the last 6 months?
+- Do you understand it well enough to debug it without its documentation?
+If any answer is no — find an alternative or write it yourself.
+
+## On Comments
+Comments explain WHY, not WHAT. The code explains what.
+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.

package/base/skills/engineering-judgment.md

@@ -0,0 +1,71 @@
+# Engineering Judgment — Reasoning About Hard Decisions
+
+This skill provides a framework for reasoning through non-obvious engineering decisions.
+Apply it before writing anything that feels complex, uncertain, or requires a tradeoff.
+
+## The Five Questions (ask before writing anything non-trivial)
+
+**1. What is the exact problem I'm solving?**
+Write it in one sentence. Not the category of problem — the specific problem.
+"Users need to reset passwords" is not specific enough.
+"Users who forget their password need to verify identity via email and create a new one" is.
+If you cannot write the sentence, stop and clarify before writing code.
+
+**2. What is the simplest thing that could possibly work?**
+Start there. Always. Complexity is additive — you can always add it later.
+Complexity is almost never removable once it exists, because people build on top of it.
+A direct implementation that solves today's problem beats a flexible framework
+that solves tomorrow's hypothetical problems.
+
+**3. What will break when requirements change?**
+Identify the parts of your design that are tightly coupled to current requirements.
+Isolate those parts behind boundaries (functions, modules, interfaces).
+Do not protect everything — just the things that are genuinely likely to change.
+Protecting stable things is overhead. Protecting volatile things is architecture.
+
+**4. Who reads this code next?**
+They have your codebase, no Slack history, no memory of your decisions, and a deadline.
+What do they absolutely need to understand?
+- What this code does: conveyed by naming
+- Why it exists: conveyed by comments
+- How to change it safely: conveyed by tests
+Make sure all three are present. Everything else is optional.
+
+**5. What would you cut if you had to ship in half the time?**
+Cut it now. If the answer is "nothing," your scope is already minimal.
+If the answer is "the caching layer" or "the plugin system" or "the admin dashboard,"
+those things are not part of the core problem. Ship the core. Add the rest when needed.
+
+## The YAGNI Test
+"You Aren't Gonna Need It" is not pessimism — it's empirical engineering.
+Studies consistently show that 70%+ of speculative features are never used.
+Every hour on YAGNI code is an hour not spent on things users actually need.
+Apply it ruthlessly to: abstractions, configuration, generalization, future-proofing.
+
+## When to Refactor
+Refactor when ONE of these is true:
+1. You are adding a feature and the existing structure makes it harder
+2. You have seen the same pattern 3 times and can now name it correctly
+Not before. Premature refactoring creates abstractions that don't fit the actual problem
+discovered later. The Rule of Three exists for good reason — once is an instance,
+twice is coincidence, three times is a pattern worth naming.
+
+## On Technical Debt
+Not all debt is bad. Deliberate shortcuts with known payoff timelines are engineering
+decisions. Document them: what was cut, why, and when it should be paid back.
+The only debt worth preventing is accidental complexity — code that is harder than
+it needs to be because no one asked "can we simplify this?"
+
+## The Reversibility Test
+Before any significant decision, ask: how hard is this to undo?
+- Easy to undo → move fast, decide now
+- Hard to undo → move deliberately, decide with evidence
+Two-way doors get opened quickly. One-way doors require the Five Questions above.
+
+## On Code Review
+When reviewing code (your own or others), ask these in order:
+1. Does it correctly solve the stated problem?
+2. Is it as simple as it could be while remaining correct?
+3. Will the next engineer understand it?
+4. Are the failure paths handled?
+If all four pass, approve. Style differences below this threshold are preferences, not correctness.

package/base/skills/px-code-gc/SKILL.md

@@ -197,5 +197,5 @@ Do NOT auto-remediate. Always ask first.
 ---
 
 ## Removal Condition
-Remove when static analysis tooling (Semgrep, SonarQube, or equivalent) is wired
-into the pre-commit hook and covers all six entropy categories with automated reporting.
+Remove when static analysis tooling (DeepSource or equivalent) is wired
+into CI and covers all six entropy categories with automated reporting.