@esoteric-logic/praxis-harness 1.1.0

package/base/commands/standup.md

@@ -0,0 +1,57 @@
+---
+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.
+---
+
+You are generating a standup summary for the current project.
+
+**Step 1 — Load project state**
+Read vault_path from `~/.claude/praxis.config.json`. Then read in order (detect from CWD — do not ask):
+1. `{vault_path}/_index.md` → project name, stack, goals
+1b. `{vault_path}/claude-progress.json` → check `ralph_state`
+2. `{vault_path}/status.md` → current_plan, last_updated, What/So What/Now What
+3. `{vault_path}/tasks.md` → Active, Blocked sections
+4. If `current_plan` is set → read `{vault_path}/plans/{current_plan}` → Milestones, Blockers
+
+**Ralph state check:**
+- If `.ralph_state.current_story` is set: note "Ralph iteration active" for output
+- Use `completed_stories` count and `last_iteration` alongside `status.md`
+- If `status.md` last_updated is stale but `ralph_state.last_iteration` is recent: suppress stale warning
+
+**Step 2 — Output standup format**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  STANDUP — {Project Name}  ({today_date})
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  DONE
+  {bullet from completed milestones or tasks}
+
+  IN PROGRESS
+  {active plan name} — {next milestone}
+
+  RALPH STATUS
+  {current story if active, or "No Ralph iteration running"}
+  Completed: {n} stories | Last: {last_iteration}
+
+  BLOCKED
+  {blocker with owner if known}
+
+  NEXT
+  {first item from Now What in status.md}
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  Last updated: {last_updated from status.md}
+  Active plan:  {current_plan or "none"}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+**Rules:**
+- If status.md `## What` is empty: say so — do not invent state.
+- If no active plan: say "No active plan — check tasks.md backlog."
+- If last_updated is >7 days ago: warn "⚠ status.md is {N} days stale"
+- Standup = facts only. No opinions or recommendations.
+
+**Step 3 — Offer next action**
+After printing standup, ask one question only:
+"Update status.md with today's progress, or continue working?"

package/base/rules/architecture.md

@@ -0,0 +1,51 @@
+# Architecture Rules
+<!-- Universal — applies when designing systems, documenting decisions, writing proposals -->
+
+## Invariants — BLOCK on violation
+
+### Decision capture
+- Architecture decisions affecting system design, network topology, identity model,
+  data residency, security posture, or compliance scope MUST be written to
+  `{vault_path}/specs/` as an ADR before implementation.
+- Never leave a significant decision only in conversation.
+- ADR minimum structure: Decision / Context / Options Considered / Consequences.
+
+### What / So What / Now What
+- Every status update, blocker report, and spec summary MUST follow this structure:
+  - **What**: Facts only. What exists, what was done, what failed.
+  - **So What**: Why it matters. Risk, dependency, compliance gap, or opportunity.
+  - **Now What**: Ordered actions informed by the above.
+- Never write a What without a So What. Facts without implications are incomplete.
+
+### Vault vs repo boundary
+- Code and configuration: repo. Decisions, rationale, risk context, research: vault.
+- If in doubt: repo = what runs, vault = why it runs that way.
+- Never put credentials, client-specific data, or engagement PII in the repo.
+
+---
+
+## Conventions — WARN on violation
+
+### Specs before implementation
+- Significant changes need a spec before implementation begins. A single ADR is sufficient.
+
+### Phase and milestone tracking
+- Active engagements with defined phases must track completion in `claude-progress.json`.
+- Phase completion criteria documented before the phase begins — not retroactively.
+- 99% complete is not complete. One remaining blocker = log it, don't round to done.
+
+---
+
+## Verification Commands
+```bash
+# Check for ADRs missing required sections
+grep -rL "## Decision\|## Context\|## Consequences" {vault_path}/specs/ 2>/dev/null
+
+# Find specs older than 90 days that may be stale
+find {vault_path}/specs/ -name "*.md" -mtime +90 -ls 2>/dev/null
+```
+
+---
+
+## Removal Condition
+Permanent. These are workflow guardrails, not project-specific.

package/base/rules/azure.md

