@esoteric-logic/praxis-harness 1.1.0

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

@@ -0,0 +1,205 @@
+---
+name: code-gc
+disable-model-invocation: true
+description: Detect code entropy in the current repo. Dead code, test debt, stale
+  TODOs, oversized functions, commented-out blocks, unused deps. Two modes:
+  lightweight (called by session-retro) and full audit (manual /code-gc).
+  Never auto-deletes or auto-fixes. Side-effect skill — never auto-triggers.
+allowed-tools: Bash, Read, Write
+---
+
+# code-gc Skill
+
+## Vault Path Resolution
+Read vault_path from `~/.claude/praxis.config.json`.
+Detect current project by matching CWD to `local_path` in vault `_index.md`.
+
+## Two Modes
+
+| Mode | Trigger | Scope | Output |
+|------|---------|-------|--------|
+| **Lightweight** | Called by `session-retro` Phase 6b | TODOs + test debt delta only | One line or silence |
+| **Full Audit** | Manual `/code-gc` | All 6 entropy checks | Prioritized report, offer to write vault |
+
+---
+
+## Mode A — Lightweight (session-retro)
+
+Run only these two checks against the current session's diff:
+
+```bash
+# New TODOs/FIXMEs introduced this session
+git diff HEAD -- '*.ts' '*.py' '*.go' '*.js' '*.rs' '*.rb' | \
+  grep "^+" | grep -cE "(TODO|FIXME|HACK|XXX)"
+
+# Production files touched without corresponding test file touched
+git diff --name-only HEAD | grep -vE "(test|spec|__tests__|_test)" | \
+  grep -E "\.(ts|py|go|js|rs|rb)$"
+```
+
+Output rules:
+- 0 TODOs added, test files touched: **silent**
+- TODOs added OR prod files touched without tests: `⚠ code-gc: {n} TODOs added, {n} prod files touched without tests`
+- Never block. Exit 0 always.
+
+---
+
+## Mode B — Full Audit
+
+### Check 1: Dead Code
+```bash
+# TODOs/FIXMEs with age
+rg "(TODO|FIXME|HACK|XXX)" --line-number --glob "!*.lock" . | head -50
+# For each hit: git blame to get age
+
+# Commented-out code blocks (language-agnostic)
+rg --multiline "(^\s*(#|//|--)\s*(def |function |class |const |let |var |func ))"
+```
+Flag:
+- CRITICAL: TODO older than 90 days in a production path
+- HIGH: Commented-out function/class definition
+- MEDIUM: TODO 30–90 days old
+
+### Check 2: Test Debt
+```bash
+# Find production source files
+find . -type f \( -name '*.ts' -o -name '*.py' -o -name '*.go' -o -name '*.js' \) \
+  -not -path '*/test*' -not -path '*/spec*' -not -path '*/node_modules*' \
+  -not -path '*/__tests__*'
+
+# For each: check if a corresponding test file exists
+# ts: src/foo.ts → check src/foo.test.ts, src/foo.spec.ts, test/foo.test.ts
+# py: foo.py → check test_foo.py, tests/test_foo.py
+# go: foo.go → check foo_test.go
+```
+Flag:
+- CRITICAL: Production file with no test file, NOT marked spike/prototype in status.md
+- MEDIUM: Production file with no test, IS marked spike (test debt acknowledged)
+
+Also check `status.md` for `## Test Debt` section — report any items there that
+have been stale for >30 days.
+
+### Check 3: Oversized Functions
+```bash
+# Count lines between function definitions (approximate)
+# TypeScript/JavaScript
+rg --line-number "^(export\s+)?(async\s+)?function |^\s+(async\s+)?[a-zA-Z]+\s*\(" \
+  --glob '*.ts' --glob '*.js'
+# Python
+rg --line-number "^def |^    def " --glob '*.py'
+# Go
+rg --line-number "^func " --glob '*.go'
+```
+For each match: count lines to next same-indent definition.
+Flag:
+- HIGH: >100 lines
+- MEDIUM: 50–100 lines
+
+### Check 4: Unused Dependencies
+```bash
+# Node/npm
+if [ -f package.json ]; then
+  # declared deps vs. actual imports
+  node_deps=$(jq -r '.dependencies // {} | keys[]' package.json 2>/dev/null)
+  for dep in $node_deps; do
+    rg "require\(['\"]}$dep|from ['\"]$dep" --quiet || echo "UNUSED: $dep"
+  done
+fi
+
+# Python
+if [ -f requirements.txt ]; then
+  while read pkg; do
+    name=$(echo $pkg | sed 's/[>=<].*//' | tr '[:upper:]' '[:lower:]')
+    rg -i "import $name|from $name" --quiet || echo "UNUSED: $pkg"
+  done < requirements.txt
+fi
+
+# Go
+if [ -f go.mod ]; then
+  go mod tidy -e 2>&1 | grep "^unused"
+fi
+```
+Flag:
+- MEDIUM: Declared dependency with no import found
+
+### Check 5: Orphan Files
+```bash
+# Files not touched in >180 days in an active project
+git log --diff-filter=M --name-only --format="" --since="180 days ago" | sort -u > /tmp/recent_files
+find . -type f \( -name '*.ts' -o -name '*.py' -o -name '*.go' \) \
+  -not -path '*/node_modules*' > /tmp/all_source
+comm -23 <(sort /tmp/all_source) /tmp/recent_files
+```
+Flag:
+- MEDIUM: Source file not touched in 180+ days in an active project
+
+### Check 6: Stale Comments
+```bash
+# Comments on lines adjacent to recently changed code that are >90 days old
+# For each comment line in staged/recent changes:
+git log --since='90 days ago' --diff-filter=M -p -- '*.ts' '*.py' '*.go' | \
+  grep "^+.*(//)|(#)" | head -20
+```
+Flag:
+- LOW: Comments that describe WHAT the code does (heuristic match against adjacent code)
+
+---
+
+## Report Format
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  CODE GC — {project-slug}  {today_date}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+CRITICAL ({n})
+  ✗ [test-debt] src/auth/login.ts — production path, 0 tests, not marked spike
+  ✗ [dead-code] utils/legacy.ts — TODO age 94 days (line 88)
+
+HIGH ({n})
+  ✗ [oversized] api/handler.go:ProcessRequest — 143 lines
+  ✗ [commented-code] services/payment.py:44 — commented-out function definition
+
+MEDIUM ({n})
+  ⚠ [todo-debt] 14 TODOs — oldest: 47 days (billing/invoice.ts:88)
+  ⚠ [unused-dep] "lodash" declared in package.json, never imported
+  ⚠ [orphan-file] src/utils/old-formatter.ts — not touched 210 days
+
+LOW ({n})
+  — [stale-comment] api/routes.ts:22 — comment describes WHAT not WHY
+
+CLEAN
+  ✓ Test coverage: all production paths have tests
+  ✓ No commented-out code blocks
+  ✓ All deps used
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  {n} findings  |  {n} clean
+  code-gc never auto-fixes — act on findings manually
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+After report, offer:
+1. Write findings to `{vault_path}/specs/code-gc-{YYYY-MM-DD}.md`
+2. Add CRITICAL + HIGH items as tasks to `{vault_path}/tasks.md`
+3. Address a specific finding now
+
+Do NOT auto-remediate. Always ask first.
+
+---
+
+## Error Handling
+
+| Condition | Action |
+|-----------|--------|
+| Not a git repo | STOP. Report — code-gc requires git history for age detection |
+| No source files found | Report clean, note stack not detected |
+| Dep check tool missing | Skip that check, note in report |
+| `go mod tidy` fails | Skip Go dep check, note in report |
+| Project not in vault | Run checks, skip vault write offer |
+
+---
+
+## 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.

