@esoteric-logic/praxis-harness 2.11.0 → 2.13.0

package/base/rules/phase-detection.md

@@ -0,0 +1,52 @@
+# Phase Detection — Rules
+# Scope: All projects, all sessions
+# Automatic detection of current workflow phase for adaptive rule loading
+
+## Phase Definitions
+
+| Phase | Signals | Active Rule Focus |
+| ----- | ------- | ----------------- |
+| **Planning** | `/px-discuss`, `/px-plan`, `/px-spec` invoked; reading specs/plans; no code edits | engineering-judgment, architecture patterns |
+| **Implementing** | Code files being written/edited; tests being written | code-quality, code-excellence, language-specific rules |
+| **Testing** | Test files being run; test output being analyzed | self-verify, observable-code |
+| **Debugging** | `/px-debug` invoked; error analysis; stack traces being read | coding (Context7 mandate), language-specific rules |
+| **Reviewing** | `/px-review`, `/px-simplify` invoked; diff analysis | refactor-triggers, code-quality |
+| **Shipping** | `/px-ship`, `/px-verify` invoked; pre-commit checks | git-workflow, security-posture |
+
+## Detection Heuristic — Conventions (WARN on violation)
+
+Phase detection is heuristic — infer from the most recent actions:
+
+1. **Explicit signal**: A phase-associated skill was invoked → phase is known
+2. **File type signal**: Editing `.ts` files → Implementing. Reading test output → Testing.
+3. **Conversation signal**: Discussing tradeoffs → Planning. Analyzing errors → Debugging.
+
+When phase is ambiguous: default to the broader rule set rather than the narrower one.
+Loading extra rules is preferable to missing a constraint.
+
+## Adaptive Loading Behavior — Conventions (WARN on violation)
+
+### What changes per phase
+- **Planning**: Prioritize engineering-judgment.md, deprioritize language-specific rules
+- **Implementing**: Load language-specific rules for active file types, full code-quality
+- **Reviewing**: Load refactor-triggers.md, emphasize simplicity checks
+- **Shipping**: Load git-workflow.md pre-commit invariants, security-posture checks
+
+### What never changes
+Universal rules (14) are always loaded regardless of phase.
+Phase detection adjusts emphasis and attention, not which rules are loaded.
+Claude Code does not support dynamic rule unloading — phase detection shapes
+which rules get actively applied, not which are present in context.
+
+## Kit Phase Integration
+
+Kits define `skills_chain` with phase fields in their manifests.
+When a kit is active, its phases override the generic phases above:
+- `code-quality` kit: gate → ai-review → self-review
+- `infrastructure` kit: plan → apply → drift → compliance
+- `web-designer` kit: design-system-init → component-build → audit → final-lint
+
+Kit phases take precedence when the kit is active.
+
+## Removal Condition
+Remove when Claude Code provides native phase-aware rule loading.

package/base/rules/refactor-triggers.md

