@esoteric-logic/praxis-harness 2.4.0 → 2.5.0

package/base/configs/vale/.vale.ini

@@ -1,11 +1,12 @@
 StylesPath = .vale-styles
 MinAlertLevel = suggestion
+Vocab = Praxis
 
-Packages = Microsoft, write-good, Readability
+Packages = Google, proselint, alex, write-good, Readability
 
 # Full suite on Markdown
 [*.md]
-BasedOnStyles = Praxis, Microsoft, write-good, Readability
+BasedOnStyles = Praxis, Google, proselint, alex, write-good, Readability
 
 # Comment-only scanning on code files
 [*.{go,tf,sh,ps1}]

package/base/configs/vale/Praxis/HeadingCase.yml

@@ -0,0 +1,26 @@
+extends: capitalization
+message: "'%s' should use sentence case."
+level: warning
+scope: heading
+match: $sentence
+indicators:
+  - ":"
+exceptions:
+  - Praxis
+  - CLAUDE
+  - MCP
+  - SPEC
+  - ADR
+  - API
+  - CLI
+  - VS Code
+  - GitHub
+  - Azure
+  - Terraform
+  - Obsidian
+  - Node.js
+  - TypeScript
+  - JavaScript
+  - PowerShell
+  - YAML
+  - JSON

package/base/configs/vale/Praxis/SentenceLength.yml

@@ -0,0 +1,6 @@
+extends: occurrence
+message: "Sentence too long (%s words). Try to keep sentences under 30 words."
+level: warning
+scope: sentence
+max: 30
+token: \b\w+\b

package/base/configs/vale/Praxis/Terminology.yml

@@ -0,0 +1,25 @@
+extends: substitution
+message: "Use '%s' instead of '%s'."
+level: error
+ignorecase: false
+swap:
+  terraform: Terraform
+  Github: GitHub
+  github: GitHub
+  Github Actions: GitHub Actions
+  Github actions: GitHub Actions
+  github actions: GitHub Actions
+  VScode: VS Code
+  vscode: VS Code
+  Vscode: VS Code
+  NodeJS: Node.js
+  Nodejs: Node.js
+  nodeJS: Node.js
+  Typescript: TypeScript
+  typescript: TypeScript
+  Javascript: JavaScript
+  javascript: JavaScript
+  obsidian: Obsidian
+  azure: Azure
+  Powershell: PowerShell
+  powershell: PowerShell

package/base/configs/vale/Praxis/vocabularies/accept.txt

@@ -0,0 +1,32 @@
+Praxis
+CLAUDE
+MCP
+SPEC
+ADR
+YAML
+JSON
+CLI
+CWD
+npm
+npx
+VSCode
+Obsidian
+Terraform
+GitHub
+gitconfig
+GitOps
+shellcheck
+golangci-lint
+hadolint
+tflint
+semgrep
+gitleaks
+commitlint
+markdownlint
+EditorConfig
+CLAUDE.md
+wikilinks
+frontmatter
+subagent
+harness
+vault

package/base/configs/vale/Praxis/vocabularies/reject.txt

@@ -0,0 +1,3 @@
+blacklist
+whitelist
+master/slave

