@esoteric-logic/praxis-harness 2.10.0 → 2.12.0

package/base/rules/typescript-quality.md

@@ -0,0 +1,26 @@
+# TypeScript Quality — Generation Constraints
+# Scope: **/*.ts, **/*.tsx
+# Active during code generation, not post-hoc review
+
+## Invariants — BLOCK on violation
+
+- No `any` type — ever. Use `unknown` and narrow, or define the actual type.
+- Explicit return types on all exported functions.
+- No non-null assertion (`!`) without an inline comment explaining why it's safe.
+- No `@ts-ignore` or `@ts-expect-error` without an inline comment explaining why.
+- No `as` type assertions unless narrowing from `unknown` — prefer type guards.
+- Strict null checks: handle `null` and `undefined` explicitly, never assume presence.
+
+## Conventions — WARN on violation
+
+- `const` by default — `let` only when reassignment is necessary. Never `var`.
+- Discriminated unions over optional fields for modeling distinct states.
+- `readonly` on properties that should not be mutated after construction.
+- `interface` for object shapes, `type` for unions, intersections, and computed types.
+- Named exports over default exports — better refactoring support and tree-shaking.
+- `Promise.all` for independent async operations — never sequential awaits for parallel work.
+- Error boundaries in React components that render user-generated or external data.
+- `satisfies` operator over `as` for type validation without widening.
+
+## Removal Condition
+Remove when a TypeScript-specific linter rule engine replaces generation-time constraints.

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-complexity-audit/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: px-complexity-audit
+disable-model-invocation: true
+description: "Codebase debt scanner. Ranks files by complexity score (size, nesting, debt markers, generic names). Use at sprint start, before major features, or quarterly. Outputs heat map and refactor targets."
+---
+
+# px-complexity-audit — Codebase Debt Scanner
+
+## Purpose
+
+Scans the existing codebase for accumulated technical debt.
+Outputs a ranked heat map of files needing attention.
+Use before starting major feature work or at sprint boundaries.
+
+## When To Use
+
+1. Sprint start: identify cleanup targets before new work begins
+2. Pre-feature: assess the health of files you are about to modify
+3. Quarterly: full codebase scan, results written to vault
+4. On-demand: `/px-complexity-audit {directory}` for targeted scan
+
+## What It Scans
+
+### File-level metrics
+
+```bash
+FILE_LINES=$(wc -l < "$f")
+TODO_COUNT=$(grep -cE 'TODO|FIXME|HACK|QUALITY:' "$f" || echo 0)
+FUNC_COUNT=$(grep -cE '(func |def |function |const .* = )' "$f" || echo 0)
+DEEP_NEST=$(grep -cE '^\s{16,}\S|^\t{4,}\S' "$f" || echo 0)
+GENERIC_NAMES=$(grep -oE '\b(data|result|info|temp|tmp|obj|val|item|stuff|thing|ret|res)\b' "$f" | wc -l || echo 0)
+```
+
+### Debt score formula
+
+Each file receives a composite score (higher = more urgent):
+
+```
+debt_score = (
+  (file_lines / 300 * 30)           +  # Over size limit: 30 points at 300 lines
+  (todo_count * 10)                  +  # 10 points per debt marker
+  (deep_nest_lines * 5)             +  # 5 points per deeply nested line
+  (generic_name_count * 2)          +  # 2 points per generic name
+  (longest_function / 30 * 20)         # Over function limit: 20 points at 30 lines
+)
+```
+
+Thresholds:
+
+- Score 0-20: CLEAN — no action needed
+- Score 21-50: WATCH — consider cleanup if touching this file
+- Score 51-80: REFACTOR — clean up before adding features
+- Score 81+: CRITICAL — stop and refactor now
+
+### Potential dead code detection
+
+```bash
+for func_name in $(grep -ohE '(func|def|function)\s+\w+' "$f" | awk '{print $2}'); do
+  refs=$(rg -l "$func_name" --type-add 'code:*.{go,ts,py,js,rs,java}' -t code . | grep -v "$f" | wc -l || echo 0)
+  if [[ "$refs" -eq 0 ]]; then
+    echo "POTENTIAL_DEAD: $func_name in $f (0 external references)"
+  fi
+done
+```
+
+## Output Format
+
+### Heat Map (terminal output)
+
+```
+━━━ COMPLEXITY AUDIT ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Scanned: 47 files | CLEAN: 31 | WATCH: 9 | REFACTOR: 5 | CRIT: 2
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+TOP 5 REFACTOR TARGETS
+
+ Rank | File                        | Score | Primary Issue
+ ─────┼─────────────────────────────┼───────┼────────────────────
+  1   | services/auth/handler.go    |  94   | 342 lines, 4 TODOs
+  2   | services/billing/calc.py    |  87   | 60-line function
+  3   | handlers/api/v2/users.ts    |  73   | 5-level nesting
+  4   | lib/cache/redis.go          |  58   | 12 generic names
+  5   | cmd/worker/process.go       |  52   | 3 TODOs, 280 lines
+
+Estimated effort: ~4 hours for top 5
+```
+
+### Effort estimation heuristic
+
+| Action | Estimated time |
+| ------ | -------------- |
+| Split a 300+ line file | 30-45 min |
+| Extract a 30+ line function | 15-20 min |
+| Flatten deep nesting | 10-15 min per function |
+| Rename generic variables | 5-10 min per file |
+| Address a TODO with ticket | 5 min (triage) or 30+ min (fix) |
+
+### Vault output
+
+When run with `--write-vault` or during quarterly scan:
+
+```
+Output path: {vault_path}/specs/debt-audit-{YYYY-MM-DD}.md
+```
+
+Contents:
+
+- Full ranked file list with scores
+- Top 5 refactor targets with specific actions
+- Trend comparison if previous audit exists (score delta per file)
+- Recommended sprint allocation (hours) for debt reduction
+
+## Limitations
+
+- Dead code detection is heuristic — false positives on exported/public APIs
+- Nesting depth uses indentation as proxy — may miscount in some styles
+- Does not analyze cyclomatic complexity (would require AST parsing per language)
+- Effort estimates are rough guides, not commitments

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