@@ -0,0 +1,90 @@
+---
+paths:
+  - "**/*.tf"
+  - "**/*.tfvars"
+  - "**/*.bicep"
+  - "**/*.azcli"
+  - "**/azure-*"
+  - "**/arm-*"
+---
+# Azure Rules
+<!-- Scope: Azure infrastructure work -->
+<!-- CUSTOMIZE: Add engagement-specific naming, tags, and subscription rules -->
+
+## Invariants — BLOCK on violation
+
+### Naming
+- Resource names MUST follow the engagement naming convention before any deployment.
+  <!-- CUSTOMIZE: Define your naming standard per engagement -->
+  <!-- Example: `{project}-{env}-{region}-{resource_type}` -->
+- Never use default Azure-generated names (e.g., `resource-group-1`, `vnet-eastus`).
+
+### Mandatory Tags
+<!-- CUSTOMIZE: Define required tags per engagement -->
+<!-- Example: Every resource must include `project`, `environment`, `owner` -->
+- Never deploy or script a resource block missing required tags. Add them first.
+
+### Subscription Boundaries
+- Never reference resources across subscription boundaries without explicit cross-subscription
+  peering or private endpoint design.
+- Never suggest moving a resource across subscriptions without first checking:
+  Recovery Services Vault compatibility, private endpoint re-registration,
+  NSG rule updates, and RBAC re-assignment.
+
+### Identity and RBAC
+- Never recommend Owner or Contributor at subscription scope as a permanent assignment.
+- Never suggest disabling MFA for any account, service principal, or managed identity.
+- Managed Identity is preferred over Service Principal for Azure-native workloads.
+- RBAC changes to production subscriptions must be documented in `specs/` before implementation.
+
+### Network Security
+- Never recommend NSG rules with `source: Any` and `destination: Any`.
+- Private Endpoints are the default for PaaS data services (Storage, SQL, Key Vault).
+  Public endpoints require explicit justification written to `specs/`.
+
+### Secrets and Credentials
+- Never output real connection strings, SAS tokens, storage keys, or client secrets.
+- Key Vault is the required secret store. Hard-coded credentials in any artifact = BLOCK.
+- Certificate-based auth over password-based for service principals.
+
+---
+
+## Conventions — WARN on violation
+
+### Cost Awareness
+- Flag any change estimated to increase monthly cost by >5%.
+- Flag when a stable workload is a good Reserved Instance candidate (>1 year, predictable).
+
+### Defender and Monitoring
+- Defender for Cloud recommendations rated HIGH or CRITICAL: note in `status.md`.
+- Confirm Log Analytics workspace exists before suggesting new diagnostic settings.
+
+### Documentation
+- Architecture decisions affecting subscription design, network topology, or identity model
+  belong in `specs/` as an ADR.
+
+---
+
+## Verification Commands
+```bash
+# Audit missing mandatory tags across a resource group
+az resource list -g <rg-name> \
+  --query "[?tags.project == null].[name,type]" -o table
+
+# Find any-any NSG rules
+az network nsg list \
+  --query "[].securityRules[?sourceAddressPrefix=='*' && destinationAddressPrefix=='*'].[name]" -o table
+
+# Verify no public endpoints on storage accounts
+az storage account list -g <rg-name> \
+  --query "[?publicNetworkAccess!='Disabled'].[name,publicNetworkAccess]" -o table
+
+# Check Owner/Contributor at subscription scope
+az role assignment list --scope /subscriptions/<sub-id> \
+  --query "[?roleDefinitionName=='Owner' || roleDefinitionName=='Contributor'].[principalName,roleDefinitionName]" -o table
+```
+
+---
+
+## Removal Condition
+Remove or archive when no active Azure engagements remain in the project registry.

package/base/rules/code-quality.md

@@ -0,0 +1,65 @@
+# 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/coding.md

