@esoteric-logic/praxis-harness 2.0.0 → 2.0.2

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

@@ -0,0 +1,69 @@
+---
+name: plan-writer
+disable-model-invocation: true
+description: "Writes a dated work plan to the vault plans/ directory. Creates the plan file with YAML frontmatter, milestones, and acceptance criteria. Updates status.md current_plan field. Called by /plan and /discuss workflows."
+---
+
+# plan-writer Skill
+
+## Inputs
+
+| Input | Required | Source |
+|-------|----------|--------|
+| SPEC block | Yes | From `/discuss` output or user-provided scope |
+| vault_path | Yes | From `~/.claude/praxis.config.json` |
+| project_slug | Yes | From CWD → `_index.md` detection |
+
+## Output
+
+A plan file at `{vault_path}/plans/{YYYY-MM-DD}_{task-slug}.md`
+
+## Plan File Format
+
+```markdown
+---
+tags: [plan, {project-slug}]
+date: {YYYY-MM-DD}
+status: active
+source: agent
+---
+
+# Plan: {task title}
+
+## SPEC
+PROBLEM: {from discuss}
+DELIVERABLE: {from discuss}
+ACCEPTANCE: {from discuss}
+BOUNDARIES: {from discuss}
+
+## Milestones
+
+### M1 — {milestone title}
+- [ ] {step}
+- [ ] {step}
+**Acceptance:** {how to verify this milestone}
+
+### M2 — {milestone title}
+...
+
+## Verification
+{end-to-end checks that prove the plan is complete}
+```
+
+## Steps
+
+1. Read vault_path from config
+2. Detect project from CWD matching `local_path` in vault `_index.md`
+3. Generate task slug from the SPEC PROBLEM field (kebab-case, max 40 chars)
+4. Write the plan file with frontmatter
+5. Update `status.md`:
+   - Set `current_plan:` to the plan file path
+   - Set `loop_position: PLAN`
+   - Set `last_updated:` to today
+
+## Constraints
+
+- Each milestone must be independently verifiable
+- Max 5 milestones per plan — if more are needed, split into sub-plans
+- Never write a milestone without acceptance criteria
+- Plan files are immutable once execution starts — create a new plan for scope changes

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

@@ -1,11 +1,7 @@
 ---
 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
+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."
 ---
 
 # pre-commit-lint Skill

package/base/{commands/quick.md → skills/quick/SKILL.md}

@@ -1,4 +1,6 @@
 ---
+name: quick
+disable-model-invocation: true
 description: Ad-hoc task with full quality guarantees in a single compressed flow. Use for tasks that need planning but aren't worth the full loop.
 ---
 

package/base/{commands/review.md → skills/review/SKILL.md}

@@ -1,7 +1,11 @@
 ---
-description: Manual code review trigger. Launches a subagent to review a diff for bugs, security, and convention violations. Use independently of Praxis phases.
+name: review
+disable-model-invocation: true
+description: "Manual code review trigger. Launches a subagent to review a diff for bugs, security, and convention violations. Use independently of Praxis phases."
 ---
 
+# review Skill
+
 You are running a manual code review.
 
 **Step 1 — Determine diff scope**
@@ -21,7 +25,7 @@ Ask: "Review staged changes, last commit, or specific SHA?"
   - `.tf` / `.tfvars` → `~/.claude/rules/terraform.md`
   - `.yml` / `.yaml` in `.github/` → `~/.claude/rules/github-actions.md`
   - `.ps1` / `.psm1` → `~/.claude/rules/powershell.md`
-  - Any file → `~/.claude/rules/coding.md`, `~/.claude/rules/security.md`
+  - Any file → `~/.claude/rules/coding.md`
 
 **Step 4 — Launch subagent review**
 Launch a subagent with ONLY these inputs (zero conversation history):
@@ -30,13 +34,17 @@ Launch a subagent with ONLY these inputs (zero conversation history):
 - Relevant rules files (from Step 3)
 
 Subagent prompt:
