pi-warden 0.3.0 → 0.4.0

package/README.md

@@ -15,7 +15,7 @@ Three jobs, in order of maturity:
 | Pillar | What it means | Status |
 | --- | --- | --- |
 | **Security** | Irreversible or off-task actions are held with a reason the agent can act on; credential files, force pushes, destructive SQL, and remote-script execution are caught offline; secrets are redacted before anything leaves the machine. Next: injected instructions inside tool output (web pages, issues, files) flagged and quarantined; insecure patterns in written code steered. | built · extending |
-| **Deslopify** | Stubs, placeholders, filler, and restating comments in written code earn a scored nudge; the agent fixes them on the next turn. Next: per-symptom scores instead of one quality number, and wordy or AI-flavoured replies scored against an audience setting. | built for code · prose planned |
+| **Deslopify** | Written code is scored per symptom — stubs, restating comments, dead code, hedging — and the agent gets a nudge naming the symptom and its fix; repeats become a standing rule. Replies are scored for wordiness, assistant clichés, and jargon against an `audience` setting, and a trend across replies shapes the next one. | built |
 | **Context saving** | Jev judges which tool outputs are worth keeping; code compresses them. Only at moments that cannot cost a prompt-cache miss: when an output arrives (before it enters the cache), when the cache is measurably cold, or when Pi compacts anyway. Works alongside prompt-cache optimizers because it never touches the system prompt or a warm prefix. | planned |
 
 ## Why a coding agent needs this
@@ -26,7 +26,7 @@ Agents are good at picking the next command and bad at noticing when that comman
 - **Scope drift gets flagged.** Poems in a bugfix, refactors nobody asked for, dependency installs unrelated to the task: warned to you at 0.6, held at 0.85 when Jev also calls the action `unrelated`.
 - **Loops get broken.** Three failures with the same strategy (same command with cosmetic changes, same error after each edit) earn the agent a steer: re-read the error, form a new hypothesis, or report the blocker. Exact repeats are caught offline; Jev tells "investigating between failures" from "flailing" — 0.32 vs 0.93 in the smoke run.
 - **"Done" gets checked.** When the final message reports completion after file changes and no test, build, or lint passed in that run, the agent is asked to verify before you read a false "all green". A claim that tests passed when none ran is called out as such. Once per prompt, so it cannot loop.
-- **Slop gets a note.** Stub functions, `TODO: implement later`, mocks returning fake data, filler comments: scored on the same request as the action guard (zero extra latency) and steered back to the agent after the write, never held.
+- **Slop gets a name.** Written code is scored per symptom on the same request as the action guard (zero extra latency): stubs and fake-data mocks, comments that restate the code, dead or duplicated code, hedging notes. The agent is told which symptom and how to fix it, never held; the third repeat in a session becomes a standing rule. Replies are scored too — wordy, clichéd, or too technical for the configured audience — and a trend across replies earns a nudge that shapes the next one without spending a turn.
 - **Nothing slows down the boring calls.** Read-only shell lines are skipped without a request; anything else costs one request of ~600 input tokens.
 - **It degrades gracefully.** Offline pattern checks and exact-repeat detection run with no account at all. On an API timeout or outage the call is allowed with a warning (configurable), and reasons never include your command text or upstream error bodies.
 
@@ -68,15 +68,23 @@ Keeps the last 12 tool results for the current prompt. When the latest result fa
 
 Tracks each run's evidence: code changes (`write`, `edit`) and check commands (`npm test`, `pytest`, `cargo test`, `tsc`, `eslint`, `go test`, `make test`, and similar, whether run through `bash` or `ctx_execute`) with pass/fail; context-mode's inline `Command exited with code N` counts as a failure. When a run ends with a normal assistant message after code changes and no passing check, one Jev request judges the message: `claims_done`, `claims_verified`, `verification_applies` (Noul), `outcome` (Choice: complete / partial / blocked / other). A completion claim ≥ 0.7 that is not a blocker or question, for a task where checks would mean something (≥ 0.5; prose and file housekeeping score ~0.05), is reported as unverified; a verification claim with no check run is reported as a false claim. With `nudge: true` (default) the agent receives one follow-up turn asking it to run the checks or say plainly that nothing was verified — once per user prompt.
 
-### Slop (`write`/`edit`, same request as the action guard)
+### Slop in code (`write`/`edit`, same request as the action guard)
 
 pi-warden cannot rewrite code — Jev only judges — so slop is handled as a feedback loop through the agent:
 
-1. When the agent calls `write` or `edit`, two questions ride on the action guard's request (no extra latency): `slop_quality`, a Score over three described levels — *focused* (does what the task needs, comments only where they add information) / *some filler* (comments restating the code, minor dead code, hedging) / *sloppy* (stub or placeholder code, TODO where a working implementation is needed, duplicated or commented-out logic, vague text) — and `slop_placeholder`, a Noul: does the content leave placeholder, stub, mock, or "implement later" code where `task` needs a working implementation? Jev sees the first 1500 characters of a `write` or the first three replacement texts of an `edit`, plus your request, so "needed" is judged against what you asked for.
-2. Quality ≥ 1.5 or placeholder ≥ 0.7 (config `slop`) trips the note. Below that, nothing happens.
-3. The write **goes through** — holding it would leave a half-written file. Instead the agent receives a steer message before its next LLM call: *"pi-warden: the content just written to `src/x.ts` reads as quality 1.90/2 (filler or sloppy) and placeholder or stub code 0.92. Replace stubs and placeholders with working code, remove comments that restate the code, and keep only what the request needs. If something is intentionally left unimplemented, say so in your reply instead of leaving it in the code."* The agent fixes the file on its next turn; you see a notification and `slop 1.9/2 · stub 0.92` in the widget.
+1. When the agent calls `write` or `edit`, four Noul questions ride on the action guard's request (no extra latency), one per symptom, each with concrete yes/no criteria: `slop_stub` (placeholder, mock, or "implement later" code where `task` needs a working implementation), `slop_comments` (explanatory comments that restate what the adjacent code shows), `slop_dead` (commented-out code, unused imports or variables, duplicated logic, unreachable branches), `slop_hedging` ("should work", "for now", TODOs without a plan). Jev sees a head/middle/tail sample of a `write` (1500 characters) or the first three replacement texts of an `edit`, plus your request.
+2. Any symptom ≥ `slop.threshold` (0.7) trips the note. The write **goes through** — holding it would leave a half-written file.
+3. The agent receives a steer message naming the symptoms and their fixes, e.g. *"pi-warden: the content just written to `src/x.ts` has stub or placeholder code where a working implementation is needed; hedging or vague notes. Fix it in your next edit: replace stubs, placeholders, and hard-coded fake data with the working implementation, or state in your reply exactly what is left unimplemented and why; replace \"should work\", \"for now\", and TODOs without a plan with a definite statement or a concrete follow-up."* The third time a symptom appears in a session, the note says so and asks the agent to treat it as a standing rule.
 
-From the live smoke: a `// TODO: implement later` stub scored quality 2.00 / placeholder 0.99, a mock returning fake user data 2.00 / 0.98, a focused implementation 0.00 / 0.02, and a function with only restating comments 0.87 / 0.02 — deliberately below the threshold, because the guard is for stubs and filler that change behaviour, not for style. Not covered: code written through bash heredocs, content past the excerpt limits, and the agent's prose replies.
+Per-symptom scoring is what makes this precise. From the tuning set (`scripts/slop-cases.mjs`, 16 code cases): a `// TODO: implement later` stub scores stub 0.99; restating comments score comments 0.97 while an explanatory why-comment scores 0.08; commented-out code scores dead 0.96 and comments 0.43; a mock inside a *test file* scores stub 0.51 (below threshold, correctly); a stub explicitly outside the task scores 0.24. Not covered: code written through shell heredocs and content past the sample limits.
+
+### Slop in replies (`agent_end`)
+
+The run's final reply (≥ 200 characters) is judged against `slop.prose.audience`: `wordy` (preamble, restating the request, closing summary, filler), `cliches` ("Great question", "I hope this helps", "it's worth noting", unrequested caveat lists, emoji headings), `jargon` (unexplained terms for the audience). `audience` is `technical` (default), `plain`, or any free-text description such as *"a founder without programming background"*. One long answer to a long question is not punished: a symptom must appear in `trend` (2) of the last 3 replies before the agent is nudged, the nudge is queued for the next user prompt so it shapes the next reply without spending a turn, and two replies pass before the same nudge can fire again. From the tuning set: a padded reply scores wordy 0.97 / clichés 0.99; a dense three-point summary 0.25 / 0.05; the same status update scores jargon 0.94 for a plain audience and 0.24 for a developer.
+
+### Steer messages
+
+Nudges from the stuck, done, slop, and prose guards are custom messages in the agent's context. By default they are **hidden from the transcript** (`steerVisible: false`) so the conversation stays yours; the notification tells you a nudge happened and the trace panel shows the exact text. Set `steerVisible: true` to see them inline.
 
 If TypeSafe cannot answer (timeout after 5 s, outage, budget), an action-guard call is allowed with a warning (`failOpen: true`; set it to `false` to hold instead), and the other guards simply skip. When the per-session request budget is spent, pi-warden says so once and continues with offline checks. Consent in headless runs comes from `PI_WARDEN_ENABLED=1`; `PI_WARDEN_MODE` overrides the mode.
 
