@esoteric-logic/praxis-harness 1.1.0

package/base/skills/subagent-review/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: subagent-review
+disable-model-invocation: true
+description: Reusable code review subagent. Accepts a diff, optional spec, and rules
+  files. Launches a subagent with zero conversation history to review for bugs,
+  security, and convention violations. Called by /review and gsd-verify — never
+  invoked directly by users.
+allowed-tools: Bash, Read
+---
+
+# subagent-review Skill
+
+## Purpose
+Encapsulates the Self-Review Protocol as a reusable skill. Callers provide the
+diff and context; this skill launches the subagent and returns structured findings.
+
+## Inputs
+
+| Input | Required | Default | Description |
+|-------|----------|---------|-------------|
+| diff | Yes | — | The diff to review (string or file path) |
+| spec_path | No | — | Path to the SPEC/plan for context |
+| rules_files | No | `CLAUDE.md`, `coding.md`, `security.md` | Rules files to load |
+
+## DONE-WHEN
+- [ ] Subagent launched with ONLY diff + spec + rules (zero conversation history)
+- [ ] Findings returned in structured format
+- [ ] Each finding rated Critical / Major / Minor
+
+## NON-GOALS
+- Does NOT fix findings — callers handle remediation
+- Does NOT write to vault — callers decide what to persist
+- Does NOT interact with the user — callers present findings
+
+---
+
+## Phase 1 — Validate Inputs
+
+- Diff must be non-empty. If empty: return `{ "findings": [], "status": "empty_diff" }`.
+- If spec_path provided: verify the file exists. If not: proceed without spec.
+- If rules_files not provided: default to:
+  - `~/.claude/CLAUDE.md`
+  - `~/.claude/rules/coding.md`
+  - `~/.claude/rules/security.md`
+
+## Phase 2 — Compose Subagent Prompt
+
+Build the subagent prompt from these components ONLY:
+
+```
+You are a critical code reviewer. Review the following diff.
+
+## Rules
+{contents of each rules file}
+
+## SPEC (if available)
+{contents of spec file, or "No spec provided."}
+
+## Diff
+{the diff}
+
+## Instructions
+Review for:
+1. Bugs and logic errors
+2. Edge cases and off-by-one errors
+3. Error handling gaps (missing catches, swallowed errors)
+4. Security issues (injection, secrets, auth gaps)
+5. Convention violations (from the Rules above)
+
+Rate each finding: Critical / Major / Minor.
+Format each as: `{file}:{line} — {severity} — {description} — {fix}`
+
+If the diff is clean, say "No findings."
+```
+
+Do NOT include any conversation history, project context, or user preferences
+beyond the explicitly provided inputs.
+
+## Phase 3 — Launch Subagent
+
+- Launch a subagent (Task tool) with the composed prompt.
+- The subagent runs in isolation — fresh context, no memory of the current session.
+
+## Phase 4 — Return Structured Findings
+
+Parse the subagent output into:
+
+```json
+{
+  "status": "findings" | "clean" | "empty_diff",
+  "critical": [{ "file": "", "line": 0, "description": "", "fix": "" }],
+  "major": [{ "file": "", "line": 0, "description": "", "fix": "" }],
+  "minor": [{ "file": "", "line": 0, "description": "", "fix": "" }],
+  "summary": "1 critical, 2 major, 0 minor"
+}
+```
+
+Return this structure to the caller. The caller decides:
+- Whether to present findings to the user
+- Whether to trigger remediation
+- Whether to re-run (max 3 rounds, managed by caller)
+
+## Callers
+
+| Caller | Context |
+|--------|---------|
+| `/review` (commit 6) | Manual review trigger, writes summary to vault |
+| `gsd-verify` Step 5 | Post-milestone Self-Review Protocol |
+| `execution-loop.md` | Self-Review Protocol description (future: replace inline with skill ref) |
+
+Note: `execution-loop.md` and `gsd-verify.md` still contain inline descriptions of the
+review pattern. Future cleanup can replace those with a reference to this skill. Both
+approaches produce identical behavior — the duplication is accepted for now.
+
+## Error Handling
+
+| Condition | Action |
+|-----------|--------|
+| Empty diff | Return `empty_diff` status immediately |
+| Subagent fails to launch | Return error to caller, do not retry |
+| Subagent output unparseable | Return raw output as single Minor finding |
+| Rules file missing | Warn, proceed with available rules |
+
+## Removal Condition
+Remove when code review is fully handled by a dedicated external service
+integrated via MCP, making subagent-based review redundant.

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

