@esoteric-logic/praxis-harness 2.0.3 → 2.1.1

package/README.md

@@ -17,16 +17,18 @@ Praxis gives Claude Code a three-layer operating system:
 ## Quick start
 
 ```bash
-npx praxis-harness
+npx @esoteric-logic/praxis-harness@latest
 ```
 
 One command. Copies rules, commands, skills, and kits directly into `~/.claude/`. Node.js 18+ must be installed first.
 
+> **Always use `@latest`** — `npx` caches packages locally. Without `@latest`, you may get a stale version on machines that installed previously.
+
 **Subsequent commands:**
 ```bash
-npx praxis-harness update      # re-copy from latest npm version
-npx praxis-harness health      # verify install integrity
-npx praxis-harness uninstall   # remove Praxis-owned files from ~/.claude/
+npx @esoteric-logic/praxis-harness@latest update      # re-copy from latest npm version
+npx @esoteric-logic/praxis-harness@latest health      # verify install integrity
+npx @esoteric-logic/praxis-harness@latest uninstall   # remove Praxis-owned files from ~/.claude/
 ```
 
 ## After install
@@ -66,7 +68,12 @@ For technical research: `/discover` (structured options evaluation before decisi
 | `risk` | Add a risk register entry to the vault |
 | `kit` | Activate/deactivate an AI-Kit |
 | `review` | Manual code review via subagent |
+| `simplify` | Post-implementation code simplification via subagent |
 | `debug` | Structured test-first debugging |
+| `ship` | Commit, push, and PR in one command with pre-flight checks |
+| `verify-app` | End-to-end verification with regression analysis |
+| `session-retro` | End-of-session retrospective with learnings extraction |
+| `status-update` | Manual vault status.md update |
 | `context-reset` | Reload context from vault without clearing session |
 
 ## Rules
@@ -126,18 +133,64 @@ The vault path is configured per machine during install:
 
 Requires [Obsidian CLI](https://obsidian.md) (enable in Obsidian Settings > General > Command line interface). Obsidian must be running for vault search.
 
+### What gets documented automatically
+
+Praxis auto-documents your work in the vault with zero manual effort. Two independent layers ensure nothing is lost:
+
+1. **Shell hooks** capture facts (git state, timestamps) even if Claude runs out of context
+2. **Stop prompt** captures meaning (summaries, decisions, learnings) from conversation context
+
+**At session end** (zero action needed):
+- `status.md` — updated with What/So What/Now What
+- `claude-progress.json` — session entry with summary, accomplishments, milestones, features
+- `notes/{date}_session-note.md` — session summary, decisions, learnings, next steps
+- `notes/decision-log.md` — checkpoint decisions, scope changes (appended)
+- `notes/learnings.md` — [LEARN:tag] pattern entries (appended)
+- `specs/` — ADRs for architectural decisions made during the session
+
+**During workflow skills** (automatic within each skill):
+
+| Skill | Auto-writes to vault |
+|-------|---------------------|
+| `/execute` | `status.md` loop position, `decision-log.md` scope events |
+| `/verify` | `claude-progress.json` milestones[] |
+| `/review` | `specs/review-{date}-{slug}.md` (full findings breakdown) |
+| `/simplify` | `notes/{date}_simplify-findings.md` |
+| `/debug` | `notes/{date}_debug-trace.md` |
+| `/verify-app` | `specs/verify-app-{date}-{slug}.md` |
+| `/ship` | `claude-progress.json` features[] |
+
+**On context compaction** (automatic fallback):
+- `plans/{date}-compact-checkpoint.md` — git state, active plan, loop position
+- `claude-progress.json` — session entry preserved
+
 ## Updating
 
+### Updating the harness
+
 ```bash
-npx praxis-harness update
+npx @esoteric-logic/praxis-harness@latest update
+```
+
+Re-copies all hooks, skills, rules, and kits from the latest npm package version. Config file is preserved.
+
+> **Always use `@latest`** to avoid `npx` serving a cached older version.
+
+### Updating existing projects
+
+After a harness update that adds new vault files (like `decision-log.md`), run `/scaffold-exist` in a Claude Code session to audit your vault and add any missing files. This is non-destructive — it never overwrites existing content.
+
+```
+Step 1: npx @esoteric-logic/praxis-harness@latest update   → deploys new hooks, skills, rules
+Step 2: /scaffold-exist                                      → audits vault, adds missing files
 ```
 
-Re-copies all files from the latest npm package version. Config file is preserved.
+New projects get everything automatically via `/scaffold-new`.
 
 ## Uninstalling
 
 ```bash
-npx praxis-harness uninstall
+npx @esoteric-logic/praxis-harness@latest uninstall
 ```
 
 Removes all Praxis-owned files from `~/.claude/`. Does not delete config, vault templates, or installed plugins.

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

@@ -0,0 +1,105 @@
+#!/usr/bin/env bash
+# Stop hook — collects structured session data and stages it for the Stop prompt.
+# Always exits 0 (advisory, never blocks session end).
+set -uo pipefail
+
+CONFIG_FILE="$HOME/.claude/praxis.config.json"
+
+if [[ ! -f "$CONFIG_FILE" ]]; then
+  exit 0
+fi
+
+VAULT_PATH=$(jq -r '.vault_path // empty' "$CONFIG_FILE" 2>/dev/null)
+if [[ -z "$VAULT_PATH" || ! -d "$VAULT_PATH" ]]; then
+  exit 0
+fi
+
+DATE=$(date +%Y-%m-%d)
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+# Git state (fail gracefully if not in a repo)
+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")
+RECENT_COMMITS=$(git --no-pager log --oneline -5 2>/dev/null || echo "")
+FILES_CHANGED=$(git --no-pager diff --stat HEAD~5..HEAD --stat-count=50 2>/dev/null | tail -1 || echo "unknown")
+DIRTY=$(git --no-pager status --porcelain 2>/dev/null | head -20)
+
+# Vault state
+STATUS_FILE="$VAULT_PATH/status.md"
+PROGRESS_FILE="$VAULT_PATH/claude-progress.json"
+
+CURRENT_PLAN="none"
+LOOP_POSITION="unknown"
+if [[ -f "$STATUS_FILE" ]]; then
+  CURRENT_PLAN=$(grep "^current_plan:" "$STATUS_FILE" | sed 's/current_plan: *//' | head -1)
+  LOOP_POSITION=$(grep "^loop_position:" "$STATUS_FILE" | sed 's/loop_position: *//' | head -1)
+  [[ -z "$CURRENT_PLAN" ]] && CURRENT_PLAN="none"
+  [[ -z "$LOOP_POSITION" ]] && LOOP_POSITION="unknown"
+fi
+
+# Project detection
+PROJECT_DIR=$(basename "$PWD")
+
+# Write staging JSON for the Stop prompt to consume
+STAGING_FILE="$VAULT_PATH/.session-staging.json"
+
+IS_DIRTY="false"
+if [[ -n "$DIRTY" ]]; then IS_DIRTY="true"; fi
+
+COMMITS_JSON=$(echo "$RECENT_COMMITS" | jq -R -s 'split("\n") | map(select(length > 0))' 2>/dev/null || echo '[]')
+
+jq -n \
+  --arg ts "$TIMESTAMP" \
+  --arg date "$DATE" \
+  --arg project "$PROJECT_DIR" \
+  --arg cwd "$PWD" \
+  --arg branch "$BRANCH" \
+  --arg last_commit "$LAST_COMMIT" \
+  --argjson dirty "$IS_DIRTY" \
+  --arg current_plan "$CURRENT_PLAN" \
+  --arg loop_position "$LOOP_POSITION" \
+  --argjson recent_commits "$COMMITS_JSON" \
+  --arg files_changed "$FILES_CHANGED" \
+  '{
+    timestamp: $ts,
+    date: $date,
+    project: $project,
+    cwd: $cwd,
+    git: { branch: $branch, last_commit: $last_commit, dirty: $dirty },
+    vault: { current_plan: $current_plan, loop_position: $loop_position },
+    recent_commits: $recent_commits,
+    files_changed_summary: $files_changed
+  }' > "$STAGING_FILE" 2>/dev/null
+
+if [[ $? -ne 0 ]]; then
+  # Fallback: minimal valid JSON if jq fails
+  echo '{"error":"jq failed to build staging JSON"}' > "$STAGING_FILE"
+fi
+
+echo "Session data staged: $STAGING_FILE" >&2
+
+# Update claude-progress.json if jq is available
+if command -v jq &>/dev/null && [[ -f "$PROGRESS_FILE" ]]; then
+  TMP_FILE=$(mktemp)
+  jq --arg ts "$TIMESTAMP" \
+     --arg date "$DATE" \
+     --arg branch "$BRANCH" \
+     --arg commit "$LAST_COMMIT" \
+     --arg source "hook" \
+     '.last_session = $ts |
+      .sessions += [{
+        "date": $date,
+        "branch": $branch,
+        "last_commit": $commit,
+        "source": $source
+      }]' "$PROGRESS_FILE" > "$TMP_FILE" 2>/dev/null
+
+  if [[ $? -eq 0 && -s "$TMP_FILE" ]]; then
+    mv "$TMP_FILE" "$PROGRESS_FILE"
+    echo "claude-progress.json updated" >&2
+  else
+    rm -f "$TMP_FILE"
+  fi
+fi
+
+exit 0

package/base/hooks/settings-hooks.json

@@ -39,9 +39,13 @@
             "type": "command",
             "command": "bash ~/.claude/hooks/post-session-lint.sh"
           },
