stack/tools/unslop-hook/README.md

unslop-hook

Mechanical AI-tell enforcement for pi seats. Anti-drift gate for the writing standard in SYSTEM.md / ms-unslop: prose distribution alone decays over long sessions; this check cannot forget.

• lists.json: committed machine source for every list the checker enforces: words, phrases, punct rules, regex patterns, density thresholds. Each entry carries provenance (ms-unslop:<pattern id> or system-md), the mention convention, and the documented divergence of the density gate from SYSTEM.md's outright em-dash ban. Edit lists here, not in code.
• unslop-check.js: dependency-free checker (node CLI + module) driven by lists.json. Loads and schema-validates the lists on first use and hard-fails closed: empty, unparseable, or invalid lists throw. Detects banned vocabulary, chatbot/sycophancy phrases, filler phrases, em/en dashes, curly quotes, not just X but Y. Strips fenced and inline code first, so quoted code is never flagged. Exit 0 clean, 1 violations, 2 gate broken (lists unreadable, never a clean verdict).
• extension.ts: pi extension. message_end checks finalized assistant text and notifies the operator (TUI/RPC). before_agent_start reads the most recent assistant reply from the session file and, if it carries tells, injects a correction notice the model sees on its next turn. /unslop reports session stats. Violation state lives in the session file, so the injection path survives restart, resume, fork, and reload (an in-memory pending flag was measured dead across print-mode turns, 2026-08-19). A broken lists.json fails closed: checks stop, broken_lists / skipped_broken events log the reason, operator notified once, seat keeps running.
• test-unslop-check.js: unit tests with red and green controls.

Use

node test-unslop-check.js                                   # suite
node unslop-check.js <file>                                 # CLI check
UNSLOP_LISTS=<path> node unslop-check.js <file>             # alt lists location
pi -e ~/.mosaic/tools/unslop-hook/extension.ts              # ad-hoc load
# deploy: copy dir to ~/.pi/agent/extensions/unslop-hook/ or seat .pi
#         equivalent, or list it in settings.json "extensions"

Env: MOSAIC_UNSLOP_HOOK=0 disables. MOSAIC_UNSLOP_LOG=<path> appends JSONL events (loaded / flagged / notice_injected / checked / broken_lists / skipped_broken) for headless evidence. UNSLOP_LISTS=<path> overrides the lists.json location for both CLI and extension.

Verified here (2026-08-19)

• Unit suite 24/24 (8 behavioral, 11 loader/CLI, 5 review follow-up), red and green controls both exercised, including exit-2 on broken lists and on an unreadable input file (S3).
• CLI: slop file exit 1, clean file exit 0, broken lists exit 2 with the fault named on stderr.
• Extension, healthy path (print mode, zai/glm-5.3:low): startup probe loads lists.json, reply checked clean.
• Extension, broken-lists path (print mode): broken_lists at startup, skipped_broken per turn, seat survives, reply still delivered.
• Earlier live evidence (pre-C1, inline lists): forced-slop turn flagged; fresh-process follow-up injected the notice and the reply came back clean; full TUI trial (notify line, injection, /unslop stats) on session vision-unslop.
• Log evidence in session scratchpad.

Limits

• /unslop command not tested headless (print mode has no command surface); it is a thin stats wrapper.
• En dash flag fires on typographic ranges too (2–3); acceptable for fleet prose, revisit if it noisifies technical writing.
• Notice injection is a nudger, not a blocker. Output already streamed to the user stays as-is; correction lands on the next turn.
• A broken lists.json latches for the session: repairing the file mid-session does not revive checks until the seat restarts. Acceptable for an advisory gate (review S1).
• The fail-closed operator notification requires a UI. Print-mode sessions log skipped_broken but notify nobody (review S2).
• The word/phrase lists are the mechanical subset of ms-unslop only, keyed to pattern ids in lists.json. Style judgments (voice, rhythm, structure) stay in the skill, not the gate.

Promotion path

Stack issue (A4): checker shared as the single source for a matching Claude Code Stop-hook script; lists versioned beside SYSTEM.md contract text.