cursordoctrine 0.3.0 → 0.3.1

package/README.md

@@ -6,7 +6,7 @@ Thin self-review hooks for Cursor. Five hook events, one message bus. The model
 
 A small set of Cursor hooks that make the agent review its own work without bolting a static-analysis pipeline onto every keystroke. There is no regex army and no scoring engine. The hooks do three jobs:
 
-1. **Inject the doctrine** at session start, so every chat begins with the same short governing text (`doctrine.md` + `USER-RULES.md`).
+1. **Inject the doctrine** at session start, so every chat begins with the same short governing text (`doctrine.md` + `USER-RULES.md` + `declared-editing.md` — the YAGNI ultra ladder that prevents over-building before a single line is written).
 2. **Hand the model its own edits back.** After each agent edit, a self-review prompt (plus minimal-edit, semantic-density, and anti-slop advisories when they trip) is stashed and delivered on the next turn. The model reads its own diff, fixes real bugs, and stays quiet otherwise.
 3. **Gate blast radius.** One permission gate denies a short, explicit list of dangerous commands (`rm -rf /`, `curl | sh`, force-push, `npm publish`, ...). Everything else is allowed.
 

package/bin/cli.mjs

@@ -40,7 +40,7 @@ const pendingDir = join(cursorDst, '.hooks-pending');
 const hooksJsonDst = join(cursorDst, 'hooks.json');
 
 const injectName = platform === 'windows' ? 'inject-doctrine.ps1' : 'inject-doctrine.sh';