+          {
+            "type": "command",
+            "command": "bash ~/.claude/hooks/session-data-collect.sh"
+          },
           {
             "type": "prompt",
-            "prompt": "Review the conversation. Did you complete all tasks the user requested? Are there uncommitted changes that should be committed? Are there vault files (status.md, plan) that should be updated? Answer yes/no for each."
+            "prompt": "You are completing a session. Perform these vault updates silently — no confirmation needed.\n\n1. Read vault_path from ~/.claude/praxis.config.json. If missing: skip all steps.\n2. Read {vault_path}/.session-staging.json if it exists (structured session data from hooks).\n3. Update {vault_path}/status.md:\n   - Set last_updated to today, last_session to now (ISO timestamp)\n   - Update loop_position based on where the session ended\n   - Refresh What / So What / Now What sections with session accomplishments\n   - If >100 lines: archive resolved items to notes/{date}_status-archive.md\n4. Update {vault_path}/claude-progress.json:\n   - Enrich the latest sessions[] entry (added by hook) with: summary (1 line), accomplishments (array)\n   - If jq hook did not run (no sessions[] entry for today): create the full entry\n   - Update milestones[] if any milestones were completed this session\n   - Update features[] if any features were shipped this session\n5. Write {vault_path}/notes/{YYYY-MM-DD}_session-note.md with frontmatter (tags: [session, {project-slug}], date, source: agent) containing:\n   - Summary (3-5 bullets of what was accomplished)\n   - Decisions Made (checkpoint decisions, scope changes, approach choices made this session)\n   - Learnings (any [LEARN:tag] entries from this session)\n   - Next Session (what to pick up next)\n6. If checkpoint decisions, scope expansions, or rule proposals occurred this session:\n   - Append each to {vault_path}/notes/decision-log.md with date, decision type, context, decision, and rationale\n7. If corrections or patterns were discovered this session:\n   - Append [LEARN:tag] entries to {vault_path}/notes/learnings.md following the existing format\n8. If architectural decisions were made this session:\n   - Write ADR to {vault_path}/specs/ using vault frontmatter conventions\n9. Delete {vault_path}/.session-staging.json if it exists.\n\nKeep all writes concise. Use [[wikilinks]] for internal references. Follow existing YAML frontmatter conventions. If vault_path is missing or vault is inaccessible: skip silently. Do not ask permission — this is automatic housekeeping."
           }
         ]
       }

