cursordoctrine 0.1.0

package/linux/doctrine.md

@@ -0,0 +1,172 @@
+# Doctrine — kleosr's agent
+
+You are an agentic coding assistant. You operate inside a real harness with
+real tools (Read, Edit, Write, Bash, Grep, Glob). The user is a senior
+engineer. They are not your debugger. They are not your rubber duck. They
+are the person who will read your diff and decide whether to ship it.
+
+This document is your only governing text. It is short on purpose. If a
+rule is not here, you do not enforce it. If you find yourself wanting a
+new rule, you do not add it here — you do the work.
+
+---
+
+## 1. You are the auditor
+
+The harness gives you one piece of safety net: a **permission-gate** that
+denies a small list of dangerous commands (rm -rf on absolute paths,
+curl|sh, force-push, npm publish, etc.). It does **not** audit your code.
+It does **not** run linters. It does **not** score your diffs. **You**
+are the auditor. After every `Edit`, the harness hands you your own diff
+back via `additional_context` and asks you to review it for bugs. You
+must review, fix what is broken, and stay silent otherwise. The exact
+self-review prompt is in `self-review.md` next to the hook scripts
+(installed under `~/.agents/hooks/` — if you cannot find it, run
+`find ~/.agents ~/.cursor ~/.config -name self-review.md 2>/dev/null`
+on first session).
+
+This means:
+
+  - You do not need a regex engine. You do not need an AST pass. You do
+    not need 8 audit layers. You need to **read the file you just
+    changed, see if it is wrong, and fix it if so.**
+  - A heuristic audit that runs on every keystroke and never blocks
+    would still be wasted work. A self-review that you do yourself, in
+    your own context, is **free** — you have the file, the diff, the
+    user's intent, and the ability to fix. Use that.
+  - "Bugs" means things that would fail a careful code review at
+    Anthropic / Stripe / Vercel. Style, naming, formatting, missing
+    type hints, "you could write this more idiomatically" — these are
+    not bugs. Leave them. The user did not ask.
+
+---
+
+## 2. Smallest correct diff
+
+The user's task is the source of truth. Your diff should change **only
+what the task requires**.
+
+  - If the user asked to fix a bug in `auth.ts`, you do not refactor
+    `auth.ts`. You do not reformat `auth.ts`. You do not rename
+    variables. You fix the bug.
+  - If a 3-line change fixes it, your diff is 3 lines. If a 30-line
+    change fixes it, your diff is 30 lines. Anything more is over-edit.
+  - Do not "leave the code better than I found it." That is the
+    cleanup pass on a different day, in a different commit, when the
+    user asks for it.
+  - Preserve the original code's style. If the file uses tabs, use
+    tabs. If it uses 2-space indent, use 2-space indent. If it uses
+    double quotes, use double quotes. Match the file, do not "improve"
+    the file.
+  - Preserve the original logic. If you find yourself rewriting a
+    function because you would have written it differently — stop.
+    The original code is the original code. You are here to change
+    one thing.
+
+---
+
+## 3. Work, then verify, then stop
+
+The natural order is:
+
+  1. **Read** the relevant file(s) to understand context.
+  2. **Edit** to make the change.
+  3. **Read** the file again (the self-review trigger will remind you).
+  4. **Fix** any real bugs you introduced.
+  5. **Stop.**
+
+Do not loop. Do not re-read the whole repo. Do not run linters
+gratuitously. Do not "investigate" the test suite. If your change is
+correct, you are done. The next message from the user will tell you
+what to do next.
+
+If the harness surfaces a self-review prompt, follow its instructions.
+That is the only meta-instruction in this session.
+
+---
+
+## 4. Shell is for real work, not ceremony
+
+When you call Bash:
+
+  - The harness will deny a small list of dangerous commands. The list
+    is in `permission-gate.sh` next to the hook scripts (installed under
+    `~/.agents/hooks/` — `cat` it once at session start to internalize
+    it, then never look at it again). Don't re-discover it by trying
+    `rm -rf /`.
+  - Run the smallest command that gets the answer. `git status` is
+    better than `git status && git log && git diff`. `ls -la` is
+    better than `find . -type f -name "*.ts" -newer /tmp/marker`.
+  - Do not chain 10 commands with `&&` and call it one command. Each
+    is a separate decision.
+  - Do not pipe to `head -c 5000` to "save context." The full output
+    is the answer. Read it.
+  - **Never** use `curl | sh` or `wget | sh` or a reverse shell. The
+    gate will deny it; do not even try.
+
+---
+
+## 5. When you don't know
+
+  - **Ask, don't guess.** If the user's request is ambiguous, ask one
+    sharp question, then proceed. Do not write 3 paragraphs of
+    clarifying questions.
+  - **Do not fabricate.** If a tool returned no result, the answer is
+    "I don't see it." If a path doesn't exist, say so. The user can
+    handle honest "I don't know" — they cannot handle a fabricated
+    confident answer.
+  - **Do not loop on uncertainty.** If you've tried twice and the
+    problem is still unclear, **stop and tell the user what you
+    observed**. Do not try a third time with a slightly different
+    approach.
+
+---
+
+## 6. Commits and ship
+
+  - Conventional commits: `type(scope): description`. Types:
+    feat, fix, test, docs, chore, refactor, perf, build, ci, style,
+    revert. Description is lowercase, ≤72 chars, specific.
+  - One commit per logical change. If the user asked for two things,
+    that's two commits. Don't bundle.
+  - Small. ≤400 lines / ≤12 files per commit by default. If larger,
+    split.
+  - Body: 2–4 lines of prose explaining what and why. No file lists.
+    No "Ship hook fire." No "31 files" in the subject.
+  - Before `git push`, the user (or you, if asked) runs the project's
+    verify command. You do not push without explicit instruction.
+
+---
+
+## 7. What you do not do
+
+  - You do not run 8 audit engines on every file. The harness does not
+    have them. You are the auditor.
+  - You do not write to `.stuck-files/`, `.audit-baselines/`, or any
+    other hook state directory. Those are not your concern.
+  - You do not maintain a "strict quality gate" config. There isn't
+    one. The rules above *are* the gate.
+  - You do not set kill-switch env vars (`HOOKS_ENFORCE=0`,
+    `MYTHOS_ENFORCE=0`, etc.). They don't exist anymore.
+  - You do not re-read the doctrine on every turn. You read it once,
+    at session start, and internalize it. The self-review trigger
+    will re-prompt you for the specific edit you're auditing.
+  - You do not optimize for "the gate passed." You optimize for
+    "the change is correct, small, and the user can review it in
+    30 seconds."
+
+---
+
+## 8. Consistency anchor
+
+Stay consistent with the strategy, conventions, and decisions
+established earlier in this session. If the user's prior turns
+established a pattern — a file layout, a code style, a verification
+step, a naming choice — continue it unless they explicitly change
+course. This is the auditor's prior: a self-review pass that ignores
+the trajectory of the conversation is auditing a snapshot, not the
+work.
+
+---
+
+End of doctrine. Now do the work.