-> Review this diff for bugs, edge cases, error handling gaps, security issues,
-> and convention violations. Rate each finding:
-> Critical / Major / Minor.
+> You are a critical code reviewer. Review this diff for bugs, edge cases,
+> error handling gaps, security issues, and convention violations.
+> Rate each finding: Critical / Major / Minor.
 > Format: `{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.
 
 **Step 5 — Present findings**
-Structure output by severity:
+Parse the subagent output and structure by severity:
 
 ```
 ━━━ REVIEW RESULTS ━━━
@@ -72,10 +80,25 @@ CLEAN
   source: agent
   ---
   ```
-- Vault indexing is automatic.
 
-**Rules:**
+## Error Handling
+
+| Condition | Action |
+|-----------|--------|
+| Empty diff | "Nothing to review." Exit. |
+| Subagent fails to launch | Return error, do not retry |
+| Subagent output unparseable | Return raw output as single Minor finding |
+| Rules file missing | Warn, proceed with available rules |
+
+## Callers
+
+| Caller | Context |
+|--------|---------|
+| User via `/review` | Manual review trigger |
+| `/verify` Step 5 | Post-milestone Self-Review Protocol |
+| `execution-loop.md` | Self-Review Protocol reference |
+
+## Rules
 - Works independently of Praxis phases.
 - Never skip the subagent — review must come from fresh context.
 - Subagent receives zero conversation history.
-- If no project CLAUDE.md exists: proceed with base rules only.

package/base/{commands/risk.md → skills/risk/SKILL.md}

@@ -1,4 +1,6 @@
 ---
+name: risk
+disable-model-invocation: true
 description: Add a new risk register entry to the current project vault. Assigns a risk ID, severity, mitigation, and writes to specs/risk-register.md.
 ---
 

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

@@ -1,9 +1,7 @@
 ---
 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.
+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

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

@@ -1,9 +1,7 @@
 ---
 name: scaffold-new
 disable-model-invocation: true
-description: Scaffold a brand new project into the full harness. Invoke with /scaffold-new only.
-  Creates repo CLAUDE.md, vault subtree, git identity verification, gitignore,
-  pre-commit hook, and Project Registry entry. Side-effect skill — never auto-triggers.
+description: "Scaffold a brand new project into the full harness. Invoke with /scaffold-new only. Creates repo CLAUDE.md, vault subtree, git identity verification, gitignore, pre-commit hook, and Project Registry entry. Side-effect skill — never auto-triggers."
 ---
 
 # scaffold-new Skill
@@ -14,7 +12,6 @@ If config is missing: STOP. Tell user to run `praxis/install.sh`.
 
 ## Boundaries — Rules Loading
 - Do NOT load `git-workflow.md` — identity and init handled inline
-- Do NOT load `security.md` — not relevant during scaffolding
 - Do NOT load `terraform.md` or `github-actions.md` — no infra files touched
 
 ## Overview

package/base/skills/secret-scan/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: secret-scan
+description: "Canonical secret scanning skill. Scans files for credential patterns (API keys, tokens, connection strings). Called by pre-commit-lint and ship workflows. Also usable standalone for repo-wide audits. Replaces all inline secret scan regex instances with a single authoritative source."
+---
+
+# secret-scan Skill
+
+## The Pattern
+
+Single authoritative regex for all secret detection in Praxis:
+
+```
+(sk-|ghp_|pplx-|AKIA|Bearer [A-Za-z0-9+/]{20,}|DefaultEndpointsProtocol|AccountKey=)
+```
+
+Covers: OpenAI (`sk-`), GitHub PAT (`ghp_`), Perplexity (`pplx-`), AWS (`AKIA`),
+Bearer tokens, Azure Storage connection strings.
+
+## Modes
+
+### Staged files (pre-commit)
+```bash
+rg "(sk-|ghp_|pplx-|AKIA|Bearer [A-Za-z0-9+/]{20,}|DefaultEndpointsProtocol|AccountKey=)" $(git diff --staged --name-only)
+```
+
+### Full repo audit
+```bash
+rg "(sk-|ghp_|pplx-|AKIA|Bearer [A-Za-z0-9+/]{20,}|DefaultEndpointsProtocol|AccountKey=)" --glob "!*.lock" .
+```
+
+### .env files check
+```bash
+git diff --staged --name-only | grep -E "\.env$|\.env\."
+```
+
+## Invocation
+
+| Caller | When |
+|--------|------|
+| `secret-scan.sh` hook | PreToolUse on Write/Edit |
+| `pre-commit-lint` skill | Before every commit |
+| `/ship` workflow | Pre-flight Step 1 |
+| Manual `/secret-scan` | On-demand repo audit |
+
+## On Detection
+
+1. Report file path and line number of each match.
+2. BLOCK — do not proceed until the secret is removed or confirmed false positive.
+3. If the match is in a regex pattern itself (e.g., in a rules file defining the scan):
+   that is a false positive — skip it.
+
+## Extending the Pattern
+
+To add new credential patterns, update the regex in this skill.
+All callers reference this skill as the canonical source.

package/base/skills/session-retro/SKILL.md

@@ -1,10 +1,7 @@
 ---
 name: session-retro
 disable-model-invocation: true
-description: End-of-session retrospective. Invoke manually with /session-retro only.
-  Writes [LEARN:tag] entries, proposes rule updates, updates claude-progress.json,
-  triggers vault-gc lightweight check. Side-effect skill — never auto-triggers.
-allowed-tools: Bash, Read, Write, Edit
+description: "End-of-session retrospective. Invoke manually with /session-retro only. Writes [LEARN:tag] entries, proposes rule updates, updates claude-progress.json, triggers vault-gc lightweight check. Side-effect skill — never auto-triggers."
 ---
 
 # session-retro Skill

package/base/{commands/ship.md → skills/ship/SKILL.md}

@@ -1,4 +1,6 @@
 ---
+name: ship
+disable-model-invocation: true
 description: Commit, push, and open a PR in one shot. Runs pre-commit checks, crafts a commit message, pushes, and creates a PR with structured description. Use when a milestone or feature is complete and verified.
 ---
 
@@ -7,7 +9,7 @@ You are running the ship workflow — commit, push, and PR in one command.
 **Step 1 — Pre-flight checks**
 - Read project CLAUDE.md for build/test/lint commands
 - Run in order (all must pass):
-  1. Secret scan: `rg "(sk-|ghp_|pplx-|AKIA|Bearer [A-Za-z0-9+/]{20,})" $(git diff --staged --name-only)`
+  1. Secret scan: `rg "(sk-|ghp_|pplx-|AKIA|Bearer [A-Za-z0-9+/]{20,}|DefaultEndpointsProtocol|AccountKey=)" $(git diff --staged --name-only)`
   2. Linter (from CLAUDE.md `## Commands`)
   3. Typecheck (if applicable)
   4. Test suite (from CLAUDE.md `## Commands`)