@@ -10,7 +10,10 @@ You are running a structured technical discovery.
 - Read vault_path from `~/.claude/praxis.config.json`
 - What decision needs to be made? (one sentence)
 - What are the constraints? (compliance, performance, compatibility, cost)
-- What is already known? (run `obsidian search query="{topic}" limit=5`)
+- What is already known? Search vault using configured backend:
+  - If `obsidian`: run `obsidian search query="{topic}" limit=5`
+  - If `ripgrep`: run `rg --files-with-matches "{topic}" {vault_path}/`
+  - If vault search fails: proceed without blocking
 
 **Step 2 — Research options**
 - Identify 2-4 viable options. For each:

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

@@ -23,7 +23,10 @@ Do NOT present a template or form. Let them talk.
 
 **Step 3 — Search for related work**
 After the user describes the task, search vault for prior art:
-Run: `obsidian search query="{topic}" limit=5`
+Read `vault_backend` from `~/.claude/praxis.config.json`.
+- If `obsidian`: run `obsidian search query="{topic}" limit=5`
+- If `ripgrep`: run `rg --files-with-matches "{topic}" {vault_path}/`
+- If vault search fails (e.g., Obsidian not running): warn and proceed without blocking.
 If related specs, plans, or research exist: mention them briefly.
 If nothing exists: proceed silently.
 