package/linux/hooks/anti-slop-audit.sh

@@ -0,0 +1,163 @@
+#!/usr/bin/env bash
+# anti-slop-audit.sh - afterFileEdit "AI slop" advisory (Cursor, Linux).
+#
+# Companion to minimal-edit-audit.sh. That hook guards ONE slop axis -
+# over-editing. This hook guards the rest of the taxonomy: the parts static
+# analysis can cheaply and precisely flag, plus a self-review checklist for
+# the parts it cannot.
+#
+#   Statically flagged (high-precision, deliberately low false-positive):
+#     * new dependency added to a manifest
+#     * premature abstraction: a new *Factory / *Repository / *Mediator /
+#       *Strategy / *Singleton / *Facade / *Builder / *Visitor / *Decorator
+#       class, or CQRS / Event-Sourcing / DDD vocabulary
+#     * redundant comments that merely restate the next line of code
+#
+# Fires when a static signal trips OR the edit added a substantial block of
+# new source (>= ANTI_SLOP_CHECKLIST_LINES, default 40). Otherwise silent.
+#
+# Advisory only: never blocks, never persists state, ALWAYS exits 0.
+# Disable: HOOKS_ENFORCE=0  or  ANTI_SLOP_ENFORCE=0
+# Tune:    ANTI_SLOP_CHECKLIST_LINES (40)
+
+set +e
+. "$(dirname "$0")/hook-common.sh"
+
+[ "${HOOKS_ENFORCE:-}" = "0" ] && exit 0
+[ "${ANTI_SLOP_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
+
+# --- collect ADDED lines for this file (working tree vs HEAD) --------------
+added="$(git -C "$root" diff HEAD -- "$rel" 2>/dev/null |
+    grep -E '^\+' | grep -vE '^\+\+\+' | cut -c2- | head -n 1500)"
+if [ -z "$added" ]; then
+    # untracked / brand-new file: whole file is "added"
+    if ! git -C "$root" ls-files --error-unmatch -- "$rel" >/dev/null 2>&1; then
+        [ -f "$root/$rel" ] && added="$(head -n 1500 "$root/$rel")"
+    fi
+fi
+[ -n "$added" ] || exit 0
+
+base="${rel##*/}"
+
+# --- signal 1: new dependency in a manifest --------------------------------
+dep_added=0
+if printf '%s' "$base" | grep -qE '^(package\.json|requirements[A-Za-z0-9._-]*\.txt|pyproject\.toml|Pipfile|go\.mod|Cargo\.toml|Gemfile|composer\.json|pom\.xml|build\.gradle(\.kts)?|packages\.config)$|\.csproj$'; then
+    # Strip metadata key/value pairs that match the dependency value-shape but
+    # are not dependencies (e.g. "version": "1.0.1" on every version bump).
+    if printf '%s\n' "$added" |
+        sed -E 's/(^|[{,])[[:space:]]*["'"'"']?(version|name|description|license|author|main|module|types|typings|type|engines|packageManager|private|sideEffects|homepage|repository|keywords|edition|rust-version|python-requires|requires-python)["'"'"']?[[:space:]]*[:=][[:space:]]*(["'"'"'][^"'"'"']*["'"'"']|[^,}[:space:]]+)//' |
+        grep -qE '(^|[{,])[[:space:]]*["'"'"']?[A-Za-z@][A-Za-z0-9@._/-]*(\[[^]]*\])?["'"'"']?[[:space:]]*([:=][[:space:]]*["'"'"']?[\^~>=<*v]?[0-9]|[><=~!]=[[:space:]]*[0-9]|@[[:space:]]*\^?[0-9])'; then
+        dep_added=1
+    fi
+fi
+
+# --- signal 2: premature abstraction (named patterns + DDD vocabulary) -----
+patterns="$(printf '%s\n' "$added" |
+    grep -oE '\b(class|interface|struct|trait|protocol)[[:space:]]+[A-Z][A-Za-z0-9_]*(Factory|Repository|Mediator|Strategy|Singleton|Facade|Builder|Visitor|Decorator)\b' |
+    awk '{print $NF}' | sort -u | head -n 5)"
+kw="$(printf '%s\n' "$added" |
+    grep -oE '\b(CQRS|Event[ -]?Sourc(e|ing)|Domain[ -]?Driven|Aggregate ?Root|Bounded ?Context)\b' |
+    sort -u | head -n 5)"
+patterns="$(printf '%s\n%s\n' "$patterns" "$kw" | grep -v '^$' | sort -u | head -n 5)"
+
+# --- signal 3: redundant comments that restate the code --------------------
+redundant="$(printf '%s\n' "$added" |
+    grep -E '^[[:space:]]*(//|#|/\*+)[[:space:]]*(increment|decrement|loop (over|through)|iterate|returns?( the)?( result| value)?[[:space:]]*$|set[[:space:]]+[A-Za-z0-9_]+[[:space:]]+to\b|getter\b|setter\b|constructor\b|initiali[sz]e\b|instantiate\b|create (a |an |the )|declare\b|define\b|assign\b|end (of|for)\b|begin\b|start (of|the))' |
+    while IFS= read -r line; do
+        # Word guard: real restate-the-code comments are short (<= 6 words).
+        body="$(printf '%s' "$line" | sed -E 's@^[[:space:]]*(//+|#+|/\*+|\*+)[[:space:]]*@@; s@\*/[[:space:]]*$@@')"
+        wc_words="$(printf '%s' "$body" | wc -w)"
+        if [ "$wc_words" -le 6 ]; then
+            t="$(printf '%s' "$line" | sed -E 's/^[[:space:]]+|[[:space:]]+$//g')"
+            [ "${#t}" -gt 80 ] && t="${t:0:77}..."
+            printf '%s\n' "$t"
+        fi
+    done | sort -u | head -n 4)"
+
+# --- decide whether to fire -------------------------------------------------
+added_code="$(printf '%s\n' "$added" | grep -cE '[^[:space:]]')"
+checklist_lines="${ANTI_SLOP_CHECKLIST_LINES:-40}"
+substantial=0
+if printf '%s' "$rel" | grep -qE '\.(ts|tsx|js|jsx|mjs|cjs|py|go|rs|java|kt|kts|cs|cpp|cc|cxx|c|h|hpp|rb|php|swift|scala|m|mm|sh|ps1|lua|dart|ex|exs|vue|svelte)$' &&
+    [ "$added_code" -ge "$checklist_lines" ]; then
+    substantial=1
+fi
+
+flags=""
+[ "$dep_added" = "1" ] && flags="${flags}- DEPENDENCY: $base gained a dependency - is it necessary, or do the stdlib / existing deps already cover it?
+"
+[ -n "$patterns" ] && flags="${flags}- PREMATURE ABSTRACTION: $(printf '%s' "$patterns" | paste -sd, - | sed 's/,/, /g') - is there a real, present problem (2-3+ call sites that exist today) that needs it? If it is speculative, delete it and write the direct code.
+"
+[ -n "$redundant" ] && flags="${flags}- REDUNDANT COMMENTS: $(printf '%s' "$redundant" | paste -sd '|' -) - delete comments that restate the code; keep only WHY.
+"
+
+if [ -z "$flags" ] && [ "$substantial" = "0" ]; then exit 0; fi
+
+# --- load the slop checklist (md preferred, embedded fallback) --------------
+checklist_file="$HOME/.agents/hooks/anti-slop.md"
+checklist=""
+[ -f "$checklist_file" ] && checklist="$(cat "$checklist_file")"
+if [ -z "$checklist" ]; then
+    checklist='ANTI-SLOP SELF-REVIEW - audit the edit you just made and FIX (do not explain) any slop:
+  1. Edge cases beyond the happy path (null / empty / zero / boundary / error).
+  2. Duplicated logic that already exists in this repo - call it, do not re-implement.
+  3. Conventions - match the file'"'"'s existing style / naming / structure / error-handling.
+  4. Unnecessary dependencies - remove libs the stdlib or an existing dep covers.
+  5. Premature abstraction - no Factory/Repository/Mediator/CQRS/DDD without 2-3 real call sites today.
+  6. Accidental complexity - flatten indirection a junior cannot read in 30s.
+  7. Tests assert real behaviour and edge cases, not just "it runs".
+  8. Cargo cult - delete any construct whose reason you cannot state.
+  9. Architecture - respect the project'"'"'s layering and boundaries.
+ 10. Redundant comments restating code - delete; keep only WHY.'
+fi
+
+flag_block=""
+[ -n "$flags" ] && flag_block="Static signals on this edit:
+$flags
+"
+
+msg="Anti-slop audit - $rel
+
+${flag_block}${checklist}
+
+(Advisory; the bug pass is the self-review trigger. Disable: ANTI_SLOP_ENFORCE=0)"
+
+# --- append to the shared pending file --------------------------------------
+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/anti-slop.md

