docs: Frame review vs audit distinctively and prune negations

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: MinecraftFuns

AGENTS.md

@@ -278,15 +278,15 @@ implements the core eight, each through its own lens:
 | design | Plan before code exists |
 | build | Write new code |
 | refactor | Rewrite existing code, behavior preserved |
-| review | Findings on a diff or file set |
-| audit | Ranked ledger over a repository or module |
+| review | Judge a change: total over the diff, sound areas named |
+| audit | Judge a codebase: sampled by blast radius, unexamined areas named |
 | test | Derive checks from the lens's own laws |
 | teach | Explain a judgment, calibrated to audience |
 | help | Quick-reference card |
 
 Laws:
 
-* `build` and `refactor` apply changes; every other verb edits nothing.
+* `build` and `refactor` apply changes; every other verb is read-only.
 * Same verb, same contract in every persona; only the lens differs.
 * A read-only verb names what is outside its lens and routes it to the
   sibling persona's same verb in slash form.
@@ -295,8 +295,9 @@ Laws:
 * One verb file per invocation, registered under the verb's name.
 
 Beyond the core the namespace is free (`ponytail` carries `debt` and
-`gain`): never give a core verb name different semantics, and never reuse
-another skill's verb name for a different thing. Levels are optional per
+`gain`), and a verb name keeps one meaning across the library: core names
+keep the table's semantics, and a name another skill already uses keeps
+that skill's meaning. Levels are optional per
 persona; where present they are `lite | full | ultra` meaning advise /
 enforce (default) / maximalist, persist until changed, and stay orthogonal
 to verbs.

pl-theorist/SKILL.md

@@ -91,8 +91,8 @@ exists.
 | design | Plan, model, or architect a domain before code exists |
 | build | Write or implement new code |
 | refactor | Rewrite existing code, behavior preserved (default) |
-| review | Read-only findings on a diff, PR, or file set |
-| audit | Ranked sweep of a repository or module |
+| review | Judge a change: read-only findings on a diff, PR, or file set |
+| audit | Judge a codebase: ranked, sampled sweep of a repository or module |
 | test | Derive tests from the code's algebra and laws |
 | teach | Explain a design in PL terms, calibrated to audience |
 | help | Quick-reference card of verbs and languages |

pl-theorist/references/verbs/audit.md

@@ -1,8 +1,9 @@
 # Verb: audit
 
-Whole-repository or module-level sweep through the PL lens, producing a ranked
-ledger of modeling and cost debt. `review` judges a diff; `audit` judges a
-codebase. Read-only. Over-engineering and bloat route to `/ponytail audit`.
+Judge a codebase: whole-repository or module-level sweep through the PL
+lens, producing a ranked ledger of modeling and cost debt. `review` is total
+over a diff and gates a decision; `audit` samples by blast radius and ranks
+a backlog. Read-only. Over-engineering and bloat route to `/ponytail audit`.
 
 ## Pipeline
 
@@ -29,7 +30,7 @@ repo-scale categories only an audit can see:
 | Capability sprawl | Scripts and workflows holding broader permissions or secrets than their effects require |
 
 Sample honestly: if scope forces sampling, choose by blast radius and name
-every area not examined.
+every unexamined area.
 
 ### 3. Rank
 
@@ -43,16 +44,16 @@ A ledger table, ranked:
 
 `| # | location | category | finding | suggested shape | effort (S/M/L) |`
 
-Then: at most five lines summarizing systemic themes, the single highest-value
-fix, and the areas not examined. No edits; fixing proceeds through `refactor`
-or `build` invocations per ledger row.
+Then: at most five lines summarizing systemic themes, the single
+highest-value fix, and the unexamined areas. Fixing proceeds through
+`refactor` or `build` invocations per ledger row.
 
 ## Completion Checks
 
 <verb_checklist>
-  <item>No file was modified.</item>
+  <item>The working tree is untouched.</item>
   <item>Hot paths and trust boundaries were examined before peripheral code.</item>
   <item>Both diff-scale and repo-scale categories were swept.</item>
   <item>Unexamined areas are named explicitly.</item>
-  <item>Ranking reflects severity times reach, not discovery order.</item>
+  <item>Ranking reflects severity times reach.</item>
 </verb_checklist>

pl-theorist/references/verbs/review.md

@@ -1,8 +1,9 @@
 # Verb: review
 
-Read-only PL-lens review of a diff, PR, or file set. Produce ranked findings;
-change nothing. This lens hunts unsound domain modeling and unsound cost, not
-bloat; route over-engineering findings to `/ponytail review`.
+Judge a change: read-only PL-lens review of a diff, PR, or file set,
+total over its scope. This lens hunts unsound
+domain modeling and unsound cost; over-engineering findings route to
+`/ponytail review`.
 
 ## Pipeline
 
@@ -30,9 +31,9 @@ Sweep the scope once per category, citing file and line for each hit:
 ### 3. Verify before reporting
 
 Re-derive each candidate finding against the loaded profile's cost model and
