@esoteric-logic/praxis-harness 1.1.0

package/base/rules/execution-loop.md

@@ -0,0 +1,84 @@
+# Execution Loop — Rules
+# Scope: All projects, all sessions
+# Extracted from ~/.claude/CLAUDE.md to reduce root file size
+
+## Core Loop (MANDATORY — every non-trivial task)
+
+### Phase 1: SPEC
+Answer four questions before any code or file is written:
+- **WHAT**: Concrete deliverable (not vague goals)
+- **DONE-WHEN**: Specific checks that prove completion
+- **CONSTRAINTS**: Performance, compatibility, style requirements
+- **NON-GOALS**: What this task explicitly does NOT include
+If ambiguous: ask 2–3 clarifying questions before proceeding.
+
+### Risk Check (MANDATORY if any apply)
+Run `/risk` before proceeding to PLAN if the task:
+- Touches infrastructure files (`*.tf`, `*.bicep`, `*.yml` in `.github/workflows/`)
+- Touches authentication, credentials, or secrets handling
+- Modifies >3 files across different domains
+- Has a NON-GOALS list that explicitly defers something risky
+
+If any condition is met: `/risk` must produce at minimum one risk entry before `/gsd:plan-phase`.
+
+### Phase 2: PLAN
+- Break work into milestones small enough to complete and verify in one pass.
+- Each milestone MUST have: description, acceptance criteria, validation command.
+- Save plan to `{vault_path}/plans/YYYY-MM-DD_[task-slug].md` with frontmatter:
+  ```yaml
+  ---
+  created: YYYY-MM-DD
+  status: active
+  tags: [relevant, tags]
+  ---
+  ```
+- Update `{vault_path}/status.md` → `current_plan:` field.
+- Do NOT begin implementation until the plan is approved.
+
+### Phase 3: IMPLEMENT
+- One milestone at a time. Keep diffs scoped.
+- Do not expand scope without explicit approval.
+- Use extended thinking for tasks touching >3 files or requiring architectural decisions.
+
+### Phase 4: VALIDATE
+After EACH milestone — show actual output, not assertions:
+1. Run test suite → show output
+2. Run linter → show output, fix ALL warnings
+3. Run typecheck (if applicable) → show output
+4. Run build (if applicable) → show output
+5. Report: PASS or FAIL with specifics
+
+### Phase 5: REPAIR (Stop-and-Fix)
+If ANY validation fails:
+- Do NOT proceed to the next milestone.
+- Fix NOW. Re-validate. Then proceed.
+- If cannot fix in 3 attempts: STOP.
+  Report: **What** (full error + 3 attempts) → **So What** (root cause) → **Now What** (next steps)
+
+### Phase 6: COMMIT
+- Commit at milestone completion. See git-workflow.md.
+- Never let uncommitted work span multiple milestones.
+
+### Phase 7: LOG
+- Update `{vault_path}/status.md`: what was done, decisions made, what's next.
+- Mark completed milestone status in the plan file.
+- Update `{vault_path}/_index.md` goals if project direction changed.
+- Vault indexing is automatic (obsidian) or not needed (other backends).
+
+### Phase 8: REPEAT
+Next milestone. Loop until plan complete.
+
+## Self-Review Protocol
+After ALL milestones, before reporting done:
+1. Use a subagent to review the diff as a critical code reviewer.
+   Prompt: "Review this diff for bugs, edge cases, error handling gaps, security issues,
+   and violations of project conventions. Rate each: Critical / Major / Minor."
+   — Subagent receives ONLY: the diff, the SPEC, relevant rules files. NOT the conversation history.
+2. Address all Critical and Major findings.
+3. Re-validate after fixes.
+4. If reviewer found >3 issues: run review again (max 3 rounds).
+
+## Context Management
+See `~/.claude/rules/context-management.md` for complete context discipline:
+GSD phase scoping, Ralph story sizing, context reset protocol.
+- Use subagents (Task tool) for exploration, research, and review.

package/base/rules/git-workflow.md