@@ -0,0 +1,59 @@
+# Refactor Triggers — Pre-Check Protocol
+# Scope: All code modifications
+# Always active during code generation
+# Cross-reference: code-quality.md defines the hard limits (30 lines, 3 nesting,
+#   4 params, 300-line files, no TODO/FIXME). This file defines WHEN and HOW
+#   to refactor — not the thresholds themselves.
+
+## Invariants — BLOCK on violation
+
+### Before touching any existing file
+Check the file against `code-quality.md` hard limits before adding code.
+If the file already violates limits:
+1. Do NOT add new code to it
+2. Refactor the file to compliance first
+3. THEN make the intended change
+4. Commit the refactor separately from the feature
+
+This is mandatory. Adding to an already-broken file compounds debt exponentially.
+
+### Commit refactor separately from feature
+- Refactoring commits use `refactor(scope):` prefix
+- Feature commits use `feat(scope):` prefix
+- Never mix structural changes and behavior changes in one commit
+- Rationale: reviewers cannot distinguish "moved code" from "changed behavior" in a mixed diff
+
+### Copy-paste detection
+If you find yourself copying 3+ lines from elsewhere in the same codebase: stop.
+Extract a shared function in a common location.
+Duplication is the root of divergent behavior bugs.
+
+## Conventions — WARN on violation
+
+### The QUALITY comment convention
+When you encounter a known violation in code you are NOT tasked with fixing:
+```
+// QUALITY: function exceeds 30 lines — refactor tracked in #123
+```
+
+Rules for QUALITY comments:
+- QUALITY: is the ONLY allowed debt marker. `TODO`, `FIXME`, and `HACK` are banned (see `code-quality.md`).
+- Every QUALITY comment MUST include a tracking reference (issue number, ADR, or ticket).
+- QUALITY comments are allowed in commits — unlike TODO/FIXME which are not.
+- A QUALITY comment is NOT a license to defer indefinitely. It is a documented acknowledgment.
+
+### Refactor vs rewrite decision gate
+- **Refactor** (preferred): same behavior, improved structure. Small, safe, incremental.
+- **Rewrite**: new behavior or complete structural replacement.
+
+If >50% of a file needs changing during a feature task:
+1. Stop. Do not incrementally refactor to the point of a full rewrite.
+2. File an issue for the rewrite.
+3. Complete the minimum viable refactor for the current feature.
+4. Propose the rewrite as a separate milestone with its own plan.
+
+Never rewrite during a feature task without an explicit plan.
+
+## Removal Condition
+Remove when automated refactoring tools (e.g., language-specific AST transforms)
+handle pre-check validation and commit separation automatically.

package/base/rules/self-repair.md

@@ -0,0 +1,53 @@
+# Self-Repair — Rules
+# Scope: All projects, all sessions
+# Structured recovery protocol for repeated failures
+
+## Recovery Escalation — Invariants (BLOCK on violation)
+
+### Attempt tracking
+Track consecutive failures on the same task. A "failure" is:
+- Test failure after implementation
+- Lint error after fix attempt
+- User correction of the same issue
+- Build failure after code change
+
+### Escalation ladder
+
+| Attempt | Action |
+| ------- | ------ |
+| 1st failure | Fix the specific error. Re-validate. |
+| 2nd failure (same issue) | Step back. Re-read the relevant code and spec. Try a different approach. |
+| 3rd failure (same issue) | STOP. Report What / So What / Now What. Do not attempt a 4th fix. |
+
+This is already in `execution-loop.md` as "Stop-and-Fix Rule." This rule adds
+the structured escalation between attempts.
+
+### Strategy rotation on 2nd failure
+When the first fix doesn't work, rotate strategy before retrying:
+
+| Failed strategy | Try instead |
+| --------------- | ----------- |
+| Modify existing code | Rewrite the function from scratch |
+| Add logic | Remove logic (simplify) |
+| Fix forward | Revert to last working state, approach differently |
+| Local fix | Check if the problem is upstream (caller, input, config) |
+
+### 3rd failure report format
+```
+STOP — REPAIR FAILED
+━━━━━━━━━━━━━━━━━━━━━
+What:    {exact error after 3 attempts}
+So What: {root cause hypothesis — why all 3 attempts failed}
+Now What: {recommended next step — different approach, user input, or scope change}
+━━━━━━━━━━━━━━━━━━━━━
+```
+
+## Anti-Patterns — Conventions (WARN on violation)
+
+- Do NOT retry the identical fix. If attempt 1 failed, attempt 2 must differ.
+- Do NOT add complexity to fix a failure. If the fix is more complex than the original code, the approach is wrong.
+- Do NOT blame the tooling. If tests fail, the code is likely wrong.
+- Do NOT suppress errors to make validation pass. Fix the root cause.
+
+## Removal Condition
+Remove when Claude Code provides native failure tracking and strategy rotation.

package/base/rules/session-bridge.md