package/base/skills/{code-simplifier → simplify}/SKILL.md

@@ -1,13 +1,10 @@
 ---
-name: code-simplifier
+name: simplify
 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
+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."
 ---
 
-# code-simplifier Skill
+# simplify Skill
 
 ## Vault Path Resolution
 Read vault_path from `~/.claude/praxis.config.json`.

package/base/{commands/spec.md → skills/spec/SKILL.md}

@@ -1,4 +1,6 @@
 ---
+name: spec
+disable-model-invocation: true
 description: Create a structured spec or ADR for the current project. Writes to vault specs/ directory. Use for architecture decisions, technical designs, and risk documentation — NOT for task framing (use /discuss for that).
 ---
 

package/base/{commands/standup.md → skills/standup/SKILL.md}

@@ -1,4 +1,6 @@
 ---
+name: standup
+disable-model-invocation: true
 description: Generate a standup summary for the current project. Reads status.md, tasks.md, and active plan. Use at the start or end of any working session.
 ---
 

package/base/skills/status-update/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: status-update
+disable-model-invocation: true
+description: "Atomic update to vault status.md. Ensures consistent format, enforces the 100-line limit, and archives resolved items. Called at milestone boundaries, session end, and phase transitions."
+---
+
+# status-update Skill
+
+## Required Fields (top of status.md, always present)
+
+```yaml
+current_plan: {path or "none"}
+last_updated: {YYYY-MM-DD}
+last_session: {ISO timestamp}
+loop_position: DISCUSS | PLAN | EXECUTE | VERIFY | IDLE
+```
+
+## Steps
+
+1. Read vault_path from `~/.claude/praxis.config.json`
+2. Read current `{vault_path}/status.md`
+3. Update the required fields at the top
+4. Add or update the What / So What / Now What section:
+   - **What**: Facts only — what was done, what exists now
+   - **So What**: Why it matters — blockers, risks, progress
+   - **Now What**: Next actions, ordered by priority
+5. Check line count — if >100 lines, archive resolved sections:
+   - Move completed What/So What/Now What blocks to `{vault_path}/notes/{date}_status-archive.md`
+   - Keep only active/unresolved items in status.md
+6. Write the updated file
+
+## When to Call
+
+| Trigger | What to Update |
+|---------|---------------|
+| Milestone complete | Add accomplishment to What, advance Now What |
+| Phase transition | Update `loop_position` |
+| Session end | Update `last_session`, write current state |
+| Blocker hit | Add blocker to So What, propose resolution in Now What |
+| Plan created/changed | Update `current_plan` |
+
+## Constraints
+
+- status.md must stay under 100 lines — archive aggressively
+- Never delete content — always archive to notes/
+- A status.md older than 14 days is stale — vault-gc flags these
+- Use `[[wikilinks]]` for all internal vault references

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