@@ -0,0 +1,139 @@
+# Coding — Universal Rules
+<!-- Universal — applies to ALL code regardless of language or stack -->
+<!-- Merged from coding.md + code-quality.md -->
+
+---
+
+## Invariants — BLOCK on violation
+
+### Documentation lookup before implementation
+- Before implementing anything that uses an external library, framework, or API:
+  use Context7 to get current docs. Training data has a cutoff. Context7 does not.
+- Append "use context7" to any prompt involving a library not personally verified as current.
+- Never suggest a method, constructor, or API signature from memory for a library
+  that releases frequently. Look it up first via Context7.
+- If Context7 is unavailable: state that docs could not be verified and flag the
+  specific method/API as "unverified against current version."
+
+### Error handling
+- Never silently swallow exceptions. Every catch block must either re-throw,
+  log with context, or return a typed error.
+- No empty catch blocks. No fallback defaults unless explicitly asked.
+- Error messages MUST include context: request params, response body, status codes.
+- Use structured logging fields, not string interpolation.
+- External calls: retries with exponential backoff + warnings, then raise last error.
+- Validate response shape, not just status code — a 200 with error body is a silent failure.
+- Every function that can fail must have an explicit failure path.
+- Validate inputs at the boundary. Never assume callers pass correct data.
+
+### No hardcoded values
+- No credentials, tokens, connection strings, or API keys inline. Ever.
+  Use environment variables, Key Vault references, or parameter files.
+- No hardcoded paths specific to one machine. Use relative paths or env-derived roots.
+- No magic numbers without a named constant and a comment explaining the value.
+
+### State and side effects
+- Pure functions where possible. If a function mutates state, its name must signal that.
+- Never mutate input parameters. Return new values.
+- Write pure functions — only modify return values, never inputs or global state.
+
+### Typing
+- Strict typing everywhere: function signatures, variables, collections.
+- No implicit `any` or untyped parameters in typed languages.
+
+### No flag parameters
+- Never write a function with a boolean/enum parameter that switches behavior.
+  Write separate named functions instead.
+
+### Dead code
+- Delete dead code. Do not comment it out.
+  Commented-out code belongs in git history, not in files.
+- Check if logic already exists before writing new code: `rg` to search first.
+
+---
+
+## Conventions — WARN on violation
+
+### Code structure
+- Functions do one thing. If you are writing "and" in a function description,
+  split it into two functions.
+- Prefer functional programming in greenfield code; classes only for connectors/interfaces.
+  Follow existing project conventions in established codebases.
+- All imports at the top of the file.
+- Follow DRY, KISS, YAGNI.
+
+### Naming
+- Variable names describe what they contain: `subscriptionIds` not `ids`,
+  `retryDelayMs` not `delay`.
+- Functions: verb-noun format. Name signals intent and side effects.
+
+### Testing
+- Write tests for ALL new code in production paths.
+- Spike/prototype carve-out: skip tests only if explicitly marked spike/prototype.
+  Flag test debt in `status.md` under `## Test Debt`.
+- Run tests before marking any task complete.
+- Mock external dependencies only — never mock the code under test.
+- Test edge cases and error paths, not just happy paths.
+- If existing tests break: fix them. Do not claim they are unrelated.
+- Never say "this should work" — demonstrate it with output, log line, or test result.
+
+### Dependency management
+Before adding any new package:
+1. Search first — check if functionality exists in codebase or stdlib (`rg`).
+2. Evaluate: maintenance status, last publish, open issues, bus factor.
+3. Minimize surface area — implement yourself if you only need one function.
+4. Pin versions — exact versions in lockfiles. No floating ranges in production deps.
+5. New production dependency requires explicit approval.
+
+### Documentation
+- Comments explain WHY, not WHAT. If the comment describes what the code does,
+  rewrite the code to be self-describing instead.
+- Update docs and comments when changing logic. Stale comments actively mislead.
+- Code is primary documentation — clear naming, types, docstrings.
+- YAML frontmatter on all markdown files:
+  ```yaml
+  ---
+  created: YYYY-MM-DD
+  status: draft|active|completed
+  tags: [relevant, tags]
+  source: agent
+  ---
+  ```
+
+### Scripts
+- Scripts that modify resources must have a dry-run or preview step before live run.
+
+### Tool preferences
+- Use Read/Edit/Write tools instead of cat/sed/echo.
+- Use `rg` (ripgrep) for searching code, not grep.
+- Use `git --no-pager` for all git commands.
+- Use subagents for context-heavy research and code review.
+- Non-interactive commands only — no interactive prompts.
+- Prefer MCP tools for current documentation (context7, Playwright).
+
+---
+
+## Verification Commands
+
+```bash
+# Verify Context7 MCP is active
+claude mcp list | grep context7
+
+# Check for hardcoded credential patterns in staged files
+git diff --staged | grep -iE "(password|secret|token|key)\s*=\s*['\"][^'\"$]"
+
+# Find TODO/FIXME left in staged files
+git diff --staged | grep -E "(TODO|FIXME|HACK|XXX)"
+
+# Find commented-out code blocks (language-agnostic)
+git diff --staged | grep -E "^\+\s*(#|//|--|\*)\s*(def |function |class |var |const |let )"
+
+# Check for untyped any in TypeScript staged files
+git diff --staged -- '*.ts' | grep -E ": any"
+```
+
+---
+
+## Removal Condition
+Permanent. Remove only if a dedicated AI coding assistant replaces Claude Code
+entirely and handles all enforcement automatically without instruction.