@@ -0,0 +1,51 @@
+# Git Workflow — Rules
+# Scope: All projects with git repos
+
+## Identity — Invariants (BLOCK on violation)
+<!-- CUSTOMIZE: Replace with your git identities -->
+<!-- Example identity table: -->
+<!-- | Type | gitconfig | SSH Key | Email | includeIf Path | -->
+<!-- |------|-----------|---------|-------|----------------| -->
+<!-- | Work | ~/.gitconfig-work | ~/.ssh/id_ed25519_work | you@company.com | ~/Projects/Work/ | -->
+<!-- | Personal | ~/.gitconfig-personal | ~/.ssh/id_ed25519_personal | you@personal.com | ~/Projects/Personal/ | -->
+
+**Verification:** `git --no-pager config user.email`
+**On mismatch:** STOP. Report `expected: X, got: Y`. Do not commit.
+
+## Branch Strategy
+- Feature branches off `main`: `feat/[task-slug]` or `fix/[task-slug]`
+- Never commit directly to `main`
+- Delete branches after merge
+
+## Commit Standards
+- Commit at every completed milestone. Never batch milestones into one commit.
+- Format:
+  ```
+  type(scope): concise description
+
+  - What changed and why (not how)
+  - Milestone reference if applicable
+  ```
+  Types: `feat`, `fix`, `refactor`, `test`, `docs`, `chore`
+- Never amend published commits — use new commits for fixes.
+- Always use `git --no-pager` for all git commands.
+- Keep working tree clean — no untracked debris, no partial stages.
+
+## Pre-Commit Invariants (BLOCK on violation)
+1. Secret scan staged files: `rg "(sk-|ghp_|pplx-|AKIA|Bearer [A-Za-z0-9+/]{20,})" $(git diff --staged --name-only)`
+2. Confirm `git config user.email` matches expected identity for this repo path.
+3. Run stack linter (see terraform.md, github-actions.md as applicable).
+4. Run typecheck if applicable — no commits with type errors.
+
+## Rollback Protocol
+When a previously-passing milestone breaks:
+1. Identify breaking commit: `git bisect` or `git --no-pager log --oneline`
+2. Surgical fix (<10 lines, isolated): fix forward, re-validate, commit.
+3. Complex or unclear: `git revert <breaking-commit>`, re-validate, re-approach with revised plan.
+4. Never leave `main` broken. If can't fix or revert cleanly: STOP and report.
+
+## Vault Git Checkpoint Rule
+Vault is git-tracked. Read vault_path from `~/.claude/praxis.config.json`.
+- Auto-committed at session end by the export hook.
+- Do not manually commit vault files during a session unless explicitly asked.
+- Vault indexing is automatic (obsidian) or not needed (other backends).

package/base/rules/github-actions.md

@@ -0,0 +1,48 @@
+---
+paths:
+  - ".github/workflows/**"
+  - ".github/actions/**"
+---
+# GitHub Actions — Rules
+# Scope: Projects with .github/workflows/*.yml files
+
+## Invariants (BLOCK on violation)
+
+### Secret Handling
+- NEVER hardcode secrets in workflow files — use `${{ secrets.NAME }}` only.
+- NEVER print secrets to logs — mask all secret values.
+- Check: `rg "(password|token|key|secret)\s*[:=]\s*['\"]?[A-Za-z0-9+/]{8,}" .github/`
+- On violation: BLOCK commit immediately.
+
+### Action Pinning
+- Pin all third-party actions to a full commit SHA, not a tag.
+  Correct:   `uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683`
+  Incorrect: `uses: actions/checkout@v4`
+
+### Permissions
+- Declare explicit `permissions:` block on every job — no implicit defaults.
+- Minimum required permissions only. No `write-all`.
+
+## Conventions (WARN on violation)
+
+### Workflow Structure
+- One workflow file per concern (deploy, test, lint — not one monolithic workflow)
+- Job names: kebab-case, descriptive (`deploy-staging`, not `job1`)
+- Use `environment:` protection rules for production deployments
+
+### Triggers
+- Be explicit — avoid `on: push` without branch filters
+- PRs: `on: pull_request: branches: [main]`
+- Deploys: `on: push: branches: [main]` or manual `workflow_dispatch`
+
+## Verification Commands
+```bash
+# actionlint (if installed)
+actionlint .github/workflows/*.yml
+
+# Check for unpinned actions
+rg "uses: [^@]+@(v[0-9]|main|master|latest)" .github/
+
+# Check for hardcoded secrets
+rg "(password|token|key|secret)\s*[:=]\s*['\"]?[A-Za-z0-9+/]{8,}" .github/
+```