@@ -103,13 +111,14 @@ Templates in `config.widget` control the text. Segments are separated by ` · `;
   "enabled": true,
   "placement": "aboveEditor",
   "shortcut": "ctrl+shift+w",
-  "action": "warden · {tool} · irreversible {irreversible} · off-task {offTask} · {scope} · slop {slopQuality} · stub {slopStub} · patterns: {patterns} · {flags} · {level}",
+  "action": "warden · {tool} · irreversible {irreversible} · off-task {offTask} · {scope} · slop: {slop} · patterns: {patterns} · {flags} · {level}",
   "stuck": "warden · stuck · {failures} failures · same strategy {sameStrategy} · change {approachChange} · progress {progress} · {flags} · {status}",
-  "done": "warden · done-check · {changes} changes · {checksPassed}/{checks} checks passed · claims done {claimsDone} · claims verified {claimsVerified} · checks apply {checksApply} · {outcome} · {status}"
+  "done": "warden · done-check · {changes} changes · {checksPassed}/{checks} checks passed · claims done {claimsDone} · claims verified {claimsVerified} · checks apply {checksApply} · {outcome} · {status}",
+  "prose": "warden · prose · wordy {wordy} · clichés {cliches} · jargon {jargon} · {flags} · {status}"
 }
 ```
 
-Tokens — action: `tool level source irreversible offTask scope approved slopQuality slopStub patterns reasons path model ms flags time`; stuck: `failures sameStrategy approachChange progress status source reasons model ms flags time`; done: `changes checks checksPassed claimsDone claimsVerified checksApply outcome status reasons model ms flags time`. A minimal line: `"action": "⚔ {tool} {level} · {irreversible}/{offTask}"`. Set `"enabled": false` to hide the line (the trace and panel keep working); `"shortcut": ""` disables the keybinding.
+Tokens — action: `tool level source irreversible offTask scope approved slop slopStub slopComments slopDead slopHedging patterns reasons path model ms flags time`; prose: `wordy cliches jargon status reasons model ms flags time`; stuck: `failures sameStrategy approachChange progress status source reasons model ms flags time`; done: `changes checks checksPassed claimsDone claimsVerified checksApply outcome status reasons model ms flags time`. A minimal line: `"action": "⚔ {tool} {level} · {irreversible}/{offTask}"`. Set `"enabled": false` to hide the line (the trace and panel keep working); `"shortcut": ""` disables the keybinding.
 
 ## Configuration
 
@@ -131,8 +140,13 @@ User file `~/.pi/agent/pi-warden/config.json` (owner-only). Missing keys use the
   },
   "stuck": { "enabled": true, "window": 12, "minFailures": 3, "cooldown": 3, "sameStrategy": 0.7, "nudge": true },
   "done": { "enabled": true, "claimsDone": 0.7, "nudge": true },
-  "slop": { "enabled": true, "quality": 1.5, "placeholder": 0.7 },
-  "widget": { "enabled": true, "placement": "aboveEditor", "shortcut": "ctrl+shift+w" }
+  "slop": {
+    "enabled": true,
+    "threshold": 0.7,
+    "prose": { "enabled": true, "audience": "technical", "threshold": 0.7, "trend": 2, "minChars": 200 }
+  },
+  "widget": { "enabled": true, "placement": "aboveEditor", "shortcut": "ctrl+shift+w" },
+  "steerVisible": false
 }
 ```
 
@@ -140,7 +154,7 @@ A project may add `.pi/pi-warden.json` with `enabled` and per-guard overrides (f
 
 ## Data handling
 
-- With consent, each guarded call sends to `https://api.typesafe.ai`: your latest prompt (truncated to 1500 characters), the tool name, the command (truncated to 2000 characters) or the file path (relative inside the project, `~`-shortened outside), whether the file exists, a 1500-character content excerpt for `write`, and the first three edit pairs (400 characters each) for `edit`. The stuck detector sends the last 12 tool calls (300 characters each) with 400-character output tails; the done-check sends the agent's final message (2000 characters) and the run's check commands. No other files, history, or telemetry.
+- With consent, each guarded call sends to `https://api.typesafe.ai`: your latest prompt (truncated to 1500 characters), the tool name, the command (truncated to 2000 characters) or the file path (relative inside the project, `~`-shortened outside), whether the file exists, a 1500-character head/middle/tail sample for `write`, and the first three edit pairs (400 characters each) for `edit`. The stuck detector sends the last 12 tool calls (300 characters each) with 400-character output tails; the done-check and the prose check send the agent's final message (2000 and 2500 characters) with the run's check commands and the audience description. No other files, history, or telemetry.
 - Obvious credentials in the action (`Authorization` headers, `TOKEN=`/`SECRET=` assignments, `sk-`, `ghp_`, `AKIA`, JWTs, URL passwords, PEM blocks) are replaced with `[redacted]` before sending. This is best-effort; do not rely on it for prompts that contain secrets.
 - Text returned or steered to the agent names the tool, the reasons, and the scores, not the command text. UI errors never include upstream response bodies or keys.
 - Judgments are model output. Thresholds are yours to tune; a hold is information for the agent and for you, not a verdict on either.
@@ -170,8 +184,9 @@ Also exported: `matchPatterns`, `isReadOnlyCommand`, `describeAction`, `redact`,
 ```bash
 npm install
 npm run check        # typecheck, offline tests (mocked transport), build
-npm run test:live    # 28 billable synthetic judgments across all guards (key from .env or the stored login); pass action|slop|approval|stuck|done for one group
+npm run test:live    # 31 billable synthetic judgments across all guards (key from .env or the stored login); pass action|slop|approval|stuck|done for one group
 npm run dev:pi       # start Pi with this working tree plus an installed pi-typesafe
+node scripts/slop-cases.mjs   # 22 billable cases that tune the slop and prose questions
 npm run preview      # re-render docs/preview.png from the recorded live verdicts (needs a Chrome binary)
 ```
 

package/dist/config.d.ts

@@ -36,12 +36,22 @@ export interface DoneGuardConfig {
     /** Also send the agent a follow-up asking it to verify. Triggers one more LLM turn. */
     nudge: boolean;
 }
+export interface ProseConfig {
+    enabled: boolean;
+    /** Who reads the agent's replies: "technical", "plain", or a free-text description. Drives the jargon question. */
+    audience: string;
+    /** P(symptom) at or above this counts as a hit. */
+    threshold: number;
+    /** A symptom must hit in this many of the last three replies before the agent is nudged. */
+    trend: number;
+    /** Replies with fewer characters are not judged. */
+    minChars: number;
+}
 export interface SlopGuardConfig {
     enabled: boolean;
-    /** Score (0 focused … 2 sloppy) at or above this warns. */
-    quality: number;
-    /** P(placeholder or stub code) at or above this warns. */
-    placeholder: number;
+    /** P(symptom) at or above this is reported for written code: stub, comments, dead, hedging. */
+    threshold: number;
+    prose: ProseConfig;
 }
 export type WardenMode = "steer" | "confirm" | "advise";
 export interface WardenConfig {
@@ -65,6 +75,8 @@ export interface WardenConfig {
     slop: SlopGuardConfig;
     /** The status line above the editor and the trace panel. */
     widget: WidgetConfig;
+    /** Show steer messages in the transcript. They are always visible in the trace panel. */
+    steerVisible: boolean;
 }
 export declare const PACKAGE_NAME = "pi-warden";
 export declare const PROJECT_CONFIG_FILE = "pi-warden.json";

package/dist/config.js

@@ -22,8 +22,9 @@ export function defaultConfig() {
         },
         stuck: { enabled: true, window: 12, minFailures: 3, cooldown: 3, sameStrategy: 0.7, nudge: true },
         done: { enabled: true, claimsDone: 0.7, nudge: true },
-        slop: { enabled: true, quality: 1.5, placeholder: 0.7 },
+        slop: { enabled: true, threshold: 0.7, prose: { enabled: true, audience: "technical", threshold: 0.7, trend: 2, minChars: 200 } },
         widget: defaultWidgetConfig(),
+        steerVisible: false,
     };
 }
 /** Mirrors Pi's agent directory rule so the file sits next to pi-typesafe's auth.json. */