@@ -0,0 +1,39 @@
+# Session Bridge — Rules
+# Scope: All projects, all sessions
+# Protocol for session handoff: end-of-session persist + start-of-session rehydrate
+
+## End-of-Session Persist — Invariants (BLOCK on violation)
+
+### Mandatory writes before session ends
+1. Update `{vault_path}/status.md` with current What / So What / Now What
+2. Update `{vault_path}/claude-progress.json` with session entry
+3. Write session note to `{vault_path}/notes/{YYYY-MM-DD}_session-note.md`
+
+These are already enforced by the Stop hook prompt. This rule makes explicit
+that the vault write is the bridge — conversation state that isn't persisted is lost.
+
+## Start-of-Session Rehydrate — Conventions (WARN on violation)
+
+### Bootstrap sequence (extends After Compaction § in CLAUDE.md)
+1. Read project CLAUDE.md
+2. Read `{vault_path}/status.md` for loop position and current plan
+3. Read active plan file (current milestone only)
+4. Search vault for context relevant to active task: `rg "{task topic}" {vault_path}/specs/ {vault_path}/notes/`
+5. Load rules scoped to the current task's file types
+
+## Cross-Session Continuity — Conventions (WARN on violation)
+
+### What survives sessions (via vault)
+- Decisions, specs, ADRs → `{vault_path}/specs/`
+- Session summaries → `{vault_path}/notes/`
+- Learnings → `{vault_path}/notes/learnings.md`
+- Task state → `{vault_path}/status.md`, `claude-progress.json`
+- Plan progress → `{vault_path}/plans/`
+
+### What does NOT survive sessions
+- Conversation context (volatile — this is by design)
+- File contents read into context (re-read as needed)
+- Subagent outputs (summarize findings into vault if important)
+
+## Removal Condition
+Remove when Claude Code provides native cross-session memory persistence.

package/base/rules/session-metrics.md

@@ -0,0 +1,61 @@
+# Session Metrics — Rules
+# Scope: All projects, all sessions
+# Tracks harness-level performance for self-improvement
+
+## Metric Collection — Conventions (WARN on violation)
+
+### Metrics captured by existing hooks
+The Stop hook and session-data-collect.sh already capture:
+- Session date and timestamp
+- Branch and last commit
+- Accomplishments (via vault prompt)
+- Corrections count (via session-retro)
+- Learn entries count (via session-retro)
+
+### Additional metrics to track (when session-retro runs)
+Append these to the session entry in `claude-progress.json`:
+
+| Metric | Source | Purpose |
+| ------ | ------ | ------- |
+| `compaction_count` | Count compact checkpoints for today | How often context exhausted |
+| `files_modified` | `git diff --stat` at session end | Session scope indicator |
+| `milestones_completed` | Plan file milestone checkmarks | Throughput indicator |
+| `repair_attempts` | Count repair traces in vault | Code quality signal |
+| `phase_time` | Estimated split across plan/implement/verify | Bottleneck detection |
+
+### Metrics directory
+When session-retro produces structured metrics, write to:
+`{vault_path}/metrics/{YYYY-MM-DD}_session-metrics.md`
+
+Format:
+```markdown
+---
+tags: [metrics, session]
+date: YYYY-MM-DD
+source: agent
+---
+# Session Metrics — {YYYY-MM-DD}
+
+| Metric | Value |
+| ------ | ----- |
+| Milestones completed | {n} |
+| Files modified | {n} |
+| Compactions | {n} |
+| Repair attempts | {n} |
+| Corrections | {n} |
+| Learnings | {n} |
+| Phase split | Plan {n}% / Implement {n}% / Verify {n}% |
+```
+
+## Pattern Detection — Conventions (WARN on violation)
+
+After 5+ sessions with metrics, look for:
+- Debugging consistently >40% of session time → suggest architectural review
+- Compaction count >2 per session → suggest smaller task scoping
+- Repair attempts >3 per session → suggest better spec clarity
+- Corrections >2 per session → suggest context reset or rule update
+
+Surface patterns in `/px-session-retro` Phase 7 (Session Health Assessment).
+
+## Removal Condition
+Remove when Claude Code provides native session analytics and performance tracking.

package/base/rules/skill-authoring.md