package/base/rules/communication.md

@@ -0,0 +1,69 @@
+# Communication Rules
+<!-- Universal — applies to all client-facing writing, proposals, status reports, specs -->
+
+## Invariants — BLOCK on violation
+
+### Executive summary first
+- Every client-facing document must open with a plain-language summary of 1–3 sentences
+  before any technical detail. The summary answers: what is this, what does the reader
+  need to know, what action if any is required.
+
+### No AI attribution in commits or documents
+- Never include: "Generated by Claude", "AI-assisted", "Co-authored by Claude",
+  or similar in git commits, document footers, spec headers, PR descriptions,
+  or any client-facing artifact.
+- Commit messages describe the change, not the tool. Conventional commits only.
+
+### No AI-style filler prose
+- Never use: "Certainly!", "Absolutely!", "Great question!", "I'd be happy to",
+  "It's worth noting that", "In conclusion", "To summarize the above".
+- Never open with "In today's rapidly evolving landscape" or equivalent.
+
+---
+
+## Conventions — WARN on violation
+
+### Proposal structure
+Every proposal follows this order:
+1. Executive Summary (1–3 sentences)
+2. Current State (facts only)
+3. Gaps / Problems (specific, measurable where possible)
+4. Recommendations (ranked by impact or urgency)
+5. Investment / Effort (time, cost, risk introduced)
+6. Next Steps (dated, owned)
+
+### Audience calibration
+- Technical detail belongs in appendices or separate specs — not in the executive narrative.
+- Non-technical stakeholders: no acronyms without definition on first use.
+- Technical implementers: be precise. Specify the command, the flag, the exact resource name.
+
+### Status reports
+- Use What / So What / Now What. Always.
+- "We are working on X" is not a status update. State what is done, what is in progress,
+  and what the blocker or next step is.
+
+### .gitignore — AI and Local File Hygiene
+Every repo scaffolded by scaffold-new must include these in `.gitignore`:
+```gitignore
+CLAUDE.md
+.claude/
+.mcp.json
+*.claude-session
+agent-memory.jsonl
+.context7-cache/
+.vault-path
+```
+
+---
+
+## Verification Commands
+```bash
+# Check commit messages for AI attribution
+git log --oneline -20 | grep -iE "(claude|ai-generated|co-authored by ai)"
+
+# Check staged markdown for AI filler phrases
+git diff --staged -- "*.md" | grep -iE "(certainly|absolutely|great question|i'd be happy)"
+
+# Verify .gitignore covers CLAUDE.md
+grep -q "CLAUDE.md" .gitignore && echo "✓ CLAUDE.md ignored" || echo "✗ CLAUDE.md NOT in .gitignore"
+```

package/base/rules/context-management.md

