cursordoctrine 0.1.0

package/windows/hooks/minimal-edit-audit.ps1

@@ -0,0 +1,116 @@
+# minimal-edit-audit.ps1 - afterFileEdit minimal-editing advisory (Cursor).
+#
+# Audits the just-edited file for over-editing:
+#   * line-count  - git diff --numstat thresholds (any language). Native git,
+#                   no bash (Git's MSYS bash mangles Windows paths / lacks PATH
+#                   when spawned from pwsh, so we compute this directly).
+#   * token metrics - audit-metrics.py (token-Levenshtein + cognitive
+#                   complexity), Python files only, via a resolved interpreter.
+# On WARN/FAIL it APPENDS a short advisory to the shared pending-feedback file;
+# post-tool-use.ps1 delivers it as additional_context on the next tool turn.
+#
+# Advisory only: never blocks, never writes persistent state. afterFileEdit
+# output isn't consumed and a non-zero exit shows as "hook failed", so we
+# ALWAYS exit 0. Self-contained.
+#
+# Thresholds (env-overridable): MINIMAL_EDIT_FAIL_LINES (400), MINIMAL_EDIT_WARN_LINES (100).
+# Disable: HOOKS_ENFORCE=0  or  MINIMAL_EDITING_ENFORCE=0
+
+$ErrorActionPreference = 'SilentlyContinue'
+. "$PSScriptRoot\hook-common.ps1"
+
+if ($env:HOOKS_ENFORCE -eq '0' -or $env:MINIMAL_EDITING_ENFORCE -eq '0') { exit 0 }
+
+$obj = Read-HookStdinJson
+if (-not $obj) { exit 0 }
+
+# audit root = project from JSON (cwd, then workspace_roots), else CURSOR_PROJECT_DIR / HOME
+$root = ''
+$cands = @()
+if ($obj.PSObject.Properties['cwd'] -and $obj.cwd) { $cands += [string]$obj.cwd }
+if ($obj.PSObject.Properties['workspace_roots']) { foreach ($w in $obj.workspace_roots) { $cands += [string]$w } }
+foreach ($c in $cands) { $f = ConvertTo-FwdPath $c; if ($f -and (Test-Path -LiteralPath $f)) { $root = $f.TrimEnd('/'); break } }
+if (-not $root) { $root = (& { if ($env:CURSOR_PROJECT_DIR) { $env:CURSOR_PROJECT_DIR } else { $HOME } }).Replace('\', '/').TrimEnd('/') }
+
+# edited file -> repo-relative forward-slash path
+$fp = ''
+foreach ($k in 'file_path', 'path', 'filename', 'absolute_path', 'abs_path') {
+    if ($obj.PSObject.Properties[$k] -and $obj.$k) { $fp = [string]$obj.$k; break }
+}
+if (-not $fp) { exit 0 }
+$rel = ConvertTo-FwdPath $fp
+if ($rel.StartsWith($root + '/', [System.StringComparison]::OrdinalIgnoreCase)) { $rel = $rel.Substring($root.Length + 1) }
+if (Test-IsCursorConfigPath $fp) { exit 0 }
+if (Test-IsCursorConfigPath $rel) { exit 0 }
+
+# git repo?
+& git -C $root rev-parse --git-dir 2>$null | Out-Null
+if ($LASTEXITCODE -ne 0) { exit 0 }
+
+# --- line-count audit (any language) via native git ----------------------
+$failLines = if ($env:MINIMAL_EDIT_FAIL_LINES) { [int]$env:MINIMAL_EDIT_FAIL_LINES } else { 400 }
+$warnLines = if ($env:MINIMAL_EDIT_WARN_LINES) { [int]$env:MINIMAL_EDIT_WARN_LINES } else { 100 }
+$ins = 0; $del = 0
+foreach ($line in (& git -C $root diff HEAD --numstat -- $rel 2>$null)) {
+    $parts = $line -split "`t"
+    if ($parts.Count -lt 3 -or $parts[0] -eq '-') { continue }   # skip header/binary
+    $ins += [int]$parts[0]; $del += [int]$parts[1]
+}
+$changed = $ins + $del
+
+$grade = 'OK'; $hint = ''
+if ($changed -gt $failLines) { $grade = 'FAIL'; $hint = "$changed lines changed (limit $failLines) - likely over-editing; trim or split" }
+elseif ($changed -gt $warnLines) { $grade = 'WARN'; $hint = "$changed lines changed - justify each hunk or split the task" }
+
+# --- token metrics (.py only) via a resolved interpreter -----------------
+$auditMetrics = Join-Path $HOME '.cursor\skills\minimal-editing\scripts\audit-metrics.py'
+if ((Test-Path $auditMetrics) -and ($rel -match '\.py$')) {
+    # Windows often ships the interpreter as `py` or `python3`, not `python`.
+    # Without this resolution the call errored silently and .py metrics never ran.
+    $py = Get-Command python, python3, py -ErrorAction SilentlyContinue | Select-Object -First 1
+    if ($py) {
+        $mout = & $py.Source $auditMetrics --root $root --format json --path $rel 2>$null
+        $mo = $null; try { $mo = ($mout -join "`n") | ConvertFrom-Json } catch { }
+        if ($mo -and $mo.grade) {
+            if ($mo.grade -eq 'FAIL') { $grade = 'FAIL' }
+            elseif ($mo.grade -eq 'WARN' -and $grade -eq 'OK') { $grade = 'WARN' }
+        }
+    }
+}
+
+if ($grade -eq 'OK') { exit 0 }
+
+# --- compose advisory + append to the shared pending file ----------------
+$hintTxt = if ($hint) { " - $hint" } else { '' }
+if ($grade -eq 'FAIL') {
+    $actions = @"
+  - Trim every hunk that isn't required by the task.
+  - Prefer narrow, targeted edits over rewriting blocks.
+  - If the change is genuinely large, split it into smaller logical commits.
+"@
+} else {
+    $actions = '  Advisory only - trim unrelated hunks if any; otherwise proceed.'
+}
+
+$msg = @"
+Minimal-edit audit $grade - $rel
+
+IMPORTANT: Try to preserve the original code and the logic of the original code as much as possible.
+
+grade: $grade$hintTxt
+
+$actions
+
+(Disable for this session: HOOKS_ENFORCE=0)
+"@
+
+$cid = Get-SafeConversationId $obj
+$pending = Join-Path (Get-HooksPendingDir) "feedback-$cid.txt"
+try {
+    New-Item -ItemType Directory -Path (Split-Path $pending) -Force | Out-Null
+    $prefix = ''
+    if ((Test-Path $pending) -and ((Get-Item $pending).Length -gt 0)) { $prefix = "`n`n---`n`n" }
+    Add-Content -Path $pending -Value ($prefix + $msg) -NoNewline
+} catch { }
+
+exit 0

package/windows/hooks/permission-gate.ps1

@@ -0,0 +1,98 @@
+# permission-gate.ps1 - beforeShellExecution for Cursor.
+#
+# Single responsibility: deny a small, explicit list of dangerous commands.
+# This is a *permission* gate, not a *quality* gate. The model handles
+# quality; the harness handles blast radius.
+#
+# Behavior:
+#   - Exit 0 always.
+#   - Print Cursor-canonical {"permission": "allow"|"deny", ...} JSON.
+#   - On internal failure: fail OPEN (allow), never block the user.
+#
+# Disable: PERM_GATE_ENFORCE=0
+
+$ErrorActionPreference = 'SilentlyContinue'
+. "$PSScriptRoot\hook-common.ps1"
+
+if ($env:PERM_GATE_ENFORCE -eq '0') {
+    Write-HookJson @{ permission = 'allow' }
+    exit 0
+}
+
+# Without BOM-safe decode the JSON never parses, the raw-text fallback below
+# matches deny patterns anywhere in the envelope (false positives), and the
+# deny message leaks conversation id / transcript path / user email into the UI.
+$inputText = Read-HookStdin
+
+$cmd = ''
+if ($inputText) {
+    try {
+        $obj = $inputText | ConvertFrom-Json
+        if ($obj -and $obj.PSObject.Properties['command']) {
+            $cmd = [string]$obj.command
+        }
+    } catch {
+        $cmd = ''
+    }
+    # Belt-and-braces: if stdin was not the documented JSON shape, still gate
+    # on the raw text rather than waving everything through.
+    if (-not $cmd) { $cmd = $inputText }
+}
+
+if (-not $cmd) {
+    Write-HookJson @{ permission = 'allow' }
+    exit 0
+}
+
+function Test-Deny {
+    param([string]$Pattern, [string]$Reason)
+    if ($cmd -match $Pattern) { Deny $Reason }
+}
+
+function Deny {
+    param([string]$Reason)
+    # Truncate the echo: the command can be a multi-hundred-char one-liner and
+    # the UI message only needs enough to identify it.
+    $shown = if ($cmd.Length -gt 400) { $cmd.Substring(0, 400) + '...' } else { $cmd }
+    $userMsg = "BLOCKED by permission-gate: $Reason`n`nCommand: $shown`n`nIf this is genuinely intended, run it yourself in your terminal."
+    Write-HookJson @{
+        permission    = 'deny'
+        user_message  = $userMsg
+        agent_message = "$userMsg Do not retry verbatim. Ask the user to run it manually if it is truly intended."
+    }
+    exit 0
+}
+
+# --- POSIX-flavored ---------------------------------------------------------
+# Anchored to start OR a command separator so `cd /tmp && rm -rf /` is caught,
+# while `git rm`, `npm run rm-cache`, `echo "rm -rf /"` stay allowed.
+Test-Deny '(?:^|[;&|]\s*)(?:sudo\s+)?rm\s+-[a-zA-Z]*([rR][fF]|[fF][rR])[a-zA-Z]*\s+/' 'destructive rm -rf on absolute path (use relative paths or be more specific)'
+Test-Deny ':\(\)\{\s*:\|:&\s*\};:|bash\s+-c\s+["'']*:\s*\(\)\{' 'reverse shell / fork-bomb pattern'
+Test-Deny 'curl\s.*\|\s*(sudo\s*)?(bash|sh|zsh|dash|ash)' 'curl piped to shell'
+Test-Deny 'wget\s.*\|\s*(sudo\s*)?(bash|sh|zsh|dash|ash)' 'wget piped to shell'
+Test-Deny 'git\s+push\s+.*--force(-with-lease)?(\s|$)' 'git push --force'
+Test-Deny 'git\s+push\s+(-f|--force)(\s|$)' 'git push -f / --force'
+Test-Deny 'git\s+reset\s+--hard' 'git reset --hard (data loss)'
+Test-Deny 'git\s+clean\s+-[a-zA-Z]*f' 'git clean -f (untracked data loss)'
+Test-Deny 'dd\s.*of=/dev/(sd|nvme|hd|xvd)' 'dd to block device'
+Test-Deny 'mkfs(\.[a-z0-9]+)?\s+/dev/' 'mkfs on device'
+Test-Deny 'chmod\s+-R\s+777\s+/' 'chmod -R 777 on root'
+Test-Deny 'chown\s+-R\s+[^\s]+\s+/' 'chown -R on root'
+Test-Deny '^(npm|pnpm|yarn)\s+publish(\s|$)' 'package publish (use ship-hook, not direct publish)'
+
+# --- Windows equivalents (the agent shell here IS PowerShell) ---------------
+# iwr/irm | iex is the moral twin of curl|sh.
+Test-Deny '\b(iwr|irm|curl|wget|Invoke-WebRequest|Invoke-RestMethod)\b[^|]*\|\s*(iex\b|Invoke-Expression)' 'web download piped to Invoke-Expression'
+# Disk-level destruction, twin of mkfs / dd-to-device.
+Test-Deny '\b(Format-Volume|Clear-Disk)\b' 'disk format / clear (destructive)'
+# Recursive+forced delete of a bare drive root, user-profile root, or
+# C:\Users / C:\Windows. Twin of rm -rf /. Composed checks instead of one
+# unreadable regex; subfolder deletes (e.g. C:\Temp\x) stay allowed.
+$rmVerb    = '(?:^|[;&|]\s*)(?:Remove-Item|rm|ri|del|erase|rd|rmdir)\s'
+$rootPath  = '(?:^|[\s"''])(?:[A-Za-z]:[\\/]{0,2}|[A-Za-z]:[\\/](?:Users|Windows)[\\/]?|\$(?:env:USERPROFILE|HOME)[\\/]?)["'']?\s*(?:$|[;&|-])'
+if (($cmd -match $rmVerb) -and ($cmd -match $rootPath) -and ($cmd -match '(?:-Recurse\b|/s\b)') -and ($cmd -match '(?:-Force\b|/q\b)')) {
+    Deny 'recursive forced delete of a drive root / Users / Windows / profile root'
+}
+
+Write-HookJson @{ permission = 'allow' }
+exit 0

package/windows/hooks/post-tool-use.ps1

@@ -0,0 +1,46 @@
+# post-tool-use.ps1 - postToolUse for Cursor.
+#
+# Two responsibilities, both message-bus work, keyed by conversation_id so
+# concurrent sessions never receive each other's prompts:
+#
+#   1. Fold completed subagents' session-edits markers into this
+#      conversation's marker (postToolUse does NOT fire for the Task tool -
+#      verified - so this per-tool-boundary fold is how delegated edits reach
+#      the parent's stop-hook final review). When a fold happens, prime the
+#      parent to audit the subagent's diff now.
+#   2. Drain this conversation's stashed self-review / advisory messages into
+#      Cursor's additional_context channel. One-shot delivery.
+#
+# We do not parse, score, or filter. We do not run any audit. We do not
+# block. The model that already produced the edit will, on its next
+# turn, do the self-review.
+
+$ErrorActionPreference = 'SilentlyContinue'
+. "$PSScriptRoot\hook-common.ps1"
+
+$obj = Read-HookStdinJson
+$cid = Get-SafeConversationId $obj
+
+$foldNote = ''
+if (Merge-SubagentEditMarkers $obj $cid) {
+    $foldNote = "SUBAGENT WORK DETECTED - a subagent of this conversation edited files (its edits fired hooks in ITS context, not yours). YOU are the auditor of its work: audit its diff (git status / git diff on the files it touched) against ~/.agents/hooks/self-review.md. Fix real bugs; stay silent otherwise. Its files are folded into this conversation's end-of-implementation review."
+}
+
+$pendingFile = Join-Path (Get-HooksPendingDir) "feedback-$cid.txt"
+
+$msg = ''
+if (Test-Path $pendingFile) {
+    if ((Get-Item $pendingFile).Length -gt 0) {
+        $msg = Get-Content $pendingFile -Raw
+    }
+    # One-shot: clear before emitting so a hook error doesn't replay forever.
+    Remove-Item $pendingFile -Force -ErrorAction SilentlyContinue
+}
+
+if ($foldNote) {
+    if ($msg) { $msg = "$foldNote`n`n---`n`n$msg" } else { $msg = $foldNote }
+}
+if (-not $msg) { exit 0 }
+
+Write-HookJson @{ additional_context = $msg }
+exit 0

package/windows/hooks/self-review-trigger.ps1

@@ -0,0 +1,83 @@
+# self-review-trigger.ps1 - afterFileEdit for Cursor.
+#
+# Single responsibility: when the model just edited a file, hand the
+# edit context to the NEXT model turn as additional_context. The model
+# is the auditor; the harness is just the message bus.
+#
+# This is intentionally minimal:
+#   - We do NOT parse the diff ourselves.
+#   - We do NOT spawn a sub-agent.
+#   - We do NOT write to .stuck-files/.
+#   - We do NOT block.
+#
+# We DO:
+#   - Capture the edited file path.
+#   - Stash a self-review prompt that primes the model's next turn.
+#   - Exit 0 always.
+#
+# Cursor's afterFileEdit doesn't consume its own output. To actually
+# surface the message, post-tool-use.ps1 re-emits it on the next tool
+# boundary. See hooks.json.
+
+$ErrorActionPreference = 'SilentlyContinue'
+. "$PSScriptRoot\hook-common.ps1"
+
+$inputText = Read-HookStdin
+
+$filePath = ''
+$cid = ''
+if ($inputText) {
+    try {
+        $obj = $inputText | ConvertFrom-Json
+        if ($obj) {
+            if     ($obj.PSObject.Properties['file_path']) { $filePath = [string]$obj.file_path }
+            elseif ($obj.PSObject.Properties['path'])      { $filePath = [string]$obj.path }
+            elseif ($obj.PSObject.Properties['filePath'])  { $filePath = [string]$obj.filePath }
+            $cid = Get-SafeConversationId $obj
+        }
+    } catch {
+        $filePath = ''
+    }
+}
+
+# Empty path (JSON parse failed, or no file_path field) -> nothing to record.
+# Without this guard the .cursor regex below doesn't match '' and we append a
+# blank line to the session-edits marker on every such fire (it accumulates fast).
+if (-not $filePath) { exit 0 }
+if (Test-IsCursorConfigPath $filePath) { exit 0 }
+
+# State is keyed by conversation_id and lives under $HOME, never the project:
+# no repo litter, works in workspace-less sessions (CURSOR_PROJECT_DIR/
+# workspace_roots are empty there), and concurrent sessions cannot drain each
+# other's prompts.
+$pendingDir = Get-HooksPendingDir
+
+# Record this edit for the end-of-implementation review. The stop hook
+# (final-review.ps1) drains this marker to fire one final review pass over
+# everything changed this agent loop. Append = running list of edits.
+try {
+    $mk = Join-Path $pendingDir "session-edits-$cid.txt"
+    New-Item -ItemType Directory -Path $pendingDir -Force | Out-Null
+    Add-Content -Path $mk -Value $filePath
+} catch { }
+
+$doctrineFile = Join-Path $HOME '.agents\hooks\self-review.md'
+if (-not (Test-Path $doctrineFile)) { exit 0 }
+$doctrine = Get-Content $doctrineFile -Raw
+
+$msg = "SELF-REVIEW TRIGGER - you just edited: $filePath`n`n$doctrine"
+
+$pendingFile = Join-Path $pendingDir "feedback-$cid.txt"
+
+try {
+    New-Item -ItemType Directory -Path $pendingDir -Force | Out-Null
+    $prefix = ''
+    if ((Test-Path $pendingFile) -and ((Get-Item $pendingFile).Length -gt 0)) {
+        $prefix = "`n`n---`n`n"
+    }
+    Add-Content -Path $pendingFile -Value ($prefix + $msg) -NoNewline
+} catch {
+    # Silently fail open
+}
+
+exit 0

package/windows/hooks/self-review.md

@@ -0,0 +1,48 @@
+You are the auditor of your own edit. The user's `Edit` tool just changed a
+file. Your job, on this turn, is to:
+
+  1. Read the file that was just changed.
+  2. Read the diff (provided in the prior tool output).
+  3. Decide: does this edit introduce any of the following?
+     - **Security**: hardcoded secret (AWS key, private key, API token,
+       password in source), `eval(`, `exec(`, `pickle.loads`, `verify=False`,
+       `child_process` with user input, `dangerouslySetInnerHTML` with
+       untrusted data, SQL string concat.
+     - **Correctness**: assignment-in-condition (`if (x = 5)`), `==`/`!=`
+       with `null`/`None`/`NaN` in a comparison, `forEach` with `await`,
+       async `useEffect` with side-effects missing cleanup, `==` instead
+       of `===` in JS, mutable default args in Python, shadowed imports,
+       dead relative imports.
+     - **Safety**: `rm -rf /`, `curl ... | sh`, force-push, `git reset --hard`
+       without a backup, `npm publish` without version bump, secret
+       committed to a public file.
+     - **Logic bugs that the user would actually care about**: a function
+       that returns the wrong thing, an off-by-one, a missing `return`, a
+       wrong import path.
+  4. If you find a real bug, **fix it with `Edit`**, then say nothing.
+     Do not report it. Do not explain it. The user will see the fix
+     in the next message; the bug is gone.
+  5. If the edit is clean, respond with the single word: `clean`.
+
+Hard constraints:
+
+  - **Never revert or re-do work the user asked for.** The user's intent
+    is the source of truth. You are a *post-hoc* auditor, not a rewriter.
+  - **Never change style, naming, formatting, or "improvements" the user
+    did not ask for.** If the user added a one-liner with bad formatting,
+    leave it. Self-review is for *bugs*, not taste.
+  - **Never re-read the whole repo.** Only the file you just edited, and
+    the diff. Context is finite.
+  - **Never run shell commands in this turn.** Your only allowed tool is
+    `Read` and `Edit`. (And `Edit` only if you are fixing a real bug.)
+  - **If you are uncertain whether something is a bug, leave it.** False
+    positives waste user time. The bar is "this would fail a careful
+    code review at Anthropic / Stripe / Vercel." Cosmetic things, missing
+    type hints, and "you could write this more idiomatically" are NOT bugs.
+  - **One pass, no recursion.** If you fix one bug and find another, fix
+    that too — but stop after at most 2 edits. Beyond that you are
+    thrashing.
+
+This is the entire self-review prompt. It is the same prompt, every
+edit, forever. The model is the auditor. There is no regex, no AST
+parse, no Python — the model itself does the work.

package/windows/hooks/subagent-stop-review.ps1

@@ -0,0 +1,89 @@
+# subagent-stop-review.ps1 - subagentStop for Cursor.
+#
+# Counterpart of final-review.ps1 for delegated work. afterFileEdit DOES fire
+# inside subagents (verified: a poteto subagent run left ~58 entries in
+# session-edits-<subagent-cid>.txt), but subagents get no `stop` event, so
+# that marker is never drained and the four-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.ps1:
+#   - 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.ps1 / final-review.ps1 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.
+
+$ErrorActionPreference = 'SilentlyContinue'
+. "$PSScriptRoot\hook-common.ps1"
+
+function Emit-None { '{}'; exit 0 }
+
+if ($env:HOOKS_ENFORCE -eq '0' -or $env:SUBAGENT_REVIEW_ENFORCE -eq '0') { Emit-None }
+
+$obj = Read-HookStdinJson
+if (-not $obj) { Emit-None }
+
+$status = ''
+if ($obj.PSObject.Properties['status']) { $status = [string]$obj.status }
+$cid = Get-SafeConversationId $obj
+
+$pendingDir = Get-HooksPendingDir
+$marker = Join-Path $pendingDir "session-edits-$cid.txt"
+$flag   = Join-Path $pendingDir "reviewed-$cid.flag"
+
+# One-shot brake: the previous subagentStop for this id emitted the review.
+if (Test-Path $flag) {
+    Remove-Item $flag, $marker -Force -ErrorAction SilentlyContinue
+    Emit-None
+}
+
+# Review only a clean completion; otherwise clear the marker and stop.
+if ($status -and $status -ne 'completed') {
+    Remove-Item $marker -Force -ErrorAction SilentlyContinue
+    Emit-None
+}
+
+# No edits this run -> nothing to review.
+if (-not (Test-Path $marker)) { Emit-None }
+$edited = @(Get-Content $marker -ErrorAction SilentlyContinue |
+    Where-Object { $_ -and $_.Trim() } | Select-Object -Unique)
+Remove-Item $marker -Force -ErrorAction SilentlyContinue
+if ($edited.Count -eq 0) { Emit-None }
+
+$body = ''
+$promptFile = Join-Path $HOME '.agents\hooks\final-review.md'
+if (Test-Path $promptFile) { $body = Get-Content -Raw $promptFile }
+if (-not $body) {
+    $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 - no duplicate helpers, premature abstraction, unneeded deps,
+     redundant comments, dead code.
+If an axis is clean, say so in one line. Then stop.
+'@
+}
+
+$fileList = ($edited | Select-Object -First 30) -join "`n  "
+$msg = "SUBAGENT FINAL REVIEW - you just finished delegated implementation work. Before your result returns to the parent agent, audit it.`n`nFiles you changed this run:`n  $fileList`n`n$body"
+
+# Arm the one-shot brake BEFORE emitting, so a crash after emit can't re-fire.
+New-Item -ItemType File -Path $flag -Force -ErrorAction SilentlyContinue | Out-Null
+
+Write-HookJson @{ followup_message = $msg }
+exit 0

package/windows/hooks.json

@@ -0,0 +1,64 @@
+{
+  "version": 1,
+  "hooks": {
+    "sessionStart": [
+      {
+        "command": "pwsh.exe -NoProfile -File ~/.cursor/inject-doctrine.ps1",
+        "timeout": 5,
+        "_comment": "5s: inject the agent doctrine + user rules at session start. inject-doctrine.ps1 reads ~/.cursor/doctrine.md + USER-RULES.md and emits them as {\"additional_context\": ...} JSON (sessionStart does NOT consume raw stdout)."
+      }
+    ],
+    "afterFileEdit": [
+      {
+        "command": "pwsh.exe -NoProfile -File ~/.agents/hooks/self-review-trigger.ps1",
+        "timeout": 5,
+        "matcher": "^(Write|StrReplace|EditNotebook)$",
+        "_comment": "5s: record the edit in ~/.cursor/.hooks-pending/session-edits-<conversation_id>.txt and stash the self-review prompt in feedback-<conversation_id>.txt. The harness normalizes agent file edits (incl. StrReplace) to tool type 'Write' in this event - verified via payload capture - so ^Write$ matches them all; the alternation is defensive against future harness versions reporting raw tool names. Anchored so TabWrite (every user tab-completion) stays excluded. The model is the auditor. NOTE: fires inside subagent contexts too, keyed by the SUBAGENT's conversation_id - see subagentStop + the marker fold in post-tool-use.ps1/final-review.ps1."
+      },
+      {
+        "command": "pwsh.exe -NoProfile -File ~/.agents/hooks/minimal-edit-audit.ps1",
+        "timeout": 15,
+        "matcher": "^(Write|StrReplace|EditNotebook)$",
+        "_comment": "15s: minimal-editing advisory on the edited file (native git --numstat line-count + audit-metrics.py token metrics on .py, from ~/.cursor/skills/minimal-editing/). Appends findings to the conversation's pending file; never blocks. Disable: HOOKS_ENFORCE=0 or MINIMAL_EDITING_ENFORCE=0."
+      },
+      {
+        "command": "pwsh.exe -NoProfile -File ~/.agents/hooks/anti-slop-audit.ps1",
+        "timeout": 15,
+        "matcher": "^(Write|StrReplace|EditNotebook)$",
+        "_comment": "15s: AI-slop advisory, companion to minimal-edit-audit. Native git diff flags new deps / premature abstractions (Factory/Repository/Mediator/CQRS/DDD) / redundant comments, and injects the anti-slop.md self-review checklist on substantial edits (>= ANTI_SLOP_CHECKLIST_LINES, default 40). Appends to the conversation's pending file; never blocks. Disable: HOOKS_ENFORCE=0 or ANTI_SLOP_ENFORCE=0."
+      }
+    ],
+    "postToolUse": [
+      {
+        "command": "pwsh.exe -NoProfile -File ~/.agents/hooks/post-tool-use.ps1",
+        "timeout": 5,
+        "_comment": "5s: (1) fold completed subagents' session-edits markers into this conversation's marker - subagent edits fire afterFileEdit under the SUBAGENT's conversation_id, and postToolUse does NOT fire for the Task tool (verified by payload logging), so per-tool-boundary folding is how delegated edits reach the parent's stop-hook review - and prime the parent to audit the subagent diff; (2) drain this conversation's pending-feedback file (self-review + advisories) into additional_context. One-shot. No matcher: fires after EVERY tool so pending is delivered promptly."
+      }
+    ],
+    "subagentStop": [
+      {
+        "command": "pwsh.exe -NoProfile -File ~/.agents/hooks/subagent-stop-review.ps1",
+        "timeout": 5,
+        "matcher": "^(generalPurpose|poteto-agent|best-of-n-runner|impeccable-manual-edit-applier)$",
+        "loop_limit": 3,
+        "_comment": "5s: ONE in-subagent final review per implementation before the result returns to the parent. Matcher = editing-capable subagent types only. Marker-gated like final-review.ps1: afterFileEdit fires inside subagents keyed by the subagent's conversation_id, so session-edits-<subagent-cid>.txt exists exactly when the run edited files; reviewed-<cid>.flag is the per-implementation brake, loop_limit 3 is the harness-side runaway cap (1 would suppress the review after a resumed subagent's second implementation). Disable: HOOKS_ENFORCE=0 or SUBAGENT_REVIEW_ENFORCE=0."
+      }
+    ],
+    "beforeShellExecution": [
+      {
+        "command": "pwsh.exe -NoProfile -File ~/.agents/hooks/permission-gate.ps1",
+        "timeout": 5,
+        "failClosed": false,
+        "_comment": "5s: deny a small explicit list of dangerous commands. Default-allow, deny-by-list."
+      }
+    ],
+    "stop": [
+      {
+        "command": "pwsh.exe -NoProfile -File ~/.agents/hooks/final-review.ps1",
+        "timeout": 5,
+        "loop_limit": 5,
+        "_comment": "5s: ONE comprehensive end-of-implementation review across correctness + reliability + coverage + anti-slop. If the agent edited files this loop (session-edits-<conversation_id> marker), returns {followup_message} so Cursor auto-submits ONE review pass. Bounded by the script's per-conversation reviewed-flag (one review per implementation); loop_limit counts follow-ups per CONVERSATION (docs), so 5 = harness-side runaway cap, not the per-implementation bound (2 would silently kill reviews after the 2nd implementation in a long chat). Disable: HOOKS_ENFORCE=0 or FINAL_REVIEW_ENFORCE=0."
+      }
+    ]
+  }
+}

package/windows/inject-doctrine.ps1

@@ -0,0 +1,58 @@
+# 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