@@ -0,0 +1,85 @@
+# Skill Authoring — Rules
+# Scope: Creating or editing base/skills/*/SKILL.md files
+# Codifies agent-first skill design principles
+
+## Agent-First Principle
+
+The agent is the primary reader of every skill. Design decisions optimize for
+how Claude discovers, loads, and executes a skill — not for how a human browses.
+
+## SKILL.md Structure — Invariants (BLOCK on violation)
+
+### Frontmatter (required)
+```yaml
+---
+name: px-{skill-name}
+disable-model-invocation: true  # false only for auto-trigger skills
+description: "{what it does}. {when to use it}."
+---
+```
+
+### Description as discovery API
+The description field is how Claude selects this skill from 40+ candidates.
+
+- Write in third person — descriptions are injected into the system prompt
+- Include BOTH what the skill does AND when to activate it
+- Include trigger keywords the user is likely to say
+- Bad: "Helps with infrastructure" (too vague to discover)
+- Good: "Generates Terraform modules for Azure resources. Use when the user asks to create, modify, or scaffold infrastructure."
+
+### Body structure
+- Imperative voice — step-by-step, not conversational
+- Flat structure — one level of headings, no deep nesting
+- Every line must change agent behavior or it's dead weight
+- Under 150 lines — skills over 150 lines should split into a skill + reference file
+
+## Degrees of Freedom — Conventions (WARN on violation)
+
+Calibrate constraint tightness to operation risk:
+
+| Freedom | When | Example skills |
+| ------- | ---- | -------------- |
+| High (text guidance) | Multiple valid paths, creative work | px-discuss, px-review |
+| Medium (templates) | Structured output, consistent format | px-plan, px-session-retro |
+| Low (exact scripts) | Destructive ops, security-sensitive | px-ship, px-secret-scan |
+
+### Feedback loops
+Non-trivial skills must include a validate → fix → repeat cycle:
+- Produce intermediate artifact
+- Validate it (test, lint, structural check)
+- Iterate until validation passes
+- Verbose error messages so Claude can self-correct
+
+## Naming Convention — Conventions (WARN on violation)
+
+- Prefix: `px-` for all Praxis skills
+- Format: short verb or noun — `px-verify`, `px-plan`, `px-debug`
+- Not gerunds — slash commands read better as `/px-verify` than `/px-verifying`
+- Kit skills: `{kit-prefix}:{action}` — `/infra:plan`, `/kg:query`
+
+## Boundaries Section — Conventions (WARN on violation)
+
+Every skill with side effects must include a `## Boundaries` section:
+- What is explicitly out of scope
+- What the skill must NOT modify
+- Maximum attempts before escalation
+- Whether user approval is required for destructive actions
+
+## Progressive Disclosure — Conventions (WARN on violation)
+
+- SKILL.md is the entry point — keep it under 150 lines
+- Additional context in reference files one level deep from SKILL.md
+- Prefer executing scripts over reading them into context
+- Name files for content, not sequence: `validation_rules.md` not `doc2.md`
+
+## Testing New Skills
+
+1. Write the skill
+2. Load it in a fresh session (Claude B)
+3. Invoke with a realistic prompt
+4. Check: Did Claude discover it? Execute it correctly? Follow boundaries?
+5. Tighten constraints where Claude diverged from intent
+
+## Removal Condition
+Remove when Claude Code provides a native skill authoring wizard with
+built-in agent-first validation.

package/base/rules/writing-quality.md