-const doctrineFiles = [injectName, 'doctrine.md', 'USER-RULES.md'];
+const doctrineFiles = [injectName, 'doctrine.md', 'USER-RULES.md', 'declared-editing.md'];
 
 function payloadHookFiles() {
   return readdirSync(join(payload, 'hooks'));

package/linux/declared-editing.md

@@ -0,0 +1,30 @@
+# Declared-editing — YAGNI ultra
+
+ACTIVE EVERY RESPONSE. No drift back to over-building. Still active if unsure.
+
+Before writing any code, stop at the first rung that holds:
+
+1. Does this need to exist at all? (YAGNI) If no — say so, don't build it.
+2. Does the stdlib already do this? Use it.
+3. Does a native platform feature cover it? Use it.
+4. Does an already-installed dependency solve it? Use it.
+5. Can this be one line? Make it one line.
+6. Only then: write the minimum code that works.
+
+Ultra means:
+
+- Deletion before addition. If you can remove code to solve the problem, remove it.
+- Ship the one-liner and challenge the rest of the requirement in the same breath.
+- A hand-rolled abstraction is a bug farm with a hit rate. Say so.
+- Question complex requests: "Do you actually need X, or does Y cover it?"
+
+Mark intentional simplifications with a `declared:` comment naming the ceiling
+and the upgrade path: `// declared: O(n^2) scan, fine <10k rows; index at 50k`.
+
+Not lazy about: input validation at trust boundaries, error handling that
+prevents data loss, security, accessibility, anything explicitly requested.
+Non-trivial logic leaves ONE runnable check behind (an assert or one small
+test, no framework, no fixtures). Trivial one-liners need none.
+
+Output format when you skipped building something:
+  -> skipped: [X], add when [Y]

package/linux/hooks/subagent-stop-review.sh

@@ -1,103 +1,103 @@
-#!/usr/bin/env bash
-# subagent-stop-review.sh - subagentStop for Cursor (Linux).
-#
-# Counterpart of final-review.sh for delegated work. afterFileEdit DOES fire
-# inside subagents (verified: a subagent run left its edits in
-# session-edits-<subagent-cid>.txt), but subagents get no `stop` event, so
-# that marker is never drained and the five-axis review never fires for
-# delegated implementations. This hook closes the loop: when a subagent
-# finishes and ITS conversation has a session-edits marker, return ONE
-# followup_message so the subagent audits its own implementation before the
-# result goes back to the parent.
-#
-# Same bounding pattern as final-review.sh:
-#   - marker-gated: no edits in the subagent run -> no review, no noise,
-#   - reviewed-<cid>.flag one-shot brake: the stop AFTER the review pass
-#     clears flag + marker and ends the loop (one review per implementation;
-#     resumed subagents with a second implementation get a second review),
-#   - loop_limit in hooks.json caps runaway follow-ups harness-side,
-#   - only on status == 'completed' when a status field is present.
-#
-# If subagentStop's stdin carries a conversation_id that doesn't match the
-# id afterFileEdit used, the marker lookup misses and this emits {} - the
-# marker fold in post-tool-use.sh / final-review.sh still routes the
-# subagent's edits into the parent's stop review as the backstop.
-#
-# Always emits valid JSON ({} = no follow-up). Review body reuses
-# final-review.md (embedded fallback if missing).
-# Disable: HOOKS_ENFORCE=0 or SUBAGENT_REVIEW_ENFORCE=0.
-
-set +e
-. "$(dirname "$0")/hook-common.sh"
-
-emit_none() { printf '{}'; exit 0; }
-
-[ "${HOOKS_ENFORCE:-}" = "0" ] && emit_none
-[ "${SUBAGENT_REVIEW_ENFORCE:-}" = "0" ] && emit_none
-
-input="$(read_hook_stdin)"
-[ -n "$input" ] || emit_none
-
-status="$(json_get "$input" status)"
-cid="$(safe_conversation_id "$input")"
-
-pending_dir="$(hooks_pending_dir)"
-marker="$pending_dir/session-edits-$cid.txt"
-flag="$pending_dir/reviewed-$cid.flag"
-
-# One-shot brake: the previous subagentStop for this id emitted the review.
-if [ -f "$flag" ]; then
-    rm -f "$flag" "$marker" 2>/dev/null
-    emit_none
-fi
-
-# Review only a clean completion; otherwise clear the marker and stop.
-if [ -n "$status" ] && [ "$status" != "completed" ]; then
-    rm -f "$marker" 2>/dev/null
-    emit_none
-fi
-
-# No edits this run -> nothing to review.
-[ -f "$marker" ] || emit_none
-edited="$(grep -vE '^[[:space:]]*$' "$marker" 2>/dev/null | sort -u)"
-rm -f "$marker" 2>/dev/null
-[ -n "$edited" ] || emit_none
-
-# Compose the follow-up review prompt (md preferred, embedded fallback).
-prompt_file="$HOME/.agents/hooks/final-review.md"
-body=""
-[ -f "$prompt_file" ] && body="$(cat "$prompt_file")"
-if [ -z "$body" ]; then
-    body='Audit everything you changed in this run and FIX what fails (do NOT revert the
-behaviour the task asked for):
-  1. Correctness - logic, edge cases (null/empty/zero/boundary), language traps, security.
-  2. Reliability - error paths handled, no swallowed errors, resources released.
-  3. Coverage - behaviour-bearing changes have real tests; RUN the suite if present.
-  4. Anti-slop - if ~/.cursor/skills/anti-slop/scripts/scan_slop.py exists, run
-     `python ~/.cursor/skills/anti-slop/scripts/scan_slop.py --all`; otherwise
-     apply ~/.agents/hooks/anti-slop.md to the session diff.
-If an axis is clean, say so in one line. Then stop.'
-fi
-body="$(expand_agent_paths "$body")"
-
-file_list=""
-while IFS= read -r p; do
-    [ -n "$p" ] || continue
-    rp="$(resolve_agent_path "$p")"
-    file_list="${file_list}  ${rp}"$'\n'
-done <<EOF
-$edited
-EOF
-file_list="$(printf '%s' "$file_list" | head -n 30)"
-msg="SUBAGENT FINAL REVIEW - you just finished delegated implementation work. Before your result returns to the parent agent, audit it.
-
-Files you changed this run:
-$file_list
-
-$body"
-
-# Arm the one-shot brake BEFORE emitting, so a crash after emit can't re-fire.
-touch "$flag" 2>/dev/null
-
-emit_json followup_message "$msg"
-exit 0
+#!/usr/bin/env bash
+# subagent-stop-review.sh - subagentStop for Cursor (Linux).
+#
+# Counterpart of final-review.sh for delegated work. afterFileEdit DOES fire
+# inside subagents (verified: a subagent run left its edits in
+# session-edits-<subagent-cid>.txt), but subagents get no `stop` event, so
+# that marker is never drained and the five-axis review never fires for
+# delegated implementations. This hook closes the loop: when a subagent
+# finishes and ITS conversation has a session-edits marker, return ONE
+# followup_message so the subagent audits its own implementation before the
+# result goes back to the parent.
+#
+# Same bounding pattern as final-review.sh:
+#   - marker-gated: no edits in the subagent run -> no review, no noise,
+#   - reviewed-<cid>.flag one-shot brake: the stop AFTER the review pass
+#     clears flag + marker and ends the loop (one review per implementation;
+#     resumed subagents with a second implementation get a second review),
+#   - loop_limit in hooks.json caps runaway follow-ups harness-side,
+#   - only on status == 'completed' when a status field is present.
+#
+# If subagentStop's stdin carries a conversation_id that doesn't match the
+# id afterFileEdit used, the marker lookup misses and this emits {} - the
+# marker fold in post-tool-use.sh / final-review.sh still routes the
+# subagent's edits into the parent's stop review as the backstop.
+#
+# Always emits valid JSON ({} = no follow-up). Review body reuses
+# final-review.md (embedded fallback if missing).
+# Disable: HOOKS_ENFORCE=0 or SUBAGENT_REVIEW_ENFORCE=0.
+
+set +e
+. "$(dirname "$0")/hook-common.sh"
+
+emit_none() { printf '{}'; exit 0; }
+
+[ "${HOOKS_ENFORCE:-}" = "0" ] && emit_none
+[ "${SUBAGENT_REVIEW_ENFORCE:-}" = "0" ] && emit_none
+
+input="$(read_hook_stdin)"
+[ -n "$input" ] || emit_none
+
+status="$(json_get "$input" status)"
+cid="$(safe_conversation_id "$input")"
+
+pending_dir="$(hooks_pending_dir)"
+marker="$pending_dir/session-edits-$cid.txt"
+flag="$pending_dir/reviewed-$cid.flag"
+
+# One-shot brake: the previous subagentStop for this id emitted the review.
+if [ -f "$flag" ]; then
+    rm -f "$flag" "$marker" 2>/dev/null
+    emit_none
+fi
+
+# Review only a clean completion; otherwise clear the marker and stop.
+if [ -n "$status" ] && [ "$status" != "completed" ]; then
+    rm -f "$marker" 2>/dev/null
+    emit_none
+fi
+
+# No edits this run -> nothing to review.
+[ -f "$marker" ] || emit_none
+edited="$(grep -vE '^[[:space:]]*$' "$marker" 2>/dev/null | sort -u)"
+rm -f "$marker" 2>/dev/null
+[ -n "$edited" ] || emit_none
+
+# Compose the follow-up review prompt (md preferred, embedded fallback).
+prompt_file="$HOME/.agents/hooks/final-review.md"
+body=""
+[ -f "$prompt_file" ] && body="$(cat "$prompt_file")"
+if [ -z "$body" ]; then
+    body='Audit everything you changed in this run and FIX what fails (do NOT revert the
+behaviour the task asked for):
+  1. Correctness - logic, edge cases (null/empty/zero/boundary), language traps, security.
+  2. Reliability - error paths handled, no swallowed errors, resources released.
+  3. Coverage - behaviour-bearing changes have real tests; RUN the suite if present.
+  4. Anti-slop - if ~/.cursor/skills/anti-slop/scripts/scan_slop.py exists, run
+     `python ~/.cursor/skills/anti-slop/scripts/scan_slop.py --all`; otherwise
+     apply ~/.agents/hooks/anti-slop.md to the session diff.
+If an axis is clean, say so in one line. Then stop.'
+fi
+body="$(expand_agent_paths "$body")"
+
+file_list=""
+while IFS= read -r p; do
+    [ -n "$p" ] || continue
+    rp="$(resolve_agent_path "$p")"
+    file_list="${file_list}  ${rp}"$'\n'
+done <<EOF
+$edited
+EOF
+file_list="$(printf '%s' "$file_list" | head -n 30)"
+msg="SUBAGENT FINAL REVIEW - you just finished delegated implementation work. Before your result returns to the parent agent, audit it.
+
+Files you changed this run:
+$file_list
+
+$body"
+
+# Arm the one-shot brake BEFORE emitting, so a crash after emit can't re-fire.
+touch "$flag" 2>/dev/null
+
+emit_json followup_message "$msg"
+exit 0