package/base/rules/powershell.md

@@ -0,0 +1,72 @@
+---
+paths:
+  - "**/*.ps1"
+  - "**/*.psm1"
+  - "**/*.psd1"
+---
+# PowerShell — Rules
+# Scope: Projects with *.ps1 files
+# Runtime: PowerShell 7+ required. PSScriptAnalyzer required for lint.
+
+## Invariants (BLOCK on violation)
+
+### Error Handling
+- Every script MUST begin with: `Set-StrictMode -Version Latest`
+- Every script MUST begin with: `$ErrorActionPreference = 'Stop'`
+- No bare `catch {}` blocks — every catch must either re-throw or log + re-throw.
+- No `-ErrorAction SilentlyContinue` without an explicit comment explaining why.
+
+### Secrets
+- No hardcoded credentials, connection strings, or tokens in any .ps1 file.
+- Key Vault references preferred: `Get-AzKeyVaultSecret -VaultName $VaultName -Name $SecretName`
+- Never log sensitive values — mask before `Write-Host` or `Write-Output`.
+
+## Conventions (WARN on violation)
+
+### Naming
+- Functions: `Verb-Noun` format, approved PowerShell verbs only.
+- Variables: `$PascalCase` for script-scope, `$camelCase` for local loop vars.
+- Parameters: `$PascalCase`, always typed.
+- Files: `Verb-Noun.ps1` matching the primary function name.
+
+### Structure
+Every script must have:
+```powershell
+#Requires -Version 7.0
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+<#
+.SYNOPSIS
+    One-line description.
+.DESCRIPTION
+    Full description.
+.PARAMETER ParamName
+    Description.
+.EXAMPLE
+    ./Script-Name.ps1 -Param Value
+#>
+param(
+    [Parameter(Mandatory)]
+    [string]$RequiredParam
+)
+```
+
+### Output
+- Use `Write-Host` for human-readable progress (goes to host, not pipeline).
+- Use `Write-Output` or `return` for pipeline data.
+- Use `Write-Warning` for non-fatal issues.
+- Use `Write-Error` or `throw` for fatal issues — never silently continue.
+- Structured output: return `[PSCustomObject]` for data, not formatted strings.
+
+## Verification Commands
+```powershell
+# PSScriptAnalyzer lint (if installed)
+Invoke-ScriptAnalyzer -Path . -Recurse -Severity Warning,Error
+
+# Check for SilentlyContinue without comments
+rg "SilentlyContinue" --glob "*.ps1" .
+
+# Check for missing StrictMode
+rg -L "Set-StrictMode" --glob "*.ps1" .
+```

package/base/rules/profile.md

@@ -0,0 +1,31 @@
+# Profile
+# Universal — loads every session. Static context foundation.
+# No paths: scoping — always in context
+
+## Setup Detection
+If "Your Name" or "Your Role" appears below, this file is not configured.
+STOP and tell the user:
+"profile.md is not configured. Fill in Who You Are Working With below before starting."
+Do NOT proceed with an empty profile — it causes silent context gaps every session.
+
+## Who You Are Working With
+Your Name — Your Role. Primary focus: your domains.
+
+## Active Projects
+Project context is loaded dynamically per session via /scaffold-new and /standup.
+Do NOT maintain a static project list here — it will drift.
+To add a new project: run /scaffold-new in the project repo.
+To see current project state: run /standup.
+
+## How You Work
+- Writes for two audiences: technical implementers and non-technical stakeholders.
+- Communication style: direct, structured, What/So What/Now What.
+- Deliverables over discussion — prefers concrete output to long explanations.
+- Vault-first: decisions, specs, and plans live in the vault, not in conversation.
+- Git identity is project-specific — always verify before committing.
+
+## What Claude Should Always Remember
+- Never assume a dormant project is dead — verify from status.md before deprioritizing.
+- When project context is ambiguous: check CWD against local_path in vault _index.md before asking.
+- Context7 is installed — always use it before implementing with an external library or API.
+- Add any project-agnostic rules or constraints here (not project-specific — those go in repo CLAUDE.md).