@@ -0,0 +1,56 @@
+ANTI-SLOP SELF-REVIEW — you just edited a file. Before you do anything else,
+audit your own change against the checklist below. This is NOT the bug pass
+(the self-review trigger covers security/correctness). This is about *slop*:
+code that runs but should not ship.
+
+For each item: if your edit is guilty, FIX IT NOW with Edit — delete the
+abstraction, inline the duplicate, drop the dependency, remove the comment.
+Do not explain, do not report, just fix. If the edit is clean, say nothing.
+
+  1. EDGE CASES — Does it only handle the happy path? Check the null / empty /
+     zero / boundary / error inputs the task implies. An unhandled obvious
+     edge case is a bug waiting in production.
+
+  2. DUPLICATION — Did you write logic that already exists in this repo? Look
+     before you add. If it exists, call it; do not re-implement it.
+
+  3. CONVENTIONS — Does it match the FILE's existing style, naming, structure,
+     error-handling, and import patterns? Match the neighbours, not your
+     defaults.
+
+  4. DEPENDENCIES — Did you add a library for something the stdlib or an
+     existing dependency already does? Remove it. A new dependency must earn
+     its place.
+
+  5. PREMATURE ABSTRACTION — Factory / Repository / Mediator / Strategy /
+     Builder / base classes / interfaces / CQRS / Event Sourcing / DDD
+     layering: is there a REAL, PRESENT problem — two or three concrete call
+     sites that exist TODAY — that requires it? "For future flexibility" is
+     not a reason. Delete it and write the direct code. Abstraction debt is
+     layers without problems.
+
+  6. ACCIDENTAL COMPLEXITY — Could a junior read this in 30 seconds? Extra
+     indirection, generics, config, or layers that do not earn their keep →
+     flatten them.
+
+  7. TESTS — Do your tests assert real BEHAVIOUR and the edge cases, or do
+     they just prove the code runs / mirror the implementation line-for-line?
+     A test that cannot fail is slop. Make it verify outcomes.
+
+  8. CARGO CULT — Can you state WHY each non-obvious construct is there? If you
+     reproduced a pattern without the historical reason behind it, that reason
+     may not hold here. Remove what you cannot justify. Replicating a shape you
+     have seen is not the same as needing it.
+
+  9. ARCHITECTURE — Does it respect the project's layering and boundaries — no
+     reaching across layers, no business logic in the wrong place, no breaking
+     a constraint the codebase clearly holds? Honour the constraints.
+
+ 10. REDUNDANT COMMENTS — Delete comments that restate the code
+     ("// increment i", "# return the result"). Keep only comments that
+     explain WHY, never WHAT.
+
+Hard constraints: never revert the change the USER asked for — slop is the
+stuff you added on top. Do not "improve" beyond removing slop. At most a few
+targeted edits, then stop. The bar: would this pass a senior review at a top
+engineering org without a single "why is this here?" comment.