@@ -0,0 +1,93 @@
+---
+name: vault-gc
+disable-model-invocation: true
+description: Audit vault health and detect entropy. Invoke manually with /vault-gc
+  only. Two modes — full audit (manual) and lightweight staleness check (called
+  inline by session-retro). Never auto-deletes. Side-effect skill — never auto-triggers.
+allowed-tools: Bash, Read, Write
+---
+
+# vault-gc Skill
+
+## Vault Path Resolution
+Read vault_path from `~/.claude/praxis.config.json`. Scan projects under `{vault_path}/01_Projects/`.
+
+## Two Modes
+
+| Mode | Trigger | Scope | Output |
+|------|---------|-------|--------|
+| **Lightweight** | Called by session-retro | Staleness check only | One line or silence |
+| **Full Audit** | Manual `/vault-gc` | All entropy categories | Prioritized report |
+
+---
+
+## Mode A — Lightweight
+
+Scan `last_updated` from every `status.md` in active project directories.
+Flag any project >14 days stale.
+
+- Silent if 0 stale
+- One line if 1–2: `⚠ vault-gc: 2 projects stale (project-a, project-b)`
+- Escalate if 3+: `⚠ vault-gc: {N} projects stale — run /vault-gc for details`
+- Exit 0 always — never block the session
+
+---
+
+## Mode B — Full Audit
+
+### Check 1: Stale Projects
+For each project in active directories:
+- CRITICAL: >60 days stale
+- HIGH: 30–60 days stale
+- MEDIUM: 14–30 days stale
+
+### Check 2: Orphan Plans
+Plans in `plans/` not referenced by `current_plan:` in `status.md`,
+and not status: completed or archived.
+
+### Check 3: Vault↔Repo Drift
+Projects with `local_path` in `_index.md` where the repo no longer exists on disk,
+or repo exists but is missing CLAUDE.md.
+
+### Check 4: Secret Exposure Scan
+Scan last 10 commits across all active repos for accidental secret patterns.
+
+### Report Format
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  VAULT GC — Full Audit  ({today_date})
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+CRITICAL ({n})
+  ✗ [secret-exposure] project-a — potential secret in last 10 commits
+  ✗ [stale] project-b — 72 days since last update
+
+HIGH ({n})
+  ✗ [repo-drift] project-c — local_path not found
+
+MEDIUM ({n})
+  ⚠ [orphan-plan] project-d — old-plan.md (status: active, not current)
+
+CLEAN ({n} projects)
+  ✓ project-e, project-f
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  {total} findings  |  {clean} clean
+  vault-gc never auto-deletes — act on findings manually
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+After report: ask user if they want to address any specific finding.
+Do NOT auto-remediate.
+
+## Error Handling
+
+| Condition | Action |
+|-----------|--------|
+| `status.md` missing | Use `_index.md` mtime as fallback |
+| `last_updated` malformed | Skip project, note in report |
+| `local_path` expansion fails | Skip drift check, note in report |
+| `git log` fails | Skip secret scan, note in report |
+
+## Removal Condition
+Remove when a dedicated vault health dashboard covers all four entropy categories.

