agent-simple-english 0.1.0 → 0.2.0

package/.claude-plugin/marketplace.json

@@ -10,8 +10,8 @@
   "plugins": [
     {
       "name": "simple-english",
-      "description": "Apply Simplified Technical English rules to writes, edits, and git commit messages.",
-      "version": "0.1.0",
+      "description": "Apply technical and house-style writing rules to writes, edits, and git commit messages.",
+      "version": "0.2.0",
       "author": {
         "name": "JIA YI"
       },

package/.claude-plugin/plugin.json

@@ -1,8 +1,8 @@
 {
   "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
   "name": "simple-english",
-  "version": "0.1.0",
-  "description": "Apply Simplified Technical English rules to writes, edits, and git commit messages.",
+  "version": "0.2.0",
+  "description": "Apply technical and house-style writing rules to writes, edits, and git commit messages.",
   "repository": "https://github.com/jyooi/agent-simple-english",
   "license": "MIT",
   "keywords": ["simplified-technical-english", "lint", "hooks"],

package/README.md

@@ -1,6 +1,6 @@
 # agent-simple-english
 
-`agent-simple-english` checks ASD-STE100 Simplified Technical English (STE).
+`agent-simple-english` checks rules derived from ASD-STE100 Simplified Technical English (STE) and two enabled house-style rules.
 It supplies one Engine, one CLI, a pi Adapter, and a Claude Code Adapter.
 The Claude Code plugin uses CLI Hook mode to enforce the same rules.
 
@@ -9,7 +9,7 @@ It does not rewrite text because an automatic rewrite can change its meaning.
 
 ## What the pi Adapter does
 
-The pi Adapter adds its active STE rules to the model prompt before each agent turn.
+The pi Adapter adds its active writing rules to the model prompt before each agent turn.
 It then applies the rules at three layers.
 
 1. **Write and edit gate.**
@@ -33,7 +33,7 @@ It then applies the rules at three layers.
 
 The pi Adapter checks Markdown prose and source comments according to the [content kinds](#content-kinds).
 It gives the line, column, rule ID, and suggested correction for a blocked tool call.
-A config or dictionary load error makes enabled write, edit, and commit gates fail closed.
+A config, dictionary, or rule-data load error makes enabled write, edit, and commit gates fail closed.
 
 ## Install the Claude Code Adapter
 
@@ -52,7 +52,7 @@ The repository supplies the local marketplace manifest.
 Marketplace publication is outside this package release.
 
 At `SessionStart`, the Adapter loads the merged config for an enabled session.
-It reads the config from the session working directory and adds the active STE rule summary to context.
+It reads the config from the session working directory and adds the active writing-rule summary to context.
 The summary honors `hard`, `soft`, and `off` rule settings plus `maxSentenceWords`.
 
 The `PreToolUse` gate checks `Write`, `Edit`, and `Bash` events.
@@ -166,8 +166,44 @@ In strict mode, it blocks a reply that has hard violations.
 A `UserPromptSubmit` event adds pending feedback to context and clears that feedback.
 Every hook reads the current session mode before it applies a gate.
 Malformed JSON returns a non-blocking error so Claude Code can continue.
-The hook also allows the event when configuration, dictionary, tagger, transcript, state, or file processing fails.
-It adds warning text.
+The hook also allows the event when configuration, dictionary, rule-data, tagger, transcript, state, or file processing fails.
+It adds warning text for these operational failures.
+Observation-write failures are silent and do not change the hook output or decision.
+
+### Review hook observations
+
+Enabled Hook mode logs every write, edit, static commit-message, and reply lint decision to the local XDG state directory.
+Observation logging is on by default, and the log includes clean allows and soft Findings.
+Plain lint runs, disabled hook sessions, and the pi Adapter do not write Observations.
+Set `SIMPLE_ENGLISH_OBSERVE=0` to stop observation logging.
+
+Monthly Observation files use `$XDG_STATE_HOME/simple-english/observations/YYYY-MM.jsonl`.
+The default base directory is `~/.local/state`.
+Each Finding stores its offending snippet for later review.
+Verdicts use the separate `$XDG_STATE_HOME/simple-english/verdicts.jsonl` file.
+These global, host-local records can contain snippets, working directories, and file paths.
+New state directories use mode `0700`, and new JSONL files use mode `0600`.
+Each record uses one append-mode write without a lock, so concurrent hooks can safely add complete lines.
+
+Review each unjudged Finding:
+
+```sh
+simple-english observe review
+```
+
+Press `t` for a true positive or `f` for a false positive.
+Press `s` to leave a Finding unjudged or `q` to quit.
+A Verdict can include an optional note.
+A false positive exists only after a human records that Verdict.
+The latest Verdict for a Finding wins.
+
+Show fire counts, judged counts, and false-positive rates for each rule:
+
+```sh
+simple-english observe stats
+```
+
+The report also shows total Observations and clean allows.
 
 ### Lint files and standard input
 
@@ -214,6 +250,7 @@ Soft violations can appear with exit code 0.
 ### CLI flags
 
 - `--json` writes one JSON report with `violations` and `summary` fields.
+  Each violation includes its offending sentence or paragraph as `snippet`.
 
 - `--config <path>` uses only that config file and disables config discovery.
 
@@ -221,6 +258,12 @@ Soft violations can appear with exit code 0.
   Valid values are `prose-file`, `slash-source`, `hash-source`, and `commit-message`.
   The form `--kind=<kind>` also works.
 
+- `--help` writes the command usage.
+
+- `--version` writes the package version.
+
+- The command rejects an unknown flag as an argument error.
+
 - A path of `-` reads standard input.
   With no paths, the command also reads standard input.
 
@@ -238,10 +281,39 @@ It is the default for standard input, extensionless paths, and file types that h
 `commit-message` checks the complete input as a commit message.
 
 File extension matching does not depend on letter case.
-Source kinds ignore comment markers inside string literals.
+Source kinds ignore comment markers inside supported string literal forms.
 All kinds preserve the original line and column.
-They ignore identifiers plus fenced and indented Markdown code.
-Inline Markdown code is outside every rule except `semicolon`.
+They ignore identifiers, YAML frontmatter, valid GFM tables, and fenced, indented, and inline Markdown code.
+
+### Inline suppression
+
+A suppression directive names one or more registered rule IDs and applies only to the next physical line.
+Use this Markdown comment form in prose files:
+
+```md
+<!-- ste-disable-next-line marketing -->
+The robust estimator uses this sample.
+```
+
+Use the matching plain comment form in slash and hash source files:
+
+```ts
+// ste-disable-next-line marketing
+// The robust estimator uses this sample.
+```
+
+```py
+# ste-disable-next-line marketing
+# The robust estimator uses this sample.
+```
+
+Separate multiple rule IDs with whitespace.
+Commas are also accepted as separators.
+A missing or unknown rule ID produces an `invalid-suppression` violation, which is hard by default.
+
+Directive recognition uses lightweight per-language comment extraction rather than full language parsers.
+Known accepted losses are JavaScript regular expressions inside template expressions, Ruby and Perl regular-expression literals containing directive text, Perl `<<~` heredocs, adjacent multiline YAML flow scalars, and compact nested YAML block scalars with explicit indentation.
+Engine fixtures pin these limitations pending per-language lexers.
 
 ## Configuration
 
@@ -261,7 +333,6 @@ The global fallback is `simple-english.json` in the pi agent config directory.
 The default pi agent config directory is `~/.pi/agent`.
 `PI_CODING_AGENT_DIR` can change that directory.
 
-The loader resolves a relative value from the working directory that requested the config.
 The loader reads a fallback file only when the new file at the same level is absent.
 
 This example contains every config key and every rule:
@@ -269,10 +340,19 @@ This example contains every config key and every rule:
 ```json
 {
   "maxSentenceWords": 25,
+  "exemptBlockQuotes": true,
+  "approvedWordsPath": "./approved-words.json",
+  "ruleDataExtensions": {
+    "phrasal-verb": ["config/phrasal-verbs.json"],
+    "hedging": ["config/hedging.json"],
+    "marketing": ["config/marketing.json"],
+    "adjectival-participle": ["config/adjectival-participles.json"]
+  },
   "rules": {
     "contraction": "hard",
     "dictionary-not-approved-word": "hard",
     "hedging": "soft",
+    "invalid-suppression": "hard",
     "marketing": "soft",
     "paragraph-length": "hard",
     "phrasal-verb": "hard",
@@ -291,117 +371,122 @@ A soft violation produces a report or warning but does not block the action.
 The `off` value disables that rule.
 
 `maxSentenceWords` must be a positive integer and has a default value of 25.
+`exemptBlockQuotes` must be a boolean and has a default value of `false`.
+When it is omitted or `false`, block quotes receive the same checks as other prose.
+When it is `true`, CommonMark block quote content is exempt from `dictionary-not-approved-word`, `contraction`, `phrasal-verb`, `hedging`, and `marketing` checks.
+All other rules continue to check block quote content.
+`approvedWordsPath` selects a user-owned approved-word list.
+The loader resolves a relative path from the working directory that requested the config.
+This list replaces the bundled not-approved sample and any `SIMPLE_ENGLISH_DICTIONARY` replacement.
+A missing, unreadable, or invalid list causes lint exit code 2.
+The enabled pi Adapter gates fail closed after this error.
+Claude Code Hook mode reports a warning and allows the event, as it does for other load errors.
 Unknown keys, unknown rule IDs, and invalid values cause a config error.
 
+`ruleDataExtensions` maps each list-backed data set to more JSON data files.
+The loader adds entries from these files after the bundled entries.
+The loader resolves relative paths from the current working directory.
+Each file must use the [package dictionary data format](src/dictionary/README.md).
+An `adjectival-participle` extension adds exact tagged-token forms that the progressive and passive rules allow after a form of `be`.
+A lint command reports an extension load error and continues with the bundled rule data.
+The enabled pi Adapter fails closed after that error, while Claude Code Hook mode allows the event and adds a warning.
+
 ## Rule reference
 
-### `contraction`
+### Rules derived from ASD-STE100
+
+#### `contraction`
 
 Default: hard.
 Reports apostrophe contractions such as forms that end in `n't`, `'re`, `'ve`, `'ll`, `'d`, or `'m`.
 It also reports unambiguous forms that end in `'s`.
 
-### `dictionary-not-approved-word`
+#### `dictionary-not-approved-word`
 
 Default: hard.
-Reports an unapproved word or phrase from the bundled dictionary and supplies approved alternatives.
-Part-of-speech data limits applicable entries when that data exists.
-Matching does not depend on letter case.
-
-### `hedging`
-
-Default: soft.
-Reports these phrases: `it is important to note`, `it should be noted`, `it is worth noting`, `please note that`, `as mentioned`, `as noted above`.
-A phrase match stays on one source line.
+Without an approved-word list, this rule reports forms from the bundled not-approved sample and supplies approved alternatives.
+Part-of-speech data limits applicable sample entries when that data exists.
+With an approved-word list, this rule reports each prose token that the list does not contain.
+Matching uses exact surface forms without regard to case.
+See [Configuration](#configuration) for list selection, precedence, and load errors.
 
-### `marketing`
-
-Default: soft.
-Reports the first listed term in each token.
-Matching does not depend on letter case, and it also examines components of hyphenated tokens.
-
-- `seamless`.
-- `seamlessly`.
-- `robust`.
-- `powerful`.
-- `cutting-edge`.
-- `effortless`.
-- `effortlessly`.
-- `world-class`.
-- `next-generation`.
-- `revolutionary`.
-- `blazing`.
-- `lightning-fast`.
-- `elegant`.
-- `delightful`.
-- `turnkey`.
-- `best-in-class`.
-- `state-of-the-art`.
-- `game-changing`.
-- `battle-tested`.
-- `enterprise-grade`.
-- `supercharge`.
-- `unleash`.
-- `empower`.
-- `empowers`.
-
-### `paragraph-length`
+#### `paragraph-length`
 
 Default: hard.
 Reports a prose paragraph that has more than six sentences.
 Markdown block boundaries and list items start separate paragraphs.
+Sentence counts use the [`sentence-length`](#sentence-length) segmentation rules.
 
-### `phrasal-verb`
+#### `phrasal-verb`
 
 Default: hard.
-Reports these forms and supplies the listed suggestion:
-
-| Forms | Suggestion |
-| --- | --- |
-| `carry out`, `carries out`, `carried out`, `carrying out` | `do`. |
-| `spin up`, `spins up`, `spun up`, `spinning up` | `start`. |
-| `spin down`, `spins down`, `spun down`, `spinning down` | `stop`. |
-| `tear down`, `tears down`, `tore down`, `torn down`, `tearing down` | `remove`. |
-| `reach out`, `reaches out`, `reached out`, `reaching out` | `ask`. |
-| `dive into`, `dives into`, `dived into`, `dove into`, `diving into` | `examine`. |
-| `kick off`, `kicks off`, `kicked off`, `kicking off` | `start`. |
-| `roll out`, `rolls out`, `rolled out`, `rolling out` | `release`. |
-| `ramp up`, `ramps up`, `ramped up`, `ramping up` | `increase`. |
-| `circle back`, `circles back`, `circled back`, `circling back` | `return`. |
-| `drill down`, `drills down`, `drilled down`, `drilling down` | `examine`. |
+Reports listed forms and supplies their suggestion.
+The bundled forms and suggestions are in [`src/dictionary/data/phrasal-verbs.json`](src/dictionary/data/phrasal-verbs.json).
 
 Matching does not depend on letter case.
 A phrase match stays on one source line.
 
-### `semicolon`
+#### `semicolon`
 
 Default: hard.
-Reports each semicolon and asks for two sentences.
-This rule also checks semicolons inside inline Markdown code.
+Reports each prose semicolon and asks for two sentences.
 
-### `sentence-length`
+#### `sentence-length`
 
 Default: hard.
 Reports a sentence above `maxSentenceWords`.
 The default maximum is 25 words.
+Sentence segmentation recognizes only `e.g.`, `i.e.`, `etc.`, `vs.`, `Fig.`, `No.`, and a single capital letter followed by a period as abbreviation forms.
+It keeps an abbreviation in the current sentence when lowercase prose follows it.
+It preserves a sentence boundary before capitalized prose, except after a single capital letter or before a short `Fig.` or `No.` designator such as `Fig. A` or `No. 7`.
+Markdown block boundaries stop abbreviation lookahead.
 
-### `verb-progressive`
+#### `verb-progressive`
 
 Default: hard.
 Reports a form of `be` followed by an `-ing` verb, with optional adverbs or `not` between them.
 
-### `verb-passive`
+#### `verb-passive`
 
 Default: soft.
 Reports a form of `be` followed by a past participle, with optional adverbs or `not` between them.
 
-### `verb-perfect`
+Before either rule reports a finding, it checks the exact tagged token against the [bundled adjectival-participle allowlist](src/dictionary/data/adjectival-participles.json).
+The `ruleDataExtensions.adjectival-participle` configuration extends that allowlist.
+
+#### `verb-perfect`
 
 Default: hard.
 Reports auxiliary `have` followed by a past participle, with optional adverbs or `not` between them.
 
 The three verb rules and applicable dictionary entries use the bundled English part-of-speech tagger.
 
+### Directive validation
+
+#### `invalid-suppression`
+
+Default: hard.
+Reports a suppression directive that has no rule ID or names an unknown rule ID.
+
+### House-style rules
+
+These rules define package house style.
+They do not come from ASD-STE100.
+The default config enables both rules.
+
+#### `hedging`
+
+Default: soft.
+Reports the phrases in [`src/dictionary/data/hedging.json`](src/dictionary/data/hedging.json).
+A phrase match stays on one source line.
+
+#### `marketing`
+
+Default: soft.
+Reports complete listed forms from [`src/dictionary/data/marketing.json`](src/dictionary/data/marketing.json).
+A multi-word form stays on one source line.
+Matching does not depend on letter case, and the rule also reports the first listed single-token component of a hyphenated token.
+
 ## Dictionary and attribution
 
 The package vendors dictionary data converted from Cameron Moore's MIT-licensed [`ctotheameron/pi-ste`](https://github.com/ctotheameron/pi-ste).
@@ -412,8 +497,18 @@ This package does not include the official specification or the complete ASD dic
 Get the current official specification from the [ASD-STE100 site](https://www.asd-ste100.org/).
 This project has no affiliation with or endorsement from ASD.
 
-The package dictionary format and match rules are in [`src/dictionary/README.md`](src/dictionary/README.md).
-Set `SIMPLE_ENGLISH_DICTIONARY` to a replacement dictionary file if necessary.
+The package dictionary format and token rules are in [`src/dictionary/README.md`](src/dictionary/README.md).
+
+To create an approved-word list, use your own licensed copy of the current ASD-STE100 specification.
+Extract the approved words into the [package approved-word list format](src/dictionary/README.md#approved-word-list).
+Follow that format's exact surface-form requirements.
+Add source metadata that identifies your licensed revision and extraction record.
+Repeat the extraction and update the metadata when you adopt a new licensed revision.
+Keep the list private unless your license lets you distribute it.
+This package does not extract, include, or distribute that data.
+See [Configuration](#configuration) to select the list.
+
+Set `SIMPLE_ENGLISH_DICTIONARY` to replace only the bundled not-approved sample.
 Hook mode resolves a relative replacement path from the session working directory.
 A lint command reports a replacement dictionary load error and continues with all other rules.
 The enabled pi Adapter fails closed after that error.
@@ -423,6 +518,7 @@ The enabled pi Adapter fails closed after that error.
 ```sh
 bun install
 bun run test
+bun run bench:markdown
 bun run lint
 bun run typecheck
 npm publish --dry-run

package/commands/ste.md

@@ -1,5 +1,5 @@
 ---
-description: Control STE for this Claude Code session
+description: Control writing-rule enforcement for this Claude Code session
 argument-hint: on|off|status|strict|strict off
 allowed-tools: Bash
 disable-model-invocation: true

package/hooks/hooks.json

@@ -1,5 +1,5 @@
 {
-  "description": "Inject active STE rules, gate changes, and return reply feedback on the next prompt.",
+  "description": "Inject active writing rules, gate changes, and return reply feedback on the next prompt.",
 
   "hooks": {
     "SessionStart": [

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "agent-simple-english",
-  "version": "0.1.0",
-  "description": "ASD-STE100 Simplified Technical English lint engine, CLI, and host adapters",
+  "version": "0.2.0",
+  "description": "Technical and house-style English lint engine, CLI, and host adapters",
   "license": "MIT",
   "type": "module",
   "author": {
@@ -33,11 +33,22 @@
   },
   "scripts": {
     "test": "vitest run",
+    "bench:markdown": "vitest bench test/engine/markdown.bench.ts",
     "lint": "biome check .",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
+    "@lezer/html": "^1.3.12",
+    "@lezer/markdown": "^1.7.2",
     "effect": "^3.14.0",
+    "micromark": "^4.0.2",
+    "micromark-extension-frontmatter": "^2.0.0",
+    "micromark-extension-gfm-table": "^2.1.1",
+    "micromark-util-character": "^2.1.1",
+    "micromark-util-html-tag-name": "^2.0.1",
+    "micromark-util-normalize-identifier": "^2.0.1",
+    "micromark-util-types": "^2.0.2",
+    "unicode-case-folding": "^1.1.1",
     "wink-eng-lite-web-model": "^1.8.1",
     "wink-nlp": "^2.4.0"
   },

package/src/adapter/feedback.ts

@@ -8,8 +8,9 @@ function suggestedFix(violation: Violation): string {
   }
   const fixes: Readonly<Record<RuleId, string>> = {
     contraction: "Write the contracted words in full.",
-    "dictionary-not-approved-word": "Replace the unapproved word with an approved alternative.",
+    "dictionary-not-approved-word": "Use a word from the approved-word list.",
     hedging: "Delete the hedging phrase.",
+    "invalid-suppression": "Name one or more registered rule IDs.",
     marketing: "Replace the phrase with factual language.",
     "paragraph-length": "Split the paragraph into shorter paragraphs.",
     "phrasal-verb": "Replace the phrasal verb with one approved verb.",

package/src/adapter/rule-summary.ts

@@ -7,6 +7,7 @@ const DEFAULT_RULE_SETTINGS: Readonly<Record<RuleId, RuleSetting>> = {
   contraction: "hard",
   "dictionary-not-approved-word": "hard",
   hedging: "soft",
+  "invalid-suppression": "hard",
   marketing: "soft",
   "paragraph-length": "hard",
   "phrasal-verb": "hard",
@@ -21,6 +22,7 @@ export const RULE_SUMMARIES: Readonly<Record<RuleId, string>> = {
   contraction: "Do not use contractions. Write the words in full.",
   "dictionary-not-approved-word": "Use approved words from the STE dictionary.",
   hedging: "Remove hedging phrases.",
+  "invalid-suppression": "Name registered rule IDs in suppression directives.",
   marketing: "Use factual language instead of marketing language.",
   "paragraph-length": "Use no more than six sentences in one paragraph.",
   "phrasal-verb": "Use an approved single-word verb instead of a phrasal verb.",
@@ -63,9 +65,16 @@ export function formatStatusSummary(
   ].join("\n")
 }
 
-export function ruleSummary(config: SteConfig): string {
-  const maxSentenceWords = config.maxSentenceWords ?? DEFAULT_MAX_SENTENCE_WORDS
-  const rules = (Object.keys(RULE_SUMMARIES) as RuleId[])
+const HOUSE_STYLE_RULE_IDS: ReadonlySet<RuleId> = new Set(["hedging", "marketing"])
+const DIRECTIVE_RULE_IDS: ReadonlySet<RuleId> = new Set(["invalid-suppression"])
+
+function formatRuleGroup(
+  heading: string,
+  ruleIds: readonly RuleId[],
+  config: SteConfig,
+  maxSentenceWords: number,
+): string | undefined {
+  const rules = ruleIds
     .filter((ruleId) => resolvedRuleSetting(config, ruleId) !== "off")
     .map((ruleId) => {
       const summary =
@@ -74,6 +83,38 @@ export function ruleSummary(config: SteConfig): string {
           : RULE_SUMMARIES[ruleId]
       return `- [${resolvedRuleSetting(config, ruleId)}] ${summary}`
     })
-    .join("\n")
-  return `## Simplified Technical English\n\nFollow these STE rules in prose that you write or edit:\n${rules}\n\nWrites, edits, and git commit messages reject hard violations. Correct the reported text and retry. Soft violations produce warnings.`
+  if (rules.length === 0) return undefined
+  return `### ${heading}\n\n${rules.join("\n")}`
+}
+
+export function ruleSummary(config: SteConfig): string {
+  const maxSentenceWords = config.maxSentenceWords ?? DEFAULT_MAX_SENTENCE_WORDS
+  const ruleIds = Object.keys(RULE_SUMMARIES) as RuleId[]
+  const sections = [
+    formatRuleGroup(
+      "Rules derived from ASD-STE100 Simplified Technical English",
+      ruleIds.filter(
+        (ruleId) => !HOUSE_STYLE_RULE_IDS.has(ruleId) && !DIRECTIVE_RULE_IDS.has(ruleId),
+      ),
+      config,
+      maxSentenceWords,
+    ),
+    formatRuleGroup(
+      "Directive validation",
+      ruleIds.filter((ruleId) => DIRECTIVE_RULE_IDS.has(ruleId)),
+      config,
+      maxSentenceWords,
+    ),
+    formatRuleGroup(
+      "House-style rules",
+      ruleIds.filter((ruleId) => HOUSE_STYLE_RULE_IDS.has(ruleId)),
+      config,
+      maxSentenceWords,
+    ),
+  ].filter((section): section is string => section !== undefined)
+  const rules =
+    sections.length === 0
+      ? "No writing rules are enabled."
+      : `Apply these enabled rules to prose that you write or edit:\n\n${sections.join("\n\n")}`
+  return `## Writing rules\n\n${rules}\n\nWrites, edits, and git commit messages reject hard violations. Correct the reported text and retry. Soft violations produce warnings.`
 }