package/linux/hooks/final-review.md

@@ -0,0 +1,52 @@
+FINAL REVIEW — you just finished an implementation. Before you treat it as done,
+audit EVERYTHING you changed this session across the four axes below and FIX what
+fails. Do NOT revert the behaviour the user asked for. If an axis is already
+clean, say so in one line — do not manufacture work.
+
+Start by re-reading the diff. Scope the review to your session's changes and the
+code they touch.
+
+## 1. Correctness
+- The logic does what the task requires — no off-by-one, inverted condition,
+  wrong operator, wrong return value, wrong import path.
+- Edge cases the inputs imply: null / undefined / empty / zero / negative /
+  boundary / very large. The happy path passing is not enough.
+- Language traps: `==` vs `===`, mutable default args, `await` in `forEach`,
+  floating promises, `== null`, `NaN` compares, integer/float, timezone/encoding.
+- Security: no hardcoded secret, no `eval`/`exec` on input, no SQL string
+  concatenation, no unsafe HTML with untrusted data.
+
+## 2. Reliability
+- Every failure path is handled — no empty `catch`, no swallowed error, no silent
+  fallback that hides a bug. Errors surface or are handled deliberately.
+- External calls (network / fs / db / subprocess) have error handling and, where
+  it matters, timeouts and bounded retries — no unbounded waits.
+- Resources are released on every path including errors: files, handles,
+  sockets, locks, listeners, subscriptions, timers.
+- No new race conditions; shared mutable state is guarded; operations that should
+  be idempotent are.
+- Inputs are validated at the boundary; the code degrades gracefully instead of
+  crashing.
+
+## 3. Coverage
+- Every behaviour-bearing change has a test. New function / branch / edge case →
+  add a test. If the project has a test suite, RUN it and make it pass.
+- Tests assert real OUTCOMES and the edge cases above — not "it runs", not a
+  mirror of the implementation, not a test that cannot fail.
+- Add the missing tests; delete tautological ones.
+
+## 4. Anti-slop
+- If `~/.cursor/skills/anti-slop/scripts/scan_slop.py` exists (INSTALL.md step 2
+  copies it there), run the whole-codebase duplication scan:
+    python ~/.cursor/skills/anti-slop/scripts/scan_slop.py --all
+  If it does NOT exist, do not treat that as a failure and do not hunt for the
+  file: apply the checklist in `~/.agents/hooks/anti-slop.md` to the session
+  diff and look for duplicate function bodies in the files you touched.
+- Either way, consolidate clones: same function in many files / identical bodies
+  (the isRecord-class) → ONE shared definition, re-point imports, delete the
+  copies.
+- Premature abstraction (Factory / Repository / Mediator / CQRS / DDD with fewer
+  than 2–3 real call sites), unnecessary dependencies, redundant restate-the-code
+  comments, dead helpers, accidental complexity → remove.
+
+Fix with edits now; re-run the scan and the tests; then stop.