package/base/skills/verify-app/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: verify-app
+disable-model-invocation: true
+description: End-to-end application verification. Launches a subagent to run the full
+  test suite, check build, verify runtime behavior, and confirm acceptance criteria.
+  Use after implementation to catch integration issues that unit tests miss.
+  Side-effect skill — never auto-triggers.
+allowed-tools: Bash, Read
+---
+
+# verify-app 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
+- [ ] Full test suite passes (not just changed tests)
+- [ ] Build succeeds with zero warnings
+- [ ] Lint passes with zero warnings
+- [ ] Typecheck passes (if applicable)
+- [ ] Acceptance criteria verified (from active plan done-when)
+- [ ] No regressions detected in related functionality
+- [ ] Verification report written
+
+## NON-GOALS
+- Does not fix issues — reports them for the user to address
+- Does not modify code
+- Does not deploy or publish
+
+---
+
+## Phase 1 — Load Verification Context
+
+- Read project CLAUDE.md `## Commands` section for test/build/lint commands
+- If no commands defined: STOP. Ask user for the correct commands.
+- Read active plan (if `current_plan:` set in status.md) — extract `## Done When` criteria
+- Read `claude-progress.json` for current milestone context
+
+## Phase 2 — Run Verification Suite
+
+Execute in order, capturing ALL output:
+
+### 2a — Build
+```bash
+{build_command from CLAUDE.md}
+```
+- PASS: zero exit code, zero warnings
+- FAIL: capture full error output
+
+### 2b — Lint
+```bash
+{lint_command from CLAUDE.md}
+```
+- PASS: zero exit code, zero warnings
+- FAIL: capture warnings/errors with file:line
+
+### 2c — Typecheck
+```bash
+{typecheck_command from CLAUDE.md}
+```
+- PASS: zero exit code
+- FAIL: capture type errors
+- SKIP: if no typecheck command configured
+
+### 2d — Test Suite
+```bash
+{test_command from CLAUDE.md}
+```
+- PASS: all tests pass
+- FAIL: capture failing test names + error output
+
+### 2e — Acceptance Criteria
+For each item in the plan's `## Done When`:
+- If it's a command: run it and check output
+- If it's a manual check: present to user for confirmation
+- If it's a URL or UI check: ask user to verify
+- Mark each criterion: PASS / FAIL / NEEDS HUMAN
+
+## Phase 3 — Regression Check
+
+Launch a subagent with zero conversation history:
+
+```
+You are a regression analyst. Given the following changes and test results,
+identify potential regressions in related functionality.
+
+## Recent changes
+{git diff HEAD~1 --stat}
+
+## Changed files
+{list of modified files}
+
+## Test output
+{test suite output}
+
+## Questions to answer:
+1. Are there changed files with no corresponding test coverage?
+2. Do any changed files have downstream consumers that weren't tested?
+3. Are there integration points (API boundaries, shared state, event handlers)
+   that the unit tests might miss?
+4. Based on the file names and structure, what manual checks would you recommend?
+
+Format each concern as:
+- {file} — {concern} — {recommended verification step}
+```
+
+## Phase 4 — Report
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  VERIFY-APP — {project} ({date})
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  Build:        {PASS | FAIL}
+  Lint:         {PASS | FAIL | {n} warnings}
+  Typecheck:    {PASS | FAIL | SKIP}
+  Tests:        {PASS | FAIL — {n}/{total} passed}
+
+  Acceptance Criteria:
+  {criterion 1}:  {PASS | FAIL | NEEDS HUMAN}
+  {criterion 2}:  {PASS | FAIL | NEEDS HUMAN}
+
+  Regression Concerns:
+  {file} — {concern}
+
+  Overall:      {READY TO SHIP | ISSUES FOUND}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## Phase 5 — Guidance
+
+- **READY TO SHIP**: "All checks pass. Run `/ship` to commit, push, and PR."
+- **ISSUES FOUND**: List each issue with recommended fix. Do not attempt to fix.
+- **NEEDS HUMAN**: List what the user needs to manually verify.
+
+## Error Handling
+
+| Condition | Action |
+|-----------|--------|
+| No test command | STOP. Ask user for commands. |
+| Build/test command crashes | Report crash, suggest checking deps |
+| No active plan | Run checks without acceptance criteria |
+| All checks pass but regression concerns exist | Report as READY with caveats |
+
+## Integration Points
+
+| Caller | When |
+|--------|------|
+| Manual `/verify-app` | After any implementation |
+| `/gsd:verify` | Can replace or complement Step 1 |
+| Ralph iteration | After story completion |
+
+## Removal Condition
+Remove when CI/CD pipeline covers all verification steps and results are
+accessible via MCP or CLI, making local verification redundant.