package/base/skills/code-simplifier/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: code-simplifier
+disable-model-invocation: true
+description: Post-implementation code simplification. Launches a subagent to review
+  recent changes for unnecessary complexity, over-abstraction, and opportunities to
+  simplify. Runs after any implementation phase. Side-effect skill — never auto-triggers.
+allowed-tools: Bash, Read, Edit
+---
+
+# code-simplifier Skill
+
+## Vault Path Resolution
+Read vault_path from `~/.claude/praxis.config.json`.
+Detect current project by matching CWD to `local_path` in vault `_index.md`.
+
+## DONE-WHEN
+- [ ] Diff analyzed by isolated subagent
+- [ ] Simplification opportunities identified and categorized
+- [ ] User-approved changes applied
+- [ ] No functional regressions (tests pass after changes)
+
+## NON-GOALS
+- Does not add features or change behavior
+- Does not refactor architecture — only simplifies within existing structure
+- Does not touch files outside the recent diff
+- Does not run without user reviewing proposed changes
+
+---
+
+## Phase 1 — Determine Scope
+
+Determine what to simplify:
+- Default: `git diff HEAD~1` (last commit)
+- Accept: `HEAD~N`, specific SHA, or `staged`
+- If diff is empty: "Nothing to simplify." Exit.
+- If diff >2000 lines: warn and ask to narrow scope
+
+## Phase 2 — Launch Subagent
+
+Launch a subagent with ONLY these inputs (zero conversation history):
+
+```
+You are a code simplification expert. Your only goal is to make this code
+simpler, more readable, and more maintainable WITHOUT changing behavior.
+
+## Diff to simplify
+{the diff}
+
+## Project conventions (if available)
+{contents of project CLAUDE.md}
+
+## Review for these simplification patterns:
+
+1. **Over-abstraction**: helpers/utilities created for one-time use,
+   premature abstractions, unnecessary indirection layers
+2. **Unnecessary complexity**: complex conditionals that could be simplified,
+   nested ternaries, over-engineered error handling for impossible cases
+3. **Dead paths**: code paths that can never execute given the current logic,
+   unused parameters, redundant null checks
+4. **Verbosity**: code that does in 10 lines what could be done in 3,
+   unnecessary intermediate variables, redundant type annotations
+5. **Missed language idioms**: patterns where the language has a simpler
+   built-in way (e.g., optional chaining, destructuring, list comprehensions)
+
+For each finding, provide:
+- File and line range
+- Category (1-5 above)
+- Current code (exact snippet)
+- Simplified code (exact replacement)
+- Why it's simpler (one sentence)
+
+If the code is already clean, say "No simplifications found."
+Do NOT suggest changes that alter behavior or add features.
+```
+
+## Phase 3 — Present Findings
+
+Structure output by impact:
+
+```
+━━━ SIMPLIFY — {n} opportunities ━━━
+
+{file}:{lines} — {category}
+  Before: {current code snippet}
+  After:  {simplified code snippet}
+  Why:    {one sentence}
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Ask: "Apply all / select specific / skip?"
+
+## Phase 4 — Apply Changes
+
+For each approved simplification:
+1. Apply the edit
+2. Run the test suite after ALL edits
+3. If tests fail: revert the last edit, report which simplification broke tests
+4. Show final diff of simplifications applied
+
+## Phase 5 — Write Learning (optional)
+
+If a pattern recurred (same category hit 3+ times):
+- Write a `[LEARN:simplify]` entry to `{vault_path}/notes/learnings.md`:
+  ```markdown
+  ## [LEARN:simplify] {Pattern name}
+  - **What**: {what complexity pattern was found}
+  - **So What**: {why it makes code harder to maintain}
+  - **Now What**: {what to do instead going forward}
+  - **Date**: {YYYY-MM-DD}
+  ```
+
+## Error Handling
+
+| Condition | Action |
+|-----------|--------|
+| Empty diff | Exit cleanly |
+| Tests fail after simplification | Revert last edit, report |
+| Subagent finds nothing | "Code is clean. No simplifications." |
+| No test command configured | Warn, ask user to verify manually |
+
+## Integration Points
+
+| Caller | When |
+|--------|------|
+| `/gsd:verify` Step 3b | After UNIFY, before session-retro |
+| Manual `/simplify` | Any time after implementation |
+| Ralph iteration | After story completion, before commit |
+
+## Removal Condition
+Remove when an external linter or formatter handles all 5 simplification
+categories with auto-fix support.

package/base/skills/prd-writer/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: prd-writer
+disable-model-invocation: true
+description: Structured PRD authoring for Ralph. Gathers context, builds stories,
+  validates against Ralph constraints, writes PRD to vault. Invoke manually with
+  /prd-writer only. Side-effect skill — never auto-triggers.
+allowed-tools: Bash, Read, Write, Edit
+---
+
+# prd-writer Skill
+
+## Vault Path Resolution
+Read vault_path from `~/.claude/praxis.config.json`. If missing: tell user to run `install.sh`.
+
+## DONE-WHEN
+- [ ] PRD written to vault with all stories populated
+- [ ] Every story has: role, capability, outcome, done-when, file group, dependencies, estimate
+- [ ] No story marked L (must be split before writing)
+- [ ] Total stories ≤15
+- [ ] ralph_state.prd_path set in claude-progress.json
+- [ ] status.md updated with PRD reference
+- [ ] Vault indexed (automatic)
+
+## NON-GOALS
+- Does not execute stories — that is Ralph's job
+- Does not create plans — use `/plan` for that
+- Does not write specs or ADRs — use `/spec` for that
+
+---
+
+## Phase 1 — Gather Context
+
+1. Read `{vault_path}/status.md` — current state and active work
+2. Read `{vault_path}/_index.md` — project goals and metadata
+3. Ask the user:
+   - What is the PRD objective? (one sentence)
+   - What area of the codebase does this cover?
+   - Any known constraints or dependencies?
+
+## Phase 2 — Build Stories
+
+For each story, collect:
+- **Title**: short identifier (e.g., `add-auth-middleware`)
+- **As a**: role
+- **I want**: capability
+- **So that**: outcome
+- **Done when**: list of verifiable checks
+- **File group**: list of files (max 3 groups per story)
+- **Dependencies**: story-ids that must complete first, or "none"
+- **Estimate**: S / M / L
+
+Present stories in a table for user review before proceeding.
+
+## Phase 3 — Validate Against Ralph Constraints
+
+For each story, check:
+- Completable in ~10k output tokens
+- Touches ≤3 file groups
+- Requires ≤1 architectural decision
+- No cross-story reasoning required
+- Estimate is S or M (never L)
+
+Violations:
+- L estimate → STOP. Story must be split before PRD is written.
+- >3 file groups → STOP. Reduce scope or split.
+- Cross-story dependency chains → WARN. Ralph executes stories independently.
+- >15 stories total → suggest splitting into multiple PRDs.
+
+## Phase 4 — Write PRD
+
+Use `references/prd-template.md` as the canonical format.
+
+1. Fill all fields. No placeholders may remain.
+2. Scan the output for unreplaced `{placeholder}` patterns. Zero must survive.
+3. Write to: `{vault_path}/plans/{YYYY-MM-DD}_{kebab-title}-prd.md`
+
+## Phase 5 — Wire State
+
+1. Update `{vault_path}/status.md`:
+   - Set `current_plan:` to the PRD path
+   - Update `## Now What` with "PRD ready for Ralph execution"
+2. Update `{vault_path}/claude-progress.json`:
+   - Set `ralph_state.prd_path` to the PRD file path
+   - Set `ralph_state.mode` to "idle"
+   - Set `ralph_state.completed_stories` to `[]`
+   - Set `ralph_state.blocked_stories` to `[]`
+3. Report:
+   ```
+   ✓ PRD written:      {path}
+   ✓ Stories:           {n} (S: {n}, M: {n})
+   ✓ ralph_state:       prd_path set, mode idle
+   ✓ status.md:         updated
+
+   Next: run /ralph to begin autonomous execution.
+   ```
+
+## Error Handling
+
+| Condition | Action |
+|-----------|--------|
+| All stories marked L | Warn: "No stories are Ralph-suitable. Split or use GSD." |
+| >15 stories | Suggest splitting into 2+ PRDs |
+| Missing file groups | STOP. Every story needs a file group for Ralph |
+| User declines story edits | Write PRD as-is with warnings noted |
+| vault_path missing | Tell user to run install.sh |
+
+## Removal Condition
+Remove when PRD authoring is fully automated from issue trackers or when Ralph accepts unstructured input.

