cursordoctrine 0.1.0

package/linux/hooks/minimal-edit-audit.sh

@@ -0,0 +1,112 @@
+#!/usr/bin/env bash
+# minimal-edit-audit.sh - afterFileEdit minimal-editing advisory (Cursor, Linux).
+#
+# Audits the just-edited file for over-editing:
+#   * line-count    - git diff --numstat thresholds (any language).
+#   * token metrics - audit-metrics.py (token-Levenshtein + cognitive
+#                     complexity), Python files only, if the script exists.
+# On WARN/FAIL it APPENDS a short advisory to the shared pending-feedback file;
+# post-tool-use.sh 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.
+#
+# Thresholds (env-overridable): MINIMAL_EDIT_FAIL_LINES (400), MINIMAL_EDIT_WARN_LINES (100).
+# Disable: HOOKS_ENFORCE=0  or  MINIMAL_EDITING_ENFORCE=0
+
+set +e
+. "$(dirname "$0")/hook-common.sh"
+
+[ "${HOOKS_ENFORCE:-}" = "0" ] && exit 0
+[ "${MINIMAL_EDITING_ENFORCE:-}" = "0" ] && exit 0
+
+input="$(read_hook_stdin)"
+[ -n "$input" ] || exit 0
+
+# audit root = project from JSON (cwd, then workspace_roots), else CURSOR_PROJECT_DIR / HOME
+root=""
+while IFS= read -r cand; do
+    [ -n "$cand" ] && [ -d "$cand" ] && { root="${cand%/}"; break; }
+done <<EOF
+$(json_get "$input" cwd)
+$(json_get_array "$input" workspace_roots)
+EOF
+[ -n "$root" ] || root="${CURSOR_PROJECT_DIR:-$HOME}"
+root="${root%/}"
+
+# edited file -> repo-relative path
+fp=""
+for k in file_path path filename absolute_path abs_path; do
+    fp="$(json_get "$input" "$k")"
+    [ -n "$fp" ] && break
+done
+[ -n "$fp" ] || exit 0
+rel="$fp"
+case "$rel" in "$root"/*) rel="${rel#"$root"/}" ;; esac
+if is_cursor_config_path "$fp" || is_cursor_config_path "$rel"; then exit 0; fi
+
+# git repo?
+git -C "$root" rev-parse --git-dir >/dev/null 2>&1 || exit 0
+
+# --- line-count audit (any language) --------------------------------------
+fail_lines="${MINIMAL_EDIT_FAIL_LINES:-400}"
+warn_lines="${MINIMAL_EDIT_WARN_LINES:-100}"
+changed="$(git -C "$root" diff HEAD --numstat -- "$rel" 2>/dev/null |
+    awk '$1 != "-" && $2 != "-" { n += $1 + $2 } END { print n + 0 }')"
+
+grade="OK"; hint=""
+if [ "$changed" -gt "$fail_lines" ]; then
+    grade="FAIL"; hint="$changed lines changed (limit $fail_lines) - likely over-editing; trim or split"
+elif [ "$changed" -gt "$warn_lines" ]; then
+    grade="WARN"; hint="$changed lines changed - justify each hunk or split the task"
+fi
+
+# --- token metrics (.py only) ---------------------------------------------
+audit_metrics="$HOME/.cursor/skills/minimal-editing/scripts/audit-metrics.py"
+if [ -f "$audit_metrics" ] && have_py; then
+    case "$rel" in
+    *.py)
+        mgrade="$(python3 "$audit_metrics" --root "$root" --format json --path "$rel" 2>/dev/null |
+            { if have_jq; then jq -r '.grade // empty'; else python3 -c 'import json,sys
+try: print(json.load(sys.stdin).get("grade",""))
+except Exception: pass'; fi; })"
+        if [ "$mgrade" = "FAIL" ]; then grade="FAIL"
+        elif [ "$mgrade" = "WARN" ] && [ "$grade" = "OK" ]; then grade="WARN"; fi
+        ;;
+    esac
+fi
+
+[ "$grade" = "OK" ] && exit 0
+
+# --- compose advisory + append to the shared pending file ------------------
+hint_txt=""
+[ -n "$hint" ] && hint_txt=" - $hint"
+if [ "$grade" = "FAIL" ]; then
+    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."
+fi
+
+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$hint_txt
+
+$actions
+
+(Disable for this session: HOOKS_ENFORCE=0)"
+
+cid="$(safe_conversation_id "$input")"
+pending="$(hooks_pending_dir)/feedback-$cid.txt"
+mkdir -p "$(dirname "$pending")" 2>/dev/null
+if [ -s "$pending" ]; then
+    printf '\n\n---\n\n%s' "$msg" >> "$pending" 2>/dev/null
+else
+    printf '%s' "$msg" >> "$pending" 2>/dev/null
+fi
+
+exit 0

package/linux/hooks/permission-gate.sh

@@ -0,0 +1,75 @@
+#!/usr/bin/env bash
+# permission-gate.sh - beforeShellExecution for Cursor (Linux).
+#
+# 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
+
+set +e
+. "$(dirname "$0")/hook-common.sh"
+
+allow() { printf '{"permission":"allow"}'; exit 0; }
+
+[ "${PERM_GATE_ENFORCE:-}" = "0" ] && allow
+
+input="$(read_hook_stdin)"
+cmd="$(json_get "$input" command)"
+# Belt-and-braces: if stdin was not the documented JSON shape, still gate
+# on the raw text rather than waving everything through.
+[ -n "$cmd" ] || cmd="$input"
+[ -n "$cmd" ] || allow
+
+deny() {
+    local reason="$1" shown="$cmd"
+    # Truncate the echo: the UI message only needs enough to identify it.
+    [ "${#shown}" -gt 400 ] && shown="${shown:0:400}..."
+    local user_msg="BLOCKED by permission-gate: $reason
+
+Command: $shown
+
+If this is genuinely intended, run it yourself in your terminal."
+    if have_jq; then
+        jq -cna --arg u "$user_msg" \
+            '{permission:"deny", user_message:$u, agent_message:($u + " Do not retry verbatim. Ask the user to run it manually if it is truly intended.")}'
+    elif have_py; then
+        U="$user_msg" python3 -c '
+import json, os
+u = os.environ["U"]
+print(json.dumps({"permission": "deny", "user_message": u,
+                  "agent_message": u + " Do not retry verbatim. Ask the user to run it manually if it is truly intended."},
+                 ensure_ascii=True, separators=(",", ":")))'
+    else
+        printf '{"permission":"deny"}'
+    fi
+    exit 0
+}
+
+# test_deny <ERE pattern> <reason>
+test_deny() {
+    if printf '%s' "$cmd" | grep -qE "$1"; then deny "$2"; fi
+}
+
+# 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 '(^|[;&|][[:space:]]*)(sudo[[:space:]]+)?rm[[:space:]]+-[a-zA-Z]*([rR][fF]|[fF][rR])[a-zA-Z]*[[:space:]]+/' 'destructive rm -rf on absolute path (use relative paths or be more specific)'
+test_deny ':\(\)\{[[:space:]]*:\|:&[[:space:]]*\};:' 'fork-bomb pattern'
+test_deny 'curl[[:space:]].*\|[[:space:]]*(sudo[[:space:]]*)?(bash|sh|zsh|dash|ash)' 'curl piped to shell'
+test_deny 'wget[[:space:]].*\|[[:space:]]*(sudo[[:space:]]*)?(bash|sh|zsh|dash|ash)' 'wget piped to shell'
+test_deny 'git[[:space:]]+push[[:space:]]+.*--force(-with-lease)?([[:space:]"'"'"']|$)' 'git push --force'
+test_deny 'git[[:space:]]+push[[:space:]]+(-f|--force)([[:space:]"'"'"']|$)' 'git push -f / --force'
+test_deny 'git[[:space:]]+reset[[:space:]]+--hard' 'git reset --hard (data loss)'
+test_deny 'git[[:space:]]+clean[[:space:]]+-[a-zA-Z]*f' 'git clean -f (untracked data loss)'
+test_deny 'dd[[:space:]].*of=/dev/(sd|nvme|hd|xvd)' 'dd to block device'
+test_deny 'mkfs(\.[a-z0-9]+)?[[:space:]]+/dev/' 'mkfs on device'
+test_deny 'chmod[[:space:]]+-R[[:space:]]+777[[:space:]]+/' 'chmod -R 777 on root'
+test_deny 'chown[[:space:]]+-R[[:space:]]+[^[:space:]]+[[:space:]]+/' 'chown -R on root'
+test_deny '^(npm|pnpm|yarn)[[:space:]]+publish([[:space:]]|$)' 'package publish (use ship-hook, not direct publish)'
+
+allow

package/linux/hooks/post-tool-use.sh

@@ -0,0 +1,53 @@
+#!/usr/bin/env bash
+# post-tool-use.sh - postToolUse for Cursor (Linux).
+#
+# 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.
+
+set +e
+. "$(dirname "$0")/hook-common.sh"
+
+input="$(read_hook_stdin)"
+cid="$(safe_conversation_id "$input")"
+
+fold_note=""
+if merge_subagent_edit_markers "$input" "$cid"; then
+    fold_note="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."
+fi
+
+pending_file="$(hooks_pending_dir)/feedback-$cid.txt"
+
+msg=""
+if [ -f "$pending_file" ]; then
+    [ -s "$pending_file" ] && msg="$(cat "$pending_file" 2>/dev/null)"
+    # One-shot: clear before emitting so a hook error doesn't replay forever.
+    rm -f "$pending_file" 2>/dev/null
+fi
+
+if [ -n "$fold_note" ]; then
+    if [ -n "$msg" ]; then
+        msg="$fold_note
+
+---
+
+$msg"
+    else
+        msg="$fold_note"
+    fi
+fi
+[ -n "$msg" ] || exit 0
+
+emit_json additional_context "$msg"
+exit 0

package/linux/hooks/self-review-trigger.sh

@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+# self-review-trigger.sh - afterFileEdit for Cursor (Linux).
+#
+# 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.
+#
+# We DO:
+#   - Capture the edited file path.
+#   - Record it in the session-edits marker (drained by final-review.sh).
+#   - 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.sh re-emits it on the next tool
+# boundary. See hooks.json.
+
+set +e
+. "$(dirname "$0")/hook-common.sh"
+
+input="$(read_hook_stdin)"
+
+file_path="$(json_get "$input" file_path)"
+[ -n "$file_path" ] || file_path="$(json_get "$input" path)"
+[ -n "$file_path" ] || file_path="$(json_get "$input" filePath)"
+cid="$(safe_conversation_id "$input")"
+
+# Empty path (JSON parse failed, or no file_path field) -> nothing to record.
+[ -n "$file_path" ] || exit 0
+if is_cursor_config_path "$file_path"; then exit 0; fi
+
+# State is keyed by conversation_id and lives under $HOME, never the project:
+# no repo litter, works in workspace-less sessions, and concurrent sessions
+# cannot drain each other's prompts.
+pending_dir="$(hooks_pending_dir)"
+mkdir -p "$pending_dir" 2>/dev/null
+
+# Record this edit for the end-of-implementation review (final-review.sh).
+printf '%s\n' "$file_path" >> "$pending_dir/session-edits-$cid.txt" 2>/dev/null
+
+doctrine_file="$HOME/.agents/hooks/self-review.md"
+[ -f "$doctrine_file" ] || exit 0
+doctrine="$(cat "$doctrine_file")"
+
+msg="SELF-REVIEW TRIGGER - you just edited: $file_path
+
+$doctrine"
+
+pending_file="$pending_dir/feedback-$cid.txt"
+if [ -s "$pending_file" ]; then
+    printf '\n\n---\n\n%s' "$msg" >> "$pending_file" 2>/dev/null
+else
+    printf '%s' "$msg" >> "$pending_file" 2>/dev/null
+fi
+
+exit 0

package/linux/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/linux/hooks/subagent-stop-review.sh

@@ -0,0 +1,93 @@
+#!/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 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.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 - no duplicate helpers, premature abstraction, unneeded deps,
+     redundant comments, dead code.
+If an axis is clean, say so in one line. Then stop.'
+fi
+
+file_list="$(printf '%s\n' "$edited" | head -n 30 | sed 's/^/  /')"
+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/hooks.json

@@ -0,0 +1,64 @@
+{
+  "version": 1,
+  "hooks": {
+    "sessionStart": [
+      {
+        "command": "bash ~/.cursor/inject-doctrine.sh",
+        "timeout": 5,
+        "_comment": "5s: inject the agent doctrine + user rules at session start. inject-doctrine.sh reads ~/.cursor/doctrine.md + USER-RULES.md and emits them as {\"additional_context\": ...} JSON (sessionStart does NOT consume raw stdout)."
+      }
+    ],
+    "afterFileEdit": [
+      {
+        "command": "bash ~/.agents/hooks/self-review-trigger.sh",
+        "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.sh/final-review.sh."
+      },
+      {
+        "command": "bash ~/.agents/hooks/minimal-edit-audit.sh",
+        "timeout": 15,
+        "matcher": "^(Write|StrReplace|EditNotebook)$",
+        "_comment": "15s: minimal-editing advisory on the edited file (git --numstat line-count + audit-metrics.py token metrics on .py, from ~/.cursor/skills/minimal-editing/ if installed). Appends findings to the conversation's pending file; never blocks. Disable: HOOKS_ENFORCE=0 or MINIMAL_EDITING_ENFORCE=0."
+      },
+      {
+        "command": "bash ~/.agents/hooks/anti-slop-audit.sh",
+        "timeout": 15,
+        "matcher": "^(Write|StrReplace|EditNotebook)$",
+        "_comment": "15s: AI-slop advisory, companion to minimal-edit-audit. 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": "bash ~/.agents/hooks/post-tool-use.sh",
+        "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": "bash ~/.agents/hooks/subagent-stop-review.sh",
+        "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.sh: 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": "bash ~/.agents/hooks/permission-gate.sh",
+        "timeout": 5,
+        "failClosed": false,
+        "_comment": "5s: deny a small explicit list of dangerous commands. Default-allow, deny-by-list."
+      }
+    ],
+    "stop": [
+      {
+        "command": "bash ~/.agents/hooks/final-review.sh",
+        "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 is the harness-side runaway cap. Disable: HOOKS_ENFORCE=0 or FINAL_REVIEW_ENFORCE=0."
+      }
+    ]
+  }
+}

package/linux/inject-doctrine.sh

@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+# inject-doctrine.sh - Cursor sessionStart injection (Linux).
+#
+# Emits {"additional_context": "<doctrine + USER-RULES>"} as compact,
+# ASCII-escaped JSON (jq -a / python ensure_ascii), so multi-byte characters
+# in the doctrine can never be mangled by encoding layers.
+#
+# Fail open: missing files or any error -> "{}" (valid, empty). Never block
+# or crash session start.
+
+set +e
+. "$HOME/.agents/hooks/hook-common.sh" 2>/dev/null || {
+    cat >/dev/null; printf '{}'; exit 0; }
+
+# Drain stdin (Cursor sends session metadata) so the pipe never blocks.
+cat >/dev/null
+
+context=""
+for p in "$HOME/.cursor/doctrine.md" "$HOME/.cursor/USER-RULES.md"; do
+    if [ -f "$p" ]; then
+        part="$(cat "$p")"
+        if [ -n "$context" ]; then context="$context
+
+$part"; else context="$part"; fi
+    fi
+done
+
+if [ -z "$context" ]; then printf '{}'; exit 0; fi
+
+emit_json additional_context "$context"
+exit 0

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "cursordoctrine",
+  "version": "0.1.0",
+  "description": "Thin self-review hooks for Cursor — the model is the auditor. One command installs the doctrine, the hook pack, and the anti-slop skill.",
+  "bin": {
+    "cursordoctrine": "bin/cli.mjs"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "bin/",
+    "windows/",
+    "linux/",
+    "skills/",
+    "INSTALL.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kleosr/cursordoctrine.git"
+  },
+  "homepage": "https://github.com/kleosr/cursordoctrine#readme",
+  "bugs": {
+    "url": "https://github.com/kleosr/cursordoctrine/issues"
+  },
+  "keywords": [
+    "cursor",
+    "cursor-hooks",
+    "hooks",
+    "agent",
+    "ai-agents",
+    "self-review",
+    "anti-slop",
+    "code-review",
+    "cli"
+  ],
+  "author": "Mario Pulice (kleosr)",
+  "license": "MIT"
+}