package/base/skills/px-doc-lint/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: px-doc-lint
+disable-model-invocation: true
+description: "Fast structural markdown check. No subagent — pure pattern matching. Completes in under 5 seconds. Fires inside px-quality-gate for staged *.md files, or on-demand via /px-doc-lint."
+---
+
+# px-doc-lint — Fast Structural Markdown Check
+
+## Purpose
+
+Lightweight structural validation for markdown files. No subagent.
+Pure pattern matching. Completes in under 5 seconds.
+Use as a quick pre-save check or let px-quality-gate invoke it automatically.
+
+## When It Fires
+
+1. Automatically inside px-quality-gate for every staged `*.md` file
+2. On-demand: `/px-doc-lint {filepath}`
+3. On-demand batch: `/px-doc-lint {directory}` (all .md files in directory)
+
+## Checks by Document Type
+
+### All markdown files
+
+```bash
+# 1. Frontmatter check — if present, must be valid
+head -1 "$f" | grep -q '^---$' && {
+  awk '/^---$/{c++} c==2{found=1; exit} END{if(!found) print "BLOCK: unclosed frontmatter"}' "$f"
+}
+
+# 2. No trailing whitespace
+grep -nE ' +$' "$f" && echo "WARN: trailing whitespace"
+
+# 3. No consecutive blank lines (more than 2)
+awk '/^$/{blank++; if(blank>2) print "WARN: line "NR": excessive blank lines"} /^.+$/{blank=0}' "$f"
+
+# 4. Headers must increment by one level (no h1 -> h3 skip)
+grep -E '^#{1,6} ' "$f" | awk '{
+  level = length($0) - length(gensub(/^#+/, "", 1, $0)) - 1
+  if (prev > 0 && level > prev + 1)
+    print "WARN: header level skip at: "$0
+  prev = level
+}'
+
+# 5. No empty headers
+grep -nE '^#{1,6}\s*$' "$f" && echo "BLOCK: empty header"
+
+# 6. Fluff kill list (same as px-quality-gate prose check)
+grep -inE "$FLUFF_PATTERN" "$f" && echo "BLOCK: fluff phrases detected"
+```
+
+### Design docs (DESIGN-*.md, *-design.md)
+
+```bash
+for section in "## Problem" "## Decision" "## Tradeoffs" "## Acceptance Criteria"; do
+  grep -q "$section" "$f" || echo "BLOCK: missing required section: $section"
+done
+
+tradeoff_count=$(awk '/## Tradeoffs/,/## /' "$f" | grep -c '^- ' || true)
+if [[ "$tradeoff_count" -lt 2 ]]; then
+  echo "BLOCK: Tradeoffs section needs at least 2 items (found: $tradeoff_count)"
+fi
+```
+
+### ADRs (ADR-*.md)
+
+```bash
+for field in "Status:" "Date:" "## Context" "## Decision" "## Consequences"; do
+  grep -q "$field" "$f" || echo "BLOCK: missing required field: $field"
+done
+
+status=$(grep -oE 'Status: .*' "$f" | head -1)
+echo "$status" | grep -qE '(Proposed|Accepted|Deprecated|Superseded)' || \
+  echo "BLOCK: invalid ADR status. Must be: Proposed | Accepted | Deprecated | Superseded by ADR-NNN"
+
+grep -q '### Positive' "$f" || echo "BLOCK: missing Consequences > Positive"
+grep -q '### Negative' "$f" || echo "BLOCK: missing Consequences > Negative"
+```
+
+### READMEs (README.md)
+
+```bash
+for section in "## Install\|## Setup" "## Run" "## Test"; do
+  grep -qE "$section" "$f" || echo "BLOCK: missing required section matching: $section"
+done
+
+awk '/^```/,/^```/' "$f" | grep -E '\{placeholder\}|\{TODO\}|\{TBD\}' && \
+  echo "BLOCK: placeholder found inside code block"
+```
+
+## Output Format
+
+```
+px-doc-lint: {filename}
+Type: {Design Doc | ADR | README | General}
+  [PASS] frontmatter valid
+  [PASS] no trailing whitespace
+  [BLOCK] missing required section: ## Tradeoffs
+  [WARN] header level skip at: ### Details
+Result: BLOCK (1 error, 1 warning)
+```
+
+## Performance Contract
+
+- Single file: under 2 seconds
+- Batch (10 files): under 5 seconds
+- No network calls. No subagent. Pure grep/awk/sed.

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