@@ -1,10 +1,7 @@
 ---
 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
+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."
 ---
 
 # vault-gc Skill

package/base/{commands/verify.md → skills/verify/SKILL.md}

@@ -1,4 +1,6 @@
 ---
+name: verify
+disable-model-invocation: true
 description: Validation phase — runs test/lint/typecheck/build and reports PASS or FAIL. Use after each milestone completion.
 ---
 

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

@@ -1,11 +1,7 @@
 ---
 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
+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."
 ---
 
 # verify-app Skill

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@esoteric-logic/praxis-harness",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "description": "Layered Claude Code harness — workflow discipline, AI-Kits, persistent vault integration",
   "bin": {
     "praxis-harness": "./bin/praxis.js"

package/scripts/lint-harness.sh

@@ -46,7 +46,7 @@ fi
 
 # ─── 2. Skill frontmatter ───
 echo ""
-echo "Skills (name:, disable-model-invocation:, description:):"
+echo "Skills (name:, description:):"
 if [[ -d "$REPO_PATH/base/skills" ]]; then
   for skill_dir in "$REPO_PATH"/base/skills/*/; do
     [[ -d "$skill_dir" ]] || continue
@@ -60,10 +60,14 @@ if [[ -d "$REPO_PATH/base/skills" ]]; then
     header=$(head -10 "$skill_file")
     missing=""
     echo "$header" | grep -q "^name:" || missing="$missing name:"
-    echo "$header" | grep -q "^disable-model-invocation:" || missing="$missing disable-model-invocation:"
     echo "$header" | grep -q "^description:" || missing="$missing description:"
     if [[ -z "$missing" ]]; then
-      ok "skills/$skill_name"
+      # Note auto-invocable skills (no disable-model-invocation)
+      if echo "$header" | grep -q "^disable-model-invocation:"; then
+        ok "skills/$skill_name"
+      else
+        ok "skills/$skill_name (auto-invocable)"
+      fi
     else
       error "skills/$skill_name SKILL.md missing:$missing"
     fi

package/base/commands/simplify.md

@@ -1,15 +0,0 @@
----
-description: Post-implementation code cleanup. Launches a subagent to find and
-  simplify over-abstraction, dead paths, verbosity, and missed idioms in the
-  recent diff. Run after implementation, before /verify-app or /ship.
----
-
-Invoke the code-simplifier skill on the current project's recent changes.
-
-Accept an optional scope argument:
-- No argument → `git diff HEAD~1` (default)
-- `staged` → staged changes only
-- `HEAD~N` or SHA → specific range
-
-The code-simplifier skill handles all phases: scope detection, subagent launch,
-finding presentation, user-approved edits, and optional [LEARN:simplify] capture.

package/base/rules/code-quality.md

@@ -1,65 +0,0 @@
-# Code Quality — Rules
-# Scope: All projects, all sessions
-# Complements `coding.md` with structural quality thresholds.
-
-## Invariants — BLOCK on violation
-
-### No deep nesting
-- Conditionals nested >3 levels deep must be refactored (extract function, early return, guard clause).
-- Applies to if/else, try/catch, loops, and match/switch statements.
-
-### Cyclomatic complexity
-- Functions with cyclomatic complexity >15: BLOCK. Refactor before commit.
-- Measure by counting decision points (if, else if, for, while, case, &&, ||, catch).
-
-### Public function documentation
-- All public functions and methods must have doc comments.
-- Doc comments describe intent and constraints, not implementation.
-- Internal/private helpers: doc comments optional, but name must be self-describing.
-
-### No commented-out code
-- No commented-out code blocks in committed files.
-- Dead code belongs in git history, not in source files.
-- `// TODO:` and `// FIXME:` are annotations, not commented-out code — these are allowed.
-
----
-
-## Conventions — WARN on violation
-
-### Complexity awareness
-- Cyclomatic complexity >10: WARN. Consider splitting the function.
-- Functions longer than 50 lines: review for single-responsibility violation.
-
-### No magic numbers
-- No magic numbers without a named constant and a comment explaining the value.
-- Exception: 0, 1, -1, and values obvious from immediate context (e.g., `array.length - 1`).
-
-### Single responsibility
-- Each function does one thing. If the description requires "and", split it.
-- Each file has one primary concern. Utility grab-bags indicate missing abstractions.
-
-### No hardcoded environment values
-- No hardcoded URLs, ports, hostnames, or credentials specific to an environment.
-- Use environment variables, config files, or parameter injection.
-- Cross-ref: `coding.md` — No hardcoded values invariant.
-
----
-
-## Verification Commands
-
-```bash
-# Find deeply nested blocks (rough heuristic — look for 4+ indent levels)
-rg '^\s{16,}(if|for|while|try)' --type-add 'code:*.{ts,js,py,go,rs}' -t code
-
-# Find commented-out code blocks (multi-line)
-rg '^\s*//\s*(const|let|var|function|class|import|return|if|for)' --type-add 'code:*.{ts,js}' -t code
-rg '^\s*#\s*(def |class |import |return |if |for )' -t py
-
-# Find magic numbers in staged files
-git diff --staged | grep -E '[^0-9][2-9][0-9]{2,}[^0-9]' | grep -v 'const\|#\|//'
-```
-
----
-
-## Removal Condition
-Permanent. Structural quality thresholds apply regardless of project or language.

package/base/rules/security.md

@@ -1,40 +0,0 @@
-# Security — Rules
-# Scope: All projects, all sessions
-
-## Invariants (BLOCK on violation)
-
-### Secrets
-- NEVER hardcode secrets — no API keys, tokens, passwords, connection strings in code.
-  Use environment variables or a secrets manager.
-- If a secret is found in code: flag immediately, do not proceed until remediated.
-- Pre-commit scan (always): `rg "(sk-|ghp_|pplx-|AKIA|Bearer [A-Za-z0-9+/]{20,})" $(git diff --staged --name-only)`
-- Secrets in logs: never log request bodies, headers, or responses that may contain credentials. Redact before logging.
-
-### Input Validation
-- Validate all inputs at boundaries — APIs, user input, file uploads, environment variables.
-- Never trust external data without validation.
-- Validate response shape, not just status code — 200 with error body is a silent failure.
-
-### Permissions
-- Least privilege — request only permissions and scopes needed.
-- No wildcard IAM policies. No `chmod 777`.
-- GitHub Actions: pin action versions to commit SHA, not tags.
-
-## Conventions (WARN on violation)
-
-### Dependencies
-- Audit new dependencies before adding: `npm audit`, `pip audit`, or equivalent.
-- Check for known CVEs before adding any package.
-- Pin to exact versions. No floating ranges in production.
-
-## Verification Commands
-```bash
-# Secret scan staged files
-rg "(sk-|ghp_|pplx-|AKIA|Bearer [A-Za-z0-9+/]{20,})" $(git diff --staged --name-only)
-
-# Secret scan entire repo (audit mode)
-rg "(sk-|ghp_|pplx-|AKIA|Bearer [A-Za-z0-9+/]{20,})" --glob "!*.lock" .
-
-# Check for .env files accidentally staged
-git diff --staged --name-only | grep -E "\.env$|\.env\."
-```