Self-evolving second brain with 35 AI skills, 10 agents, and people CRM. Closed-loop harness: a V-model verification lifecycle where the worker never grades its own homework. Plus paired anti-slop design skills for marketing and product UI. Works with Claude Code, Cursor, Kiro, Gemini CLI, Codex.
Python agent-loopagent-pluginsagent-skillsagenticai-agentsclaude-codeclosed-loopcursorgarry-tangbraingstackknowledge-managementloop-engineeringobsidianpeople-crmproductivitysecond-brainself-evolvingverification-harnessworker-agents
feat: slop-gate + voice-baseline — enforcement and measurement for anti-slop (v3.13.0)
Huy Tieuc6cb32807254
diff --git a/.agents/skills/slop-gate/SKILL.md b/.agents/skills/slop-gate/SKILL.mdnew file mode 100644index 0000000..72abaf8--- /dev/null+++ b/.agents/skills/slop-gate/SKILL.md@@ -0,0 +1,10 @@+---+name: slop-gate+description: Deterministic pre-publish scan that refuses AI-slop tells in anything about to be written, published, or sent: files, artifacts, slide titles, table headers, diagram labels, chat messages, commit messages. Use before publishing or sending any deliverable, in CI, or wired as a Claude Code hook so the check runs without being remembered. The editorial counterpart is no-ai-slop, which rewrites; this one blocks.+---++Read `.claude/skills/slop-gate/SKILL.md` and execute it exactly as written; that file is the authoritative+playbook. Then follow `.agents/rules/cog.md`.++Antigravity substitution: where the playbook delegates to a `.claude/agents/<name>`+worker, invoke `.agents/agents/<name>.md` via `invoke_subagent` instead.diff --git a/.agents/skills/voice-baseline/SKILL.md b/.agents/skills/voice-baseline/SKILL.mdnew file mode 100644index 0000000..cf7cc74--- /dev/null+++ b/.agents/skills/voice-baseline/SKILL.md@@ -0,0 +1,10 @@+---+name: voice-baseline+description: Measure your own writing corpus for the words and sentence shapes you over-use, so an agent writing in your voice stops amplifying your tics into a style. Produces a counted baseline file and checks any new draft against it. Use when an agent's drafts start sounding like a caricature of you, before publishing anything written in your voice, or every ten new pieces to re-measure.+---++Read `.claude/skills/voice-baseline/SKILL.md` and execute it exactly as written; that file is the authoritative+playbook. Then follow `.agents/rules/cog.md`.++Antigravity substitution: where the playbook delegates to a `.claude/agents/<name>`+worker, invoke `.agents/agents/<name>.md` via `invoke_subagent` instead.diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.jsonindex 0e5d730..f091c5d 100644--- a/.claude-plugin/plugin.json+++ b/.claude-plugin/plugin.json@@ -1,7 +1,7 @@{"name": "cog-second-brain",- "version": "3.12.0",- "description": "Self-evolving second brain with 33 AI agent skills, 10 agents, and people CRM. Closed-loop harness release: a V-model verification lifecycle (spec to evidence, criterion-traced checkpoints), read-only verifier agents that observe artifacts instead of trusting worker summaries, risk lanes, multi-session ultragoals with a north-star acceptance gate, plus craft skills for writing, visual work, and a paired anti-slop design system for marketing and product UI. Inspired by Garry Tan's gstack specialist sessions, gbrain knowledge patterns, and dwarves-kit closed-loop execution. Works with Claude Code, Antigravity, Cursor, Kiro, Gemini CLI, Codex, and any markdown-reading agent.",+ "version": "3.13.0",+ "description": "Self-evolving second brain with 35 AI agent skills, 10 agents, and people CRM. Closed-loop harness release: a V-model verification lifecycle (spec to evidence, criterion-traced checkpoints), read-only verifier agents that observe artifacts instead of trusting worker summaries, risk lanes, multi-session ultragoals with a north-star acceptance gate, plus craft skills for writing, visual work, and a paired anti-slop design system for marketing and product UI. Inspired by Garry Tan's gstack specialist sessions, gbrain knowledge patterns, and dwarves-kit closed-loop execution. Works with Claude Code, Antigravity, Cursor, Kiro, Gemini CLI, Codex, and any markdown-reading agent.","author": {"name": "Huy Tieu","url": "https://github.com/huytieu"@@ -240,6 +240,16 @@"name": "product-ui-taste","path": ".claude/skills/product-ui-taste/SKILL.md","description": "Anti-slop skill for dense product surfaces (dashboards, tables, forms, wizards, admin consoles) - frame-first, correct at every edge case real data produces"+ },+ {+ "name": "slop-gate",+ "description": "Refuse AI-slop tells in anything about to be written, published, or sent; runs in CI or as a hook",+ "path": ".claude/skills/slop-gate/SKILL.md"+ },+ {+ "name": "voice-baseline",+ "description": "Measure the words and sentence shapes you over-use so an agent stops amplifying your tics",+ "path": ".claude/skills/voice-baseline/SKILL.md"}],"metadata": {diff --git a/.claude/skills/no-ai-slop/SKILL.md b/.claude/skills/no-ai-slop/SKILL.mdindex abc4671..9b6ef0a 100644--- a/.claude/skills/no-ai-slop/SKILL.md+++ b/.claude/skills/no-ai-slop/SKILL.md@@ -83,6 +83,81 @@ Often-empty phrases: it's worth noting, it's important to note, at the end of th**Em dashes.** Do not use them as a default rhythm crutch. In short copy, use none. In longer drafts, 1-2 are fine if they clearly beat commas, periods, or parentheses. Remove clusters and decorative dashes.+## Scope: every medium, not only prose++These rules govern the substance and the labels of every output, not paragraphs alone:+slide titles and kickers, tile and card labels, table headers and row keys, diagram node+and edge labels, chart titles and legends, button copy, subtitles, alt text, chat and+email drafts, issue and PR bodies, commit messages, code comments, memory files.++A rules file that says "writing" fires in the step a model calls writing and stays silent+in the step it calls layout. That is how a deck ends up with clean paragraphs under+headline slide titles. Name every surface, then scan every heading and label before+publishing, separately from reading the body.++**Titles and headings name their subject.** "New runner architecture", "Current+challenges", "Sources". Three shapes fail:++- **Number pairing.** "One harness, four swappable sides." "Four walls, seven accounts."+ "Five calls to make this month." Two small integers joined by a comma read as structure+ and carry none.+- **Metaphor in place of the noun.** "The wedge" for a differentiator, "walls" for+ challenges, "shells" for deployment targets. The reader decodes an image to reach a word+ you could have written.+- **Question or clause as title.** "Why hard apps are the niche." "Where the facts come+ from." A title that withholds its answer costs a beat every time someone scans the index.++## Reader-cited tells++From a hand-audited sample of 600 posts (out of 89,239 pulled across 47 subreddits) about+what makes writing read as AI, ranked by how often readers actually name each tell: em dash+7.1%, uniform sentence rhythm 4.0%, "not just X, it's Y" 2.8%, five-paragraph essay shape+2.5%, sycophancy such as "great question" 2.5%, "dive in / deep dive" 2.0%, bullet lists+where prose belongs 1.7%, diction memes such as "delve" 1.3%, rule-of-three triads 1.2%,+emoji headers 0.8%, "unlock the potential" 0.8%, "in today's fast-paced world" 0.7%, no+contractions 0.7%, empty phrasing 0.7%, both-sides hedging 0.3%.++Two corrections that matter more than the ranking:++- **A keyword scanner ranks the wrong things.** In the same corpus "however", "thus" and+ "hence" were the top keyword match at 6.3% of posts and were cited as a tell zero times.+ Do not flag ordinary connectives.+- **The tells readers rank highest cannot be keyword-matched at all.** Uniform rhythm and+ the fluent-but-empty paragraph need a reader. So does sycophancy.++Also named by readers and worth adding to any watchlist: genuinely, quietly, load-bearing,+hinge, seams, "let that sink in", "what nobody talks about", "this changes everything", and+subheadings shaped "The \<Noun\>" ("The Start", "The Gamechanger").++**Malicious compliance is the failure mode of a ban list.** Ban the em dash and the model+substitutes ", and" or a semicolon or a colon reveal; ban "not X but Y" and it produces+"X. Y." fragments. The driver underneath is over-explanation and restatement. A systemic+instruction ("be airy, do not over-explain, do not restate") does more than two dozen bans.++## Voice-mode tells++An agent writing in someone's voice samples the median of that person, not only the median+of the internet, and regresses toward their most frequent choices. A word that was a choice+at one use comes back at five, and the fifth use teaches the next draft.++Generic ban lists miss this, because the words are the author's own. Measure them: the+`voice-baseline` skill counts a corpus and checks a draft against its own rates. Typical+finds in a real 27-file archive: 53 headings starting with "The", 387 of 2,288 sentences+opening with "The", 25 closing lines of the form "That is the point."++Caps that hold regardless of whose voice it is:++- One paragraph-ending verdict sentence per piece ("The fix was one line."), and only when+ it carries a fact the paragraph has not already delivered.+- Zero kicker closers ("That is the point.", "That is all a title is for.").+- Do not end on a question to the reader by default. End on the last concrete fact.+- One narrative heading pattern per piece; the rest name their subject.+- A verb for each action: use "ship" for a software release, and give publishing, saving,+ sending and deploying their own verbs.++For the mechanical half of all of this, `slop-gate` scans outgoing text and refuses on a+hard tell, so the check does not depend on being remembered.+## Structural slopWord bans catch surface slop. The deeper tell is composition: predictable rhetorical structure with low information gain. A draft can pass every word check and still read as a miniature consulting memo. These patterns apply to the shape of the whole piece, not individual sentences.diff --git a/.claude/skills/slop-gate/SKILL.md b/.claude/skills/slop-gate/SKILL.mdnew file mode 100644index 0000000..634e498--- /dev/null+++ b/.claude/skills/slop-gate/SKILL.md@@ -0,0 +1,121 @@+---+name: slop-gate+description: Deterministic pre-publish scan that refuses AI-slop tells in anything about to be written, published, or sent: files, artifacts, slide titles, table headers, diagram labels, chat messages, commit messages. Use before publishing or sending any deliverable, in CI, or wired as a Claude Code hook so the check runs without being remembered. The editorial counterpart is no-ai-slop, which rewrites; this one blocks.+---++<!-- slop-ok: this skill quotes the tells it blocks -->++# slop-gate++`no-ai-slop` is an editor you invoke. This is a gate that runs whether or not anyone+remembers it. It scans outgoing text, refuses on a tell, and returns the hit list so+the rewrite is targeted.++Two rules make it usable rather than annoying: hard tells fail on a single hit, and+words that are decoration at volume but legitimate once are counted rather than+banned. Text inside quotes or backticks is stripped before scanning, so a piece that+quotes a tell as an exhibit does not fail on its own examples.++## Why a gate and not a rule++A rules file is advisory, and advisory rules fail in a specific, repeatable way: they+fire in the step the model thinks of as writing and not in the steps it thinks of as+something else. A deck built by an agent can carry clean paragraphs under headline+slide titles, because the titles were produced in a layout step where the writing+rules never ran. Every surface nobody named explicitly sits on the unchecked side:++ slide titles, kickers table headers, row keys commit messages+ tile and card labels diagram node and edge labels code comments+ chart titles and legends button copy, subtitles memory files+ alt text, image captions Slack, email, issue bodies PR descriptions++The gate closes that by scanning the text on its way out, whatever produced it.++## Run it++```bash+python3 scripts/scan.py DRAFT.md # one file+python3 scripts/scan.py content/**/*.md # many+cat draft.md | python3 scripts/scan.py - # stdin+```++Exit code 0 is clear, 1 is tells found, so it drops into CI or a pre-commit hook+unchanged. Every hit prints its label and the surrounding text.++## Wire it as a hook (Claude Code, optional)++COG ships no hooks by default. If you want the check enforced rather than remembered,+add this to `.claude/settings.json` yourself. `--hook` reads the hook payload on stdin+and answers with a permission decision.++```json+{+ "hooks": {+ "PreToolUse": [+ {+ "matcher": "Write|Edit|mcp__.*slack.*send.*|mcp__atlassian__(create|update)Confluence.*",+ "hooks": [{ "type": "command",+ "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/skills/slop-gate/scripts/scan.py\" --hook" }]+ }+ ],+ "Stop": [+ { "hooks": [{ "type": "command",+ "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/skills/slop-gate/scripts/scan.py\" --hook" }] }+ ]+ }+}+```++The `Stop` entry scans the agent's own reply, which is where most of these land in a+working session. Expect it to fire on you within the hour; that is the point of it.++## What fails on one hit++| Tell | Specimen |+|---|---|+| Em dash | any `—` |+| Honesty framing | "honestly", "the honest part:", "if I'm being honest" |+| "not X, it's Y" | "It's not about speed, it's about trust" |+| "X, not Y" (trailing form) | "a test, not a permission", "machinery, not memory" |+| Rhetorical heading | "Why this matters", "The bottom line", "What comes next" |+| "The \<Noun\>" heading | "The Wedge", "The Shot", "The Gamechanger" |+| Verdict kicker | "That is the point.", "That is all a title is for." |+| Fake-profound closer | "let that sink in", "this changes everything" |+| Throat-clearing | "Here's the thing", "It's worth noting", "At the end of the day" |+| Sycophancy | "Great question", "You were right to push back", "That's on me" |+| Recap ending | a final paragraph opening "In conclusion" or "Ultimately" |+| Emoji heading | `## 🚀 Results` |++## What is counted, not banned++`robust, seamless, leverage, utilize, delve, empower, streamline, genuinely, quietly,+load-bearing, deep dive, clean, plain, simple, elegant, powerful, lightweight,+tapestry, game-changer, paradigm shift, cutting-edge`++Three or more in one piece fails, on the reading that density means decoration. One+is a word choice. The test for any single use: remove the adjective, and if the reader+would do nothing differently, it was decoration. "A robust retry" fails that test;+"a retry that survives a mail-slot timeout" passes, because it names the behaviour.+Keep the word when it is the term of art ("robust statistics").++## Exhibits++A piece that must quote a tell (a style guide, a post about slop, a test fixture)+carries `slop-ok: <reason>` anywhere in the file, usually as an HTML comment or a+front-matter key. Quoted and backticked spans are already exempt, so the marker is+only needed when a tell appears in the author's own voice on purpose.++Never add the marker to get past a gate you disagree with. Rewrite instead, or change+the pattern list and say why.++## What it cannot see++The gate is regular expressions, so it catches surface and near-surface tells. It is+blind to the structural ones: a declared count that the source does not contain, a+framework invented to organise two paragraphs, uniform sentence rhythm, a paragraph+that restates the previous one. Those need a reader. Use `no-ai-slop` in detect mode,+and prefer a reviewer from a different model family than the author, because a+same-family reviewer shares the author's sense of what a finished answer looks like+and waves through the same shapes.++For the tics that are yours rather than universal, measure them: `voice-baseline`.diff --git a/.claude/skills/slop-gate/scripts/scan.py b/.claude/skills/slop-gate/scripts/scan.pynew file mode 100755index 0000000..e8a64f5--- /dev/null+++ b/.claude/skills/slop-gate/scripts/scan.py@@ -0,0 +1,206 @@+#!/usr/bin/env python3+"""slop-gate: deterministic scan for AI-slop tells in anything about to be published.++Usage+-----+ python3 scan.py FILE [FILE...] # scan files+ cat draft.md | python3 scan.py - # scan stdin+ python3 scan.py --hook # Claude Code PreToolUse/Stop hook mode (JSON on stdin)++Exit codes: 0 clean, 1 tells found (so it works in CI and in a pre-commit hook).++Two tiers+---------+HARD tells fail on a single hit. They have no legitimate use in finished prose.+FILLER words fail at SOFT_LIMIT or more, because one is a word choice and five is+decoration.++Text inside backticks or quotation marks is stripped before scanning, so a piece+that quotes a tell as an exhibit does not fail on its own examples.+"""+import json+import os+import re+import sys++SOFT_LIMIT = 3++HARD = [+ ("em dash", r"—", 0),+ ("honesty framing",+ r"\b(honestly|to be honest|if I'm being honest|the honest (part|truth|answer|reason)|I'll be honest)\b", re.I),+ ("not-X-it's-Y contrast",+ r"\b(it'?s|this is|that'?s|the (question|point|problem|issue)) (is )?not (just |only |about )?[^.\n]{2,60}[.,;] ?(it'?s|but|it is) ", re.I),+ ("not-X-it's-Y contrast", r"\bnot just [^.\n]{2,40}, (it'?s|but) ", re.I),+ ("not-X-it's-Y contrast",+ r"\b(it|this|that) (is|was) not (about |just |only )?[^.,;\n]{2,50}, (it|this|that) (is|was) ", re.I),+ ("X-not-Y contrast", r"\b[a-z][a-z-]+, not (a |an |the |just |only )?[a-z][a-z -]{1,30}[.;:]", 0),+ ("X-not-Y contrast", r"\b(rather than|instead of) [a-z][a-z -]{1,30}[.;]", re.I),+ ("rhetorical heading",+ r"^\s*(#{1,6}|<h[1-6][^>]*>)\s*(why (this|it) matters|the (key|real) (insight|point|opportunity|truth)|what this is not|the bottom line|the deeper point|the uncomfortable truth|here'?s the thing|the takeaway|so what|what comes next|what'?s next|where (it|this|we) go(es)? (from here|next))\b", re.I | re.M),+ ("The <Noun> heading", r"^\s*(#{1,6}|<h[1-6][^>]*>)\s*The [A-Z][a-z]+\s*(</h[1-6]>)?\s*$", re.M),+ ("verdict kicker",+ r"\bThat (is|was|'s) (the (point|lie|whole (point|thing)|part [a-z ]{3,30})|all [a-z ]{2,30} is for)\.", re.I),+ ("fake-profound closer",+ r"\b(let that sink in|this changes everything|what nobody (tells|talks about)|the part (everyone|most people) miss(es)?|and that'?s not nothing)\b", re.I),+ ("throat-clearing",+ r"\b(here'?s the thing|let me be clear|it'?s worth noting|it is worth noting|it'?s important to note|at the end of the day|in today'?s (fast-paced|ever-evolving|digital))\b", re.I),+ ("sycophancy",+ r"\b(great question|you'?re (absolutely )?right to push back|that'?s on me|you were right to)\b", re.I),+ ("summary-recap ending", r"^\s*(in conclusion|ultimately|overall|to sum up|in summary)\b", re.I | re.M),+ ("emoji heading", r"^\s*#{1,6}\s*[\U0001F300-\U0001FAFF☀-➿]", re.M),+]++FILLER = re.compile(+ r"\b(delve|delves|delving|leverag(e|es|ing)|utiliz(e|es|ing)|seamless(ly)?|robust(ly)?"+ r"|tapestry|game[- ]changer|paradigm shift|cutting-edge|empower(s|ing)?|streamlin(e|es|ing)"+ r"|load-bearing|unlock the (potential|power)|genuinely|quietly|deep dive|dive in(to)?"+ r"|clean|plain|simple|elegant|powerful|lightweight)\b", re.I)++QUOTED = re.compile(r"`[^`\n]*`|\"[^\"\n]{0,160}\"|“[^”\n]{0,160}”|^```.*?^```", re.M | re.S)++TEXT_EXT = {".md", ".mdx", ".html", ".htm", ".txt", ".svg", ".rst", ""}+SKIP_PATH = ("no-ai-slop", "slop-gate", "voice-baseline", "/memory/", "/hooks/", "/logs/",+ "node_modules", "/site/", "/build/", "/dist/")+++def strip_quoted(text):+ """Quoted, fenced and code-formatted spans are exhibits, not the author's voice."""+ return QUOTED.sub(" ", text)+++def scan(text, soft_limit=SOFT_LIMIT):+ body = strip_quoted(text)+ hits = []+ for label, rx, flags in HARD:+ for m in re.finditer(rx, body, flags):+ frag = body[max(0, m.start() - 28):m.end() + 28].replace("\n", " ").strip()+ hits.append("[%s] ...%s..." % (label, frag))+ if len(hits) >= 12:+ return hits+ soft = []+ for m in re.finditer(FILLER, body):+ frag = body[max(0, m.start() - 28):m.end() + 28].replace("\n", " ").strip()+ soft.append("[filler word, %d of %d allowed] ...%s..." % (len(soft) + 1, soft_limit, frag))+ if len(soft) >= soft_limit:+ hits.extend(soft[:6])+ return hits+++def exempt(path, text):+ if "slop-ok:" in text:+ return True+ if not path:+ return False+ if any(s in path for s in SKIP_PATH):+ return True+ ext = os.path.splitext(path)[1].lower()+ return bool(ext) and ext not in TEXT_EXT+++# --------------------------------------------------------------------------- hook mode+def hook():+ """Claude Code hook mode. Reads the hook payload on stdin, writes a decision on stdout."""+ try:+ d = json.loads(sys.stdin.read())+ except Exception:+ print("{}")+ return 0++ if d.get("hook_event_name") == "Stop":+ if d.get("stop_hook_active"):+ print("{}")+ return 0+ text, last = "", None+ try:+ with open(d.get("transcript_path", ""), encoding="utf-8") as f:+ for line in f:+ try:+ o = json.loads(line)+ except Exception:+ continue+ if o.get("type") == "assistant":+ last = o+ for c in (last or {}).get("message", {}).get("content", []):+ if c.get("type") == "text":+ text += c.get("text", "") + "\n"+ except Exception:+ pass+ hits = scan(text)+ if hits:+ print(json.dumps({"decision": "block",+ "reason": "slop-gate (reply): rewrite without these tells, then stop.\n"+ + "\n".join(hits)}))+ else:+ print("{}")+ return 0++ tool = d.get("tool_name", "")+ ti = d.get("tool_input") or {}+ path = ti.get("file_path") or ti.get("path") or ""+ text = ""+ if tool == "Write":+ text = ti.get("content", "") or ""+ elif tool == "Edit":+ text = ti.get("new_string", "") or ""+ if path and os.path.isfile(path):+ try:+ if "slop-ok:" in open(path, encoding="utf-8").read():+ print("{}")+ return 0+ except Exception:+ pass+ else:+ # Any message-sending tool: Slack, Confluence, Jira, Linear, email.+ for key in ("message", "text", "body", "content"):+ if ti.get(key):+ text = ti[key] if isinstance(ti[key], str) else json.dumps(ti[key])+ break+ path = ""+ if not text:+ print("{}")+ return 0++ if exempt(path, text) or not text:+ print("{}")+ return 0++ hits = scan(text)+ if hits:+ reason = ("slop-gate: %s blocked. Rewrite without these tells. "+ "For a deliberate exhibit add `slop-ok: <reason>` to the file.\n" % tool) + "\n".join(hits)+ print(json.dumps({"hookSpecificOutput": {"hookEventName": "PreToolUse",+ "permissionDecision": "deny",+ "permissionDecisionReason": reason}}))+ else:+ print("{}")+ return 0+++def main():+ args = [a for a in sys.argv[1:] if a != "--"]+ if "--hook" in args:+ return hook()+ if not args or "--help" in args or "-h" in args:+ print(__doc__)+ return 0+ failed = 0+ for path in args:+ text = sys.stdin.read() if path == "-" else open(path, encoding="utf-8").read()+ label = "stdin" if path == "-" else path+ if path != "-" and exempt(path, text):+ print("%s: exempt" % label)+ continue+ hits = scan(text)+ if hits:+ failed = 1+ print("%s: %d tell(s)" % (label, len(hits)))+ for h in hits:+ print(" " + h)+ else:+ print("%s: clear" % label)+ return failed+++if __name__ == "__main__":+ sys.exit(main())diff --git a/.claude/skills/voice-baseline/SKILL.md b/.claude/skills/voice-baseline/SKILL.mdnew file mode 100644index 0000000..e84fe16--- /dev/null+++ b/.claude/skills/voice-baseline/SKILL.md@@ -0,0 +1,75 @@+---+name: voice-baseline+description: Measure your own writing corpus for the words and sentence shapes you over-use, so an agent writing in your voice stops amplifying your tics into a style. Produces a counted baseline file and checks any new draft against it. Use when an agent's drafts start sounding like a caricature of you, before publishing anything written in your voice, or every ten new pieces to re-measure.+---++# voice-baseline++An agent writing in your voice does not only sample the median of the internet. It+samples the median of you, from the pieces and rules and memory files in its context,+and it regresses toward your most frequent choices because those are the highest+probability tokens in your corpus. A word that was a choice at one use comes back at+five. Then the fifth use teaches the next draft, and the tic becomes the style.++Generic ban lists cannot catch this, because the words are yours and they are not on+anyone's list. Measure instead.++## Run it++```bash+python3 scripts/census.py PATH/TO/YOUR/WRITING --out voice-baseline.md+python3 scripts/census.py PATH/TO/YOUR/WRITING --check DRAFT.md+```++The census walks a directory of your own finished pieces and reports word counts with+a per-file rate, sentence-shape counts, sentence openers, and heading first words.+`--check` compares one draft against those rates and prints only what sits above them.+Exit code 1 when something is above baseline, so it fits a pre-publish script.++Keep the output file next to your rules so the agent reads it before it writes.++## What it measures++**Words.** A watchlist of praise and emphasis words, counted with word boundaries and+reported per file. Read the per-file rate: a word used twice per file is a habit, and+the same word at eight in one draft is the draft's problem. Edit `WATCH` in the+script to add your own suspects; the point is that the list ends up specific to you.++**Paragraph-ending verdict sentences.** "The fix was one line." A concrete noun, a+past-tense verb, a short predicate, parked at the end of a paragraph so it lands like+a ruling. One per piece at most, and only when it carries a fact the paragraph has not+already delivered.++**Kicker closers.** "That is the point." "That is all a title is for." A closing line+that restates the piece as an aphorism. The cap is zero.++**Endings.** How many pieces close on a question to the reader. Most of them means the+question has become a formula.++**Sentence openers and heading first words.** These are where a personal tic hides+best, because each instance reads fine. If a third of your headings begin with the+same word, you have a template. In one real 27-file archive the census found 53+headings starting with "The", the exact shape people name as an AI tell, learned from+the author's own archive.++## How to read the result++The census counts; it does not judge. For each flagged word or shape, decide whether+it is your voice or your mode:++- **Voice.** The word carries meaning the sentence needs, or the rhythm is yours and+ deliberate. Keep it, and note the exception so the next check does not re-raise it.+- **Mode.** The word is praise, emphasis, or padding, and removing it changes nothing+ for the reader. Cut it, or replace it with the behaviour it was gesturing at.++Fix the shapes by cap rather than by ban: one verdict sentence, zero kickers, no+default question ending, one narrative heading pattern per piece.++## Re-measure++Run the census again after roughly ten new pieces. A tic you fixed should fall. A new+one will have appeared, usually the word you reached for while avoiding the last one,+which is the same substitution the model makes when a single word is banned.++Pair with `slop-gate` for the universal tells and `no-ai-slop` for the structural ones+a regular expression cannot see.diff --git a/.claude/skills/voice-baseline/scripts/census.py b/.claude/skills/voice-baseline/scripts/census.pynew file mode 100755index 0000000..35334fd--- /dev/null+++ b/.claude/skills/voice-baseline/scripts/census.py@@ -0,0 +1,183 @@+#!/usr/bin/env python3+"""voice-baseline: measure your own corpus so an agent stops amplifying your tics.++Usage+-----+ python3 census.py CORPUS_DIR [--ext .md] [--out voice-baseline.md]+ python3 census.py CORPUS_DIR --check DRAFT.md++An agent writing in your voice samples the median of *you*: it regresses toward the+words and sentence shapes that appear most in the corpus it has seen. A word that was+a choice at one use reads as a tic at five. This measures which ones you actually+over-use, so the watchlist is yours and not a generic ban list.++Two modes:+ (default) census -- walk the corpus, write a baseline file+ --check DRAFT -- compare one draft against the corpus rate, flag what is above it+"""+import argparse+import os+import re+import sys+from collections import Counter++# Words an agent reaches for as praise or emphasis. Counted, never banned: the census+# says which ones YOUR corpus over-uses. Add your own.+WATCH = [+ "actually", "just", "simply", "really", "quite", "very", "genuinely", "honestly",+ "quietly", "clean", "plain", "simple", "cheap", "small", "elegant", "powerful",+ "robust", "seamless", "leverage", "delve", "ship", "shipped", "earn", "earns",+ "the whole", "the real", "here's", "at the end of the day", "load-bearing",+]++# "The <noun> <past-tense verb> <short predicate>." parked at the end of a paragraph,+# where it lands like a verdict instead of carrying a fact.+VERDICT = re.compile(+ r"(?:^|\. )The [a-z][a-z-]{2,14} (?:was|were|is|are|went|took|did|does|fell|lives|sits|stays|goes|came|holds|catches|kills|works|stops|moves|breaks)\b[^.\n]{0,40}\.\s*$",+ re.M)+KICKER = re.compile(r"\bThat (?:is|was|'s) (?:the|all|it|what|why)\b[^.\n]{0,40}\.", re.I)+HEADING = re.compile(r"^\s*#{1,6}\s+(.+?)\s*$", re.M)+SENTENCE = re.compile(r"[.!?](?:\s|$)")+OPENER = re.compile(r"(?:^|\. )([A-Z][a-z]+) ", re.M)+FRONTMATTER = re.compile(r"\A---\n.*?\n---\n", re.S)+CODE = re.compile(r"^```.*?^```", re.M | re.S)+++def load(path):+ text = open(path, encoding="utf-8", errors="ignore").read()+ text = FRONTMATTER.sub("", text)+ return CODE.sub(" ", text)+++def count_phrase(text, phrase):+ if " " in phrase or "'" in phrase:+ return len(re.findall(re.escape(phrase), text, re.I))+ return len(re.findall(r"\b%s\b" % re.escape(phrase), text, re.I))+++def census(paths):+ words = Counter()+ docs = Counter()+ sentences = verdicts = kickers = 0+ openers = Counter()+ headings = Counter()+ closers = {"question": 0, "kicker": 0}+ for p in paths:+ t = load(p)+ sentences += len(SENTENCE.findall(t))+ verdicts += len(VERDICT.findall(t))+ k = len(KICKER.findall(t))+ kickers += k+ for m in OPENER.finditer(t):+ openers[m.group(1)] += 1+ for h in HEADING.findall(t):+ first = h.split()[0] if h.split() else ""+ headings[first] += 1+ body = [ln for ln in t.strip().splitlines() if ln.strip()]+ if body:+ last = body[-1]+ if last.rstrip().endswith("?"):+ closers["question"] += 1+ if KICKER.search(last):+ closers["kicker"] += 1+ for w in WATCH:+ n = count_phrase(t, w)+ if n:+ words[w] += n+ docs[w] += 1+ return {"files": len(paths), "sentences": sentences, "words": words, "docs": docs,+ "verdicts": verdicts, "kickers": kickers, "openers": openers,+ "headings": headings, "closers": closers}+++def render(c, corpus):+ n = max(c["files"], 1)+ lines = ["# Voice baseline", "",+ "Measured from %d files in `%s`, about %d sentences." % (c["files"], corpus, c["sentences"]),+ "Counted, not banned. A word above its baseline in a new draft is a tic to check, not an error.",+ "", "## Words", "", "| Word or phrase | Uses | Files | Per file |", "|---|---|---|---|"]+ for w, total in c["words"].most_common():+ lines.append("| %s | %d | %d | %.1f |" % (w, total, c["docs"][w], total / n))+ lines += ["", "## Sentence shapes", "",+ "| Shape | Count | Share |", "|---|---|---|",+ "| Paragraph-ending verdict (\"The X was one line.\") | %d | %.1f%% of sentences |"+ % (c["verdicts"], 100.0 * c["verdicts"] / max(c["sentences"], 1)),+ "| \"That is the point\" kicker | %d | %.1f per file |" % (c["kickers"], c["kickers"] / n),+ "| Files ending on a question to the reader | %d | %.0f%% of files |"+ % (c["closers"]["question"], 100.0 * c["closers"]["question"] / n),+ "| Files ending on a kicker | %d | %.0f%% of files |"+ % (c["closers"]["kicker"], 100.0 * c["closers"]["kicker"] / n), ""]+ lines += ["## Sentence openers", "", "| Opener | Count |", "|---|---|"]+ for w, total in c["openers"].most_common(8):+ lines.append("| %s | %d |" % (w, total))+ lines += ["", "## Heading first words", "", "| First word | Headings |", "|---|---|"]+ for w, total in c["headings"].most_common(8):+ lines.append("| %s | %d |" % (w, total))+ lines += ["", "## How to use this", "",+ "1. Before publishing, run `census.py CORPUS --check DRAFT` and read what sits above the per-file rate.",+ "2. For each flagged word, decide: does the sentence need it, or is it decoration? Remove the adjective; if the reader would do nothing differently, it was decoration.",+ "3. Cap the shapes. One paragraph-ending verdict per piece at most, and only when it carries a fact. No kicker closers. Do not end on a question by default.",+ "4. Re-run the census after ten new pieces. A tic you fixed should fall; a new one will have appeared.", ""]+ return "\n".join(lines)+++def check(c, draft):+ n = max(c["files"], 1)+ t = load(draft)+ sentences = max(len(SENTENCE.findall(t)), 1)+ print("%s: %d sentences" % (draft, sentences))+ flagged = 0+ for w, total in c["words"].most_common():+ rate = total / n+ here = count_phrase(t, w)+ if here and here > max(rate, 1):+ flagged += 1+ print(" ABOVE BASELINE %-18s %d uses here vs %.1f per file in the corpus" % (w, here, rate))+ v = len(VERDICT.findall(t))+ if v > 1:+ print(" SHAPE %d paragraph-ending verdict sentences (cap: 1)" % v)+ flagged += 1+ k = len(KICKER.findall(t))+ if k:+ print(" SHAPE %d \"That is the point\" kicker(s) (cap: 0)" % k)+ flagged += 1+ body = [ln for ln in t.strip().splitlines() if ln.strip()]+ if body and body[-1].rstrip().endswith("?"):+ print(" SHAPE ends on a question to the reader")+ flagged += 1+ if not flagged:+ print(" nothing above baseline")+ return 1 if flagged else 0+++def main():+ ap = argparse.ArgumentParser(description="Measure a writing corpus for over-used words and shapes.")+ ap.add_argument("corpus", help="directory of your own writing")+ ap.add_argument("--ext", default=".md", help="file extension to include (default .md)")+ ap.add_argument("--out", default="", help="write the baseline to this file instead of stdout")+ ap.add_argument("--check", default="", help="compare one draft against the corpus rate")+ a = ap.parse_args()++ paths = []+ for root, _, files in os.walk(a.corpus):+ for f in files:+ if f.endswith(a.ext):+ paths.append(os.path.join(root, f))+ if not paths:+ print("no %s files under %s" % (a.ext, a.corpus), file=sys.stderr)+ return 2++ c = census(sorted(paths))+ if a.check:+ return check(c, a.check)+ out = render(c, a.corpus)+ if a.out:+ open(a.out, "w", encoding="utf-8").write(out)+ print("wrote %s (%d files, %d sentences)" % (a.out, c["files"], c["sentences"]))+ else:+ print(out)+ return 0+++if __name__ == "__main__":+ sys.exit(main())diff --git a/AGENTS.md b/AGENTS.mdindex b507a16..87b8c51 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -648,6 +648,48 @@ The following 7 skills raise output quality on writing and visual work. They enc---+### /slop-gate++**Description:** Deterministic pre-publish scan that refuses AI-slop tells in anything about to be written, published, or sent.++**Triggers:**+- "scan this before I publish"+- Before any deliverable leaves the session: file, artifact, deck, Slack message, issue body, commit+- As a CI step or a Claude Code hook++**Purpose:** `/no-ai-slop` is an editor you invoke; this is a gate that runs whether or not anyone remembers it. A rules file fires in the step a model calls writing and stays silent in the step it calls layout, which is how a deck ends up with clean paragraphs under headline slide titles.++**What it does:**+1. Scans outgoing text and exits non-zero on a tell, with the hit list and surrounding context+2. Hard tells fail on one hit (em dash, honesty framing, "not X it's Y" and its trailing "X, not Y" form, rhetorical and "The \<Noun\>" headings, verdict kickers, sycophancy, recap endings)+3. Filler words are counted, not banned: three or more in one piece fails+4. Quoted and backticked spans are stripped first, so a piece may quote the tells it discusses; `slop-ok: <reason>` exempts a whole file+5. `--hook` mode answers a Claude Code PreToolUse or Stop payload with a permission decision (opt-in, wiring in the skill)++**Limit:** regular expressions cannot see structural slop (invented frameworks, uniform rhythm, restatement). Pair with `/no-ai-slop` detect mode and a reviewer from a different model family than the author.++---++### /voice-baseline++**Description:** Measure your own writing corpus for the words and sentence shapes you over-use, so an agent writing in your voice stops amplifying your tics into a style.++**Triggers:**+- "why do my drafts all sound the same?"+- Before publishing anything written in your voice+- Every ten new pieces, to re-measure++**Purpose:** An agent samples the median of *you*, not only the median of the internet, and regresses toward your most frequent choices. A generic ban list cannot catch it because the words are yours.++**What it does:**+1. Walks a directory of your finished writing and reports word counts with a per-file rate+2. Counts sentence shapes: paragraph-ending verdict sentences, kicker closers, endings that ask the reader a question+3. Reports sentence openers and heading first words, where a personal tic hides best+4. `--check DRAFT` prints only what sits above your corpus rate, exit 1 when anything does+5. Writes a baseline file to keep beside your rules so the agent reads it before writing++---+### /editorial-illustrations**Description:** Generate meaning-carrying editorial data-illustrations in a near-black grayscale + single-accent aesthetic. A **generative guide**, not a template gallery. It teaches the "claim → geometry" method.diff --git a/CHANGELOG.md b/CHANGELOG.mdindex fc4d41e..736b081 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -2,6 +2,35 @@All notable changes to COG (Cognition + Obsidian + Git) will be documented in this file.+## [3.13.0] - 2026-09-14++### Added++#### slop-gate: the anti-slop rules stop depending on being remembered+`no-ai-slop` is an editor you invoke. `slop-gate` is a scan that runs whether or not anyone remembers it: it reads outgoing text, exits non-zero on a tell, and prints the hit list with surrounding context so the rewrite is targeted.++The gap it closes came from a real failure. A slide deck built by an agent carried paragraphs that passed every rule in the file, under slide titles reading "One harness, four swappable sides", "Four walls, seven accounts", "Five calls to make this month". The rules were filed under writing; the titles were produced in a step the agent treated as layout, where the rules never ran. Every surface nobody named explicitly sat on the unchecked side: table headers, diagram labels, chart legends, button copy, commit messages, memory-file descriptions.++- `scripts/scan.py` works as a CLI (`scan.py FILE`, stdin, glob), as a CI step (exit 1 on a tell), and with `--hook` as a Claude Code PreToolUse/Stop hook. COG still ships no hooks; the wiring is a snippet in the skill for anyone who wants it.+- Two tiers: hard tells fail on one hit (em dash, honesty framing, "not X, it's Y" and its trailing "X, not Y" form, rhetorical headings, "The \<Noun\>" headings, verdict kickers, fake-profound closers, throat-clearing, sycophancy, recap endings, emoji headings). Filler words are counted and fail at three, on the reading that density means decoration.+- Quoted and backticked spans are stripped before scanning, so a style guide can quote the tells it blocks. `slop-ok: <reason>` exempts a whole file.+- Stated limit: regular expressions cannot see invented frameworks, uniform rhythm, or restatement. The skill says so and routes those to `no-ai-slop` detect mode plus a reviewer from a different model family.++#### voice-baseline: measure your own tics before an agent turns them into a style+An agent writing in your voice samples the median of you, not only the median of the internet, and regresses toward your most frequent choices. A generic ban list misses it because the words are yours.++- `scripts/census.py` walks a corpus of your finished writing and reports word counts with a per-file rate, paragraph-ending verdict sentences, kicker closers, endings that ask the reader a question, sentence openers, and heading first words.+- `--check DRAFT` prints only what sits above your corpus rate and exits 1 when anything does, so it fits a pre-publish script.+- Run on a real 27-file archive it found 53 headings starting with "The" and 387 of 2,288 sentences opening the same way: the exact shape people name as an AI tell, learned from the author's own archive rather than from the model.++### Changed++#### no-ai-slop gains scope, measured reader data, and the voice-mode section+- **Scope: every medium.** The rules now name slide titles, kickers, tile and card labels, table headers, diagram labels, chart legends, button copy, alt text, chat and email drafts, issue and PR bodies, commit messages, code comments and memory files, plus the three failing title shapes (number pairing, metaphor for the noun, question as title).+- **Reader-cited tells.** Ranked from a hand-audited sample of 600 posts drawn from 89,239 across 47 subreddits: em dash 7.1%, uniform sentence rhythm 4.0%, "not just X, it's Y" 2.8%, five-paragraph shape and sycophancy 2.5% each, diction memes 1.3%. Two corrections ride along: a keyword scanner ranks "however/thus/hence" first at 6.3% of posts where readers cite them zero times, and the tells readers rank highest cannot be keyword-matched at all.+- **Malicious compliance** named as the failure mode of a ban list: ban the dash and the model reaches for a semicolon or a colon reveal, because the driver underneath is over-explanation and restatement.+- **Voice-mode tells** with the caps that hold in any voice: one verdict sentence per piece, zero kicker closers, no default question ending, one narrative heading pattern, a distinct verb for each action.+## [3.12.0] - 2026-08-25### Changeddiff --git a/COG-VERSION b/COG-VERSIONindex 92536a9..4eba2a6 100644--- a/COG-VERSION+++ b/COG-VERSION@@ -1 +1 @@-3.12.0+3.13.0diff --git a/README.md b/README.mdindex aa02086..e05dc5d 100644--- a/README.md+++ b/README.md@@ -130,6 +130,8 @@ Opt-in. Ask for one of these and work walks a **V**: decompose left into falsifi| Skill | What it does | Try saying... ||---|---|---|| **no-ai-slop** | Sharpen a draft without flattening its voice, or just detect AI-slop patterns | "Make this less AI-sounding" |+| **slop-gate** | Refuse slop tells in anything about to be written, published, or sent; runs in CI or as a hook | "Scan this before I publish" |+| **voice-baseline** | Measure the words and shapes you over-use so an agent stops amplifying your tics | "Why do my drafts all sound the same?" || **editorial-illustrations** | Claim → geometry: derive the *right* figure from what the text argues, render it as self-contained theme-aware HTML/SVG | "Make a diagram for this argument" || **data-forms** | 20+ chart and diagram forms with when-to-use, failure modes, and the encoding discipline that makes any of them readable | "The bar chart is burying the point" || **museum-art** | Real public-domain artwork from museum open-access APIs instead of AI-generated or stock imagery | "Find a hero image for this post" |diff --git a/cog-update.sh b/cog-update.shindex 0dcfd77..f91e269 100755--- a/cog-update.sh+++ b/cog-update.sh@@ -67,6 +67,10 @@ FRAMEWORK_FILES=(".claude/skills/retro/SKILL.md"".claude/skills/review-cockpit/SKILL.md"".claude/skills/no-ai-slop/SKILL.md"+ ".claude/skills/slop-gate/SKILL.md"+ ".claude/skills/slop-gate/scripts/scan.py"+ ".claude/skills/voice-baseline/SKILL.md"+ ".claude/skills/voice-baseline/scripts/census.py"".claude/skills/editorial-illustrations/SKILL.md"".claude/skills/data-forms/SKILL.md"".claude/skills/museum-art/SKILL.md"@@ -166,6 +170,8 @@ FRAMEWORK_FILES=(".agents/skills/memory-hygiene/SKILL.md"".agents/skills/museum-art/SKILL.md"".agents/skills/no-ai-slop/SKILL.md"+ ".agents/skills/slop-gate/SKILL.md"+ ".agents/skills/voice-baseline/SKILL.md"".agents/skills/onboarding/SKILL.md"".agents/skills/product-ui-taste/SKILL.md"".agents/skills/publish-to-confluence/SKILL.md"diff --git a/marketplace-entry.json b/marketplace-entry.jsonindex 3b451d2..0679ebf 100644--- a/marketplace-entry.json+++ b/marketplace-entry.json@@ -6,8 +6,8 @@"email": "[email protected]","url": "https://github.com/huytieu"},- "description": "Self-evolving second brain with 33 AI skills, 10 agents, and people CRM. Closed-loop harness release: V-model verification lifecycle with criterion-traced evidence, read-only verifier agents, risk lanes, multi-session ultragoals with a north-star acceptance gate, craft skills for writing and visuals, and paired anti-slop design skills for marketing and product UI. Inspired by Garry Tan's gstack and gbrain, and dwarves-kit. Works with Claude Code, Antigravity, Cursor, Kiro, Gemini CLI, Codex.",- "version": "3.12.0",+ "description": "Self-evolving second brain with 35 AI skills, 10 agents, and people CRM. Closed-loop harness release: V-model verification lifecycle with criterion-traced evidence, read-only verifier agents, risk lanes, multi-session ultragoals with a north-star acceptance gate, craft skills for writing and visuals, and paired anti-slop design skills for marketing and product UI. Inspired by Garry Tan's gstack and gbrain, and dwarves-kit. Works with Claude Code, Antigravity, Cursor, Kiro, Gemini CLI, Codex.",+ "version": "3.13.0","keywords": ["second-brain","garry-tan",diff --git a/plugin.json b/plugin.jsonindex 33a885e..2ca889c 100644--- a/plugin.json+++ b/plugin.json@@ -1,8 +1,8 @@{"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json","name": "cog-second-brain",- "version": "3.12.0",- "description": "Self-evolving second brain with 33 AI agent skills, 10 agents, and people CRM. Closed-loop harness: a V-model verification lifecycle (spec to evidence, criterion-traced checkpoints), read-only verifier agents that observe artifacts instead of trusting worker summaries, risk lanes, multi-session ultragoals with a north-star acceptance gate, plus craft skills for writing, visual work, and a paired anti-slop design system for marketing and product UI. Works with Claude Code, Antigravity, Cursor, Kiro, Gemini CLI, Codex, and any Agent Plugins conformant client.",+ "version": "3.13.0",+ "description": "Self-evolving second brain with 35 AI agent skills, 10 agents, and people CRM. Closed-loop harness: a V-model verification lifecycle (spec to evidence, criterion-traced checkpoints), read-only verifier agents that observe artifacts instead of trusting worker summaries, risk lanes, multi-session ultragoals with a north-star acceptance gate, plus craft skills for writing, visual work, and a paired anti-slop design system for marketing and product UI. Works with Claude Code, Antigravity, Cursor, Kiro, Gemini CLI, Codex, and any Agent Plugins conformant client.","author": {"name": "Huy Tieu","email": "[email protected]",diff --git a/skills/no-ai-slop/SKILL.md b/skills/no-ai-slop/SKILL.mdindex abc4671..9b6ef0a 100644--- a/skills/no-ai-slop/SKILL.md+++ b/skills/no-ai-slop/SKILL.md@@ -83,6 +83,81 @@ Often-empty phrases: it's worth noting, it's important to note, at the end of th**Em dashes.** Do not use them as a default rhythm crutch. In short copy, use none. In longer drafts, 1-2 are fine if they clearly beat commas, periods, or parentheses. Remove clusters and decorative dashes.+## Scope: every medium, not only prose++These rules govern the substance and the labels of every output, not paragraphs alone:+slide titles and kickers, tile and card labels, table headers and row keys, diagram node+and edge labels, chart titles and legends, button copy, subtitles, alt text, chat and+email drafts, issue and PR bodies, commit messages, code comments, memory files.++A rules file that says "writing" fires in the step a model calls writing and stays silent+in the step it calls layout. That is how a deck ends up with clean paragraphs under+headline slide titles. Name every surface, then scan every heading and label before+publishing, separately from reading the body.++**Titles and headings name their subject.** "New runner architecture", "Current+challenges", "Sources". Three shapes fail:++- **Number pairing.** "One harness, four swappable sides." "Four walls, seven accounts."+ "Five calls to make this month." Two small integers joined by a comma read as structure+ and carry none.+- **Metaphor in place of the noun.** "The wedge" for a differentiator, "walls" for+ challenges, "shells" for deployment targets. The reader decodes an image to reach a word+ you could have written.+- **Question or clause as title.** "Why hard apps are the niche." "Where the facts come+ from." A title that withholds its answer costs a beat every time someone scans the index.++## Reader-cited tells++From a hand-audited sample of 600 posts (out of 89,239 pulled across 47 subreddits) about+what makes writing read as AI, ranked by how often readers actually name each tell: em dash+7.1%, uniform sentence rhythm 4.0%, "not just X, it's Y" 2.8%, five-paragraph essay shape+2.5%, sycophancy such as "great question" 2.5%, "dive in / deep dive" 2.0%, bullet lists+where prose belongs 1.7%, diction memes such as "delve" 1.3%, rule-of-three triads 1.2%,+emoji headers 0.8%, "unlock the potential" 0.8%, "in today's fast-paced world" 0.7%, no+contractions 0.7%, empty phrasing 0.7%, both-sides hedging 0.3%.++Two corrections that matter more than the ranking:++- **A keyword scanner ranks the wrong things.** In the same corpus "however", "thus" and+ "hence" were the top keyword match at 6.3% of posts and were cited as a tell zero times.+ Do not flag ordinary connectives.+- **The tells readers rank highest cannot be keyword-matched at all.** Uniform rhythm and+ the fluent-but-empty paragraph need a reader. So does sycophancy.++Also named by readers and worth adding to any watchlist: genuinely, quietly, load-bearing,+hinge, seams, "let that sink in", "what nobody talks about", "this changes everything", and+subheadings shaped "The \<Noun\>" ("The Start", "The Gamechanger").++**Malicious compliance is the failure mode of a ban list.** Ban the em dash and the model+substitutes ", and" or a semicolon or a colon reveal; ban "not X but Y" and it produces+"X. Y." fragments. The driver underneath is over-explanation and restatement. A systemic+instruction ("be airy, do not over-explain, do not restate") does more than two dozen bans.++## Voice-mode tells++An agent writing in someone's voice samples the median of that person, not only the median+of the internet, and regresses toward their most frequent choices. A word that was a choice+at one use comes back at five, and the fifth use teaches the next draft.++Generic ban lists miss this, because the words are the author's own. Measure them: the+`voice-baseline` skill counts a corpus and checks a draft against its own rates. Typical+finds in a real 27-file archive: 53 headings starting with "The", 387 of 2,288 sentences+opening with "The", 25 closing lines of the form "That is the point."++Caps that hold regardless of whose voice it is:++- One paragraph-ending verdict sentence per piece ("The fix was one line."), and only when+ it carries a fact the paragraph has not already delivered.+- Zero kicker closers ("That is the point.", "That is all a title is for.").+- Do not end on a question to the reader by default. End on the last concrete fact.+- One narrative heading pattern per piece; the rest name their subject.+- A verb for each action: use "ship" for a software release, and give publishing, saving,+ sending and deploying their own verbs.++For the mechanical half of all of this, `slop-gate` scans outgoing text and refuses on a+hard tell, so the check does not depend on being remembered.+## Structural slopWord bans catch surface slop. The deeper tell is composition: predictable rhetorical structure with low information gain. A draft can pass every word check and still read as a miniature consulting memo. These patterns apply to the shape of the whole piece, not individual sentences.diff --git a/skills/slop-gate/SKILL.md b/skills/slop-gate/SKILL.mdnew file mode 100644index 0000000..634e498--- /dev/null+++ b/skills/slop-gate/SKILL.md@@ -0,0 +1,121 @@+---+name: slop-gate+description: Deterministic pre-publish scan that refuses AI-slop tells in anything about to be written, published, or sent: files, artifacts, slide titles, table headers, diagram labels, chat messages, commit messages. Use before publishing or sending any deliverable, in CI, or wired as a Claude Code hook so the check runs without being remembered. The editorial counterpart is no-ai-slop, which rewrites; this one blocks.+---++<!-- slop-ok: this skill quotes the tells it blocks -->++# slop-gate++`no-ai-slop` is an editor you invoke. This is a gate that runs whether or not anyone+remembers it. It scans outgoing text, refuses on a tell, and returns the hit list so+the rewrite is targeted.++Two rules make it usable rather than annoying: hard tells fail on a single hit, and+words that are decoration at volume but legitimate once are counted rather than+banned. Text inside quotes or backticks is stripped before scanning, so a piece that+quotes a tell as an exhibit does not fail on its own examples.++## Why a gate and not a rule++A rules file is advisory, and advisory rules fail in a specific, repeatable way: they+fire in the step the model thinks of as writing and not in the steps it thinks of as+something else. A deck built by an agent can carry clean paragraphs under headline+slide titles, because the titles were produced in a layout step where the writing+rules never ran. Every surface nobody named explicitly sits on the unchecked side:++ slide titles, kickers table headers, row keys commit messages+ tile and card labels diagram node and edge labels code comments+ chart titles and legends button copy, subtitles memory files+ alt text, image captions Slack, email, issue bodies PR descriptions++The gate closes that by scanning the text on its way out, whatever produced it.++## Run it++```bash+python3 scripts/scan.py DRAFT.md # one file+python3 scripts/scan.py content/**/*.md # many+cat draft.md | python3 scripts/scan.py - # stdin+```++Exit code 0 is clear, 1 is tells found, so it drops into CI or a pre-commit hook+unchanged. Every hit prints its label and the surrounding text.++## Wire it as a hook (Claude Code, optional)++COG ships no hooks by default. If you want the check enforced rather than remembered,+add this to `.claude/settings.json` yourself. `--hook` reads the hook payload on stdin+and answers with a permission decision.++```json+{+ "hooks": {+ "PreToolUse": [+ {+ "matcher": "Write|Edit|mcp__.*slack.*send.*|mcp__atlassian__(create|update)Confluence.*",+ "hooks": [{ "type": "command",+ "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/skills/slop-gate/scripts/scan.py\" --hook" }]+ }+ ],+ "Stop": [+ { "hooks": [{ "type": "command",+ "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/skills/slop-gate/scripts/scan.py\" --hook" }] }+ ]+ }+}+```++The `Stop` entry scans the agent's own reply, which is where most of these land in a+working session. Expect it to fire on you within the hour; that is the point of it.++## What fails on one hit++| Tell | Specimen |+|---|---|+| Em dash | any `—` |+| Honesty framing | "honestly", "the honest part:", "if I'm being honest" |+| "not X, it's Y" | "It's not about speed, it's about trust" |+| "X, not Y" (trailing form) | "a test, not a permission", "machinery, not memory" |+| Rhetorical heading | "Why this matters", "The bottom line", "What comes next" |+| "The \<Noun\>" heading | "The Wedge", "The Shot", "The Gamechanger" |+| Verdict kicker | "That is the point.", "That is all a title is for." |+| Fake-profound closer | "let that sink in", "this changes everything" |+| Throat-clearing | "Here's the thing", "It's worth noting", "At the end of the day" |+| Sycophancy | "Great question", "You were right to push back", "That's on me" |+| Recap ending | a final paragraph opening "In conclusion" or "Ultimately" |+| Emoji heading | `## 🚀 Results` |++## What is counted, not banned++`robust, seamless, leverage, utilize, delve, empower, streamline, genuinely, quietly,+load-bearing, deep dive, clean, plain, simple, elegant, powerful, lightweight,+tapestry, game-changer, paradigm shift, cutting-edge`++Three or more in one piece fails, on the reading that density means decoration. One+is a word choice. The test for any single use: remove the adjective, and if the reader+would do nothing differently, it was decoration. "A robust retry" fails that test;+"a retry that survives a mail-slot timeout" passes, because it names the behaviour.+Keep the word when it is the term of art ("robust statistics").++## Exhibits++A piece that must quote a tell (a style guide, a post about slop, a test fixture)+carries `slop-ok: <reason>` anywhere in the file, usually as an HTML comment or a+front-matter key. Quoted and backticked spans are already exempt, so the marker is+only needed when a tell appears in the author's own voice on purpose.++Never add the marker to get past a gate you disagree with. Rewrite instead, or change+the pattern list and say why.++## What it cannot see++The gate is regular expressions, so it catches surface and near-surface tells. It is+blind to the structural ones: a declared count that the source does not contain, a+framework invented to organise two paragraphs, uniform sentence rhythm, a paragraph+that restates the previous one. Those need a reader. Use `no-ai-slop` in detect mode,+and prefer a reviewer from a different model family than the author, because a+same-family reviewer shares the author's sense of what a finished answer looks like+and waves through the same shapes.++For the tics that are yours rather than universal, measure them: `voice-baseline`.diff --git a/skills/slop-gate/scripts/scan.py b/skills/slop-gate/scripts/scan.pynew file mode 100755index 0000000..e8a64f5--- /dev/null+++ b/skills/slop-gate/scripts/scan.py@@ -0,0 +1,206 @@+#!/usr/bin/env python3+"""slop-gate: deterministic scan for AI-slop tells in anything about to be published.++Usage+-----+ python3 scan.py FILE [FILE...] # scan files+ cat draft.md | python3 scan.py - # scan stdin+ python3 scan.py --hook # Claude Code PreToolUse/Stop hook mode (JSON on stdin)++Exit codes: 0 clean, 1 tells found (so it works in CI and in a pre-commit hook).++Two tiers+---------+HARD tells fail on a single hit. They have no legitimate use in finished prose.+FILLER words fail at SOFT_LIMIT or more, because one is a word choice and five is+decoration.++Text inside backticks or quotation marks is stripped before scanning, so a piece+that quotes a tell as an exhibit does not fail on its own examples.+"""+import json+import os+import re+import sys++SOFT_LIMIT = 3++HARD = [+ ("em dash", r"—", 0),+ ("honesty framing",+ r"\b(honestly|to be honest|if I'm being honest|the honest (part|truth|answer|reason)|I'll be honest)\b", re.I),+ ("not-X-it's-Y contrast",+ r"\b(it'?s|this is|that'?s|the (question|point|problem|issue)) (is )?not (just |only |about )?[^.\n]{2,60}[.,;] ?(it'?s|but|it is) ", re.I),+ ("not-X-it's-Y contrast", r"\bnot just [^.\n]{2,40}, (it'?s|but) ", re.I),+ ("not-X-it's-Y contrast",+ r"\b(it|this|that) (is|was) not (about |just |only )?[^.,;\n]{2,50}, (it|this|that) (is|was) ", re.I),+ ("X-not-Y contrast", r"\b[a-z][a-z-]+, not (a |an |the |just |only )?[a-z][a-z -]{1,30}[.;:]", 0),+ ("X-not-Y contrast", r"\b(rather than|instead of) [a-z][a-z -]{1,30}[.;]", re.I),+ ("rhetorical heading",+ r"^\s*(#{1,6}|<h[1-6][^>]*>)\s*(why (this|it) matters|the (key|real) (insight|point|opportunity|truth)|what this is not|the bottom line|the deeper point|the uncomfortable truth|here'?s the thing|the takeaway|so what|what comes next|what'?s next|where (it|this|we) go(es)? (from here|next))\b", re.I | re.M),+ ("The <Noun> heading", r"^\s*(#{1,6}|<h[1-6][^>]*>)\s*The [A-Z][a-z]+\s*(</h[1-6]>)?\s*$", re.M),+ ("verdict kicker",+ r"\bThat (is|was|'s) (the (point|lie|whole (point|thing)|part [a-z ]{3,30})|all [a-z ]{2,30} is for)\.", re.I),+ ("fake-profound closer",+ r"\b(let that sink in|this changes everything|what nobody (tells|talks about)|the part (everyone|most people) miss(es)?|and that'?s not nothing)\b", re.I),+ ("throat-clearing",+ r"\b(here'?s the thing|let me be clear|it'?s worth noting|it is worth noting|it'?s important to note|at the end of the day|in today'?s (fast-paced|ever-evolving|digital))\b", re.I),+ ("sycophancy",+ r"\b(great question|you'?re (absolutely )?right to push back|that'?s on me|you were right to)\b", re.I),+ ("summary-recap ending", r"^\s*(in conclusion|ultimately|overall|to sum up|in summary)\b", re.I | re.M),+ ("emoji heading", r"^\s*#{1,6}\s*[\U0001F300-\U0001FAFF☀-➿]", re.M),+]++FILLER = re.compile(+ r"\b(delve|delves|delving|leverag(e|es|ing)|utiliz(e|es|ing)|seamless(ly)?|robust(ly)?"+ r"|tapestry|game[- ]changer|paradigm shift|cutting-edge|empower(s|ing)?|streamlin(e|es|ing)"+ r"|load-bearing|unlock the (potential|power)|genuinely|quietly|deep dive|dive in(to)?"+ r"|clean|plain|simple|elegant|powerful|lightweight)\b", re.I)++QUOTED = re.compile(r"`[^`\n]*`|\"[^\"\n]{0,160}\"|“[^”\n]{0,160}”|^```.*?^```", re.M | re.S)++TEXT_EXT = {".md", ".mdx", ".html", ".htm", ".txt", ".svg", ".rst", ""}+SKIP_PATH = ("no-ai-slop", "slop-gate", "voice-baseline", "/memory/", "/hooks/", "/logs/",+ "node_modules", "/site/", "/build/", "/dist/")+++def strip_quoted(text):+ """Quoted, fenced and code-formatted spans are exhibits, not the author's voice."""+ return QUOTED.sub(" ", text)+++def scan(text, soft_limit=SOFT_LIMIT):+ body = strip_quoted(text)+ hits = []+ for label, rx, flags in HARD:+ for m in re.finditer(rx, body, flags):+ frag = body[max(0, m.start() - 28):m.end() + 28].replace("\n", " ").strip()+ hits.append("[%s] ...%s..." % (label, frag))+ if len(hits) >= 12:+ return hits+ soft = []+ for m in re.finditer(FILLER, body):+ frag = body[max(0, m.start() - 28):m.end() + 28].replace("\n", " ").strip()+ soft.append("[filler word, %d of %d allowed] ...%s..." % (len(soft) + 1, soft_limit, frag))+ if len(soft) >= soft_limit:+ hits.extend(soft[:6])+ return hits+++def exempt(path, text):+ if "slop-ok:" in text:+ return True+ if not path:+ return False+ if any(s in path for s in SKIP_PATH):+ return True+ ext = os.path.splitext(path)[1].lower()+ return bool(ext) and ext not in TEXT_EXT+++# --------------------------------------------------------------------------- hook mode+def hook():+ """Claude Code hook mode. Reads the hook payload on stdin, writes a decision on stdout."""+ try:+ d = json.loads(sys.stdin.read())+ except Exception:+ print("{}")+ return 0++ if d.get("hook_event_name") == "Stop":+ if d.get("stop_hook_active"):+ print("{}")+ return 0+ text, last = "", None+ try:+ with open(d.get("transcript_path", ""), encoding="utf-8") as f:+ for line in f:+ try:+ o = json.loads(line)+ except Exception:+ continue+ if o.get("type") == "assistant":+ last = o+ for c in (last or {}).get("message", {}).get("content", []):+ if c.get("type") == "text":+ text += c.get("text", "") + "\n"+ except Exception:+ pass+ hits = scan(text)+ if hits:+ print(json.dumps({"decision": "block",+ "reason": "slop-gate (reply): rewrite without these tells, then stop.\n"+ + "\n".join(hits)}))+ else:+ print("{}")+ return 0++ tool = d.get("tool_name", "")+ ti = d.get("tool_input") or {}+ path = ti.get("file_path") or ti.get("path") or ""+ text = ""+ if tool == "Write":+ text = ti.get("content", "") or ""+ elif tool == "Edit":+ text = ti.get("new_string", "") or ""+ if path and os.path.isfile(path):+ try:+ if "slop-ok:" in open(path, encoding="utf-8").read():+ print("{}")+ return 0+ except Exception:+ pass+ else:+ # Any message-sending tool: Slack, Confluence, Jira, Linear, email.+ for key in ("message", "text", "body", "content"):+ if ti.get(key):+ text = ti[key] if isinstance(ti[key], str) else json.dumps(ti[key])+ break+ path = ""+ if not text:+ print("{}")+ return 0++ if exempt(path, text) or not text:+ print("{}")+ return 0++ hits = scan(text)+ if hits:+ reason = ("slop-gate: %s blocked. Rewrite without these tells. "+ "For a deliberate exhibit add `slop-ok: <reason>` to the file.\n" % tool) + "\n".join(hits)+ print(json.dumps({"hookSpecificOutput": {"hookEventName": "PreToolUse",+ "permissionDecision": "deny",+ "permissionDecisionReason": reason}}))+ else:+ print("{}")+ return 0+++def main():+ args = [a for a in sys.argv[1:] if a != "--"]+ if "--hook" in args:+ return hook()+ if not args or "--help" in args or "-h" in args:+ print(__doc__)+ return 0+ failed = 0+ for path in args:+ text = sys.stdin.read() if path == "-" else open(path, encoding="utf-8").read()+ label = "stdin" if path == "-" else path+ if path != "-" and exempt(path, text):+ print("%s: exempt" % label)+ continue+ hits = scan(text)+ if hits:+ failed = 1+ print("%s: %d tell(s)" % (label, len(hits)))+ for h in hits:+ print(" " + h)+ else:+ print("%s: clear" % label)+ return failed+++if __name__ == "__main__":+ sys.exit(main())diff --git a/skills/voice-baseline/SKILL.md b/skills/voice-baseline/SKILL.mdnew file mode 100644index 0000000..e84fe16--- /dev/null+++ b/skills/voice-baseline/SKILL.md@@ -0,0 +1,75 @@+---+name: voice-baseline+description: Measure your own writing corpus for the words and sentence shapes you over-use, so an agent writing in your voice stops amplifying your tics into a style. Produces a counted baseline file and checks any new draft against it. Use when an agent's drafts start sounding like a caricature of you, before publishing anything written in your voice, or every ten new pieces to re-measure.+---++# voice-baseline++An agent writing in your voice does not only sample the median of the internet. It+samples the median of you, from the pieces and rules and memory files in its context,+and it regresses toward your most frequent choices because those are the highest+probability tokens in your corpus. A word that was a choice at one use comes back at+five. Then the fifth use teaches the next draft, and the tic becomes the style.++Generic ban lists cannot catch this, because the words are yours and they are not on+anyone's list. Measure instead.++## Run it++```bash+python3 scripts/census.py PATH/TO/YOUR/WRITING --out voice-baseline.md+python3 scripts/census.py PATH/TO/YOUR/WRITING --check DRAFT.md+```++The census walks a directory of your own finished pieces and reports word counts with+a per-file rate, sentence-shape counts, sentence openers, and heading first words.+`--check` compares one draft against those rates and prints only what sits above them.+Exit code 1 when something is above baseline, so it fits a pre-publish script.++Keep the output file next to your rules so the agent reads it before it writes.++## What it measures++**Words.** A watchlist of praise and emphasis words, counted with word boundaries and+reported per file. Read the per-file rate: a word used twice per file is a habit, and+the same word at eight in one draft is the draft's problem. Edit `WATCH` in the+script to add your own suspects; the point is that the list ends up specific to you.++**Paragraph-ending verdict sentences.** "The fix was one line." A concrete noun, a+past-tense verb, a short predicate, parked at the end of a paragraph so it lands like+a ruling. One per piece at most, and only when it carries a fact the paragraph has not+already delivered.++**Kicker closers.** "That is the point." "That is all a title is for." A closing line+that restates the piece as an aphorism. The cap is zero.++**Endings.** How many pieces close on a question to the reader. Most of them means the+question has become a formula.++**Sentence openers and heading first words.** These are where a personal tic hides+best, because each instance reads fine. If a third of your headings begin with the+same word, you have a template. In one real 27-file archive the census found 53+headings starting with "The", the exact shape people name as an AI tell, learned from+the author's own archive.++## How to read the result++The census counts; it does not judge. For each flagged word or shape, decide whether+it is your voice or your mode:++- **Voice.** The word carries meaning the sentence needs, or the rhythm is yours and+ deliberate. Keep it, and note the exception so the next check does not re-raise it.+- **Mode.** The word is praise, emphasis, or padding, and removing it changes nothing+ for the reader. Cut it, or replace it with the behaviour it was gesturing at.++Fix the shapes by cap rather than by ban: one verdict sentence, zero kickers, no+default question ending, one narrative heading pattern per piece.++## Re-measure++Run the census again after roughly ten new pieces. A tic you fixed should fall. A new+one will have appeared, usually the word you reached for while avoiding the last one,+which is the same substitution the model makes when a single word is banned.++Pair with `slop-gate` for the universal tells and `no-ai-slop` for the structural ones+a regular expression cannot see.diff --git a/skills/voice-baseline/scripts/census.py b/skills/voice-baseline/scripts/census.pynew file mode 100755index 0000000..35334fd--- /dev/null+++ b/skills/voice-baseline/scripts/census.py@@ -0,0 +1,183 @@+#!/usr/bin/env python3+"""voice-baseline: measure your own corpus so an agent stops amplifying your tics.++Usage+-----+ python3 census.py CORPUS_DIR [--ext .md] [--out voice-baseline.md]+ python3 census.py CORPUS_DIR --check DRAFT.md++An agent writing in your voice samples the median of *you*: it regresses toward the+words and sentence shapes that appear most in the corpus it has seen. A word that was+a choice at one use reads as a tic at five. This measures which ones you actually+over-use, so the watchlist is yours and not a generic ban list.++Two modes:+ (default) census -- walk the corpus, write a baseline file+ --check DRAFT -- compare one draft against the corpus rate, flag what is above it+"""+import argparse+import os+import re+import sys+from collections import Counter++# Words an agent reaches for as praise or emphasis. Counted, never banned: the census+# says which ones YOUR corpus over-uses. Add your own.+WATCH = [+ "actually", "just", "simply", "really", "quite", "very", "genuinely", "honestly",+ "quietly", "clean", "plain", "simple", "cheap", "small", "elegant", "powerful",+ "robust", "seamless", "leverage", "delve", "ship", "shipped", "earn", "earns",+ "the whole", "the real", "here's", "at the end of the day", "load-bearing",+]++# "The <noun> <past-tense verb> <short predicate>." parked at the end of a paragraph,+# where it lands like a verdict instead of carrying a fact.+VERDICT = re.compile(+ r"(?:^|\. )The [a-z][a-z-]{2,14} (?:was|were|is|are|went|took|did|does|fell|lives|sits|stays|goes|came|holds|catches|kills|works|stops|moves|breaks)\b[^.\n]{0,40}\.\s*$",+ re.M)+KICKER = re.compile(r"\bThat (?:is|was|'s) (?:the|all|it|what|why)\b[^.\n]{0,40}\.", re.I)+HEADING = re.compile(r"^\s*#{1,6}\s+(.+?)\s*$", re.M)+SENTENCE = re.compile(r"[.!?](?:\s|$)")+OPENER = re.compile(r"(?:^|\. )([A-Z][a-z]+) ", re.M)+FRONTMATTER = re.compile(r"\A---\n.*?\n---\n", re.S)+CODE = re.compile(r"^```.*?^```", re.M | re.S)+++def load(path):+ text = open(path, encoding="utf-8", errors="ignore").read()+ text = FRONTMATTER.sub("", text)+ return CODE.sub(" ", text)+++def count_phrase(text, phrase):+ if " " in phrase or "'" in phrase:+ return len(re.findall(re.escape(phrase), text, re.I))+ return len(re.findall(r"\b%s\b" % re.escape(phrase), text, re.I))+++def census(paths):+ words = Counter()+ docs = Counter()+ sentences = verdicts = kickers = 0+ openers = Counter()+ headings = Counter()+ closers = {"question": 0, "kicker": 0}+ for p in paths:+ t = load(p)+ sentences += len(SENTENCE.findall(t))+ verdicts += len(VERDICT.findall(t))+ k = len(KICKER.findall(t))+ kickers += k+ for m in OPENER.finditer(t):+ openers[m.group(1)] += 1+ for h in HEADING.findall(t):+ first = h.split()[0] if h.split() else ""+ headings[first] += 1+ body = [ln for ln in t.strip().splitlines() if ln.strip()]+ if body:+ last = body[-1]+ if last.rstrip().endswith("?"):+ closers["question"] += 1+ if KICKER.search(last):+ closers["kicker"] += 1+ for w in WATCH:+ n = count_phrase(t, w)+ if n:+ words[w] += n+ docs[w] += 1+ return {"files": len(paths), "sentences": sentences, "words": words, "docs": docs,+ "verdicts": verdicts, "kickers": kickers, "openers": openers,+ "headings": headings, "closers": closers}+++def render(c, corpus):+ n = max(c["files"], 1)+ lines = ["# Voice baseline", "",+ "Measured from %d files in `%s`, about %d sentences." % (c["files"], corpus, c["sentences"]),+ "Counted, not banned. A word above its baseline in a new draft is a tic to check, not an error.",+ "", "## Words", "", "| Word or phrase | Uses | Files | Per file |", "|---|---|---|---|"]+ for w, total in c["words"].most_common():+ lines.append("| %s | %d | %d | %.1f |" % (w, total, c["docs"][w], total / n))+ lines += ["", "## Sentence shapes", "",+ "| Shape | Count | Share |", "|---|---|---|",+ "| Paragraph-ending verdict (\"The X was one line.\") | %d | %.1f%% of sentences |"+ % (c["verdicts"], 100.0 * c["verdicts"] / max(c["sentences"], 1)),+ "| \"That is the point\" kicker | %d | %.1f per file |" % (c["kickers"], c["kickers"] / n),+ "| Files ending on a question to the reader | %d | %.0f%% of files |"+ % (c["closers"]["question"], 100.0 * c["closers"]["question"] / n),+ "| Files ending on a kicker | %d | %.0f%% of files |"+ % (c["closers"]["kicker"], 100.0 * c["closers"]["kicker"] / n), ""]+ lines += ["## Sentence openers", "", "| Opener | Count |", "|---|---|"]+ for w, total in c["openers"].most_common(8):+ lines.append("| %s | %d |" % (w, total))+ lines += ["", "## Heading first words", "", "| First word | Headings |", "|---|---|"]+ for w, total in c["headings"].most_common(8):+ lines.append("| %s | %d |" % (w, total))+ lines += ["", "## How to use this", "",+ "1. Before publishing, run `census.py CORPUS --check DRAFT` and read what sits above the per-file rate.",+ "2. For each flagged word, decide: does the sentence need it, or is it decoration? Remove the adjective; if the reader would do nothing differently, it was decoration.",+ "3. Cap the shapes. One paragraph-ending verdict per piece at most, and only when it carries a fact. No kicker closers. Do not end on a question by default.",+ "4. Re-run the census after ten new pieces. A tic you fixed should fall; a new one will have appeared.", ""]+ return "\n".join(lines)+++def check(c, draft):+ n = max(c["files"], 1)+ t = load(draft)+ sentences = max(len(SENTENCE.findall(t)), 1)+ print("%s: %d sentences" % (draft, sentences))+ flagged = 0+ for w, total in c["words"].most_common():+ rate = total / n+ here = count_phrase(t, w)+ if here and here > max(rate, 1):+ flagged += 1+ print(" ABOVE BASELINE %-18s %d uses here vs %.1f per file in the corpus" % (w, here, rate))+ v = len(VERDICT.findall(t))+ if v > 1:+ print(" SHAPE %d paragraph-ending verdict sentences (cap: 1)" % v)+ flagged += 1+ k = len(KICKER.findall(t))+ if k:+ print(" SHAPE %d \"That is the point\" kicker(s) (cap: 0)" % k)+ flagged += 1+ body = [ln for ln in t.strip().splitlines() if ln.strip()]+ if body and body[-1].rstrip().endswith("?"):+ print(" SHAPE ends on a question to the reader")+ flagged += 1+ if not flagged:+ print(" nothing above baseline")+ return 1 if flagged else 0+++def main():+ ap = argparse.ArgumentParser(description="Measure a writing corpus for over-used words and shapes.")+ ap.add_argument("corpus", help="directory of your own writing")+ ap.add_argument("--ext", default=".md", help="file extension to include (default .md)")+ ap.add_argument("--out", default="", help="write the baseline to this file instead of stdout")+ ap.add_argument("--check", default="", help="compare one draft against the corpus rate")+ a = ap.parse_args()++ paths = []+ for root, _, files in os.walk(a.corpus):+ for f in files:+ if f.endswith(a.ext):+ paths.append(os.path.join(root, f))+ if not paths:+ print("no %s files under %s" % (a.ext, a.corpus), file=sys.stderr)+ return 2++ c = census(sorted(paths))+ if a.check:+ return check(c, a.check)+ out = render(c, a.corpus)+ if a.out:+ open(a.out, "w", encoding="utf-8").write(out)+ print("wrote %s (%d files, %d sentences)" % (a.out, c["files"], c["sentences"]))+ else:+ print(out)+ return 0+++if __name__ == "__main__":+ sys.exit(main())