@@ -0,0 +1,96 @@
+---
+name: px-prose-review
+disable-model-invocation: true
+description: "Deep document review using an isolated subagent. Checks argument quality, clarity, completeness, and adherence to writing-quality.md. Use for design docs, ADRs, READMEs, specs. More thorough than px-doc-lint."
+---
+
+# px-prose-review — Deep Document Review
+
+## Purpose
+
+Performs deep quality review on prose documents using an isolated subagent.
+More thorough than px-doc-lint — checks argument quality, clarity, completeness,
+and adherence to writing-quality.md standards.
+
+## When It Fires
+
+1. On-demand: `/px-prose-review {filepath}`
+2. Automatic: during `/px-ship` against the PR description
+3. Recommended: before finalizing any design doc, ADR, or spec
+
+## Subagent Configuration
+
+The review runs in an isolated context with zero conversation history.
+The subagent receives ONLY the document content and the review instructions.
+
+### Subagent persona
+
+```
+You are a ruthless technical editor. Your job is to make this document
+shorter, clearer, and more precise. You have no loyalty to the author's
+feelings. You have total loyalty to the reader's time.
+
+Rules:
+- Every sentence must earn its place. If it restates something already said, cut it.
+- Every paragraph must have exactly one idea. If it has two, split it.
+- Every claim must be specific. "Improves performance" is not a claim.
+  "Reduces p99 latency from 200ms to 50ms" is.
+- Active voice on all decisions and actions.
+- No fluff words (see kill list in writing-quality.md).
+- No hedging on decided things. "will" not "should" or "might".
+```
+
+The full fluff kill list from writing-quality.md is injected into the subagent prompt.
+
+## Document Type Detection
+
+The subagent detects document type from filename and content:
+
+| Pattern | Type | Structural checks applied |
+| ------- | ---- | ------------------------- |
+| `DESIGN-*.md`, `*-design.md` | Design Doc | Problem, Decision, Tradeoffs, Acceptance Criteria |
+| `ADR-*.md` | ADR | Status, Date, Context, Decision, Consequences (Positive + Negative) |
+| `README.md` | README | First paragraph, Install/Setup, Run, Test |
+| `*.md` in PR context | PR Description | What, Why, How to verify, Breaking changes |
+| All other `*.md` | General prose | Sentence limits, fluff, voice, hedging |
+
+## Review Output Format
+
+```
+## px-prose-review: {filename}
+Type detected: {Design Doc | ADR | README | PR Description | General}
+
+### Structure
+- [PASS|BLOCK] {section}: {detail}
+
+### Clarity
+- Line {N}: {issue} → {suggested fix}
+
+### Fluff
+- Line {N}: "{flagged phrase}" → {replacement or "delete"}
+
+### Voice
+- Line {N}: passive on decision → {active rewrite}
+
+### Verdict
+{CLEAN | {N} issues found — {M} auto-fixable}
+```
+
+## Auto-Fix Flow
+
+For minor issues (fluff deletion, passive-to-active rewrites on clear cases):
+1. Subagent proposes the fix with before/after
+2. Operator is shown the diff
+3. Operator approves or rejects each fix individually
+4. Approved fixes are applied in-place
+
+For structural issues (missing sections, incomplete analysis):
+- Subagent flags the gap and describes what is needed
+- Operator writes the content — subagent does NOT generate missing sections
+- Rationale: the subagent lacks project context to write accurate content
+
+## Limitations
+
+- Does not verify technical accuracy of claims — only prose quality
+- Does not check code blocks inside markdown — only surrounding prose
+- Does not run on files outside the repo (external links, references)

package/base/skills/px-quality-gate/SKILL.md