package/base/rules/security.md

@@ -0,0 +1,40 @@
+# 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\."
+```

package/base/rules/terraform.md

@@ -0,0 +1,48 @@
+---
+paths:
+  - "**/*.tf"
+  - "**/*.tfvars"
+  - "**/*.tfplan"
+---
+# Terraform — Rules
+# Scope: Projects with .tf files
+
+## Invariants (BLOCK on violation)
+
+### State Management
+- Remote state ONLY — no local state files ever committed.
+- Backend config must not contain secrets — use environment variables or Key Vault refs.
+- State locking required — never disable lock without explicit reason + approval.
+- `terraform plan` must be reviewed before every `apply`. No blind applies.
+
+### Layer Boundaries (enforce with rg checks)
+- `modules/` → MUST NOT reference `../environments/` directly
+  Check: `rg 'source\s*=\s*"\.\.\/environments' modules/`
+- `environments/` → MUST NOT contain resource definitions, only variable calls
+  Check: `rg '^resource "' environments/`
+- On violation: BLOCK commit. Hard stop.
+
+### Formatting
+- `terraform fmt -recursive` must pass before any commit touching .tf files.
+- `terraform validate` must pass.
+
+## Conventions (WARN on violation)
+
+### Naming
+- Resources: `{project}-{env}-{resource_type}-{purpose}`
+- Variables: snake_case
+- Outputs: snake_case, descriptive
+- Modules: kebab-case directory names
+
+### Provider
+- Pin provider versions exactly — no `~>` in production
+- Managed identity preferred over service principal where possible
+- Tag all resources: `project`, `environment`, `owner`, `created_by = "terraform"`
+
+## Verification Commands
+```bash
+terraform fmt -recursive -check
+terraform validate
+rg 'source\s*=\s*"\.\.\/environments' modules/
+rg '^resource "' environments/
+```

package/base/rules/vault.md

@@ -0,0 +1,134 @@
+# Vault — Second Brain Integration
+<!-- Universal — loads every session. Defines how Claude interacts with the vault. -->
+
+---
+
+## Backend Detection
+Read `vault_backend` from `~/.claude/praxis.config.json`. Defaults to `"obsidian"` if absent.
+
+| Backend | Search command | Update after write | Link format |
+|---------|---------------|-------------------|-------------|
+| `obsidian` | `obsidian search query="{query}" limit=5` | no-op (real-time indexing) | `[[wikilinks]]` |
+| `logseq` | `rg -l "{query}" {vault_path} --glob "*.md" \| head -5` | no-op | standard markdown links |
+| `plain` | `rg -l "{query}" {vault_path} --glob "*.md" \| head -5` | no-op | standard markdown links |
+| `custom` | `rg -l "{query}" {vault_path} --glob "*.md" \| head -5` | no-op | standard markdown links |
+
+**Note:** The Obsidian CLI requires Obsidian to be running. If Obsidian is not running, vault search will fail.
+Scope searches with `path=` filter: `obsidian search query="{query}" path="01_Projects" limit=5`
+
+All commands below use the backend table above. When a step says "vault search" or "vault update", substitute the correct command for the active backend.
+
+## Vault Location
+Read vault_path from `~/.claude/praxis.config.json`.
+If the config file is missing, tell the user to run `praxis/install.sh`.
+All `{vault_path}` references below resolve from this config.
+
+---
+
+## The Vault Is the Brain — Not Conversation
+
+Decisions made in conversation but not written to `specs/` do not exist next session.
+Plans discussed but not written to `plans/` will be re-discovered and re-debated.
+This is entropy. The vault prevents it.
+
+---
+
+## Invariants — BLOCK on violation
+
+### Search before reading
+- ALWAYS run a vault search before reading vault files.
+- Never navigate to a vault file by path alone — you may read a stale or superseded version.
+
+### Auto-save these to vault without being asked
+- Architecture decisions → `specs/YYYY-MM-DD_title.md`
+- Technical specs or designs → `specs/YYYY-MM-DD_title.md`
+- Research findings (>3 sentences) → `research/YYYY-MM-DD_topic.md`
+- Risk register entries → `specs/risk-register.md`
+- Patterns or corrections discovered → `notes/learnings.md` as [LEARN:tag]
+- Meeting notes or client context → `notes/YYYY-MM-DD_meeting.md`
+
+Never ask "should I save this?" for the above categories — just save it.
+
+### No manual index update needed
+- Obsidian indexes vault changes in real-time — no update command required.
+- For all other backends: files are read directly, no indexing needed.
+
+---
+
+## Conventions — WARN on violation
+
+### Project detection
+- Detect current project by matching CWD against `local_path` in any `_index.md`.
+- If CWD is ambiguous: ask before writing to vault. Never guess which project.
+
+### Vault file purposes — strict separation
+
+| File | Contains | Does NOT contain |
+|------|---------|-----------------|
+| `_index.md` | Project metadata: repo, stack, goals, links | Session state, plans, decisions |
+| `status.md` | Execution state: What/So What/Now What. **Max 100 lines.** Archive resolved items to `notes/`. | Historical completed work, session transcripts |
+| `tasks.md` | Active/Backlog/Blocked/Completed task lists | Specs, decisions, research |
+| `plans/` | Dated work plans with milestones and steps | Completed archives |
+| `specs/` | ADRs, technical specs, risk register, proposals | In-progress drafts |
+| `research/` | Investigation findings before decisions | Decisions (those go to specs/) |
+| `notes/learnings.md` | [LEARN:tag] entries, patterns, corrections | General meeting notes |
+
+### Writing format for vault files
+Every vault file must have YAML frontmatter:
+```yaml
+---
+tags: [type, project-slug]
+date: YYYY-MM-DD
+source: agent | human | meeting
+---
+```
+
+Link format depends on backend:
+- `obsidian` → use `[[wikilinks]]` for all internal vault references
+- `logseq`, `plain`, `custom` → use standard markdown links
+
+### Bootstrap templates
+If `status.md`, `tasks.md`, or `_index.md` are missing from a project vault directory,
+scaffold them from `templates/` in the praxis repo. Run `/scaffold-exist` if the
+project predates the scaffold standard. Never create these files freehand — use templates.
+
+### Planning workflow
+When "let's work on X" or "plan out Y":
+1. Run `/plan` to create a dated plan in `vault/plans/`
+2. Update `status.md` current_plan field
+3. Work from the plan — check off milestones as they complete
+4. At session end: run `/session-retro`
+
+**The vault drives work. Conversation is the interface, not the record.**
+
+### Status digest discipline
+- status.md must stay under 100 lines. If it exceeds this: archive resolved
+  What/So What/Now What sections to `notes/{date}_status-archive.md` and trim.
+- Required fields at top (always present):
+  ```
+  current_plan: {path or "none"}
+  last_updated: {YYYY-MM-DD}
+  last_session: {ISO timestamp}
+  loop_position: DISCUSS | PLAN | EXECUTE | VERIFY | IDLE
+  ```
+- loop_position tracks where in the GSD cycle the project currently sits.
+  Update at every phase transition.
+- A status.md older than 14 days is stale. vault-gc flags these.
+
+---
+
+## Second Brain Principles
+
+**Write decisions when they're made, not when they're needed.**
+
+**Update status.md at the end of every session.**
+vault-gc flags projects where status.md is >14 days stale.
+
+**Use [LEARN:tag] for patterns, not just errors.**
+Every time something works better than expected, log why.
+
+---
+
+## Removal Condition
+Permanent. Remove only if persistent vault state is replaced by
+a different mechanism entirely.