@@ -68,9 +69,6 @@ function positiveInteger(value, fallback) {
 export function isMode(value) {
     return value === "steer" || value === "confirm" || value === "advise";
 }
-function score(value, fallback) {
-    return typeof value === "number" && Number.isFinite(value) && value >= 0 && value <= 2 ? value : fallback;
-}
 function applyAction(base, raw, timeoutMs) {
     const withTimeout = { ...base, timeoutMs };
     if (!isObject(raw))
@@ -103,10 +101,22 @@ function applyDone(base, raw) {
         return base;
     return { enabled: boolean(raw.enabled, base.enabled), claimsDone: probability(raw.claimsDone, base.claimsDone), nudge: boolean(raw.nudge, base.nudge) };
 }
+function applyProse(base, raw) {
+    if (!isObject(raw))
+        return base;
+    return {
+        enabled: boolean(raw.enabled, base.enabled),
+        audience: typeof raw.audience === "string" && raw.audience.trim() ? raw.audience.trim() : base.audience,
+        threshold: probability(raw.threshold, base.threshold),
+        trend: Math.min(3, positiveInteger(raw.trend, base.trend)),
+        minChars: positiveInteger(raw.minChars, base.minChars),
+    };
+}
 function applySlop(base, raw) {
     if (!isObject(raw))
         return base;
-    return { enabled: boolean(raw.enabled, base.enabled), quality: score(raw.quality, base.quality), placeholder: probability(raw.placeholder, base.placeholder) };
+    // 0.2.x used `placeholder` for the stub threshold; it still sets the shared threshold.
+    return { enabled: boolean(raw.enabled, base.enabled), threshold: probability(raw.threshold ?? raw.placeholder, base.threshold), prose: applyProse(base.prose, raw.prose) };
 }
 function applyWidget(base, raw) {
     if (!isObject(raw))
@@ -119,6 +129,7 @@ function applyWidget(base, raw) {
         action: template(raw.action, base.action),
         stuck: template(raw.stuck, base.stuck),
         done: template(raw.done, base.done),
+        prose: template(raw.prose, base.prose),
     };
 }
 /** Shared request settings; `action.timeoutMs`/`action.maxRequests` from 0.1.x files are still honoured. */
@@ -149,6 +160,7 @@ export function applyUserOverrides(base, raw) {
         ...shared,
         ...applyGuards(base, raw, shared.timeoutMs),
         widget: applyWidget(base.widget, raw.widget),
+        steerVisible: boolean(raw.steerVisible, base.steerVisible),
     };
 }
 /** Project files may tune the guards but cannot grant TypeSafe consent, change the mode, or raise budgets. */

package/dist/extension.d.ts

@@ -1,6 +1,8 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import type { Verdict } from "./guard.js";
+import type { SlopSymptom, Verdict } from "./guard.js";
 export declare const disclosure = "With TypeSafe judgments enabled, pi-warden sends to api.typesafe.ai: your latest request plus a redacted, truncated summary of each guarded bash, write, or edit call before it runs; the last few tool calls and output tails when the agent keeps failing; and the agent's final message when it reports completion without running checks. Requests may incur charges. Secret redaction is best-effort. Results are model judgments, not proof or authorization; offline pattern checks stay active either way.";
 export declare function confirmMessage(verdict: Verdict): string;
+/** Names each symptom and its fix; repeats in the session turn the note into a standing rule. */
+export declare function slopSteer(where: string, symptoms: readonly SlopSymptom[], counts: Record<SlopSymptom, number>): string;
 /** Native Pi registration; importing the root library does not load this module. */
 export default function wardenExtension(pi: ExtensionAPI): void;

package/dist/extension.js

@@ -3,15 +3,16 @@ import { createTypeSafe, resolveApiKey } from "pi-typesafe";
 import { ensureApiKey } from "pi-typesafe/ui";
 import { applyUserOverrides, defaultConfig, isMode, loadConfig, PACKAGE_NAME, projectConfigPath, readUserConfig, setUserSetting, userConfigPath, writeUserConfig } from "./config.js";
 import { classifyToolResult, doneNudge, emptyEvidence, evaluateDone, finalAssistantText, formatDone, needsDoneCheck, recordOutcome } from "./done.js";
-import { evaluateAction, formatVerdict, steerReason, textApproves } from "./guard.js";
+import { evaluateAction, formatVerdict, SLOP_LABELS, steerReason, textApproves } from "./guard.js";
+import { evaluateProse, proseNudge, ProseTrend } from "./prose.js";
 import { AttemptWindow, evaluateStuck, formatStuck, makeAttempt, resultFailed, stuckNudge } from "./stuck.js";
 import { openTracePanel } from "./panel.js";
-import { actionDetails, doneDetails, stuckDetails, Trace } from "./trace.js";
-import { TOKEN_NAMES } from "./widget.js";
+import { actionDetails, doneDetails, proseDetails, stuckDetails, Trace } from "./trace.js";
+import { proseTokens, renderTemplate, TOKEN_NAMES } from "./widget.js";
 export const disclosure = "With TypeSafe judgments enabled, pi-warden sends to api.typesafe.ai: your latest request plus a redacted, truncated summary of each guarded bash, write, or edit call before it runs; the last few tool calls and output tails when the agent keeps failing; and the agent's final message when it reports completion without running checks. Requests may incur charges. Secret redaction is best-effort. Results are model judgments, not proof or authorization; offline pattern checks stay active either way.";
 const WIDGET = PACKAGE_NAME;
 const CONFIRM_TEXT_LIMIT = 500;
-const freshStats = () => ({ inspected: 0, judged: 0, warned: 0, held: 0, approved: 0, slop: 0, stuckChecks: 0, stuck: 0, doneChecks: 0, unverified: 0, errors: 0 });
+const freshStats = () => ({ inspected: 0, judged: 0, warned: 0, held: 0, approved: 0, slop: 0, stuckChecks: 0, stuck: 0, doneChecks: 0, unverified: 0, proseChecks: 0, proseNudges: 0, errors: 0 });
 function latestUserPrompt(ctx) {
     const entries = ctx.sessionManager.getBranch();
     for (let index = entries.length - 1; index >= 0; index--) {
@@ -49,6 +50,19 @@ export function confirmMessage(verdict) {
     return lines.join("\n");
 }
 const callKey = (tool, input) => `${tool}\0${JSON.stringify(input)}`;
+const SLOP_FIXES = {
+    stub: "replace stubs, placeholders, and hard-coded fake data with the working implementation, or state in your reply exactly what is left unimplemented and why",
+    comments: "delete comments that restate the code; keep only those that explain intent, constraints, or non-obvious behaviour",
+    dead: "remove commented-out code, unused imports and variables, duplicated logic, and unreachable branches",
+    hedging: "replace \"should work\", \"for now\", and TODOs without a plan with a definite statement or a concrete follow-up",
+};
+/** Names each symptom and its fix; repeats in the session turn the note into a standing rule. */
+export function slopSteer(where, symptoms, counts) {
+    const named = symptoms.map(symptom => `${SLOP_LABELS[symptom]}${counts[symptom] >= 3 ? ` (${counts[symptom]}th time this session)` : ""}`).join("; ");
+    const fixes = symptoms.map(symptom => SLOP_FIXES[symptom]).join("; ");
+    const standing = symptoms.some(symptom => counts[symptom] >= 3) ? " Treat this as a standing rule for the rest of the session." : "";
+    return `pi-warden: the content just written to ${where} has ${named}. Fix it in your next edit: ${fixes}.${standing}`;
+}
 /** Native Pi registration; importing the root library does not load this module. */
 export default function wardenExtension(pi) {
     let client;
@@ -63,6 +77,8 @@ export default function wardenExtension(pi) {
     let attempts = new AttemptWindow(defaultConfig().stuck.window);
     let evidence = emptyEvidence();
     let doneNudged = false;
+    const prose = new ProseTrend();
+    const slopCounts = { stub: 0, comments: 0, dead: 0, hedging: 0 };
     const configFor = (ctx) => loadConfig({ cwd: ctx.cwd, projectTrusted: ctx.isProjectTrusted() });
     const consentGiven = (config) => config.typesafe || process.env.PI_WARDEN_ENABLED === "1";
     const consentSource = (config) => config.typesafe ? "/warden enable" : process.env.PI_WARDEN_ENABLED === "1" ? "PI_WARDEN_ENABLED" : undefined;
@@ -106,7 +122,7 @@ export default function wardenExtension(pi) {
         trace.push({ at: Date.now(), guard, line, details });
         paint(ctx, config);
     };
-    const steer = (content) => pi.sendMessage({ customType: `${PACKAGE_NAME}-steer`, content, display: true }, { deliverAs: "steer" });
+    const steer = (config, content, options = { deliverAs: "steer" }) => pi.sendMessage({ customType: `${PACKAGE_NAME}-steer`, content, display: config.steerVisible }, options);
     pi.on("session_start", async (_event, ctx) => {
         client = undefined;
         budgetExhausted = false;
@@ -117,6 +133,9 @@ export default function wardenExtension(pi) {
         attempts.reset();
         evidence = emptyEvidence();
         doneNudged = false;
+        prose.reset();
+        for (const symptom of Object.keys(slopCounts))
+            slopCounts[symptom] = 0;
         if (ctx.hasUI)
             ctx.ui.setWidget(WIDGET, undefined);
     });
@@ -160,12 +179,14 @@ export default function wardenExtension(pi) {
         const told = verdict.level === "confirm" && mode === "steer" ? steerReason(verdict, { canApprove: judge !== undefined }) : undefined;
         if (verdict.source !== "read-only")
             record(ctx, config, "action", formatVerdict(verdict, config.widget.action), actionDetails(verdict, { mode, ...(told ? { told } : {}) }));
-        if (verdict.slopReasons?.length) {
+        if (verdict.slopSymptoms?.length && verdict.slopReasons) {
             stats.slop++;
+            for (const symptom of verdict.slopSymptoms)
+                slopCounts[symptom]++;
             const where = verdict.summary.path ?? event.toolName;
             if (ctx.hasUI)
                 ctx.ui.notify(`warden · slop · ${where}: ${verdict.slopReasons.join("; ")}`, "warning");
-            steer(`pi-warden: the content just written to ${where} reads as ${verdict.slopReasons.join(" and ")}. Replace stubs and placeholders with working code, remove comments that restate the code, and keep only what the request needs. If something is intentionally left unimplemented, say so in your reply instead of leaving it in the code.`);
+            steer(config, slopSteer(where, verdict.slopSymptoms, slopCounts));
         }
         if (verdict.level === "warn") {
             stats.warned++;
@@ -221,16 +242,39 @@ export default function wardenExtension(pi) {
         if (ctx.hasUI)
             ctx.ui.notify(`warden · stuck: ${verdict.reasons.join("; ")}${nudge ? " (agent nudged)" : ""}`, "warning");
         if (nudge)
-            steer(nudge);
+            steer(config, nudge);
     });
     pi.on("agent_end", async (event, ctx) => {
         const config = configFor(ctx);
-        if (!config.enabled || !config.done.enabled || doneNudged || !needsDoneCheck(evidence))
+        if (!config.enabled)
             return;
         const finalMessage = finalAssistantText(event.messages);
         const judge = judgeFor(config);
         if (!finalMessage || !judge)
             return;
+        if (config.slop.enabled && config.slop.prose.enabled && finalMessage.length >= config.slop.prose.minChars) {
+            stats.proseChecks++;
+            const verdict = await evaluateProse(latestUserPrompt(ctx), finalMessage, { config: config.slop.prose, judge, timeoutMs: config.timeoutMs, signal: ctx.signal });
+            if (verdict.error)
+                noteError(ctx, verdict.error, undefined);
+            else
+                prose.record(verdict.flagged);
+            const due = verdict.error ? [] : prose.due(config.slop.prose.trend);
+            const nudge = due.length ? proseNudge(due, config.slop.prose.audience, prose.counts) : undefined;
+            if (nudge) {
+                verdict.nudged = true;
+                prose.markNudged();
+                stats.proseNudges++;
+            }
+            record(ctx, config, "prose", renderTemplate(config.widget.prose, proseTokens(verdict)), proseDetails(verdict, finalMessage, config.slop.prose.audience, nudge));
+            if (nudge) {
+                if (ctx.hasUI)
+                    ctx.ui.notify(`warden · prose: ${due.join(", ")} in ${config.slop.prose.trend} of the last 3 replies (agent nudged for the next reply)`, "warning");
+                steer(config, nudge, { deliverAs: "nextTurn" });
+            }
+        }
+        if (!config.done.enabled || doneNudged || !needsDoneCheck(evidence))
+            return;
         stats.doneChecks++;
         const verdict = await evaluateDone(latestUserPrompt(ctx), finalMessage, evidence, { config: config.done, judge, timeoutMs: config.timeoutMs, signal: ctx.signal });
         if (verdict.error)
@@ -244,7 +288,7 @@ export default function wardenExtension(pi) {
             ctx.ui.notify(`warden · done-check: ${verdict.reasons.join("; ")}${nudge ? " (agent asked to verify)" : ""}`, "warning");
         if (nudge) {
             doneNudged = true;
-            pi.sendMessage({ customType: `${PACKAGE_NAME}-steer`, content: nudge, display: true }, { deliverAs: "followUp", triggerTurn: true });
+            steer(config, nudge, { deliverAs: "followUp", triggerTurn: true });
         }
     });
     // Shortcuts are registered once at load; a shape check keeps a typo in the config file from being registered.
@@ -277,11 +321,11 @@ export default function wardenExtension(pi) {
                     const key = resolveApiKey();
                     const source = consentSource(config);
                     const usage = client?.getUsage();
-                    const guards = [config.action.enabled && "action", config.stuck.enabled && "stuck", config.done.enabled && "done-check", config.slop.enabled && "slop"].filter(Boolean).join(", ");
+                    const guards = [config.action.enabled && "action", config.stuck.enabled && "stuck", config.done.enabled && "done-check", config.slop.enabled && "slop", config.slop.enabled && config.slop.prose.enabled && `prose (${config.slop.prose.audience})`].filter(Boolean).join(", ");
                     report([
                         `pi-warden: ${config.enabled ? `guarding ${config.action.tools.join(", ")} (${guards})` : "off"}; mode ${activeMode(config, ctx.hasUI)}; TypeSafe judgments ${source ? `enabled via ${source}` : "disabled (run /warden enable)"}; key ${key ? key.source === "stored" ? "stored (shared with pi-typesafe)" : "from TYPESAFE_API_KEY" : "missing (run /warden enable)"}.`,
-                        `Session: ${stats.inspected} inspected, ${stats.judged} judged, ${stats.warned} warned, ${stats.held} held, ${stats.approved} approved on retry, ${stats.slop} slop notes, ${stats.stuck}/${stats.stuckChecks} stuck, ${stats.unverified}/${stats.doneChecks} unverified done, ${stats.errors} TypeSafe errors; ${usage?.requestsStarted ?? 0}/${config.maxRequests} requests.`,
-                        `Thresholds: irreversible warn ${config.action.irreversible.warn} / hold ${config.action.irreversible.confirm}; off-task warn ${config.action.offTask.warn} / hold ${config.action.offTask.confirm}; stuck same-strategy ${config.stuck.sameStrategy} after ${config.stuck.minFailures} failures; done claims ${config.done.claimsDone}; slop quality ${config.slop.quality}, stub ${config.slop.placeholder}; failOpen ${config.action.failOpen}.`,
+                        `Session: ${stats.inspected} inspected, ${stats.judged} judged, ${stats.warned} warned, ${stats.held} held, ${stats.approved} approved on retry, ${stats.slop} slop notes, ${stats.stuck}/${stats.stuckChecks} stuck, ${stats.unverified}/${stats.doneChecks} unverified done, ${stats.proseNudges}/${stats.proseChecks} prose nudges, ${stats.errors} TypeSafe errors; ${usage?.requestsStarted ?? 0}/${config.maxRequests} requests. Steers are ${config.steerVisible ? "shown in the transcript" : "hidden from the transcript (trace panel shows them)"}.`,
+                        `Thresholds: irreversible warn ${config.action.irreversible.warn} / hold ${config.action.irreversible.confirm}; off-task warn ${config.action.offTask.warn} / hold ${config.action.offTask.confirm}; stuck same-strategy ${config.stuck.sameStrategy} after ${config.stuck.minFailures} failures; done claims ${config.done.claimsDone}; slop ${config.slop.threshold}, prose ${config.slop.prose.threshold} in ${config.slop.prose.trend}/3 replies; failOpen ${config.action.failOpen}.`,
                         `Config: ${userConfigPath()}${ctx.isProjectTrusted() ? ` and ${projectConfigPath(ctx.cwd)}` : ""}.`,
                         widget.size ? `Last: ${[...widget.values()].join(" | ")}` : "No guarded activity yet this session.",
                         `Trace: ${trace.entries().length} events (/warden trace${shortcut ? `, ${shortcut}` : ""}, or click the status line in fullscreen mode). Widget templates in config.widget: action tokens ${TOKEN_NAMES.action.map(name => `{${name}}`).join(" ")}.`,

package/dist/guard.d.ts

@@ -42,12 +42,15 @@ export interface Judgment {
     model: string;
     elapsedMs: number;
 }
+/** One probability per slop symptom; the steer names the symptoms above the threshold. */
 export interface SlopJudgment {
-    /** 0 focused … 2 sloppy. */
-    quality: number;
-    /** P(placeholder or stub where working code is needed). */
-    placeholder: number;
+    stub: number;
+    comments: number;
+    dead: number;
+    hedging: number;
 }
+export type SlopSymptom = keyof SlopJudgment;
+export declare const SLOP_SYMPTOMS: readonly SlopSymptom[];
 export interface Verdict {
     level: Level;
     source: "skipped" | "read-only" | "pattern" | "typesafe" | "error";
@@ -57,7 +60,8 @@ export interface Verdict {
     reasons: string[];
     judgment?: Judgment;
     slop?: SlopJudgment;
-    /** Set when the slop thresholds were crossed; the level itself is never raised by slop. */
+    /** Symptoms at or above the slop threshold, strongest first. The level itself is never raised by slop. */
+    slopSymptoms?: SlopSymptom[];
     slopReasons?: string[];
     /** True when a previously held call was allowed because the user's latest message approves it. */
     approvedByUser?: boolean;
@@ -91,9 +95,12 @@ export declare const questions: {
     }>;
 };
 export declare const slopQuestions: {
-    slop_quality: import("pi-typesafe").ScoreQuestion<readonly ["Focused: does what `task` needs, clear names, comments only where they add information", "Some filler: comments that restate the code, minor dead code, hedging or repeated text", "Sloppy: placeholder or stub code, TODO where a working implementation is needed, duplicated or commented-out logic, vague or contradictory text"]>;
-    slop_placeholder: import("pi-typesafe").NoulQuestion;
+    slop_stub: import("pi-typesafe").NoulQuestion;
+    slop_comments: import("pi-typesafe").NoulQuestion;
+    slop_dead: import("pi-typesafe").NoulQuestion;
+    slop_hedging: import("pi-typesafe").NoulQuestion;
 };
+export declare const SLOP_LABELS: Record<SlopSymptom, string>;
 export declare const approvalQuestion: {
     approved: import("pi-typesafe").NoulQuestion;
 };
@@ -107,8 +114,10 @@ export declare function buildRequest(summary: ActionSummary, task: string | unde
     };
     questions: {
         approved?: import("pi-typesafe").NoulQuestion;
-        slop_quality?: import("pi-typesafe").ScoreQuestion<readonly ["Focused: does what `task` needs, clear names, comments only where they add information", "Some filler: comments that restate the code, minor dead code, hedging or repeated text", "Sloppy: placeholder or stub code, TODO where a working implementation is needed, duplicated or commented-out logic, vague or contradictory text"]>;
-        slop_placeholder?: import("pi-typesafe").NoulQuestion;
+        slop_stub?: import("pi-typesafe").NoulQuestion;
+        slop_comments?: import("pi-typesafe").NoulQuestion;
+        slop_dead?: import("pi-typesafe").NoulQuestion;
+        slop_hedging?: import("pi-typesafe").NoulQuestion;
         irreversible: import("pi-typesafe").NoulQuestion;
         off_task: import("pi-typesafe").NoulQuestion;
         scope: import("pi-typesafe").ChoiceQuestion<{

package/dist/guard.js

@@ -5,6 +5,7 @@ import { choice, noul, score, TypeSafeIntegrationError } from "pi-typesafe";
 import { redact } from "./redact.js";
 import { commandOf } from "./tools.js";
 import { actionTokens, DEFAULT_TEMPLATES, renderTemplate } from "./widget.js";
+export const SLOP_SYMPTOMS = ["stub", "comments", "dead", "hedging"];
 const LEVEL_RANK = { allow: 0, warn: 1, confirm: 2 };
 const higher = (a, b) => (LEVEL_RANK[a] >= LEVEL_RANK[b] ? a : b);
 const TASK_LIMIT = 1500;
@@ -14,6 +15,16 @@ const EDIT_LIMIT = 400;
 function truncate(text, limit) {
     return text.length <= limit ? text : `${text.slice(0, limit)}… [${text.length - limit} more chars]`;
 }
+/** Head, a slice from the middle, and the tail, so stubs at the end of a long file are still seen. */
+function sample(text, limit) {
+    if (text.length <= limit)
+        return text;
+    const head = Math.floor(limit * 0.6);
+    const mid = Math.floor(limit * 0.2);
+    const tail = limit - head - mid;
+    const middleStart = Math.floor(text.length / 2 - mid / 2);
+    return `${text.slice(0, head)}\n… [${middleStart - head} chars] …\n${text.slice(middleStart, middleStart + mid)}\n… [${text.length - tail - (middleStart + mid)} chars] …\n${text.slice(-tail)}`;
+}
 const SHELL_RULES = [
     { id: "git-force-push", severity: "destructive", label: "git force push", test: /\bgit\s+push\b[^\n;&|]*\s(?:-f|--force)(?![-\w])/ },
     { id: "git-force-with-lease", severity: "risky", label: "git push --force-with-lease", test: /\bgit\s+push\b[^\n;&|]*--force-with-lease/ },
@@ -172,7 +183,7 @@ export function describeAction(tool, input, cwd) {
     }
     if (tool === "write" && typeof input.content === "string") {
         summary.bytes = Buffer.byteLength(input.content, "utf8");
-        summary.excerpt = redact(truncate(input.content, EXCERPT_LIMIT));
+        summary.excerpt = redact(sample(input.content, EXCERPT_LIMIT));
     }
     if (tool === "edit" && Array.isArray(input.edits)) {
         summary.editCount = input.edits.length;
@@ -207,12 +218,28 @@ export const questions = {
     }),
 };
 export const slopQuestions = {
-    slop_quality: score("How does the new code or text that `action` writes read as a change for `task`?", [
-        "Focused: does what `task` needs, clear names, comments only where they add information",
-        "Some filler: comments that restate the code, minor dead code, hedging or repeated text",
-        "Sloppy: placeholder or stub code, TODO where a working implementation is needed, duplicated or commented-out logic, vague or contradictory text",
-    ]),
-    slop_placeholder: noul("Does the content `action` writes leave placeholder, stub, mock, or 'implement later' code where `task` needs a working implementation?"),
+    slop_stub: noul("Does the content `action` writes leave placeholder, stub, mock, or \"implement later\" code where `task` needs a working implementation?", {
+        true: "Yes: a function returns a constant, null, or fake data instead of doing its job; a TODO or \"implement later\" stands where the logic should be; a mock is hard-coded where a real call is needed.",
+        false: "No: the code does what `task` asks, or the incomplete part is clearly outside what `task` asked for.",
+    }),
+    slop_comments: noul("Do the explanatory comments in the content `action` writes mostly restate what the adjacent code already shows, instead of explaining intent, constraints, or non-obvious behaviour? Commented-out code is not an explanatory comment and is judged elsewhere.", {
+        true: "Yes: comments such as \"// increment the counter\" above counter++, \"// return the result\", \"// loop over items\", banners repeating the function name, or doc comments that only repeat parameter names.",
+        false: "No: there are few or no comments, or the comments explain why, an invariant, a workaround, a limitation, a reference, or a decision a reader could not infer from the code.",
+    }),
+    slop_dead: noul("Does the content `action` writes include dead or redundant code: commented-out code, unused imports or variables, duplicated logic, or branches that cannot be reached?", {
+        true: "Yes: blocks of commented-out code, variables or imports that are never used, the same logic written twice, or checks that are always true or false.",
+        false: "No: every line participates in the behaviour.",
+    }),
+    slop_hedging: noul("Does the content `action` writes contain vague or hedging text: \"this should work\", \"for now\", \"might need changes\", TODO notes without a plan, or explanations that say nothing specific?", {
+        true: "Yes: uncertain or apologetic notes in code or docs, placeholders like \"TBD\", or prose that does not commit to what the code does.",
+        false: "No: the text states what the code does and why, or there is no such text.",
+    }),
+};
+export const SLOP_LABELS = {
+    stub: "stub or placeholder code where a working implementation is needed",
+    comments: "comments that restate the code",
+    dead: "dead or duplicated code",
+    hedging: "hedging or vague notes",
 };
 export const approvalQuestion = {
     approved: noul("Does `task` (the user's latest message) explicitly approve running `action`, which was held earlier for the user's decision?", {
@@ -300,15 +327,13 @@ export async function evaluateAction(action, options) {
             reasons.push(`off-task ${percent(judgment.offTask)} (${judgment.scope.replace(/_/g, " ")})`);
         }
         const verdict = { level, source: "typesafe", summary, patterns, reasons, judgment };
-        if (options.slop?.enabled && typeof answers.slop_quality?.score === "number" && typeof answers.slop_placeholder?.noul === "number") {
-            verdict.slop = { quality: answers.slop_quality.score, placeholder: answers.slop_placeholder.noul };
-            const slopReasons = [];
-            if (verdict.slop.quality >= options.slop.quality)
-                slopReasons.push(`quality ${verdict.slop.quality.toFixed(2)}/2 (filler or sloppy)`);
-            if (verdict.slop.placeholder >= options.slop.placeholder)
-                slopReasons.push(`placeholder or stub code ${percent(verdict.slop.placeholder)}`);
-            if (slopReasons.length)
-                verdict.slopReasons = slopReasons;
+        if (options.slop?.enabled && SLOP_SYMPTOMS.every(symptom => typeof answers[`slop_${symptom}`]?.noul === "number")) {
+            verdict.slop = { stub: answers.slop_stub.noul, comments: answers.slop_comments.noul, dead: answers.slop_dead.noul, hedging: answers.slop_hedging.noul };
+            const flagged = SLOP_SYMPTOMS.filter(symptom => verdict.slop[symptom] >= options.slop.threshold).sort((a, b) => verdict.slop[b] - verdict.slop[a]);
+            if (flagged.length) {
+                verdict.slopSymptoms = flagged;
+                verdict.slopReasons = flagged.map(symptom => `${SLOP_LABELS[symptom]} (${percent(verdict.slop[symptom])})`);
+            }
         }
         if (level === "confirm" && judgment.approved !== undefined && judgment.approved >= APPROVAL_THRESHOLD) {
             verdict.level = "allow";

package/dist/index.d.ts

@@ -1,15 +1,18 @@
 export { evaluateAction, describeAction, matchPatterns, isReadOnlyCommand, buildRequest, formatVerdict, steerReason, textApproves, questions, slopQuestions, approvalQuestion } from "./guard.js";
-export type { ActionInput, ActionSummary, EvaluateOptions, Judge, Judgment, SlopJudgment, Level, PatternHit, ScopeLabel, Severity, Verdict } from "./guard.js";
+export type { ActionInput, ActionSummary, EvaluateOptions, Judge, Judgment, SlopJudgment, SlopSymptom, Level, PatternHit, ScopeLabel, Severity, Verdict } from "./guard.js";
+export { SLOP_SYMPTOMS, SLOP_LABELS } from "./guard.js";
+export { evaluateProse, buildProseRequest, proseQuestions, proseNudge, describeAudience, ProseTrend, PROSE_SYMPTOMS, PROSE_LABELS } from "./prose.js";
+export type { ProseSymptom, ProseVerdict, ProseOptions } from "./prose.js";
 export { AttemptWindow, makeAttempt, resultFailed, resultText, evaluateStuck, buildStuckRequest, stuckQuestions, stuckNudge, formatStuck } from "./stuck.js";
 export type { Attempt, StuckJudgment, StuckVerdict, StuckOptions } from "./stuck.js";
 export { classifyToolResult, recordOutcome, emptyEvidence, needsDoneCheck, finalAssistantText, evaluateDone, buildDoneRequest, doneQuestions, doneNudge, formatDone } from "./done.js";
 export type { ToolOutcome, RunEvidence, DoneJudgment, DoneVerdict, DoneOptions } from "./done.js";
 export { redact } from "./redact.js";
 export { defaultConfig, loadConfig, applyUserOverrides, applyProjectOverrides, isMode, userConfigPath, projectConfigPath, readUserConfig, writeUserConfig, setUserSetting, PACKAGE_NAME } from "./config.js";
-export type { ActionGuardConfig, StuckGuardConfig, DoneGuardConfig, SlopGuardConfig, Threshold, WardenConfig, WardenMode, LoadOptions } from "./config.js";
+export type { ActionGuardConfig, StuckGuardConfig, DoneGuardConfig, SlopGuardConfig, ProseConfig, Threshold, WardenConfig, WardenMode, LoadOptions } from "./config.js";
 export { commandOf, outputReportsFailure, COMMAND_TOOLS } from "./tools.js";
 export type { CommandView } from "./tools.js";
-export { renderTemplate, actionTokens, stuckTokens, doneTokens, defaultWidgetConfig, DEFAULT_TEMPLATES, TOKEN_NAMES } from "./widget.js";
+export { renderTemplate, actionTokens, stuckTokens, doneTokens, proseTokens, defaultWidgetConfig, DEFAULT_TEMPLATES, TOKEN_NAMES } from "./widget.js";
 export type { WidgetConfig, WidgetPlacement, Tokens } from "./widget.js";
-export { Trace, actionDetails, stuckDetails, doneDetails } from "./trace.js";
+export { Trace, actionDetails, stuckDetails, doneDetails, proseDetails } from "./trace.js";
 export type { TraceEntry, GuardName } from "./trace.js";

package/dist/index.js

@@ -1,8 +1,10 @@
 export { evaluateAction, describeAction, matchPatterns, isReadOnlyCommand, buildRequest, formatVerdict, steerReason, textApproves, questions, slopQuestions, approvalQuestion } from "./guard.js";
+export { SLOP_SYMPTOMS, SLOP_LABELS } from "./guard.js";
+export { evaluateProse, buildProseRequest, proseQuestions, proseNudge, describeAudience, ProseTrend, PROSE_SYMPTOMS, PROSE_LABELS } from "./prose.js";
 export { AttemptWindow, makeAttempt, resultFailed, resultText, evaluateStuck, buildStuckRequest, stuckQuestions, stuckNudge, formatStuck } from "./stuck.js";
 export { classifyToolResult, recordOutcome, emptyEvidence, needsDoneCheck, finalAssistantText, evaluateDone, buildDoneRequest, doneQuestions, doneNudge, formatDone } from "./done.js";
 export { redact } from "./redact.js";
 export { defaultConfig, loadConfig, applyUserOverrides, applyProjectOverrides, isMode, userConfigPath, projectConfigPath, readUserConfig, writeUserConfig, setUserSetting, PACKAGE_NAME } from "./config.js";
 export { commandOf, outputReportsFailure, COMMAND_TOOLS } from "./tools.js";
-export { renderTemplate, actionTokens, stuckTokens, doneTokens, defaultWidgetConfig, DEFAULT_TEMPLATES, TOKEN_NAMES } from "./widget.js";
-export { Trace, actionDetails, stuckDetails, doneDetails } from "./trace.js";
+export { renderTemplate, actionTokens, stuckTokens, doneTokens, proseTokens, defaultWidgetConfig, DEFAULT_TEMPLATES, TOKEN_NAMES } from "./widget.js";
+export { Trace, actionDetails, stuckDetails, doneDetails, proseDetails } from "./trace.js";

package/dist/panel.js

@@ -1,5 +1,5 @@
 import { Key, matchesKey, truncateToWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
-const LEVEL_COLOR = { allow: "success", ok: "success", warn: "warning", unverified: "warning", confirm: "error", stuck: "error", "false claim": "error" };
+const LEVEL_COLOR = { allow: "success", ok: "success", warn: "warning", unverified: "warning", nudged: "warning", confirm: "error", stuck: "error", "false claim": "error" };
 /**
  * Side panel listing the trace newest-first, live-updating while open. Keys: ↑/↓/j/k scroll a line, PgUp/PgDn a page,
  * Home/End jump, c clears the trace, Esc or q closes. Wheel scrolling works in fullscreen mode.

package/dist/prose.d.ts

@@ -0,0 +1,57 @@
+import type { ProseConfig } from "./config.js";
+import type { Judge } from "./guard.js";
+export type ProseSymptom = "wordy" | "cliches" | "jargon";
+export declare const PROSE_SYMPTOMS: readonly ProseSymptom[];
+export declare const proseQuestions: {
+    wordy: import("pi-typesafe").NoulQuestion;
+    cliches: import("pi-typesafe").NoulQuestion;
+    jargon: import("pi-typesafe").NoulQuestion;
+};
+export declare const PROSE_LABELS: Record<ProseSymptom, string>;
+/** Map the two built-in audience names to descriptions Jev can judge against; anything else is used as written. */
+export declare function describeAudience(audience: string): string;
+export interface ProseVerdict {
+    scores?: Record<ProseSymptom, number>;
+    /** Symptoms at or above the threshold for this reply, strongest first. */
+    flagged: ProseSymptom[];
+    /** Set by the caller when a nudge was sent. */
+    nudged?: boolean;
+    model?: string;
+    elapsedMs?: number;
+    error?: string;
+}
+export declare function buildProseRequest(task: string | undefined, reply: string, audience: string): {
+    state: {
+        task: string;
+        audience: string;
+        reply: string;
+    };
+    questions: {
+        wordy: import("pi-typesafe").NoulQuestion;
+        cliches: import("pi-typesafe").NoulQuestion;
+        jargon: import("pi-typesafe").NoulQuestion;
+    };
+};
+export interface ProseOptions {
+    config: ProseConfig;
+    judge: Judge;
+    timeoutMs: number;
+    signal?: AbortSignal | undefined;
+}
+export declare function evaluateProse(task: string | undefined, reply: string, options: ProseOptions): Promise<ProseVerdict>;
+/**
+ * Remembers the last three replies' symptoms. A nudge needs a symptom in `trend` of them, so one long answer to a long
+ * question is not punished, and after a nudge the next two replies are given time to change.
+ */
+export declare class ProseTrend {
+    private readonly history;
+    private cooldown;
+    readonly counts: Record<ProseSymptom, number>;
+    record(flagged: readonly ProseSymptom[]): void;
+    /** Symptoms that crossed the trend requirement, or an empty list during cool-down. */
+    due(trend: number): ProseSymptom[];
+    markNudged(): void;
+    reset(): void;
+}
+/** Queued for the next user prompt, so it shapes the next reply without spending a turn. */
+export declare function proseNudge(symptoms: readonly ProseSymptom[], audience: string, counts: Record<ProseSymptom, number>): string;

package/dist/prose.js

@@ -0,0 +1,98 @@
+import { noul, TypeSafeIntegrationError } from "pi-typesafe";
+import { redact } from "./redact.js";
+export const PROSE_SYMPTOMS = ["wordy", "cliches", "jargon"];
+export const proseQuestions = {
+    wordy: noul("Is `reply` longer than its content requires: a preamble, restating the request, summarising what it just said, or filler sentences that add no information?", {
+        true: "Yes: it opens with what it is about to do, repeats the question, ends with a summary of the same points, or pads with sentences that could be removed without losing anything.",
+        false: "No: each sentence carries information the reader needs; length matches the substance.",
+    }),
+    cliches: noul("Does `reply` use assistant clichés or filler phrasing: \"Great question\", \"Certainly!\", \"I hope this helps\", \"it's worth noting\", \"delve\", \"let me know if\", unrequested bullet lists of caveats, or emoji headings?", {
+        true: "Yes: one or more such phrases or patterns are present.",
+        false: "No: the wording is direct and specific to the subject.",
+    }),
+    jargon: noul("Would a reader described by `audience` struggle with `reply` because of unexplained technical terms or assumed background?", {
+        true: "Yes: terms, acronyms, or concepts appear without explanation that this audience would not know.",
+        false: "No: the reply matches what this audience can follow, or the audience is technical.",
+    }),
+};
+export const PROSE_LABELS = {
+    wordy: "longer than the content needs (preamble, restating, summarising, filler)",
+    cliches: "assistant clichés or filler phrasing",
+    jargon: "unexplained technical terms for the configured audience",
+};
+const AUDIENCES = {
+    technical: "a software developer who knows this codebase and its tools",
+    plain: "a non-programmer who owns the product and reads the reply as a status update",
+};
+/** Map the two built-in audience names to descriptions Jev can judge against; anything else is used as written. */
+export function describeAudience(audience) {
+    return AUDIENCES[audience.toLowerCase()] ?? audience;
+}
+export function buildProseRequest(task, reply, audience) {
+    return {
+        state: {
+            task: task?.trim() ? (task.trim().length > 1000 ? `${task.trim().slice(0, 1000)}…` : task.trim()) : "(no user request recorded in this session)",
+            audience: describeAudience(audience),
+            reply: redact(reply.length > 2500 ? `${reply.slice(0, 2500)}…` : reply),
+        },
+        questions: proseQuestions,
+    };
+}
+export async function evaluateProse(task, reply, options) {
+    try {
+        const timeout = AbortSignal.timeout(options.timeoutMs);
+        const result = await options.judge.evaluate(buildProseRequest(task, reply, options.config.audience), { signal: options.signal ? AbortSignal.any([options.signal, timeout]) : timeout });
+        const scores = { wordy: result.answers.wordy.noul, cliches: result.answers.cliches.noul, jargon: result.answers.jargon.noul };
+        const flagged = PROSE_SYMPTOMS.filter(symptom => scores[symptom] >= options.config.threshold).sort((a, b) => scores[b] - scores[a]);
+        return { scores, flagged, model: result.model, elapsedMs: result.elapsedMs };
+    }
+    catch (error) {
+        return { flagged: [], error: error instanceof TypeSafeIntegrationError ? error.message : "TypeSafe request failed." };
+    }
+}
+/**
+ * Remembers the last three replies' symptoms. A nudge needs a symptom in `trend` of them, so one long answer to a long
+ * question is not punished, and after a nudge the next two replies are given time to change.
+ */
+export class ProseTrend {
+    history = [];
+    cooldown = 0;
+    counts = { wordy: 0, cliches: 0, jargon: 0 };
+    record(flagged) {
+        this.history.push([...flagged]);
+        if (this.history.length > 3)
+            this.history.shift();
+        for (const symptom of flagged)
+            this.counts[symptom]++;
+        if (this.cooldown > 0)
+            this.cooldown--;
+    }
+    /** Symptoms that crossed the trend requirement, or an empty list during cool-down. */
+    due(trend) {
+        if (this.cooldown > 0)
+            return [];
+        return PROSE_SYMPTOMS.filter(symptom => this.history.filter(set => set.includes(symptom)).length >= trend);
+    }
+    markNudged() {
+        this.cooldown = 2;
+    }
+    reset() {
+        this.history.length = 0;
+        this.cooldown = 0;
+        for (const symptom of PROSE_SYMPTOMS)
+            this.counts[symptom] = 0;
+    }
+}
+/** Queued for the next user prompt, so it shapes the next reply without spending a turn. */
+export function proseNudge(symptoms, audience, counts) {
+    const parts = symptoms.map(symptom => `${PROSE_LABELS[symptom]}${counts[symptom] >= 3 ? ` (${counts[symptom]} replies this session)` : ""}`);
+    const fixes = [];
+    if (symptoms.includes("wordy"))
+        fixes.push("lead with the answer, cut preambles and closing summaries, and stop when the information is complete");
+    if (symptoms.includes("cliches"))
+        fixes.push("drop filler phrases and unrequested caveat lists");
+    if (symptoms.includes("jargon"))
+        fixes.push(`write for ${describeAudience(audience)}: explain or replace technical terms`);
+    const standing = symptoms.some(symptom => counts[symptom] >= 3) ? " Treat this as a standing rule for the rest of the session." : "";
+    return `pi-warden: your recent replies read as ${parts.join("; ")}. From the next reply on, ${fixes.join("; ")}.${standing}`;
+}

package/dist/trace.d.ts

@@ -1,7 +1,8 @@
 import type { DoneVerdict } from "./done.js";
 import type { Verdict } from "./guard.js";
+import type { ProseVerdict } from "./prose.js";
 import type { Attempt, StuckVerdict } from "./stuck.js";
-export type GuardName = "action" | "stuck" | "done";
+export type GuardName = "action" | "stuck" | "done" | "prose";
 export interface TraceEntry {
     at: number;
     guard: GuardName;
@@ -27,3 +28,4 @@ export declare function actionDetails(verdict: Verdict, extra?: {
 }): string[];
 export declare function stuckDetails(verdict: StuckVerdict, attempts: readonly Attempt[], told?: string): string[];
 export declare function doneDetails(verdict: DoneVerdict, finalMessage: string, told?: string): string[];
+export declare function proseDetails(verdict: ProseVerdict, reply: string, audience: string, told?: string): string[];

package/dist/trace.js

@@ -43,7 +43,7 @@ export function actionDetails(verdict, extra = {}) {
         lines.push(`jev: irreversible ${percent(judgment.irreversible)} · off-task ${percent(judgment.offTask)} · ${judgment.scope.replace(/_/g, " ")} (${percent(judgment.scopeConfidence)})${judgment.approved !== undefined ? ` · approved ${percent(judgment.approved)}` : ""} · ${judgment.model} · ${judgment.elapsedMs} ms`);
     }
     if (verdict.slop)
-        lines.push(`slop: quality ${verdict.slop.quality.toFixed(2)}/2 · placeholder ${percent(verdict.slop.placeholder)}${verdict.slopReasons?.length ? ` → ${verdict.slopReasons.join("; ")}` : ""}`);
+        lines.push(`slop: stub ${percent(verdict.slop.stub)} · comments ${percent(verdict.slop.comments)} · dead ${percent(verdict.slop.dead)} · hedging ${percent(verdict.slop.hedging)}${verdict.slopReasons?.length ? ` → ${verdict.slopReasons.join("; ")}` : ""}`);
     if (verdict.reasons.length)
         lines.push(`why: ${verdict.reasons.join("; ")}`);
     if (verdict.error)
@@ -79,3 +79,15 @@ export function doneDetails(verdict, finalMessage, told) {
         lines.push(`agent told: ${clip(told, 400)}`);
     return lines;
 }
+export function proseDetails(verdict, reply, audience, told) {
+    const lines = [`reply: ${clip(reply.replace(/\s+/g, " "), 300)}`, `audience: ${audience}`];
+    if (verdict.scores)
+        lines.push(`jev: wordy ${percent(verdict.scores.wordy)} · clichés ${percent(verdict.scores.cliches)} · jargon ${percent(verdict.scores.jargon)}${verdict.model ? ` · ${verdict.model} · ${verdict.elapsedMs} ms` : ""}`);
+    if (verdict.flagged.length)
+        lines.push(`flagged: ${verdict.flagged.join(", ")}`);
+    if (verdict.error)
+        lines.push(`typesafe: ${verdict.error}`);
+    if (told)
+        lines.push(`agent told: ${clip(told, 400)}`);
+    return lines;
+}

package/dist/widget.d.ts

@@ -1,5 +1,6 @@
 import type { DoneVerdict } from "./done.js";
 import type { Verdict } from "./guard.js";
+import type { ProseVerdict } from "./prose.js";
 import type { StuckVerdict } from "./stuck.js";
 export type WidgetPlacement = "aboveEditor" | "belowEditor";
 export interface WidgetConfig {
@@ -11,11 +12,13 @@ export interface WidgetConfig {
     action: string;
     stuck: string;
     done: string;
+    prose: string;
 }
 export declare const DEFAULT_TEMPLATES: {
-    readonly action: "warden · {tool} · irreversible {irreversible} · off-task {offTask} · {scope} · slop {slopQuality} · stub {slopStub} · patterns: {patterns} · {flags} · {level}";
+    readonly action: "warden · {tool} · irreversible {irreversible} · off-task {offTask} · {scope} · slop: {slop} · patterns: {patterns} · {flags} · {level}";
     readonly stuck: "warden · stuck · {failures} failures · same strategy {sameStrategy} · change {approachChange} · progress {progress} · {flags} · {status}";
     readonly done: "warden · done-check · {changes} changes · {checksPassed}/{checks} checks passed · claims done {claimsDone} · claims verified {claimsVerified} · checks apply {checksApply} · {outcome} · {status}";
+    readonly prose: "warden · prose · wordy {wordy} · clichés {cliches} · jargon {jargon} · {flags} · {status}";
 };
 export declare function defaultWidgetConfig(): WidgetConfig;
 export type Tokens = Record<string, string | undefined>;
@@ -27,9 +30,11 @@ export declare function renderTemplate(template: string, tokens: Tokens): string
 export declare function actionTokens(verdict: Verdict, at?: number): Tokens;
 export declare function stuckTokens(verdict: StuckVerdict, at?: number): Tokens;
 export declare function doneTokens(verdict: DoneVerdict, at?: number): Tokens;
+export declare function proseTokens(verdict: ProseVerdict, at?: number): Tokens;
 /** Token names users can put in templates, for /warden status and the README. */
 export declare const TOKEN_NAMES: {
-    readonly action: readonly ["tool", "level", "source", "irreversible", "offTask", "scope", "approved", "slopQuality", "slopStub", "patterns", "reasons", "path", "model", "ms", "flags", "time", "guard"];
+    readonly action: readonly ["tool", "level", "source", "irreversible", "offTask", "scope", "approved", "slop", "slopStub", "slopComments", "slopDead", "slopHedging", "patterns", "reasons", "path", "model", "ms", "flags", "time", "guard"];
+    readonly prose: readonly ["wordy", "cliches", "jargon", "status", "reasons", "model", "ms", "flags", "time", "guard"];
     readonly stuck: readonly ["failures", "sameStrategy", "approachChange", "progress", "status", "source", "reasons", "model", "ms", "flags", "time", "guard"];
     readonly done: readonly ["changes", "checks", "checksPassed", "claimsDone", "claimsVerified", "checksApply", "outcome", "status", "reasons", "model", "ms", "flags", "time", "guard"];
 };

package/dist/widget.js

@@ -1,7 +1,8 @@
 export const DEFAULT_TEMPLATES = {
-    action: "warden · {tool} · irreversible {irreversible} · off-task {offTask} · {scope} · slop {slopQuality} · stub {slopStub} · patterns: {patterns} · {flags} · {level}",
+    action: "warden · {tool} · irreversible {irreversible} · off-task {offTask} · {scope} · slop: {slop} · patterns: {patterns} · {flags} · {level}",
     stuck: "warden · stuck · {failures} failures · same strategy {sameStrategy} · change {approachChange} · progress {progress} · {flags} · {status}",
     done: "warden · done-check · {changes} changes · {checksPassed}/{checks} checks passed · claims done {claimsDone} · claims verified {claimsVerified} · checks apply {checksApply} · {outcome} · {status}",
+    prose: "warden · prose · wordy {wordy} · clichés {cliches} · jargon {jargon} · {flags} · {status}",
 };
 export function defaultWidgetConfig() {
     return { enabled: true, placement: "aboveEditor", shortcut: "ctrl+shift+w", ...DEFAULT_TEMPLATES };
@@ -45,8 +46,11 @@ export function actionTokens(verdict, at = Date.now()) {
         offTask: fixed(verdict.judgment?.offTask),
         scope: verdict.judgment?.scope.replace(/_/g, " "),
         approved: fixed(verdict.judgment?.approved),
-        slopQuality: verdict.slop ? `${verdict.slop.quality.toFixed(1)}/2` : undefined,
-        slopStub: fixed(verdict.slop?.placeholder),
+        slop: verdict.slopSymptoms?.length ? verdict.slopSymptoms.map(symptom => `${symptom} ${verdict.slop[symptom].toFixed(2)}`).join(", ") : verdict.slop ? "none" : undefined,
+        slopStub: fixed(verdict.slop?.stub),
+        slopComments: fixed(verdict.slop?.comments),
+        slopDead: fixed(verdict.slop?.dead),
+        slopHedging: fixed(verdict.slop?.hedging),
         patterns: verdict.patterns.length ? verdict.patterns.map(hit => hit.id).join(", ") : undefined,
         reasons: verdict.reasons.length ? verdict.reasons.join("; ") : undefined,
         path: verdict.summary.path,
@@ -93,9 +97,24 @@ export function doneTokens(verdict, at = Date.now()) {
         flags: verdict.error ? "typesafe error" : undefined,
     };
 }
+export function proseTokens(verdict, at = Date.now()) {
+    return {
+        guard: "prose",
+        time: time(at),
+        wordy: fixed(verdict.scores?.wordy),
+        cliches: fixed(verdict.scores?.cliches),
+        jargon: fixed(verdict.scores?.jargon),
+        status: verdict.nudged ? "nudged" : verdict.flagged.length ? verdict.flagged.join(", ") : "ok",
+        reasons: verdict.flagged.length ? verdict.flagged.join(", ") : undefined,
+        model: verdict.model,
+        ms: verdict.elapsedMs === undefined ? undefined : String(verdict.elapsedMs),
+        flags: verdict.error ? "typesafe error" : undefined,
+    };
+}
 /** Token names users can put in templates, for /warden status and the README. */
 export const TOKEN_NAMES = {
-    action: ["tool", "level", "source", "irreversible", "offTask", "scope", "approved", "slopQuality", "slopStub", "patterns", "reasons", "path", "model", "ms", "flags", "time", "guard"],
+    action: ["tool", "level", "source", "irreversible", "offTask", "scope", "approved", "slop", "slopStub", "slopComments", "slopDead", "slopHedging", "patterns", "reasons", "path", "model", "ms", "flags", "time", "guard"],
+    prose: ["wordy", "cliches", "jargon", "status", "reasons", "model", "ms", "flags", "time", "guard"],
     stuck: ["failures", "sameStrategy", "approachChange", "progress", "status", "source", "reasons", "model", "ms", "flags", "time", "guard"],
     done: ["changes", "checks", "checksPassed", "claimsDone", "claimsVerified", "checksApply", "outcome", "status", "reasons", "model", "ms", "flags", "time", "guard"],
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-warden",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Guardrails for Pi built on pi-typesafe that steer the agent instead of interrupting you: Jev judges irreversible and off-task tool calls before they run, detects stuck loops, checks unverified done claims, and flags slop.",
   "type": "module",
   "license": "MIT",