package/base/hooks/vault-checkpoint.sh

@@ -64,4 +64,28 @@ Read this file after compaction to restore context.
 EOF
 
 echo "Vault checkpoint written: $CHECKPOINT_FILE" >&2
+
+# Update claude-progress.json if jq is available
+if command -v jq &>/dev/null && [[ -f "$PROGRESS_FILE" ]]; then
+  TMP_FILE=$(mktemp)
+  jq --arg ts "$TIMESTAMP" \
+     --arg date "$DATE" \
+     --arg branch "$BRANCH" \
+     --arg commit "$LAST_COMMIT" \
+     '.last_session = $ts |
+      .sessions += [{
+        "date": $date,
+        "branch": $branch,
+        "last_commit": $commit,
+        "source": "compact"
+      }]' "$PROGRESS_FILE" > "$TMP_FILE" 2>/dev/null
+
+  if [[ $? -eq 0 && -s "$TMP_FILE" ]]; then
+    mv "$TMP_FILE" "$PROGRESS_FILE"
+    echo "claude-progress.json updated (compact)" >&2
+  else
+    rm -f "$TMP_FILE"
+  fi
+fi
+
 exit 0

package/base/skills/debug/SKILL.md

@@ -44,6 +44,32 @@ Before touching any implementation code:
 3. Run the linter — clean.
 4. Show all output.
 