@@ -0,0 +1,136 @@
+# Context Management — Rules
+# Scope: All projects, all sessions
+# Prevents context rot via GSD phase discipline and Ralph story sizing
+
+## GSD Phase Discipline — Invariants (BLOCK on violation)
+
+### Phase-scoped context loading
+- Load ONLY context required for the current GSD phase.
+  SPEC needs requirements and constraints — not implementation details.
+  IMPLEMENT needs the plan and relevant source files — not research notes.
+- At the end of each phase: write a phase summary to the active plan file.
+  The summary replaces conversation memory — files are the record.
+- Never carry raw conversation reasoning forward across phases.
+  If it matters, it is written to a file. If it is not written, it does not persist.
+- One feature per session. Do not mix unrelated tasks.
+
+### File-based handoff at phase boundaries
+- Phase transitions produce artifacts, not conversation continuity.
+  SPEC → PLAN: the plan file captures all decisions from the spec phase.
+  PLAN → IMPLEMENT: the approved plan is the sole implementation guide.
+  IMPLEMENT → VALIDATE: test output and lint output are the evidence.
+- Use subagents for exploration, research, and review to protect the main context.
+
+## Ralph Story Sizing — Invariants (BLOCK on violation)
+
+### Size constraint
+- Each Ralph PRD story must be completable in a single context window (~10k output tokens).
+- Right-sized stories: add one component, one migration, one service method,
+  one test suite, or one configuration change.
+- Too large: any story requiring >3 file groups or >1 architectural decision.
+  Split before execution.
+- Stories requiring cross-story reasoning belong in GSD, not Ralph.
+  Ralph stories must be independently verifiable.
+
+### State contract
+- `claude-progress.json` is the ONLY state bridge between Ralph iterations.
+- The `ralph_state` object is authoritative:
+  ```json
+  {
+    "mode": "idle | active",
+    "prd_path": null,
+    "completed_stories": [],
+    "current_story": null
+  }
+  ```
+- Ralph reads `ralph_state` at iteration start, writes at iteration end.
+- Never reference conversation history as source of truth in Ralph mode.
+
+## When to Use GSD vs Ralph — Conventions (WARN on violation)
+
+| Trigger | Use | Reason |
+|---------|-----|--------|
+| <5 stories, needs reasoning continuity | GSD | Decisions compound across stories |
+| Architectural decisions required | GSD | Context must persist through tradeoff analysis |
+| Exploratory or ambiguous scope | GSD | Needs human-in-the-loop at phase gates |
+| >5 independent stories | Ralph | Parallelizable, no cross-story dependencies |
+| Overnight/unattended execution | Ralph | Fresh context per story prevents drift |
+| Mechanical transformations (migrations, renames) | Ralph | Repetitive, well-scoped, low judgment |
+
+Default to GSD. Use Ralph only when stories are clearly independent and well-scoped.
+
+## Compaction Safety — Invariants (BLOCK on violation)
+
+### Ralph mid-run takes precedence
+- If `claude-progress.json` → `.ralph_state.current_story` is set, ALWAYS read it — even if an active plan exists.
+- Ralph mid-run state is authoritative over plan state. The story must complete or be explicitly blocked before plan-level work resumes.
+
+## Subagent Discipline — Conventions (WARN on violation)
+
+### Subagent scope
+- Use subagents for exploration, research, and review — never for the main implementation thread.
+- Subagents protect the main context window from excessive results.
+- Each subagent receives ONLY the context it needs (diff, SPEC, relevant rules). NOT the full conversation history.
+- Do not spawn subagents for tasks that take fewer tokens than the subagent overhead.
+
+## Context Reset Protocol — Conventions (WARN on violation)
+
+### When to reset
+- Repeated corrections on the same issue (model is not incorporating feedback)
+- Loop behavior (attempting the same failed approach)
+- Instruction drift (ignoring rules that were followed earlier in the session)
+- After 2 failed corrections: suggest `/context-reset` and `/clear`
+
+### How to reset
+1. Run `/context-reset` to checkpoint current state to vault files
+2. Run `/clear` to reset the conversation
+3. Re-bootstrap from project CLAUDE.md — the files contain everything needed
+4. The vault drives work. Conversation is the interface, not the record.
+
+## Context Brackets — Conventions (WARN on violation)
+
+Adapt behavior based on estimated remaining context. Detect bracket by
+conversation length heuristic (not token count — we cannot read session JSONL).
+
+### FRESH (early session, <30% of typical session length)
+- Batch aggressively — minimize round trips
+- Lean output — trust that recent context is available
+- Load full plan context if needed — budget is high
+
+### MODERATE (mid-session, ~30-60%)
+- Re-read key requirements before implementation decisions
+- Reinforce constraint awareness — re-state SPEC if drifting
+- Prefer concise output — save context for implementation
+
+### DEPLETED (late session, >60%)
+- Checkpoint progress to vault files before continuing
+- Write milestone summaries proactively (don't wait for verify)
+- Suggest `/session-retro` + `/clear` if remaining work is substantial
+- Prepare handoff: ensure status.md and plan file capture all state
+
+### CRITICAL (after compaction or context warning)
+- Use DEPLETED rules
+- STOP new work. Complete current milestone only.
+- Write all state to vault immediately
+- Suggest new session for remaining milestones
+
+---
+
+## Verification Commands
+
+```bash
+# Check that claude-progress.json has ralph_state field
+jq '.ralph_state' {vault_path}/claude-progress.json
+
+# Verify active plan file exists and has phase summaries
+ls -la {vault_path}/plans/
+
+# Check status.md was updated this session
+stat -f "%Sm" {vault_path}/status.md
+```
+
+---
+
+## Removal Condition
+Permanent. Context rot is inherent to LLM context windows.
+Remove only if the underlying model architecture eliminates attention decay.