pi-simple-english 0.6.0 → 0.8.0

package/README.md

@@ -1,38 +1,86 @@
-# pi-simple-english
+# simple-english for `pi`
 
-Lint prose and code comments with `simple_english`, from inside pi.
+> Write for human, not for agent.
 
-The package adds two things to pi:
+You can teach an agent plain-English prose with a skill or a
+prompt. It writes clean prose in the first paragraph and slop again
+by the third. This linter keeps the agent honest: it reads what the
+agent wrote and names every broken rule. Send the findings back, and
+the agent corrects its own text.
 
-- the `se_lint` tool, which lints a file or a directory
-- the `simple-english-lint` skill, which tells the agent to lint the
-  prose it writes and fix every finding
+<table>
+<tr>
+<th width="50%">Before</th>
+<th width="50%">After</th>
+</tr>
+<tr>
+<td valign="top">
 
-## Prerequisites
+> Your API keys are rotated by the service every 90 days — you will need to update them if you get a 401; don't panic, simply re-run the setup command, which regenerates the credentials without any downtime. <!-- se: ignore -->
 
-The linter is a Ruby gem. Install it once, before the adapter:
+</td>
+<td valign="top">
 
-```bash
-gem install simple_english
-```
+> The service rotates your API keys every 90 days. If you get a 401, update them. Do not panic. Re-run the setup command. It regenerates the credentials without any downtime.
+
+</td>
+</tr>
+</table>
+
+The linter covers Markdown prose plus code comments in Python, Ruby,
+JavaScript, TypeScript, Go, Rust, Java, C#, C++, Kotlin, bash, and
+YAML.
+
+## What it checks
+
+- **Voice:** say who does the action.
+- **Tense:** simple tenses only, no present perfect.
+- **Modals:** `can`, `will`, `must` only.
+- **Punctuation:** no em-dashes, no semicolons.
+- **Contractions:** write every word in full.
+- **Sentence shape:** condition before command, no `-ing` phrase after a comma.
+- **Word choice:** about 50 substitution rules, from `leverage` to `in conclusion`.
+- **Counts:** 20 words per sentence in list items, 25 in paragraphs, six sentences per paragraph at most.
+
+It lints Markdown prose plus code comments in Python, Ruby,
+JavaScript, TypeScript, Go, Rust, Java, C#, C++, Kotlin, bash, and
+YAML. The full list, with a wrong and a right example for each rule,
+is [docs/RULES.md](https://github.com/TonyCTHsu/simple-english/blob/master/docs/RULES.md).
 
 ## Install
 
-For yourself, on every project:
+```bash
+pi install npm:pi-simple-english
+```
+
+Install it for one project only by adding `-l` and running the
+command from the project root.
 
-For one project, with the team, install into the project instead. Run
-the install with `-l` from the project root:
+The tool calls the `se` CLI. That CLI ships as a Ruby gem. Install
+it once, before the first lint:
 
 ```bash
-pi install npm:pi-simple-english -l
+gem install simple_english
+```
+
+## What you get
+
+The `se_lint` tool lints a file or a directory on demand. Every
+file edit lints too. The findings land in the edit result, so the
+agent fixes them in the same turn. Each finding carries a line
+number, a rule ID, and a fix hint:
+
+```
+README.md:12:31-32: [SE_NO_SEMICOLON] ";" - Write two sentences, or name the relation.
 ```
 
-The project install writes `.pi/settings.json`, which you commit. Pi
-loads it only after you grant project trust.
+The `write-simple-english` skill carries the rules, so the agent
+writes clean prose the first time. The `lint-simple-english` skill
+tells the agent to lint the prose it writes and fix every finding.
 
 ## Versions
 
-The package version tracks the gem version. The changelog is the
-repository changelog. See the section that matches the version:
+The package version tracks the gem version. The changelog lives in
+the repository:
 
 https://github.com/TonyCTHsu/simple-english/blob/master/CHANGELOG.md

package/extensions/se-lint.ts

@@ -1,19 +1,86 @@
 /**
  * se_lint - lint Markdown prose and code comments with simple_english.
  *
- * Shells out to the `se` CLI. Assumes the gem is installed; on a
- * missing binary the tool fails with install steps.
+ * Two layers. The se_lint tool lints on demand. Enforcement runs the
+ * same lint after every edit or write and appends the findings to the
+ * tool result, so the agent sees them in the turn that made them. It
+ * never blocks the edit. The contract mirrors the claude-code hook in
+ * integrations/claude-code/hooks/lint.sh: a clean file stays silent,
+ * a failed lint says so instead of reading as clean, and a missing
+ * binary names the install step.
  */
 
 import { execFile } from "node:child_process";
 import { Type } from "typebox";
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type {
+	AgentToolResult,
+	ExtensionAPI,
+	ToolResultEvent,
+	ToolResultEventResult,
+} from "@earendil-works/pi-coding-agent";
 
 const OUTPUT_LIMIT = 4000;
 // ponytail: 120s allows a cold daemon boot (LanguageTool + JVM). If that
 // ever proves slow in practice, cut to 30s and pre-warm via `se serve`.
 const TIMEOUT_MS = 120_000;
 
+interface SeResult {
+	stdout: string;
+	code: number;
+}
+
+interface SeDetails {
+	path: string;
+	exitCode: number;
+	findings: number;
+	full?: string;
+}
+
+function seLint(path: string, signal?: AbortSignal): Promise<SeResult> {
+	return new Promise((resolve, reject) => {
+		execFile(
+			"se",
+			["lint", path],
+			{ timeout: TIMEOUT_MS, maxBuffer: 1024 * 1024, signal },
+			(error, stdout) => {
+				if (error && typeof error.code !== "number") {
+					reject(error);
+					return;
+				}
+				resolve({ stdout, code: (error?.code as number | undefined) ?? 0 });
+			},
+		);
+	});
+}
+
+// The feedback appended to an edit or write result. undefined means
+// clean: nothing is appended, so a clean edit reads as a clean edit.
+async function lintFeedback(path: string): Promise<string | undefined> {
+	let result: SeResult;
+	try {
+		result = await seLint(path);
+	} catch (err) {
+		const e = err as NodeJS.ErrnoException;
+		if (e.code === "ENOENT") {
+			return "`se` is not installed, so the file was not linted. Install it first: `gem install simple_english`, then retry.";
+		}
+		return `se lint failed, so the file was not linted. Run \`se lint ${path}\` to see the error.`;
+	}
+	if (result.code >= 2) {
+		return `se exited ${result.code} and the file was not linted. Run \`se lint ${path}\` to see the error.`;
+	}
+	const full = result.stdout.trim();
+	if (result.code === 0 || !full) {
+		return undefined;
+	}
+	const findings = full.split("\n").length;
+	const text =
+		full.length > OUTPUT_LIMIT
+			? `${full.slice(0, OUTPUT_LIMIT)}\n... truncated (${full.length} chars, ${findings} findings). Full output: run \`se lint ${path}\` with bash.`
+			: full;
+	return `se found ${findings} lint finding(s) in ${path}. Fix them, then lint again:\n${text}`;
+}
+
 export default function (pi: ExtensionAPI) {
 	pi.registerTool({
 		name: "se_lint",
@@ -28,24 +95,11 @@ export default function (pi: ExtensionAPI) {
 			path: Type.String({ description: "File or directory to lint, relative to the CWD or absolute" }),
 		}),
 
-		async execute(_toolCallId, params, signal) {
+		async execute(_toolCallId, params, signal): Promise<AgentToolResult<SeDetails>> {
 			let stdout: string;
 			let code: number;
 			try {
-				({ stdout, code } = await new Promise<{ stdout: string; code: number }>((resolve, reject) => {
-					execFile(
-						"se",
-						["lint", params.path],
-						{ timeout: TIMEOUT_MS, maxBuffer: 1024 * 1024, signal },
-						(error, out) => {
-							if (error && typeof error.code !== "number") {
-								reject(error);
-								return;
-							}
-							resolve({ stdout: out, code: (error?.code as number | undefined) ?? 0 });
-						},
-					);
-				}));
+				({ stdout, code } = await seLint(params.path, signal));
 			} catch (err) {
 				const e = err as NodeJS.ErrnoException;
 				if (e.code === "ENOENT") {
@@ -64,7 +118,7 @@ export default function (pi: ExtensionAPI) {
 			if (!full) {
 				return {
 					content: [{ type: "text" as const, text: `clean: no findings in ${params.path}` }],
-					details: { path: params.path, exitCode: code, findings: 0 },
+					details: { path: params.path, exitCode: code, findings: 0, full: undefined },
 				};
 			}
 
@@ -79,4 +133,15 @@ export default function (pi: ExtensionAPI) {
 			};
 		},
 	});
+
+	pi.on("tool_result", async (event: ToolResultEvent): Promise<ToolResultEventResult | undefined> => {
+		if (event.toolName !== "edit" && event.toolName !== "write") return;
+		// A failed edit wrote nothing: there is nothing to lint.
+		if (event.isError) return;
+		const path = event.input.path;
+		if (typeof path !== "string" || path === "") return;
+		const feedback = await lintFeedback(path);
+		if (!feedback) return;
+		return { content: [...event.content, { type: "text" as const, text: feedback }] };
+	});
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-simple-english",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Lint prose and code comments with the simple_english plain-English rules.",
   "type": "module",
   "license": "MIT",

package/skills/{simple-english-lint → lint-simple-english}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: simple-english-lint
+name: lint-simple-english
 description: Lint prose with simple_english after writing or editing documentation,
   READMEs, or code comments. Use when the agent writes prose, when asked to lint
   or simplify text, or when a doc change lands.

package/skills/write-simple-english/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: write-simple-english
+description: Write plain English on the first pass. Use whenever the
+  output is prose, such as READMEs, docs, comments, replies, or any
+  other text a reader must understand. Use when asked for simple
+  English or no jargon.
+metadata:
+  inspired-by: ASD-STE100 Simplified Technical English
+---
+
+Write prose (READMEs, docs, comments) for a reader whose task is to
+understand the idea behind the words. They value clarity and
+conciseness. Their attention is limited, and every word competes for
+it. Minimize their cognitive load: common words, short sentences,
+one idea at a time.
+
+These rules are a controlled language like ASD-STE100, the aerospace
+standard for maintenance manuals. They bind: a sentence
+outside them is an error, not a style choice.
+
+## How to write
+
+### Mechanics
+
+Write the words in full. No contractions, no semicolons, no
+em-dashes. Two short sentences beat one joined pair. Write "A or B,
+or both", not and/or. Write "for example", not e.g., and "that is",
+not i.e. Name the items instead of etc.
+
+### Verbs
+
+Use the active voice. Say who does the action. Use simple tenses.
+State a requirement with can, will, or must. Put the condition
+before the command: "If the port is taken, pick another." No -ing
+phrase after a comma. Start a new sentence.
+
+### Keep it short
+
+Cut every word that carries no idea. One idea per sentence. One idea
+per paragraph. A sentence carries at most 20 words in instructions,
+25 in explanations. A paragraph carries at most 6 sentences.
+
+### Protect the code
+
+When you rewrite, leave code, identifiers, commands, flags, file
+paths, quoted errors, and product names untouched. The rules govern
+the prose around them.
+
+## Swap slop for short words
+
+The lists name the common offenders. When a word does what a heading
+bans, swap it, listed or not.
+
+### Filler
+
+- Empty modifiers: just, very, really, extremely, vibrant, nuanced,
+  multifaceted
+- Throat-clearing openers: it is worth noting, it is important to, is
+  designed to, aims to, in conclusion, in summary, at the end of the
+  day
+- Sign-offs and invitations: "I hope this helps", "let's dive in"
+
+### Wordiness
+
+- to, not in order to
+- because, not due to the fact that
+- if, not in the event that
+- for, not when it comes to
+- before, not prior to
+- by default, not out of the box
+- state the condition, not "as needed"
+
+### Corporate voice
+
+- use, not leverage
+- help, not facilitate
+- help, not foster
+- use, not harness
+- make simpler, not streamline
+- function, not functionality
+- you can, not enables you to
+- corrects, not addresses the issue
+- show, not showcase
+- has, not boasts
+- make sure that, not ensure
+- improve, not enhance
+- increase, not elevate
+
+### Hype
+
+- new, not groundbreaking
+- change, not revolutionize
+- say what changes, not transformative
+- complex, not intricate
+- important, not pivotal
+- careful, not meticulous
+- full, not holistic
+- model, not paradigm
+- area, not realm or landscape
+- interaction, not interplay
+- read, not delve into
+- many, not plethora
+- delete tapestry, testament, and synergy
+- internally, not under the hood
+
+### Connectors
+
+- also, not furthermore
+- but, not notwithstanding or that being said
+- start, not embark
+- busy, not bustling
+- give the location, not "nestled"
+- say what it does, not "gracefully handles"
+
+## Then lint
+
+After the text exists, run the lint-simple-english skill on it. The
+draft is done when the lint result is clean.
+
+## In chat
+
+The reply is prose too, and every rule above applies to it. Answer
+in the first sentence, then support it. Headers and bold belong in
+documents. A list only for steps in order, a code block only for
+text the reader must copy. Define a term in a few words at first
+use. The linter checks files, so the reply carries the rules on its
+own.