package/base/skills/prd-writer/references/prd-template.md

@@ -0,0 +1,22 @@
+---
+title: {PRD title}
+date: YYYY-MM-DD
+status: active
+stories_total: {n}
+---
+# PRD: {title}
+
+## Context
+Why this work exists. 1-3 sentences.
+
+## Stories
+
+### Story: {story-id}
+**As a**: {role}
+**I want**: {capability}
+**So that**: {outcome}
+**Done when**:
+- [ ] {verifiable check}
+**File group**: {list of files, max 3 groups}
+**Dependencies**: {story-ids that must complete first, or "none"}
+**Estimate**: S / M / L

package/base/skills/pre-commit-lint/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: pre-commit-lint
+disable-model-invocation: true
+description: Generate a stack-aware pre-commit hook script for a repo. Use when setting
+  up a new repo, when asked to "install pre-commit checks", "add linting to commits",
+  or "wire pre-commit-lint". Also invoked by scaffold-new Phase 5.5.
+  NOT invoked at commit time — generates a shell script that runs at commit time.
+allowed-tools: Bash, Read, Write, Edit
+---
+
+# pre-commit-lint Skill
+
+## WHAT
+A `.git/hooks/pre-commit` bash script that:
+1. Always runs: secret scan + git identity check
+2. Conditionally runs: stack-specific linters based on staged file extensions
+3. Hard blocks on secrets, identity mismatch, and critical lint failures
+4. Warns (exit 0) on missing optional tools
+
+## DONE-WHEN
+- [ ] `.git/hooks/pre-commit` exists and is executable
+- [ ] `bash -n .git/hooks/pre-commit` passes
+- [ ] Identity email hardcoded from repo CLAUDE.md
+- [ ] Script detects staged file types before running stack checks
+- [ ] All tool invocations guarded with `command -v <tool>`
+
+## CONSTRAINTS
+- Script must complete in <10 seconds
+- NEVER invoke `claude` inside the hook
+- Tool not found → WARN and skip, never block
+- Only block on: secrets, identity mismatch, syntax errors
+- Portable bash (no zsh-isms)
+
+---
+
+## Phase 0 — Detect Stack and Identity
+
+1. Read `{repo_root}/CLAUDE.md` → extract `{identity_email}` and `{stack}`
+2. Detect stack from repo: `git ls-files | grep -E "\.(tf|ps1|yml|py|ts|sh|go)$" | sed 's/.*\.//' | sort -u`
+3. Check tool availability: tflint, tfsec, actionlint, ruff, mypy, terraform, shellcheck
+
+## Phase 1 — Generate Hook
+
+Always include: preamble (helpers, staged file detection), identity check, secret scan.
+Append stack sections based on detected flags:
+- **Terraform**: fmt check, validate, layer boundary enforcement, tflint
+- **PowerShell**: StrictMode check, ErrorActionPreference check, PSScriptAnalyzer
+- **Shell**: bash -n syntax, set -euo check, shellcheck
+- **GitHub Actions**: actionlint, unpinned action check
+- **Python**: ruff, mypy
+Append summary footer.
+
+## Phase 2 — Write and Verify
+
+1. Scan for unreplaced `{placeholder}` patterns — resolve all
+2. Write to `{repo_root}/.git/hooks/pre-commit`
+3. `chmod +x`
+4. `bash -n` syntax validation
+5. Report: checks enabled, tools missing
+
+## Error Handling
+
+| Condition | Action |
+|-----------|--------|
+| CLAUDE.md missing Identity | Ask user for email |
+| `bash -n` fails | Fix before writing |
+| `.git/` not found | STOP — not a git repo |
+| All tools missing for stack | Warn, generate with skip guards |
+
+## Removal Condition
+Remove when hooks managed globally via dotfiles bootstrap.