@@ -0,0 +1,122 @@
+# Writing Quality — Prose Generation Constraints
+# Scope: All prose output — design docs, ADRs, READMEs, specs, PR descriptions,
+#         commit messages, code comments, status reports
+# Always active during prose generation
+
+## The Prime Directive for Prose
+Write for the engineer reading this at 11pm during an incident.
+They have 90 seconds. Every word must earn its place.
+
+## Invariants — BLOCK on violation
+
+### Sentence limits
+- Maximum 30 words per sentence. Count before writing long sentences.
+- Maximum 5 sentences per paragraph.
+- One idea per paragraph.
+
+### Fluff kill list — never write these words or phrases
+leverage (use: use), utilize (use: use), facilitate (use: enable, allow, help),
+moving forward, going forward, at this point in time, comprehensive solution,
+robust solution, seamlessly, cutting-edge, best-in-class,
+in order to (use: to), due to the fact that (use: because),
+at the end of the day, synergy, holistic, empower, streamline
+
+For additional banned AI-filler phrases, see `px-communication-standards` skill.
+That skill covers: "Certainly!", "Absolutely!", "Great question!", "I'd be happy to",
+"It's worth noting that", "In conclusion", "To summarize the above".
+Both lists are enforced. Neither is optional.
+
+### Voice on decisions
+- Active voice on decisions: "we decided" not "it was decided"
+- Active voice on architecture: "this service handles X" not "X is handled by"
+- Reserve passive voice for describing states: "the cache is invalidated when..."
+
+### Hedging on decided things
+- Decided things use "will", not "should" or "might"
+- Uncertain things are labeled explicitly: "open question:", "to be decided:"
+- Never hedge silently. If you are uncertain, say so.
+
+## Document Structure — Mandatory Templates
+
+### Design Doc (filename: DESIGN-*.md or *-design.md)
+Required sections — none optional, none empty:
+
+#### Problem
+- What is broken, missing, or painful? Past tense. Specific.
+- "The auth service does not rate-limit failed login attempts" — GOOD
+- "We need better authentication" — BAD (not specific, not a problem statement)
+
+#### Decision
+- What are we building? Active voice. One paragraph.
+- State what this is AND what it is NOT (explicit scope boundary).
+
+#### Tradeoffs
+- Minimum 2 items. For each: what we gain AND what we give up.
+- Not "pros and cons of the overall approach" — tradeoffs of THIS decision vs alternatives.
+
+#### Acceptance Criteria
+- Verifiable statements. Observable outcomes. Present tense.
+- GOOD: "The login endpoint returns 429 after 5 failed attempts within 60 seconds"
+- BAD: "The system handles failed logins correctly"
+- BAD: "Improved security posture"
+
+### ADR (filename: ADR-NNN-*.md)
+Required fields in this order:
+```
+# ADR-NNN: {title}
+Status: Proposed | Accepted | Deprecated | Superseded by ADR-NNN
+Date: YYYY-MM-DD
+
+## Context
+{past tense — what situation forced this decision}
+
+## Decision
+{active voice — what we decided}
+
+## Consequences
+### Positive
+- {at least one}
+### Negative
+- {at least one — if no negatives, the decision is not analyzed}
+```
+
+### README (filename: README.md)
+Required sections:
+- First paragraph: what does this do (3 sentences max, no jargon)
+- `## Install` or `## Setup` with exact commands
+- `## Run` with exact commands — no `{placeholder}` in code blocks
+- `## Test` with exact commands
+
+### PR Description
+Required sections:
+- **What**: one sentence — what changed
+- **Why**: one sentence — why this was needed
+- **How to verify**: exact steps a reviewer takes to confirm it works
+- **Breaking changes**: explicit "None" if none — do not omit
+
+## Commit Messages
+Format: `{type}({scope}): {what changed in imperative mood}`
+
+Types: feat, fix, refactor, test, docs, chore, perf, ci
+Scope: the module, package, or subsystem changed
+Subject: present tense imperative — "add retry logic" not "added retry logic"
+
+50-char subject limit. 72-char body line limit if body is present.
+Body explains WHY the change was needed, not what the diff shows.
+
+## Code Comments
+- WHY not WHAT. The code shows what.
+- GOOD: `// retry 3x — upstream returns 503 on cold start, recovers within 2s`
+- BAD: `// increment counter`
+- Zero tolerance for TODO/FIXME/HACK in committed code.
+  Use `// QUALITY: {issue} — tracked in #{issue-number}` if deferring.
+  See `refactor-triggers.md` for the QUALITY comment convention.
+
+## Cross-References
+- Document-level formatting (proposals, status reports, executive summaries): see `px-communication-standards` skill
+- Commit standards and git workflow: see `git-workflow.md`
+- Code comment rules: see `code-quality.md` § On comments
+
+## Removal Condition
+Remove when a prose linter (Vale or equivalent) runs as a generation-time hook
+on all markdown and prose output.