package/linux/inject-doctrine.sh

@@ -16,7 +16,7 @@ set +e
 cat >/dev/null
 
 context=""
-for p in "$HOME/.cursor/doctrine.md" "$HOME/.cursor/USER-RULES.md"; do
+for p in "$HOME/.cursor/doctrine.md" "$HOME/.cursor/USER-RULES.md" "$HOME/.cursor/declared-editing.md"; do
     if [ -f "$p" ]; then
         part="$(cat "$p")"
         if [ -n "$context" ]; then context="$context

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cursordoctrine",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Thin self-review hooks for Cursor — the model is the auditor. Intent-trace final review (Tier 0), unified 13-item anti-slop checklist, operational slop detection.",
   "bin": {
     "cursordoctrine": "bin/cli.mjs"

package/windows/declared-editing.md

@@ -0,0 +1,30 @@
+# Declared-editing — YAGNI ultra
+
+ACTIVE EVERY RESPONSE. No drift back to over-building. Still active if unsure.
+
+Before writing any code, stop at the first rung that holds:
+
+1. Does this need to exist at all? (YAGNI) If no — say so, don't build it.
+2. Does the stdlib already do this? Use it.
+3. Does a native platform feature cover it? Use it.
+4. Does an already-installed dependency solve it? Use it.
+5. Can this be one line? Make it one line.
+6. Only then: write the minimum code that works.
+
+Ultra means:
+
+- Deletion before addition. If you can remove code to solve the problem, remove it.
+- Ship the one-liner and challenge the rest of the requirement in the same breath.
+- A hand-rolled abstraction is a bug farm with a hit rate. Say so.
+- Question complex requests: "Do you actually need X, or does Y cover it?"
+
+Mark intentional simplifications with a `declared:` comment naming the ceiling
+and the upgrade path: `// declared: O(n^2) scan, fine <10k rows; index at 50k`.
+
+Not lazy about: input validation at trust boundaries, error handling that
+prevents data loss, security, accessibility, anything explicitly requested.
+Non-trivial logic leaves ONE runnable check behind (an assert or one small
+test, no framework, no fixtures). Trivial one-liners need none.
+
+Output format when you skipped building something:
+  -> skipped: [X], add when [Y]

package/windows/inject-doctrine.ps1

@@ -1,58 +1,59 @@
-# inject-doctrine.ps1 - Cursor sessionStart injection.
-#
-# Emits {"additional_context": "<doctrine + USER-RULES>"} as PURE-ASCII JSON.
-#
-# Why pure ASCII: the doctrine contains multi-byte UTF-8 characters (em dash,
-# section sign, <=, arrows). Written as UTF-8, their continuation bytes
-# (0x80-0x9F) get decoded by Cursor's JSON reader as C1 control characters ->
-# "Bad control character in string literal in JSON at position N". Escaping every
-# non-ASCII char to \uXXXX makes the output byte-identical under EVERY encoding,
-# so it cannot be mangled; JSON.parse turns § back into the real char. We
-# also write the bytes straight to stdout to bypass [Console]::OutputEncoding.
-#
-# Fail open: missing files or any error -> "{}" (valid, empty). Never block or
-# crash session start.
-
-$ErrorActionPreference = 'SilentlyContinue'
-
-# Drain stdin (Cursor sends session metadata) so the pipe never blocks.
-$null = [Console]::In.ReadToEnd()
-
-function Write-StdoutAscii([string]$s) {
-    # Write exact ASCII bytes to stdout, immune to whatever [Console]::OutputEncoding is.
-    $bytes = [System.Text.Encoding]::ASCII.GetBytes($s)
-    $stdout = [Console]::OpenStandardOutput()
-    $stdout.Write($bytes, 0, $bytes.Length)
-    $stdout.Flush()
-}
-
-try {
-    $paths = @(
-        (Join-Path $PSScriptRoot 'doctrine.md'),
-        (Join-Path $PSScriptRoot 'USER-RULES.md')
-    )
-
-    $parts = foreach ($p in $paths) {
-        if (Test-Path -LiteralPath $p) { Get-Content -Raw -LiteralPath $p }
-    }
-    $context = ($parts -join "`n`n").Trim()
-
-    if (-not $context) { Write-StdoutAscii '{}'; exit 0 }
-
-    $json = @{ additional_context = $context } | ConvertTo-Json -Compress
-
-    # Escape every non-ASCII (and any stray control) char to \uXXXX -> pure ASCII.
-    # ConvertTo-Json's structural chars and \n / \" escapes are ASCII and pass through.
-    $sb = [System.Text.StringBuilder]::new($json.Length + 64)
-    foreach ($ch in $json.ToCharArray()) {
-        $code = [int][char]$ch
-        if ($code -lt 32 -or $code -gt 126) { [void]$sb.AppendFormat('\u{0:x4}', $code) }
-        else { [void]$sb.Append($ch) }
-    }
-    Write-StdoutAscii $sb.ToString()
-}
-catch {
-    Write-StdoutAscii '{}'
-}
-
-exit 0
+# inject-doctrine.ps1 - Cursor sessionStart injection.
+#
+# Emits {"additional_context": "<doctrine + USER-RULES>"} as PURE-ASCII JSON.
+#
+# Why pure ASCII: the doctrine contains multi-byte UTF-8 characters (em dash,
+# section sign, <=, arrows). Written as UTF-8, their continuation bytes
+# (0x80-0x9F) get decoded by Cursor's JSON reader as C1 control characters ->
+# "Bad control character in string literal in JSON at position N". Escaping every
+# non-ASCII char to \uXXXX makes the output byte-identical under EVERY encoding,
+# so it cannot be mangled; JSON.parse turns § back into the real char. We
+# also write the bytes straight to stdout to bypass [Console]::OutputEncoding.
+#
+# Fail open: missing files or any error -> "{}" (valid, empty). Never block or
+# crash session start.
+
+$ErrorActionPreference = 'SilentlyContinue'
+
+# Drain stdin (Cursor sends session metadata) so the pipe never blocks.
+$null = [Console]::In.ReadToEnd()
+
+function Write-StdoutAscii([string]$s) {
+    # Write exact ASCII bytes to stdout, immune to whatever [Console]::OutputEncoding is.
+    $bytes = [System.Text.Encoding]::ASCII.GetBytes($s)
+    $stdout = [Console]::OpenStandardOutput()
+    $stdout.Write($bytes, 0, $bytes.Length)
+    $stdout.Flush()
+}
+
+try {
+    $paths = @(
+        (Join-Path $PSScriptRoot 'doctrine.md'),
+        (Join-Path $PSScriptRoot 'USER-RULES.md'),
+        (Join-Path $PSScriptRoot 'declared-editing.md')
+    )
+
+    $parts = foreach ($p in $paths) {
+        if (Test-Path -LiteralPath $p) { Get-Content -Raw -LiteralPath $p }
+    }
+    $context = ($parts -join "`n`n").Trim()
+
+    if (-not $context) { Write-StdoutAscii '{}'; exit 0 }
+
+    $json = @{ additional_context = $context } | ConvertTo-Json -Compress
+
+    # Escape every non-ASCII (and any stray control) char to \uXXXX -> pure ASCII.
+    # ConvertTo-Json's structural chars and \n / \" escapes are ASCII and pass through.
+    $sb = [System.Text.StringBuilder]::new($json.Length + 64)
+    foreach ($ch in $json.ToCharArray()) {
+        $code = [int][char]$ch
+        if ($code -lt 32 -or $code -gt 126) { [void]$sb.AppendFormat('\u{0:x4}', $code) }
+        else { [void]$sb.Append($ch) }
+    }
+    Write-StdoutAscii $sb.ToString()
+}
+catch {
+    Write-StdoutAscii '{}'
+}
+
+exit 0