-the repository's conventions. An imperative loop is not a finding when it is
-the honest backend; a missing `Result` is not a finding when the repository's
-error channel is exceptions. Drop what does not survive.
+the repository's conventions. An imperative loop that is the honest backend
+is sound; a missing `Result` where the repository's error channel is
+exceptions is sound. Report only what survives.
 
 ## Output Contract
 
@@ -41,14 +42,14 @@ Ranked findings, most severe first, one line each:
 `<file:line> - <category> - <violated law or bound> - <minimal fix shape>`
 
 After the list: at most three lines naming what was checked and found sound
-(so silence is distinguishable from omission). No edits, no patches beyond
-one-line fix shapes, unless the user explicitly asks to apply fixes - then
-switch to the `refactor` verb per finding.
+(so silence is distinguishable from omission). Findings and one-line fix
+shapes are the whole deliverable; when the user asks to apply fixes, switch
+to the `refactor` verb per finding.
 
 ## Completion Checks
 
 <verb_checklist>
-  <item>No file was modified.</item>
+  <item>The working tree is untouched.</item>
   <item>Every category was swept over the full scope or the skipped remainder is named.</item>
   <item>Every finding survived the cost-model and convention check.</item>
   <item>Findings are ranked by severity with file:line anchors.</item>

ponytail/SKILL.md

@@ -117,8 +117,8 @@ level - and loads nothing. Do not load reference files otherwise.
 | --- | --- |
 | design | YAGNI kill list before code: what not to build, and the rung each survivor sits on. |
 | refactor | Apply the cuts to existing code, behavior preserved: the shortest diff that simplifies. |
-| review | Over-engineering-only diff review: one line per finding, what to cut, what replaces it. |
-| audit | Whole-repo over-engineering audit: ranked list of what to delete, simplify, or replace. |
+| review | Judge a diff for smuggled complexity: one line per finding, what to cut, what replaces it. |
+| audit | Judge the repo's standing complexity: ranked list of what to delete, simplify, or replace. |
 | test | Derive the one minimal runnable check that fails if the logic breaks. |
 | teach | Explain a ladder decision to a named audience. |
 | debt | Harvest `ponytail:` shortcut comments into a tracked debt ledger. |

ponytail/references/audit.md

@@ -1,7 +1,8 @@
-# Ponytail Audit Mode
+# Ponytail Audit Verb
 
-The review verb, repo-wide. Scan the whole tree instead of a diff. Rank findings
-biggest cut first.
+Judge the codebase: scan the whole tree for standing complexity. `review`
+guards what a change brings in; `audit` ranks what already stands, biggest
+cut first.
 
 ## Tags
 
@@ -25,8 +26,7 @@ Nothing to cut: `Lean already. Ship.`
 
 ## Boundaries
 
-Scope: over-engineering and complexity only. Correctness bugs, security
-holes, and performance are explicitly out of scope - route them to
-`/pl-theorist audit`. A single smoke test or `assert`-based self-check is
-the ponytail minimum, not bloat; never flag it for deletion. Lists
-findings, applies nothing; applying the cuts is `/ponytail refactor`.
+Scope: over-engineering and complexity only; correctness bugs, security
+holes, and performance route to `/pl-theorist audit`. A single smoke test
+or `assert`-based self-check is the ponytail minimum and stays. Lists
+findings; applying the cuts is `/ponytail refactor`.

ponytail/references/debt.md

@@ -1,4 +1,4 @@
-# Ponytail Debt Mode
+# Ponytail Debt Verb
 
 Every deliberate ponytail shortcut is marked with a `ponytail:` comment
 naming its ceiling and upgrade path. This verb collects them into one ledger

ponytail/references/gain.md

@@ -1,4 +1,4 @@
-# Ponytail Gain Mode
+# Ponytail Gain Verb
 
 Display this scoreboard when invoked. One-shot: do NOT change level, write
 files, or persist anything.

ponytail/references/help.md

@@ -1,4 +1,4 @@
-# Ponytail Help Mode
+# Ponytail Help Verb
 
 Display this reference card when invoked. One-shot: do NOT change level,
 write files, or persist anything.

ponytail/references/review.md

@@ -1,8 +1,8 @@
-# Ponytail Review Mode
+# Ponytail Review Verb
 
-Review the diff for unnecessary complexity - nothing else. One line per
-finding: location, what to cut, what replaces it. The diff's best outcome is
-getting shorter.
+Judge the diff for smuggled complexity, and only that. One line per
+finding: location, what to cut, what replaces it. The diff's best outcome
+is getting shorter.
 
 ## Format
 
@@ -35,8 +35,7 @@ Nothing to cut: say `Lean already. Ship.` and stop.
 
 ## Boundaries
 
-Scope: over-engineering and complexity only. Correctness bugs, security
-holes, and performance are explicitly out of scope - route them to
-`/pl-theorist review`, not this pass. A single smoke test or `assert`-based
-self-check is the ponytail minimum, not bloat; never flag it for deletion.
-Lists findings, applies nothing; applying the cuts is `/ponytail refactor`.
+Scope: over-engineering and complexity only; correctness bugs, security
+holes, and performance route to `/pl-theorist review`. A single smoke test
+or `assert`-based self-check is the ponytail minimum and stays. Lists
+findings; applying the cuts is `/ponytail refactor`.