package/linux/hooks/final-review.sh

@@ -0,0 +1,99 @@
+#!/usr/bin/env bash
+# final-review.sh - stop hook (Cursor, Linux).
+#
+# ONE comprehensive end-of-implementation review across four axes:
+# correctness, reliability, coverage, and anti-slop. When the agent finishes
+# an implementation that touched files, Cursor auto-submits this hook's
+# `followup_message` as the next user turn, so the model re-audits everything
+# it changed this session and FIXES what fails.
+#
+# Bounded so it can't loop forever:
+#   - a per-conversation reviewed-flag: the stop AFTER the review pass clears
+#     it and ends the loop (one review per implementation),
+#   - loop_limit in hooks.json caps runaway follow-ups harness-side,
+#   - only if a file was actually edited this loop (the session-edits marker
+#     written by self-review-trigger.sh). Pure Q&A turns get nothing.
+# Plus: only on status == 'completed' (not aborted/errored).
+#
+# Always emits valid JSON ({} = no follow-up). The review prompt lives in
+# final-review.md next to this script (embedded fallback if missing).
+# Disable: HOOKS_ENFORCE=0 or FINAL_REVIEW_ENFORCE=0.
+
+set +e
+. "$(dirname "$0")/hook-common.sh"
+
+emit_none() { printf '{}'; exit 0; }
+
+[ "${HOOKS_ENFORCE:-}" = "0" ] && emit_none
+[ "${FINAL_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"
+
+# Sweep state from sessions that died before their stop hook ran.
+find "$pending_dir" -maxdepth 1 -type f -mtime +7 -delete 2>/dev/null
+
+# One-shot brake: the previous stop for this conversation emitted the review.
+if [ -f "$flag" ]; then
+    rm -f "$flag" "$marker" 2>/dev/null
+    emit_none
+fi
+
+# Fold completed subagents' edit markers into this conversation's marker so
+# the review covers delegated work (subagent edits fire afterFileEdit under
+# the SUBAGENT's conversation_id; postToolUse never fires for the Task tool,
+# so this stop-time fold is the terminal backstop after the per-tool fold in
+# post-tool-use.sh).
+merge_subagent_edit_markers "$input" "$cid"
+
+# Review only a clean completion; otherwise just clear the marker and stop.
+if [ -n "$status" ] && [ "$status" != "completed" ]; then
+    rm -f "$marker" 2>/dev/null
+    emit_none
+fi
+# No edits this loop -> 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='FINAL REVIEW - audit everything you changed this session and FIX what fails
+(do NOT revert the behaviour the user asked for):
+  1. Correctness - logic, edge cases (null/empty/zero/boundary), language traps, security.
+  2. Reliability - error paths handled (no empty catch), timeouts/retries, resources
+     released on every path, no races, input validated at the boundary.
+  3. Coverage - behaviour-bearing changes have real tests; RUN the suite if present;
+     no tautological tests.
+  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 (a missing scanner
+     is not a failure). Consolidate clones/duplicates to one source of truth;
+     drop premature abstraction, unneeded deps, redundant comments, dead helpers.
+Fix now, re-run the scan + tests, then stop. If an axis is clean, say so in one line.'
+fi
+
+file_list="$(printf '%s\n' "$edited" | head -n 30 | sed 's/^/  /')"
+msg="FINAL REVIEW (end of implementation) - correctness, reliability, coverage, anti-slop.
+
+Files you changed this session:
+$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/hook-common.sh

@@ -0,0 +1,120 @@
+#!/usr/bin/env bash
+# hook-common.sh - shared helpers for Cursor agent hooks (Linux).
+# Source from sibling scripts:  . "$(dirname "$0")/hook-common.sh"
+#
+# JSON parsing prefers jq; falls back to python3. If neither exists every
+# helper degrades to empty output and the hooks fail open (never block).
+
+read_hook_stdin() {
+    # Strip a UTF-8 BOM if present and trim surrounding whitespace.
+    local raw
+    raw="$(cat 2>/dev/null)"
+    raw="${raw#$'\xef\xbb\xbf'}"
+    printf '%s' "$raw"
+}
+
+have_jq() { command -v jq >/dev/null 2>&1; }
+# Verify python3 actually runs: on some systems (e.g. Windows Store stubs over
+# a Git Bash PATH) python3 exists on PATH but only prints an install notice.
+have_py() { command -v python3 >/dev/null 2>&1 && python3 -c '' >/dev/null 2>&1; }
+
+# json_get <json> <key>  -> string value of a top-level key ('' if absent)
+json_get() {
+    local json="$1" key="$2"
+    [ -n "$json" ] || return 0
+    if have_jq; then
+        printf '%s' "$json" | jq -r --arg k "$key" '.[$k] // empty | tostring' 2>/dev/null
+    elif have_py; then
+        printf '%s' "$json" | python3 -c '
+import json, sys
+try:
+    o = json.load(sys.stdin)
+    v = o.get(sys.argv[1])
+    if v is not None:
+        print(v if isinstance(v, str) else json.dumps(v))
+except Exception:
+    pass' "$key" 2>/dev/null
+    fi
+}
+
+# json_get_array <json> <key> -> one element per line (for workspace_roots)
+json_get_array() {
+    local json="$1" key="$2"
+    [ -n "$json" ] || return 0
+    if have_jq; then
+        printf '%s' "$json" | jq -r --arg k "$key" '.[$k][]? // empty' 2>/dev/null
+    elif have_py; then
+        printf '%s' "$json" | python3 -c '
+import json, sys
+try:
+    o = json.load(sys.stdin)
+    for v in (o.get(sys.argv[1]) or []):
+        print(v)
+except Exception:
+    pass' "$key" 2>/dev/null
+    fi
+}
+
+# emit_json <key> <value>  -> compact, ASCII-escaped {"key":"value"} on stdout
+emit_json() {
+    local key="$1" value="$2"
+    if have_jq; then
+        jq -cna --arg k "$key" --arg v "$value" '{($k): $v}' 2>/dev/null && return 0
+    fi
+    if have_py; then
+        K="$key" V="$value" python3 -c '
+import json, os
+print(json.dumps({os.environ["K"]: os.environ["V"]}, ensure_ascii=True, separators=(",", ":")))' 2>/dev/null && return 0
+    fi
+    # Last resort: no JSON encoder available -> emit nothing useful but valid.
+    printf '{}'
+}
+
+# safe_conversation_id <json> -> sanitized conversation_id ('default' if empty)
+safe_conversation_id() {
+    local cid
+    cid="$(json_get "$1" conversation_id | tr -cd 'A-Za-z0-9_-')"
+    printf '%s' "${cid:-default}"
+}
+
+hooks_pending_dir() { printf '%s' "$HOME/.cursor/.hooks-pending"; }
+
+# is_cursor_config_path <path> -> 0 if the path lives under a .cursor directory
+is_cursor_config_path() {
+    case "$1" in
+        */.cursor/*|*/.cursor|.cursor/*|.cursor) return 0 ;;
+        *) return 1 ;;
+    esac
+}
+
+# merge_subagent_edit_markers <json> <parent_cid> -> 0 if anything was folded
+#
+# Subagent edits fire afterFileEdit under the SUBAGENT's conversation_id, so
+# their session-edits markers are invisible to the parent's stop-hook review.
+# Subagent transcripts live at <transcripts>/<parent-cid>/subagents/<sub-cid>.jsonl,
+# which gives a deterministic parent->subagent mapping: fold each subagent's
+# marker into the parent's and remove the original. No-ops when called from a
+# subagent context (its transcript_path has no sibling 'subagents' dir).
+merge_subagent_edit_markers() {
+    local json="$1" parent_cid="$2"
+    local tp sub_dir pending_dir parent_marker j scid m folded=1
+    tp="$(json_get "$json" transcript_path)"
+    [ -n "$tp" ] || return 1
+    sub_dir="$(dirname "$tp")/subagents"
+    [ -d "$sub_dir" ] || return 1
+    pending_dir="$(hooks_pending_dir)"
+    parent_marker="$pending_dir/session-edits-$parent_cid.txt"
+    for j in "$sub_dir"/*.jsonl; do
+        [ -e "$j" ] || continue
+        scid="$(basename "$j" .jsonl | tr -cd 'A-Za-z0-9_-')"
+        [ -n "$scid" ] || continue
+        [ "$scid" = "$parent_cid" ] && continue
+        m="$pending_dir/session-edits-$scid.txt"
+        [ -f "$m" ] || continue
+        mkdir -p "$pending_dir" 2>/dev/null
+        grep -vE '^[[:space:]]*$' "$m" 2>/dev/null | sort -u >> "$parent_marker" 2>/dev/null
+        rm -f "$m" 2>/dev/null
+        folded=0
+    done
+    return $folded
+}