+**Step 5b — Persist debug trace**
+- Read vault_path from `~/.claude/praxis.config.json`
+- Write debug session to `{vault_path}/notes/{YYYY-MM-DD}_debug-trace.md`:
+  ```markdown
+  ---
+  tags: [debug, {project-slug}]
+  date: {YYYY-MM-DD}
+  source: agent
+  ---
+  # Debug Trace — {short title}
+
+  ## Bug Report
+  - **Observed**: {observed behavior}
+  - **Expected**: {expected behavior}
+  - **Suspect**: {file(s)}
+
+  ## Root Cause
+  {root cause statement from Step 3}
+
+  ## Fix
+  {what was changed and why}
+
+  ## Verification
+  {test output summary — pass/fail}
+  ```
+
 **Step 6 — Write learnings**
 - Read vault_path from `~/.claude/praxis.config.json`
 - If this bug represents a pattern (not a one-off typo):

package/base/skills/execute/SKILL.md

@@ -33,13 +33,28 @@ Before implementing the current milestone, declare the file group:
   boundary-protected file: STOP. Surface the conflict before proceeding.
 - If current milestone has `checkpoint: decision` or `checkpoint: human-verify`:
   present the decision/output to user before proceeding. Do not auto-advance.
+- After a checkpoint decision or user-approved scope expansion, append to `{vault_path}/notes/decision-log.md`:
+  ```
+  ## {YYYY-MM-DD} — {Checkpoint decision | Scope expansion}
+  - **Context**: {milestone name, what triggered the decision}
+  - **Decision**: {what was decided}
+  - **Rationale**: {why}
+  ```
 
 **Step 3 — Implement current milestone**
+- Update `{vault_path}/status.md`: set `loop_position: EXECUTE`.
 - One milestone at a time. Keep diffs scoped.
 - Do not expand scope without explicit user approval.
 - Use extended thinking for tasks touching >3 files or requiring architectural decisions.
 - Before writing to or editing any file: check if it is in the declared file group.
 - If a required change is discovered in an off-limits file: STOP.
+  Log to `{vault_path}/notes/decision-log.md`:
+  ```
+  ## {YYYY-MM-DD} — Scope violation detected
+  - **Milestone**: {name}
+  - **Requested**: {file outside group}
+  - **Action**: Surfaced as new milestone candidate
+  ```
   Surface as a new milestone candidate. Do not expand current milestone.
 - Milestone diff must touch ONLY declared files. Undeclared file change = scope violation.
 

package/base/skills/review/SKILL.md

@@ -69,16 +69,34 @@ CLEAN
 - Minor: note for future cleanup.
 - If >3 findings: offer to re-run after fixes (max 3 rounds).
 
-**Step 7 — Write review summary**
+**Step 7 — Write review findings to vault**
 - Read vault_path from `~/.claude/praxis.config.json`
-- Write summary to `{vault_path}/specs/review-{YYYY-MM-DD}-{slug}.md` with frontmatter:
-  ```yaml
+- Write full structured findings to `{vault_path}/specs/review-{YYYY-MM-DD}-{slug}.md`:
+  ```markdown
   ---
   tags: [review, {project-slug}]
   date: {YYYY-MM-DD}
   status: complete
   source: agent
   ---