package/base/skills/px-compact/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: px-compact
+disable-model-invocation: true
+description: "Intelligent mid-session compaction. Triages context, checkpoints to vault, triggers compact, reloads working set. Use when DEPLETED but mid-milestone — no /clear needed."
+---
+
+# compact Skill
+
+You are performing an intelligent mid-session compaction to free context budget
+while preserving the active working set.
+
+**Key difference from `/px-context-reset`:** No `/clear` required. You stay in the
+same session and resume immediately after compaction.
+
+## Vault Path Resolution
+
+Read vault_path from `~/.claude/praxis.config.json`.
+
+---
+
+**Step 1 — Pre-flight check**
+
+Assess context bracket from signals (see `context-budget.md` § Budget signals):
+
+- **FRESH** → Print: "Context is still fresh. Compaction would lose more than it saves." → STOP.
+- **CRITICAL with no active milestone** → Print: "Context is critically degraded with no active milestone. Use `/px-context-reset` + `/clear` instead." → STOP.
+- **MODERATE/DEPLETED/CRITICAL with active milestone** → Continue.
+
+**Step 2 — Triage context**
+
+Classify all loaded context into priority tiers:
+
+| Tier | Action |
+| ---- | ------ |
+| T1: Active working set (current file, active milestone, failing tests) | Keep — reload after compact |
+| T2: Decision context (SPEC, constraints, last 3 decisions) | Keep — include in checkpoint |
+| T3: Session history (earlier discussion, exploration, superseded approaches) | Offload summaries to vault |
+| T4: Reference material (docs consumed, examples applied) | Drop |
+
+For T3 items with decision value: append summaries to `{vault_path}/plans/{YYYY-MM-DD}-triage-offload.md`.
+
+**Step 3 — Write compact checkpoint**
+
+Write `{vault_path}/plans/{YYYY-MM-DD}-compact-checkpoint.md`:
+
+```markdown
+---
+tags: [checkpoint, compact, triage]
+date: {YYYY-MM-DD}
+source: agent
+---
+# Compact Checkpoint — {YYYY-MM-DD HH:MM}
+
+## Active Working Set (reload after compact)
+- File: {path} — {what you are doing with it}
+- File: {path} — {what you are doing with it}
+
+## Current Milestone
+{milestone name from active plan}
+
+## Decisions (last 3)
+1. {decision} — {rationale}
+2. {decision} — {rationale}
+3. {decision} — {rationale}
+
+## Offloaded This Session
+See: plans/{YYYY-MM-DD}-triage-offload.md
+
+## Next Step After Compact
+{exact next action — be specific}
+```
+
+**Step 4 — Update vault state**
+
+1. Update `{vault_path}/status.md` — refresh What / So What / Now What
+2. Update `{vault_path}/claude-progress.json` — add session entry with `"source": "compact"`
+
+**Step 5 — Trigger compaction**
+
+Print the bootstrap instructions first:
+
+```
+Compact checkpoint saved. Triggering compaction.
+
+After compaction, re-bootstrap:
+1. Read {vault_path}/plans/{YYYY-MM-DD}-compact-checkpoint.md
+2. Read the active plan: {plan-filename}, milestone: {milestone-name}
+3. Re-read only files listed in "Active Working Set" above
+4. Resume: {next step}
+```
+
+Then run `/compact` (Claude Code built-in).
+
+**Note:** The PreCompact hook (`vault-checkpoint.sh`) will also fire and write its own
+checkpoint. The triage checkpoint from Step 3 is authoritative — it contains the
+curated working set. The hook checkpoint is a safety net.
+
+## Removal Condition
+
+Remove when Claude Code provides native intelligent compaction with working set preservation.