package/base/skills/scaffold-exist/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: scaffold-exist
+disable-model-invocation: true
+description: Scaffold an existing project into the full harness. Invoke with /scaffold-exist only.
+  Adds missing harness files to projects that predate the scaffold standard.
+  Non-destructive — never overwrites without confirmation. Side-effect skill — never auto-triggers.
+---
+
+# scaffold-exist Skill
+
+## Vault Path Resolution
+Read vault_path from `~/.claude/praxis.config.json`. If missing: STOP.
+
+## WHAT
+Bring an existing project into full harness compliance without disrupting active work.
+
+## DONE-WHEN
+- [ ] `{vault_path}/status.md` exists with correct structure
+- [ ] `{vault_path}/tasks.md` exists
+- [ ] `{vault_path}/claude-progress.json` exists
+- [ ] `{vault_path}/specs/` and `research/` directories exist
+- [ ] `{vault_path}/_index.md` has `local_path` matching actual repo path
+- [ ] Repo `CLAUDE.md` has `## Vault Project` section
+- [ ] Repo `CLAUDE.md` has bootstrap sequence
+- [ ] Project Registry row is accurate
+
+## CONSTRAINTS
+- NEVER delete existing vault content — only add missing files
+- NEVER overwrite without explicit user confirmation
+- Read `_index.md` to resolve metadata — do not ask for info already there
+
+## NON-GOALS
+- Does not reformat existing vault notes
+- Does not touch existing specs/, research/, notes/ content
+- Does not change git history or branch structure
+
+---
+
+## Phase 0 — Audit
+
+Ask user: which project? (slug or vault path)
+Compute vault_path from config. Run: `ls -la {vault_path}/`
+
+Build and show audit table:
+
+| File/Dir | Exists? | Action |
+|----------|---------|--------|
+| `_index.md` | ? | Verify `local_path` field |
+| `status.md` | ? | Create if missing |
+| `tasks.md` | ? | Create if missing |
+| `claude-progress.json` | ? | Create if missing |
+| `plans/` | ? | Create if missing |
+| `specs/` | ? | Create if missing |
+| `research/` | ? | Create if missing |
+| `notes/learnings.md` | ? | Create if missing |
+| Repo CLAUDE.md sections | ? | Add missing sections |
+| Registry row | ? | Verify accuracy |
+
+**Get user confirmation before Phase 1.**
+
+## Phase 1 — Resolve Metadata
+Read `_index.md`, extract project name, slug, repo_root, type, stack, repo_url.
+Verify repo_root exists on disk.
+
+## Phase 2 — Create Missing Vault Files
+Use same templates as scaffold-new (`references/` dir). Existing files untouched.
+Vault indexing is automatic.
+
+## Phase 3 — Update Repo CLAUDE.md
+If missing: create from template. If exists: add only missing sections (Vault Project, bootstrap, Identity). Preserve existing content.
+
+## Phase 4 — Verify Project Registry
+Read vault CLAUDE.md registry. Row missing → append. Row inaccurate → update.
+
+## Error Handling
+
+| Condition | Action |
+|-----------|--------|
+| `_index.md` missing | STOP — run scaffold-new instead |
+| `local_path` doesn't exist | Warn, ask for correct path |
+| Existing file would be overwritten | Ask explicit confirmation |
+| Vault search fails | Warn only |
+
+## Removal Condition
+Remove when all active projects are migrated and scaffold-new is the only entry path.