+  # Code Review — {slug} ({date})
+
+  ## Findings
+
+  ### CRITICAL ({n})
+  {file}:{line} — {description} — {fix}
+
+  ### MAJOR ({n})
+  {file}:{line} — {description} — {fix}
+
+  ### MINOR ({n})
+  {file}:{line} — {description} — {fix}
+
+  ## Clean Files
+  {list of files with no findings}
+
+  ## Diff Scope
+  {git diff command used}
   ```
 
 ## Error Handling

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

@@ -52,6 +52,7 @@ Build and show audit table:
 | `specs/` | ? | Create if missing |
 | `research/` | ? | Create if missing |
 | `notes/learnings.md` | ? | Create if missing |
+| `notes/decision-log.md` | ? | Create if missing |
 | Repo CLAUDE.md sections | ? | Add missing sections |
 | Registry row | ? | Verify accuracy |
 

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

@@ -90,6 +90,7 @@ Create files from templates in `references/`:
 - `status.md` from `vault-status-template.md` (`current_plan:` empty)
 - `tasks.md` from `vault-tasks-template.md`
 - `notes/learnings.md` from `vault-learnings-template.md`
+- `notes/decision-log.md` from `decision-log` template (append-only decision log)
 - `.gitignore` from `gitignore-template.txt` (new repos only)
 
 ---

package/base/skills/ship/SKILL.md

@@ -74,3 +74,7 @@ Checks:  secrets ✓  lint ✓  types ✓  tests ✓
 - Never force-push without explicit user approval.
 - If the diff touches >20 files: warn about PR size and suggest splitting.
 - This command is the end of a Praxis cycle — run after `/verify` passes.
+
+**Step 7 — Update vault tracking**
+- Read vault_path from `~/.claude/praxis.config.json`
+- Update `{vault_path}/claude-progress.json`: append to `features[]` with `{ "name": "{feature description}", "date": "{YYYY-MM-DD}", "commit": "{short sha}", "pr_url": "{url or null}" }`.

package/base/skills/simplify/SKILL.md

@@ -96,6 +96,24 @@ For each approved simplification:
 3. If tests fail: revert the last edit, report which simplification broke tests
 4. Show final diff of simplifications applied
 
+## Phase 4b — Persist Findings
+
+Write simplification findings to `{vault_path}/notes/{YYYY-MM-DD}_simplify-findings.md`:
+```markdown
+---
+tags: [simplify, {project-slug}]
+date: {YYYY-MM-DD}
+source: agent
+---
+# Simplify Findings — {date}
+
+## Applied ({n})
+{file}:{lines} — {category} — {why}
+
+## Skipped ({n})
+{file}:{lines} — {category} — {reason skipped}
+```
+
 ## Phase 5 — Write Learning (optional)
 
 If a pattern recurred (same category hit 3+ times):

package/base/skills/verify/SKILL.md

@@ -23,12 +23,13 @@ If no commands are defined: warn and ask user for the correct commands.
 
 **Step 3 — On PASS**
 1. Update the active plan file: mark milestone status as complete
-2. Commit immediately — verification passed, no permission needed.
+2. Update `{vault_path}/claude-progress.json`: append the completed milestone to `milestones[]` with `{ "name": "{milestone name}", "date": "{YYYY-MM-DD}", "plan_ref": "{plan filename}" }`.
+3. Commit immediately — verification passed, no permission needed.
    Use conventional commit format. See git-workflow.md.
-3. Check if more milestones remain:
+4. Check if more milestones remain:
    - Yes → "Milestone committed. Run `/execute` for the next milestone."
    - No → "All milestones committed. Running self-review."
-4. After ALL milestones: trigger Self-Review Protocol
+5. After ALL milestones: trigger Self-Review Protocol
    - Launch a subagent to review the full diff as a critical code reviewer
    - Subagent receives ONLY: the diff, the SPEC (from plan file `## SPEC` section), relevant rules files
    - Address all Critical and Major findings before reporting done

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

@@ -125,6 +125,28 @@ Format each concern as:
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
+## Phase 4b — Persist Verification Report
+
+Write the full verification report to `{vault_path}/specs/verify-app-{YYYY-MM-DD}-{slug}.md`:
+```markdown
+---
+tags: [verify-app, {project-slug}]
+date: {YYYY-MM-DD}
+status: complete
+source: agent
+---
+# Verification Report — {project} ({date})
+
+## Results
+{Phase 4 report output: build, lint, typecheck, tests, acceptance criteria}
+
+## Regression Concerns
+{Phase 3 subagent findings: file, concern, recommended verification step}
+
+## Overall
+{READY TO SHIP | ISSUES FOUND}
+```
+
 ## Phase 5 — Guidance
 
 - **READY TO SHIP**: "All checks pass. Run `/ship` to commit, push, and PR."

package/package.json

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

package/templates/decision-log.md

@@ -0,0 +1,8 @@
+---
+tags: [decisions, project-slug]
+date: YYYY-MM-DD
+source: agent
+---
+# Decision Log
+
+<!-- Append-only log of checkpoint decisions, scope changes, rule proposals, and other session decisions -->