@@ -0,0 +1,182 @@
+---
+name: px-quality-gate
+disable-model-invocation: true
+description: "Code style and prose quality gate. Checks what linters cannot: naming, doc completeness, prose clarity, structural patterns. Integrated into px-verify as Step 1 item 5b. Also available standalone via /px-quality-gate."
+---
+
+# px-quality-gate — Style and Prose Quality Enforcement
+
+## Purpose
+
+Runs automated style checks against changed files. Catches issues that linters and
+test suites do not: generic variable names, missing docstrings, prose quality,
+structural violations, and import verification.
+
+Integrated into `/px-verify` as Step 1 item 5b (after security scan, before functional check).
+Also available standalone via `/px-quality-gate`.
+
+## When It Fires
+
+1. Automatically inside `/px-verify` after security scan
+2. As the first step of `/px-ship`
+3. On-demand via `/px-quality-gate` for ad-hoc checks
+
+## Scope
+
+Checks run against staged or changed files only (not the full codebase).
+Use `/px-complexity-audit` for full codebase scans.
+
+## Verdicts
+
+- **BLOCK**: violation found — must fix before proceeding. Commit blocked.
+- **WARN**: advisory issue found — commit allowed, fix recommended.
+- **PASS**: all checks clear.
+
+## Check Categories
+
+### 1. Code Structure Checks
+
+Run against all changed code files (exclude vendor/, node_modules/, .git/).
+
+#### File size
+
+```bash
+for f in $(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(go|ts|tsx|js|jsx|py|rs|java|sh|sql)$'); do
+  lines=$(wc -l < "$f")
+  if [[ "$lines" -gt 300 ]]; then
+    echo "BLOCK: $f is $lines lines (limit: 300). Split before committing."
+  fi
+done
+```
+
+#### TODO/FIXME/HACK detection
+
+```bash
+for f in $(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(go|ts|tsx|js|jsx|py|rs|java|sh|sql)$'); do
+  hits=$(grep -nE 'TODO|FIXME|HACK' "$f" || true)
+  if [[ -n "$hits" ]]; then
+    echo "BLOCK: $f contains banned markers. Use QUALITY: with a ticket number instead."
+    echo "$hits"
+  fi
+done
+```
+
+#### Nesting depth heuristic
+
+```bash
+for f in $(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(go|ts|tsx|js|jsx|py|rs|java)$'); do
+  deep=$(grep -nE '^\s{16,}\S|^\t{4,}\S' "$f" || true)
+  if [[ -n "$deep" ]]; then
+    echo "WARN: $f may have deep nesting. Review these lines:"
+    echo "$deep"
+  fi
+done
+```
+
+#### Generic variable names
+
+```bash
+git diff --cached -U0 | grep '^+' | grep -v '^+++' | \
+  grep -oE '\b(data|result|info|temp|tmp|obj|val|item|stuff|thing|ret|res)\b' | \
+  sort | uniq -c | sort -rn | head -10
+```
+
+If any appear 3+ times: WARN with suggestion to use domain-specific names.
+
+#### Missing docstrings on new public functions
+
+```bash
+git diff --cached -U3 | grep -E '^\+.*(func |def |export function |export const .* = )' | \
+  while read -r line; do
+    echo "CHECK: verify doc comment exists for: $line"
+  done
+```
+
+### 2. Prose Checks
+
+Run against all changed markdown files.
+
+#### AI fluff detection
+
+```bash
+FLUFF_PATTERN='leverage|utilize|facilitate|moving forward|going forward|at this point in time|comprehensive solution|robust solution|seamlessly|cutting-edge|best-in-class|in order to|due to the fact that|at the end of the day|synergy|holistic|empower|streamline'
+
+for f in $(git diff --cached --name-only --diff-filter=ACM | grep -E '\.md$'); do
+  hits=$(grep -inE "$FLUFF_PATTERN" "$f" || true)
+  if [[ -n "$hits" ]]; then
+    echo "BLOCK: $f contains fluff phrases. Remove or replace per writing-quality.md."
+    echo "$hits"
+  fi
+done
+```
+
+#### Passive voice on decisions
+
+```bash
+for f in $(git diff --cached --name-only --diff-filter=ACM | grep -E '\.md$'); do
+  hits=$(grep -inE '(it was decided|was implemented|was chosen|was selected|has been determined)' "$f" || true)
+  if [[ -n "$hits" ]]; then
+    echo "WARN: $f uses passive voice on decisions. Rewrite in active voice."
+    echo "$hits"
+  fi
+done
+```
+
+#### Sentence length check
+
+```bash
+for f in $(git diff --cached --name-only --diff-filter=ACM | grep -E '\.md$'); do
+  awk 'BEGIN{RS="[.!?]"} NF>30 {print NR": "NF" words: "$0}' "$f" | head -5
+done
+```
+
+#### Unreplaced placeholders
+
+```bash
+for f in $(git diff --cached --name-only --diff-filter=ACM | grep -E '\.md$'); do
+  hits=$(grep -nE '\{placeholder\}|\{TODO\}|\{TBD\}|\[INSERT\]|\[TBD\]|XXX' "$f" || true)
+  if [[ -n "$hits" ]]; then
+    echo "BLOCK: $f contains unreplaced placeholders."
+    echo "$hits"
+  fi
+done
+```
+
+### 3. Context7 Import Check
+
+```bash
+NEW_IMPORTS=$(git diff --cached -U0 | grep -E '^\+.*(import |require\(|using |use )' | grep -v '^+++' | grep -v '^//\|^#')
+
+if [[ -n "$NEW_IMPORTS" ]]; then
+  echo "GATE: New external imports detected. Each requires a Context7 lookup:"
+  echo "$NEW_IMPORTS"
+  echo ""
+  echo "Confirm each import was verified via Context7 in this session."
+  echo "Internal packages (same repo/module) are excluded."
+fi
+```
+
+## Output Format
+
+```
+━━━ QUALITY GATE ━━━━━━━━━━━━━━━━━━━
+Code checks:   PASS | WARN | BLOCK
+Prose checks:  PASS | WARN | BLOCK
+Import check:  PASS | WARN | BLOCK
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Overall:       PASS | WARN | BLOCK
+
+Details:
+  [BLOCK] services/auth.go: 342 lines (limit: 300)
+  [BLOCK] docs/DESIGN-auth.md: contains "comprehensive solution" (fluff)
+  [WARN]  handlers/login.go: possible deep nesting at line 47
+  [PASS]  All other checks
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## Rules
+
+- Any single BLOCK = overall BLOCK. Commit prevented.
+- WARN-only = overall WARN. Commit allowed. Fix recommended.
+- Gate re-runs on re-stage. Fix the issue, `git add`, gate runs again.
+- Do NOT bypass the gate. There is no `--force` flag.