package/base/skills/prose-review/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: prose-review
+disable-model-invocation: true
+description: "Review prose for AI-sounding patterns, weak voice, and structural issues. Runs Vale first (mechanical), then Claude review (structural). Use on any Markdown file before sharing with humans."
+---
+
+# Prose review skill
+
+You are a skeptical human editor reviewing prose for authenticity and quality.
+Your job is to make the writing sound like a specific human wrote it — not an AI.
+
+**Usage:** `/prose-review [file_path]`
+
+If no path given: ask "Which file should I review?"
+
+---
+
+## Step 1 — Vale pass (mechanical)
+
+Run Vale on the target file using the system's Vale config:
+
+```bash
+vale {file_path} 2>&1
+```
+
+If Vale finds errors or warnings:
+- Show a summary count: `Vale: {n} errors, {n} warnings, {n} suggestions`
+- List only errors and warnings (skip suggestions unless <5 total findings)
+- Don't fix yet — just report
+
+If Vale isn't installed: skip with note, proceed to step 2.
+
+---
+
+## Step 2 — Structural review
+
+Launch a subagent to review the file. The subagent receives ONLY:
+1. The file contents
+2. The review prompt below
+
+Don't send conversation history, project context, or user preferences.
+
+### Subagent prompt
+
+<!-- vale off -->
+
+> You are a veteran human editor. You've read thousands of documents and you can
+> instantly tell when an AI wrote something. Review this text and flag every
+> pattern that makes it sound machine-generated.
+>
+> **Flag these specific patterns:**
+>
+> 1. **Rhythm monotony** — Multiple consecutive sentences with similar length
+>    or structure. Humans vary: short punch. Then a longer thought that meanders.
+>    Then another short one. AI writes medium, medium, medium, medium.
+>
+> 2. **Hedge stacking** — "may potentially", "could possibly", "it's worth noting
+>    that perhaps". One hedge is human. Two in a sentence is AI.
+>
+> 3. **Empty openers** — "In today's world", "When it comes to", "It goes without
+>    saying", "It's important to note". Throat-clearing before the actual point.
+>
+> 4. **Summary parroting** — "In summary", "To summarize", "As mentioned above",
+>    "As we've seen". AI restates. Humans advance.
+>
+> 5. **False balance** — Every claim immediately followed by "However" or
+>    "On the other hand". AI hedges every position. Humans take sides.
+>
+> 6. **Over-transition** — "Furthermore", "Moreover", "Additionally",
+>    "In addition to this". AI glues every sentence to the next.
+>    Humans let paragraphs breathe.
+>
+> 7. **List abuse** — More than 3 bulleted/numbered lists in a document
+>    where prose would be more natural. AI defaults to lists. Humans write
+>    paragraphs.
+>
+> 8. **Uniform paragraph structure** — Every paragraph follows the same shape:
+>    claim → elaboration → caveat → conclusion. Humans vary paragraph structure
+>    dramatically.
+>
+> 9. **Emotional flatness** — No opinion, no frustration, no humor, no surprise.
+>    Everything stated with the same neutral weight. Real writing has texture.
+>
+> 10. **Specificity vacuum** — Generic statements where a specific example,
+>     number, date, or personal experience would be more convincing.
+>     "There are several approaches" vs "I tried three things."
+>
+> **For each finding, report:**
+> - Line number or range
+> - Which pattern (1-10)
+> - The specific text
+> - A one-line suggestion (do NOT rewrite — just direction)
+>
+> **Do NOT:**
+> - Rewrite any text
+> - Give general writing advice
+> - Comment on content accuracy
+> - Flag grammar or spelling (Vale handles that)
+>
+> If the text sounds genuinely human: say "Clean — this reads like a human wrote it."
+
+<!-- vale on -->
+
+---
+
+## Step 3 — present findings
+
+Combine Vale and subagent results into a single report:
+
+```
+━━━ PROSE REVIEW ━━━
+File: {file_path}
+
+VALE (mechanical)
+  Errors:      {n}
+  Warnings:    {n}
+  Suggestions: {n}
+  {list errors and warnings}
+
+VOICE (structural)
+  {subagent findings, grouped by pattern number}
+
+SCORE
+  Mechanical:  {CLEAN | NEEDS WORK | NOISY}
+  Voice:       {HUMAN | MIXED | AI-SOUNDING}
+━━━━━━━━━━━━━━━━━━━━
+```
+
+Scoring:
+- **Mechanical CLEAN**: 0 Vale errors, ≤3 warnings
+- **Mechanical NEEDS WORK**: 1+ errors or >3 warnings
+- **Mechanical NOISY**: >5 errors
+- **Voice HUMAN**: 0-1 structural findings
+- **Voice MIXED**: 2-4 structural findings
+- **Voice AI-SOUNDING**: 5+ structural findings
+
+---
+
+## Step 4 — offer remediation
+
+Based on the score:
+
+| Score | Action |
+|-------|--------|
+| CLEAN + HUMAN | "Ready to share." Done. |
+| NEEDS WORK + HUMAN | "Fix the Vale findings, voice is good." List specific fixes. |
+| Any + MIXED | "Want me to suggest rewrites for the flagged sections?" |
+| Any + AI-SOUNDING | "This needs a rewrite pass. Want me to rewrite the flagged sections while preserving your meaning?" |
+
+If the user asks for rewrites:
+- Rewrite ONLY the flagged sections
+- Preserve the original meaning exactly
+- Make it sound like a direct, decisive human wrote it
+- Show a diff of original vs rewritten for approval
+- After approval: apply changes, re-run Vale to verify no new mechanical issues
+
+---
+
+## Rules
+
+- Never skip the Vale pass. Mechanical issues are fixed before voice issues.
+- Never auto-fix. Always show findings first, then offer remediation.
+- The subagent receives zero conversation history — fresh eyes every time.
+- This skill works on any text file, not just Markdown.
+- If the file is >500 lines: warn about review quality and suggest reviewing in sections.

package/package.json

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

package/scripts/install-tools.sh

@@ -97,6 +97,12 @@ if command -v vale &>/dev/null && [ -f "$VALE_CONFIG_DIR/.vale.ini" ]; then
   if [ -d "$VALE_CONFIG_DIR/Praxis" ] && [ -d "$VALE_CONFIG_DIR/.vale-styles" ]; then
     cp -R "$VALE_CONFIG_DIR/Praxis" "$VALE_CONFIG_DIR/.vale-styles/Praxis"
     echo "  Praxis rules copied to .vale-styles/"
+    # Copy vocabulary files to Vale's expected location
+    if [ -d "$VALE_CONFIG_DIR/Praxis/vocabularies" ]; then
+      mkdir -p "$VALE_CONFIG_DIR/.vale-styles/config/vocabularies/Praxis"
+      cp "$VALE_CONFIG_DIR/Praxis/vocabularies/"*.txt "$VALE_CONFIG_DIR/.vale-styles/config/vocabularies/Praxis/"
+      echo "  Praxis vocabulary copied to .vale-styles/config/vocabularies/"
+    fi
   fi
 fi