agent-simple-english 0.3.1 → 0.5.0

package/.claude-plugin/marketplace.json

@@ -11,7 +11,7 @@
     {
       "name": "simple-english",
       "description": "Apply technical and house-style writing rules to writes, edits, and git commit messages.",
-      "version": "0.3.1",
+      "version": "0.5.0",
       "author": {
         "name": "JIA YI"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
   "name": "simple-english",
-  "version": "0.3.1",
+  "version": "0.5.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",

package/README.md

@@ -174,7 +174,7 @@ Observation-write failures are silent and do not change the hook output or decis
 
 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.
+Plain lint runs, disabled hook sessions, skipped paths, 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`.
@@ -249,13 +249,14 @@ Soft violations can appear with exit code 0.
 
 ### CLI flags
 
-- `--json` writes one JSON report with `violations` and `summary` fields.
+- `--json` writes one JSON report with `violations`, `summary`, and `skipped` fields.
+  The `skipped` array is always present, and it is empty when no input was skipped.
   Each violation includes its offending sentence or paragraph as `snippet`.
 
 - `--config <path>` uses only that config file and disables config discovery.
 
 - `--kind <kind>` sets one content kind for all inputs.
-  Valid values are `prose-file`, `slash-source`, `hash-source`, and `commit-message`.
+  Valid values are `prose-file`, `slash-source`, `hash-source`, `html`, and `commit-message`.
   The form `--kind=<kind>` also works.
 
 - `--help` writes the command usage.
@@ -278,8 +279,45 @@ It is the default for standard input, extensionless paths, and file types that h
 `hash-source` checks comments in these file types:
 `.sh`, `.bash`, `.zsh`, `.py`, `.rb`, `.yaml`, `.yml`, `.toml`, and `.pl`.
 
+`html` checks the text nodes of `.html` and `.htm` files.
+It reads the page as a reader sees it, and it ignores everything else.
+
 `commit-message` checks the complete input as a commit message.
 
+A skipped path carries no check.
+These extensions skip every check: `.css`, `.scss`, `.less`, `.json`, `.jsonc`, `.svg`, `.xml`, `.typ`, `.csv`, `.tsv`, and `.lock`.
+An extensionless path still uses `prose-file`.
+The Claude Code hook and the pi write and edit gates allow a skipped path with no lint.
+The CLI prints one line that names a skipped file and exits 0.
+An explicit `--kind` flag forces a lint on a skipped file.
+
+#### The html kind
+
+The `html` kind parses the page and keeps only its text nodes.
+It drops tags, attribute values, comments, entity references, and doctype declarations.
+It also drops the content of `script`, `style`, `pre`, `code`, and `textarea`.
+A semicolon in a style rule or an inline script stays quiet.
+A semicolon in a paragraph reports a violation at its original column.
+
+Each prose block is one unit for the sentence rules and the paragraph rule.
+A sentence split across phrasing elements counts as one sentence.
+These phrasing elements stay inside their prose block:
+
+```text
+a abbr b bdi bdo cite code data del dfn em i img ins kbd label mark q rp rt
+ruby s samp small span strong sub sup time u var wbr
+```
+
+Every other element starts a new prose block.
+That rule separates each of these elements from its neighbours:
+
+```text
+p li h1 h2 h3 h4 h5 h6 td th blockquote figcaption dt dd title br
+```
+
+Bare text directly inside `div`, `section`, or `body` is a prose block of its own.
+An unknown element also starts a prose block.
+
 File extension matching does not depend on letter case.
 Source kinds ignore comment markers inside supported string literal forms.
 All kinds preserve the original line and column.
@@ -288,7 +326,7 @@ They ignore identifiers, YAML frontmatter, valid GFM tables, and fenced, indente
 ### 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:
+Use this comment form in prose files and in HTML pages:
 
 ```md
 <!-- ste-disable-next-line marketing -->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-simple-english",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "description": "Technical and house-style English lint engine, CLI, and host adapters",
   "license": "MIT",
   "type": "module",
@@ -15,9 +15,15 @@
   "bugs": {
     "url": "https://github.com/jyooi/agent-simple-english/issues"
   },
-  "keywords": ["pi-package", "simplified-technical-english", "linter"],
+  "keywords": [
+    "pi-package",
+    "simplified-technical-english",
+    "linter"
+  ],
   "pi": {
-    "extensions": ["./src/extension/index.ts"]
+    "extensions": [
+      "./src/extension/index.ts"
+    ]
   },
   "files": [
     ".claude-plugin",
@@ -40,7 +46,7 @@
   "dependencies": {
     "@lezer/html": "^1.3.12",
     "@lezer/markdown": "^1.7.2",
-    "effect": "^3.14.0",
+    "effect": "4.0.0-rc.112",
     "micromark": "^4.0.2",
     "micromark-extension-frontmatter": "^2.0.0",
     "micromark-extension-gfm-table": "^2.1.1",
@@ -65,12 +71,12 @@
     }
   },
   "devDependencies": {
-    "@biomejs/biome": "^1.9.4",
-    "@earendil-works/pi-coding-agent": "0.83.0",
-    "@types/node": "^22.0.0",
+    "@biomejs/biome": "^2.5.12",
+    "@earendil-works/pi-coding-agent": "0.85.1",
+    "@types/node": "^26.0.0",
     "jiti": "2.7.0",
     "typebox": "1.3.7",
     "typescript": "^5.8.0",
-    "vitest": "^3.0.0"
+    "vitest": "^5.0.0"
   }
 }

package/src/cli/hook.ts

@@ -14,9 +14,9 @@ import type { Tagger } from "../engine/tagger.ts"
 import type { LintKind, LintOptions, ReportViolation } from "../engine/types.ts"
 import { TaggerService } from "../tagger/wink.ts"
 import {
+  appendObservation,
   type ObservationDraft,
   type ObservationEvent,
-  appendObservation,
 } from "./observation-log.ts"
 import {
   consumePendingFeedback,
@@ -585,6 +585,9 @@ function textDecision(
   previousText?: string,
 ): HookEvaluation {
   const classification = classifyPath(path)
+  if (classification.skipped) {
+    return { output: allow() }
+  }
   const report = lint(classification.kind, text, {
     ...options,
     sourceDialect: classification.sourceDialect,
@@ -712,7 +715,7 @@ function recordEvaluation(event: HookEvent, evaluation: HookEvaluation): Effect.
       }),
     catch: () => undefined,
   }).pipe(
-    Effect.catchAll(() => Effect.void),
+    Effect.catch(() => Effect.void),
     Effect.as(evaluation.output),
   )
 }
@@ -757,14 +760,14 @@ export function runHookMode(raw: string): Effect.Effect<HookOutput, never, Tagge
               return yield* recordEvaluation(event, evaluation)
             })
           }),
-          Effect.catchAll((error) =>
+          Effect.catch((error) =>
             Effect.succeed(
               event.hookEventName === "PreToolUse"
                 ? nonBlockingWarning(error.message)
                 : nonBlockingError(error.message),
             ),
           ),
-          Effect.catchAllCause((cause) =>
+          Effect.catchCause((cause) =>
             Effect.succeed(
               event.hookEventName === "PreToolUse"
                 ? hookInternalFailure(cause)

package/src/cli/main.ts

@@ -1,11 +1,11 @@
 #!/usr/bin/env bun
 import { readFile } from "node:fs/promises"
-import { Effect, Either } from "effect"
+import { Effect, Result } from "effect"
 import packageManifest from "../../package.json" with { type: "json" }
 import { loadConfig } from "../config/load.ts"
 import { loadConfiguredDictionary } from "../dictionary/configured.ts"
 import { loadRuleData } from "../dictionary/load.ts"
-import { classifyPath } from "../engine/kinds.ts"
+import { classifyPath, type PathClassification } from "../engine/kinds.ts"
 import { lint } from "../engine/lint.ts"
 import type { LintKind, LintReport } from "../engine/types.ts"
 import { TaggerService, WinkTaggerLive } from "../tagger/wink.ts"
@@ -13,7 +13,13 @@ import { hookInternalFailure, runHookMode } from "./hook.ts"
 import { observationStats, reviewObservations } from "./observation-log.ts"
 import { runSessionCommand } from "./session-command.ts"
 
-const KINDS: readonly LintKind[] = ["prose-file", "slash-source", "hash-source", "commit-message"]
+const KINDS: readonly LintKind[] = [
+  "prose-file",
+  "slash-source",
+  "hash-source",
+  "html",
+  "commit-message",
+]
 
 const USAGE = `Usage: simple-english [options] [paths...]
        simple-english observe review
@@ -102,6 +108,7 @@ interface FileViolation {
 interface CliReport {
   readonly violations: readonly FileViolation[]
   readonly summary: { readonly total: number; readonly hard: number }
+  readonly skipped: readonly string[]
 }
 
 const readStdin = Effect.promise(async () => {
@@ -120,7 +127,10 @@ const readInput = (path: string) =>
         catch: (cause) => new Error(`cannot read ${path}: ${cause}`),
       }).pipe(Effect.map((text) => ({ path, text })))
 
-const toCliReport = (reports: readonly { path: string; report: LintReport }[]): CliReport => {
+const toCliReport = (
+  reports: readonly { path: string; report: LintReport }[],
+  skipped: readonly string[],
+): CliReport => {
   const violations = reports.flatMap(({ path, report }) =>
     report.violations.map((violation) => ({ file: path, ...violation })),
   )
@@ -130,6 +140,7 @@ const toCliReport = (reports: readonly { path: string; report: LintReport }[]):
       total: violations.length,
       hard: violations.filter((violation) => violation.severity === "hard").length,
     },
+    skipped,
   }
 }
 
@@ -137,9 +148,13 @@ const render = (report: CliReport, json: boolean): string => {
   if (json) {
     return JSON.stringify(report, null, 2)
   }
-  return report.violations
-    .map((v) => `${v.file}:${v.line}:${v.column} [${v.severity}] ${v.ruleId} ${v.message}`)
-    .join("\n")
+  const lines = [
+    ...report.skipped.map((path) => `${path}: skipped (non-prose extension)`),
+    ...report.violations.map(
+      (v) => `${v.file}:${v.line}:${v.column} [${v.severity}] ${v.ruleId} ${v.message}`,
+    ),
+  ]
+  return lines.join("\n")
 }
 
 const args = process.argv.slice(2)
@@ -149,7 +164,7 @@ const hookProgram = Effect.gen(function* () {
   console.log(JSON.stringify(output))
   return 0
 }).pipe(
-  Effect.catchAllCause((cause) =>
+  Effect.catchCause((cause) =>
     Effect.sync(() => {
       console.log(JSON.stringify(hookInternalFailure(cause)))
       return 0
@@ -205,40 +220,49 @@ const lintProgram = Effect.gen(function* () {
     )
   }
   const config = yield* loadConfig(configPath)
-  const loadedDictionary = yield* Effect.either(
+  const loadedDictionary = yield* Effect.result(
     loadConfiguredDictionary(config, process.cwd(), process.env.SIMPLE_ENGLISH_DICTIONARY),
   )
-  const loadedRuleData = yield* Effect.either(loadRuleData(config.ruleDataExtensions))
-  if (Either.isLeft(loadedDictionary) && config.approvedWordsPath !== undefined) {
-    return yield* Effect.fail(loadedDictionary.left)
+  const loadedRuleData = yield* Effect.result(loadRuleData(config.ruleDataExtensions))
+  if (Result.isFailure(loadedDictionary) && config.approvedWordsPath !== undefined) {
+    return yield* Effect.fail(loadedDictionary.failure)
   }
-  const dictionary = Either.getOrUndefined(loadedDictionary)
-  const ruleData = Either.getOrUndefined(loadedRuleData)
-  if (Either.isLeft(loadedDictionary)) {
-    yield* Effect.sync(() => console.error(loadedDictionary.left.message))
+  const dictionary = Result.getOrUndefined(loadedDictionary)
+  const ruleData = Result.getOrUndefined(loadedRuleData)
+  if (Result.isFailure(loadedDictionary)) {
+    yield* Effect.sync(() => console.error(loadedDictionary.failure.message))
   }
-  if (Either.isLeft(loadedRuleData)) {
-    yield* Effect.sync(() => console.error(loadedRuleData.left.message))
+  if (Result.isFailure(loadedRuleData)) {
+    yield* Effect.sync(() => console.error(loadedRuleData.failure.message))
   }
   const inputs =
     paths.length === 0
       ? [{ path: "<stdin>", text: yield* readStdin }]
       : yield* Effect.forEach(paths, readInput)
 
+  const skippedPaths: string[] = []
+  const lintable: { path: string; text: string; classification: PathClassification }[] = []
+  for (const input of inputs) {
+    const classification = classifyPath(input.path)
+    if (kind === undefined && classification.skipped) {
+      skippedPaths.push(input.path)
+      continue
+    }
+    lintable.push({ ...input, classification })
+  }
+
   const report = toCliReport(
-    inputs.map(({ path, text }) => {
-      const classification = classifyPath(path)
-      return {
-        path,
-        report: lint(kind ?? classification.kind, text, {
-          ...config,
-          dictionary,
-          ruleData,
-          tagger,
-          sourceDialect: classification.sourceDialect,
-        }),
-      }
-    }),
+    lintable.map(({ path, text, classification }) => ({
+      path,
+      report: lint(kind ?? classification.kind, text, {
+        ...config,
+        dictionary,
+        ruleData,
+        tagger,
+        sourceDialect: classification.sourceDialect,
+      }),
+    })),
+    skippedPaths,
   )
 
   const output = render(report, json)
@@ -258,7 +282,7 @@ const program: Effect.Effect<number, Error> =
         : lintProgram.pipe(Effect.provide(WinkTaggerLive))
 
 const handled = program.pipe(
-  Effect.catchAll((error) =>
+  Effect.catch((error) =>
     Effect.sync(() => {
       console.error(error.message)
       return 2

package/src/cli/observation-log.ts

@@ -1,5 +1,5 @@
 import { createHash, randomUUID } from "node:crypto"
-import { mkdir, open, readFile, readdir } from "node:fs/promises"
+import { mkdir, open, readdir, readFile } from "node:fs/promises"
 import { join } from "node:path"
 import { createInterface } from "node:readline"
 import type { LintKind, ReportViolation } from "../engine/types.ts"

package/src/cli/session-command.ts

@@ -1,12 +1,12 @@
 import { resolve } from "node:path"
-import { Effect, Either } from "effect"
+import { Effect, Result } from "effect"
 import { formatFailedStatusSummary, formatStatusSummary } from "../adapter/rule-summary.ts"
 import { loadConfig } from "../config/load.ts"
 import { loadConfiguredDictionary } from "../dictionary/configured.ts"
 import { loadRuleData } from "../dictionary/load.ts"
 import {
-  type SessionControl,
   getSessionControl,
+  type SessionControl,
   setSessionEnabled,
   setSessionStrict,
   toggleSessionEnabled,
@@ -48,25 +48,25 @@ const updateStrict = (sessionId: string, strict: boolean) =>
 function status(sessionId: string, cwd: string): Effect.Effect<string, Error> {
   return Effect.gen(function* () {
     const control = yield* readControl(sessionId)
-    const configResult = yield* Effect.either(loadConfig(undefined, cwd))
-    if (Either.isLeft(configResult)) {
-      return formatFailedStatusSummary(modeName(control), configResult.left.message)
+    const configResult = yield* Effect.result(loadConfig(undefined, cwd))
+    if (Result.isFailure(configResult)) {
+      return formatFailedStatusSummary(modeName(control), configResult.failure.message)
     }
     const dictionaryPath = process.env.SIMPLE_ENGLISH_DICTIONARY
-    const dictionaryResult = yield* Effect.either(
+    const dictionaryResult = yield* Effect.result(
       Effect.all({
         dictionary: loadConfiguredDictionary(
-          configResult.right,
+          configResult.success,
           cwd,
           dictionaryPath === undefined ? undefined : resolve(cwd, dictionaryPath),
         ),
-        ruleData: loadRuleData(configResult.right.ruleDataExtensions, cwd),
+        ruleData: loadRuleData(configResult.success.ruleDataExtensions, cwd),
       }),
     )
-    const dictionary: DictionaryState = Either.isRight(dictionaryResult)
+    const dictionary: DictionaryState = Result.isSuccess(dictionaryResult)
       ? "loaded"
-      : `failed (${dictionaryResult.left.message})`
-    return formatStatusSummary(configResult.right, modeName(control), dictionary)
+      : `failed (${dictionaryResult.failure.message})`
+    return formatStatusSummary(configResult.success, modeName(control), dictionary)
   })
 }
 

package/src/config/load.ts

@@ -3,7 +3,7 @@ import { homedir } from "node:os"
 import { isAbsolute, join, resolve } from "node:path"
 import { Effect } from "effect"
 import { mergeConfigs } from "./merge.ts"
-import { ConfigError, type SteConfig, decodeConfig } from "./schema.ts"
+import { ConfigError, decodeConfig, type SteConfig } from "./schema.ts"
 
 const legacyAgentConfigDirectory = (cwd: string): string => {
   const configured = process.env.PI_CODING_AGENT_DIR

package/src/config/schema.ts

@@ -1,7 +1,13 @@
-import { Effect, ParseResult, Schema } from "effect"
+import { Effect, Schema } from "effect"
 import type { RuleDataExtensions } from "../dictionary/rule-data.ts"
 import { type RuleId, ruleIds } from "../engine/rules/registry.ts"
 import type { RuleSetting } from "../engine/types.ts"
+import {
+  formatParseErrorIssues,
+  formatParseErrorTree,
+  type ParseError,
+} from "../schema/parse-error.ts"
+import { NonEmptyTrimmedString } from "../schema/primitives.ts"
 
 export interface SteConfig {
   readonly rules?: Partial<Readonly<Record<RuleId, RuleSetting>>>
@@ -11,63 +17,53 @@ export interface SteConfig {
   readonly approvedWordsPath?: string
 }
 
-const RuleSettingSchema = Schema.Literal("hard", "soft", "off").annotations({
-  message: (issue) => ({
-    message: `must be "hard", "soft", or "off", got ${JSON.stringify(issue.actual)}`,
-    override: true,
-  }),
+const RuleSettingSchema = Schema.Literals(["hard", "soft", "off"]).annotate({
+  expected: '"hard", "soft", or "off"',
 })
 
-const RulesSchema = Schema.partial(
-  Schema.Struct(Object.fromEntries(ruleIds.map((id) => [id, RuleSettingSchema]))),
+const RulesSchema = Schema.Struct(
+  Object.fromEntries(ruleIds.map((id) => [id, Schema.optionalKey(RuleSettingSchema)])),
 )
 
-const MaxSentenceWordsSchema = Schema.Int.pipe(Schema.positive()).annotations({
-  message: (issue) => ({
-    message: `must be a positive integer, got ${JSON.stringify(issue.actual)}`,
-    override: true,
-  }),
-})
+// One refinement over Unknown, rather than Number plus two checks, so that a
+// wrong type and a wrong number both report the same text and the value.
+const MaxSentenceWordsSchema = Schema.Unknown.pipe(
+  Schema.refine(
+    (value): value is number => typeof value === "number" && Number.isInteger(value) && value > 0,
+    { expected: "a positive integer" },
+  ),
+)
 
-const ExemptBlockQuotesSchema = Schema.Boolean.annotations({
-  message: (issue) => ({
-    message: `must be a boolean, got ${JSON.stringify(issue.actual)}`,
-    override: true,
-  }),
-})
+const ExemptBlockQuotesSchema = Schema.Boolean
 
-const RuleDataExtensionsSchema = Schema.partial(
-  Schema.Struct({
-    "phrasal-verb": Schema.Array(Schema.NonEmptyTrimmedString),
-    hedging: Schema.Array(Schema.NonEmptyTrimmedString),
-    marketing: Schema.Array(Schema.NonEmptyTrimmedString),
-    "adjectival-participle": Schema.Array(Schema.NonEmptyTrimmedString),
-  }),
-)
+const RuleDataExtensionsSchema = Schema.Struct({
+  "phrasal-verb": Schema.optionalKey(Schema.Array(NonEmptyTrimmedString)),
+  hedging: Schema.optionalKey(Schema.Array(NonEmptyTrimmedString)),
+  marketing: Schema.optionalKey(Schema.Array(NonEmptyTrimmedString)),
+  "adjectival-participle": Schema.optionalKey(Schema.Array(NonEmptyTrimmedString)),
+})
 
 const SteConfigSchema = Schema.Struct({
-  rules: Schema.optional(RulesSchema),
-  maxSentenceWords: Schema.optional(MaxSentenceWordsSchema),
-  exemptBlockQuotes: Schema.optional(ExemptBlockQuotesSchema),
-  ruleDataExtensions: Schema.optional(RuleDataExtensionsSchema),
-  approvedWordsPath: Schema.optional(Schema.NonEmptyTrimmedString),
+  rules: Schema.optionalKey(RulesSchema),
+  maxSentenceWords: Schema.optionalKey(MaxSentenceWordsSchema),
+  exemptBlockQuotes: Schema.optionalKey(ExemptBlockQuotesSchema),
+  ruleDataExtensions: Schema.optionalKey(RuleDataExtensionsSchema),
+  approvedWordsPath: Schema.optionalKey(NonEmptyTrimmedString),
 })
 
-const decodeUnknown = Schema.decodeUnknown(SteConfigSchema, {
+const decodeUnknown = Schema.decodeUnknownEffect(SteConfigSchema, {
   onExcessProperty: "error",
   errors: "all",
+  // v4 omits the rejected value from an issue unless this option is on.
+  reportInput: true,
 })
 
 export class ConfigError extends Error {
   readonly _tag = "ConfigError"
 }
 
-const formatError = (error: ParseResult.ParseError, source: string): string => {
-  // Optional fields decode as `T | undefined` unions, so every failure also
-  // reports a useless "Expected undefined" branch; drop those.
-  const issues = ParseResult.ArrayFormatter.formatErrorSync(error).filter(
-    (issue) => !issue.message.startsWith("Expected undefined"),
-  )
+const formatError = (error: ParseError, source: string): string => {
+  const issues = formatParseErrorIssues(error)
   const lines = [
     ...new Set(
       issues.map(
@@ -78,7 +74,7 @@ const formatError = (error: ParseResult.ParseError, source: string): string => {
   const detail =
     lines.length > 0
       ? lines.map((line) => `  ${line}`).join("\n")
-      : `  ${ParseResult.TreeFormatter.formatErrorSync(error)}`
+      : `  ${formatParseErrorTree(error)}`
   return `invalid config in ${source}:\n${detail}`
 }
 

package/src/dictionary/load.ts

@@ -1,7 +1,8 @@
 import { readFile } from "node:fs/promises"
 import { resolve } from "node:path"
 import { fileURLToPath } from "node:url"
-import { Effect, ParseResult, Schema } from "effect"
+import { Effect, Schema } from "effect"
+import { formatParseErrorIssues, type ParseError } from "../schema/parse-error.ts"
 import type { RuleData, RuleDataExtensions, RuleDataId } from "./rule-data.ts"
 import {
   type ApprovedWordList,
@@ -34,8 +35,8 @@ export class DictionaryLoadError extends Error {
   }
 }
 
-const formatParseError = (error: ParseResult.ParseError): string => {
-  const issue = ParseResult.ArrayFormatter.formatErrorSync(error)[0]
+const formatParseError = (error: ParseError): string => {
+  const issue = formatParseErrorIssues(error)[0]
   if (issue === undefined) {
     return "invalid dictionary data"
   }
@@ -48,15 +49,15 @@ const formatParseError = (error: ParseResult.ParseError): string => {
   return path === "" ? `invalid dictionary data: ${issue.message}` : `${path}: ${issue.message}`
 }
 
-const decodeDictionary = Schema.decode(Schema.parseJson(DictionarySchema), {
-  onExcessProperty: "error",
-  errors: "all",
-})
+// v4 omits the rejected value from an issue unless reportInput is on.
+const decodeOptions = { onExcessProperty: "error", errors: "all", reportInput: true } as const
 
-const decodeApprovedWordList = Schema.decode(Schema.parseJson(ApprovedWordListSchema), {
-  onExcessProperty: "error",
-  errors: "all",
-})
+const decodeDictionary = Schema.decodeEffect(Schema.fromJsonString(DictionarySchema), decodeOptions)
+
+const decodeApprovedWordList = Schema.decodeEffect(
+  Schema.fromJsonString(ApprovedWordListSchema),
+  decodeOptions,
+)
 
 const readDictionaryFile = (
   path: string,

package/src/dictionary/schema.ts

@@ -1,25 +1,22 @@
 import { Schema } from "effect"
+import { NonEmptyTrimmedString } from "../schema/primitives.ts"
 import { DICTIONARY_FORM_PATTERN, DICTIONARY_WORD_PATTERN } from "./form.ts"
 
 const DictionarySourceSchema = Schema.Struct({
-  name: Schema.NonEmptyTrimmedString,
-  repository: Schema.NonEmptyTrimmedString,
-  commit: Schema.NonEmptyTrimmedString,
-  path: Schema.NonEmptyTrimmedString,
+  name: NonEmptyTrimmedString,
+  repository: NonEmptyTrimmedString,
+  commit: NonEmptyTrimmedString,
+  path: NonEmptyTrimmedString,
 })
 
-const DictionaryFormSchema = Schema.NonEmptyTrimmedString.pipe(
-  Schema.pattern(DICTIONARY_FORM_PATTERN),
-)
+const DictionaryFormSchema = NonEmptyTrimmedString.check(Schema.isPattern(DICTIONARY_FORM_PATTERN))
 
-const DictionaryWordSchema = Schema.NonEmptyTrimmedString.pipe(
-  Schema.pattern(DICTIONARY_WORD_PATTERN),
-)
+const DictionaryWordSchema = NonEmptyTrimmedString.check(Schema.isPattern(DICTIONARY_WORD_PATTERN))
 
 const DictionaryEntrySchema = Schema.Struct({
   unapproved: Schema.NonEmptyArray(DictionaryFormSchema),
-  suggestions: Schema.NonEmptyArray(Schema.NonEmptyTrimmedString),
-  partsOfSpeech: Schema.optional(Schema.NonEmptyArray(Schema.NonEmptyTrimmedString)),
+  suggestions: Schema.NonEmptyArray(NonEmptyTrimmedString),
+  partsOfSpeech: Schema.optional(Schema.NonEmptyArray(NonEmptyTrimmedString)),
 })
 
 export const DictionarySchema = Schema.Struct({

package/src/engine/comments.ts

@@ -354,7 +354,7 @@ interface YamlBlockScalar {
 const leadingSpaces = (line: string): number => line.length - line.replace(/^ */u, "").length
 const YAML_BLOCK_SCALAR_CONTEXT = /(?:^[ \t]*(?:[-?:][ \t]+)*|:[ \t]+)(?:[&!][^\s]+[ \t]+)*$/u
 const YAML_QUOTED_SCALAR_CONTEXT =
-  /(?:^[ \t]*(?:(?:---|\.\.\.)[ \t]+)?(?:[-?:][ \t]+)*|:[ \t]+|[\[{,][ \t]*)(?:[&!][^\s,[\]{}]+[ \t]+)*$/u
+  /(?:^[ \t]*(?:(?:---|\.\.\.)[ \t]+)?(?:[-?:][ \t]+)*|:[ \t]+|[[{,][ \t]*)(?:[&!][^\s,[\]{}]+[ \t]+)*$/u
 
 const isYamlQuotedScalarStart = (line: string, index: number): boolean =>
   YAML_QUOTED_SCALAR_CONTEXT.test(line.slice(0, index))

package/src/engine/html.ts

@@ -0,0 +1,158 @@
+import { parser as htmlParser } from "@lezer/html"
+import type { ExtractedComments, ProseBreak } from "./comments.ts"
+import type { MarkdownHtmlComment } from "./markdown.ts"
+
+// These elements hold code, markup, or preformatted content, never prose.
+// `code` is also inline, so a semicolon in inline code stays quiet while the
+// sentence around it still reads as one sentence.
+const IGNORED_CONTENT_TAGS = new Set(["code", "pre", "script", "style", "textarea"])
+
+// Phrasing elements that wrap words inside one sentence.
+// They never start a prose block, so a sentence split across them counts as one sentence.
+// Every other element starts a prose block.
+// That rule separates a heading, a list item, a table cell, and bare text in a `div`.
+const INLINE_TAGS = new Set([
+  "a",
+  "abbr",
+  "b",
+  "bdi",
+  "bdo",
+  "cite",
+  "code",
+  "data",
+  "del",
+  "dfn",
+  "em",
+  "i",
+  "img",
+  "ins",
+  "kbd",
+  "label",
+  "mark",
+  "q",
+  "rp",
+  "rt",
+  "ruby",
+  "s",
+  "samp",
+  "small",
+  "span",
+  "strong",
+  "sub",
+  "sup",
+  "time",
+  "u",
+  "var",
+  "wbr",
+])
+
+/**
+ * Find every single-line HTML comment in the document with the lezer parser.
+ * The markdown finder cannot see comments that markdown would read as indented code.
+ */
+export function htmlComments(source: string): readonly MarkdownHtmlComment[] {
+  const comments: MarkdownHtmlComment[] = []
+  const lineStarts = [0]
+  for (let offset = 0; offset < source.length; offset++) {
+    if (source.charCodeAt(offset) === 0x0a) lineStarts.push(offset + 1)
+  }
+
+  htmlParser.parse(source).iterate({
+    enter(ref) {
+      if (ref.name !== "Comment") return
+      const text = source.slice(ref.from, ref.to)
+      if (text.includes("\n")) return
+
+      let lineIndex = lineStarts.length - 1
+      while (lineIndex > 0 && (lineStarts[lineIndex] as number) > ref.from) lineIndex -= 1
+      const lineStart = lineStarts[lineIndex] as number
+      comments.push({
+        line: lineIndex + 1,
+        startColumn: ref.from - lineStart,
+        endColumn: ref.to - lineStart,
+        text,
+      })
+    },
+  })
+
+  return comments
+}
+
+interface OpenElement {
+  readonly tag: string
+  readonly inline: boolean
+}
+
+/**
+ * Keep the text nodes of an HTML document and blank every other byte with a space.
+ * Attribute values, comments, entity references, tags, and ignored element content all go.
+ * Each prose block becomes one prose break, so sentences never join across a block edge.
+ * The masked lines keep the width of the source lines, so positions stay exact.
+ */
+export function extractHtmlProse(source: string): ExtractedComments {
+  const keep = new Uint8Array(source.length)
+  const blockEdges: number[] = []
+  const open: OpenElement[] = []
+  let ignoreDepth = 0
+
+  htmlParser.parse(source).iterate({
+    enter(ref) {
+      if (ref.name === "Element") {
+        const tagName = ref.node.firstChild?.getChild("TagName")
+        const tag =
+          tagName === null || tagName === undefined
+            ? ""
+            : source.slice(tagName.from, tagName.to).toLowerCase()
+        const inline = INLINE_TAGS.has(tag)
+        if (!inline) blockEdges.push(ref.from)
+        if (IGNORED_CONTENT_TAGS.has(tag)) ignoreDepth += 1
+        open.push({ tag, inline })
+        return
+      }
+      if (ref.name === "Text" && ignoreDepth === 0) keep.fill(1, ref.from, ref.to)
+    },
+    leave(ref) {
+      if (ref.name !== "Element") return
+      const element = open.pop()
+      if (element === undefined) return
+      if (IGNORED_CONTENT_TAGS.has(element.tag)) ignoreDepth -= 1
+      if (!element.inline) blockEdges.push(ref.to)
+    },
+  })
+
+  blockEdges.sort((left, right) => left - right)
+
+  const lines = source.split("\n")
+  const contentStarts: number[] = []
+  const proseBreaks: ProseBreak[] = []
+  let lineStart = 0
+  let edgeIndex = 0
+  let blockIndex = -1
+
+  const maskedLines = lines.map((line, lineIndex) => {
+    const characters = new Array<string>(line.length).fill(" ")
+    let contentStart = -1
+
+    for (let column = 0; column < line.length; column += 1) {
+      const offset = lineStart + column
+      while (edgeIndex < blockEdges.length && (blockEdges[edgeIndex] as number) <= offset) {
+        edgeIndex += 1
+      }
+      if (keep[offset] === 0) continue
+
+      const character = source[offset] as string
+      characters[column] = character
+      if (/\s/u.test(character)) continue
+      if (contentStart === -1) contentStart = column
+      if (edgeIndex === blockIndex) continue
+      if (blockIndex !== -1) proseBreaks.push({ line: lineIndex, column })
+      blockIndex = edgeIndex
+    }
+
+    lineStart += line.length + 1
+    contentStarts.push(contentStart === -1 ? line.length : contentStart)
+    return characters.join("")
+  })
+
+  return { lines: maskedLines, contentStarts, proseBreaks, lineComments: [] }
+}

package/src/engine/kinds.ts

@@ -24,10 +24,28 @@ const SLASH_EXTENSIONS = new Set([
 const JAVASCRIPT_EXTENSIONS = new Set(["ts", "tsx", "js", "jsx", "mjs", "cjs"])
 const NESTED_SLASH_EXTENSIONS = new Set(["rs", "swift", "kt", "scala"])
 const HASH_EXTENSIONS = new Set(["sh", "bash", "zsh", "py", "rb", "yaml", "yml", "toml", "pl"])
+const HTML_EXTENSIONS = new Set(["html", "htm"])
+
+// Data and style extensions carry rules and structured data rather than prose,
+// so the writing rules would misread them as sentences (HUF-308).
+const SKIP_EXTENSIONS = new Set([
+  "css",
+  "scss",
+  "less",
+  "json",
+  "jsonc",
+  "svg",
+  "xml",
+  "typ",
+  "csv",
+  "tsv",
+  "lock",
+])
 
 export interface PathClassification {
   readonly kind: LintKind
   readonly sourceDialect: SourceDialect
+  readonly skipped?: true
 }
 
 export const classifyPath = (path: string): PathClassification => {
@@ -36,6 +54,12 @@ export const classifyPath = (path: string): PathClassification => {
     return { kind: "prose-file", sourceDialect: "general" }
   }
   const extension = path.slice(dot + 1).toLowerCase()
+  if (SKIP_EXTENSIONS.has(extension)) {
+    return { kind: "prose-file", sourceDialect: "general", skipped: true }
+  }
+  if (HTML_EXTENSIONS.has(extension)) {
+    return { kind: "html", sourceDialect: "general" }
+  }
   if (SLASH_EXTENSIONS.has(extension)) {
     const sourceDialect = JAVASCRIPT_EXTENSIONS.has(extension)
       ? "javascript"

package/src/engine/lint.ts

@@ -1,13 +1,14 @@
 import { BUNDLED_RULE_DATA } from "../dictionary/bundled-rule-data.ts"
 import type { RuleData } from "../dictionary/rule-data.ts"
 import {
-  type LineCommentSpan,
-  type ProseBreak,
   extractHashComments,
   extractSlashComments,
+  type LineCommentSpan,
+  type ProseBreak,
 } from "./comments.ts"
-import { type ScopedViolation, type ViolationScope, newFindings } from "./diff-match.ts"
 import { changedText } from "./diff.ts"
+import { newFindings, type ScopedViolation, type ViolationScope } from "./diff-match.ts"
+import { extractHtmlProse } from "./html.ts"
 import { blankIdentifiers } from "./identifiers.ts"
 import { blankMarkdownForLint } from "./markdown.ts"
 import { type Paragraph, segmentParagraphs } from "./paragraphs.ts"
@@ -21,7 +22,7 @@ import { semicolon } from "./rules/semicolon.ts"
 import { sentenceLength } from "./rules/sentence-length.ts"
 import { verbForm } from "./rules/verb-form.ts"
 import { type Sentence, segmentSentences } from "./sentences.ts"
-import { type SuppressionRange, analyzeSuppressions } from "./suppression.ts"
+import { analyzeSuppressions, type SuppressionRange } from "./suppression.ts"
 import type { Tagger } from "./tagger.ts"
 import type { LintKind, LintOptions, LintReport, Violation } from "./types.ts"
 
@@ -121,6 +122,7 @@ const splitProseRuns = (extracted: ExtractedProse): readonly ProseRun[] => {
 const extract = (kind: LintKind, text: string, options: LintOptions): ExtractedProse => {
   if (kind === "slash-source") return extractSlashComments(text, options.sourceDialect)
   if (kind === "hash-source") return extractHashComments(text, options.sourceDialect)
+  if (kind === "html") return extractHtmlProse(text)
   return wholeText(text)
 }
 

package/src/engine/suppression.ts

@@ -1,6 +1,7 @@
 import type { LineCommentSpan } from "./comments.ts"
 import type { ScopedViolation } from "./diff-match.ts"
-import { markdownHtmlComments } from "./markdown.ts"
+import { htmlComments } from "./html.ts"
+import { type MarkdownHtmlComment, markdownHtmlComments } from "./markdown.ts"
 import { type RuleId, ruleIds } from "./rules/registry.ts"
 import type { LintKind } from "./types.ts"
 
@@ -54,8 +55,10 @@ const sourceCandidates = (
     ]
   })
 
-const markdownCandidates = (text: string): readonly DirectiveCandidate[] =>
-  markdownHtmlComments(text).flatMap((comment) => {
+const commentCandidates = (
+  comments: readonly MarkdownHtmlComment[],
+): readonly DirectiveCandidate[] =>
+  comments.flatMap((comment) => {
     const match = comment.text.match(markdownDirective)
     if (match === null) return []
 
@@ -139,10 +142,12 @@ export function analyzeSuppressions(
   const lines = text.split("\n")
   const candidates =
     kind === "prose-file"
-      ? markdownCandidates(text)
-      : kind === "slash-source" || kind === "hash-source"
-        ? sourceCandidates(lines, lineComments)
-        : []
+      ? commentCandidates(markdownHtmlComments(text))
+      : kind === "html"
+        ? commentCandidates(htmlComments(text))
+        : kind === "slash-source" || kind === "hash-source"
+          ? sourceCandidates(lines, lineComments)
+          : []
   const directives = candidates.map(parseDirective)
   const offsets = offsetsForLines(lines)
   const ruleIdsByTargetLine = new Map<number, Set<RuleId>>()

package/src/engine/types.ts

@@ -3,7 +3,7 @@ import type { DictionaryData } from "../dictionary/schema.ts"
 import type { RuleId } from "./rules/registry.ts"
 import type { Tagger } from "./tagger.ts"
 
-export type LintKind = "prose-file" | "slash-source" | "hash-source" | "commit-message"
+export type LintKind = "prose-file" | "slash-source" | "hash-source" | "html" | "commit-message"
 
 export type Severity = "hard" | "soft"
 

package/src/extension/index.ts

@@ -2,15 +2,15 @@ import { constants } from "node:fs"
 import { access, mkdir, readFile, writeFile } from "node:fs/promises"
 import { dirname } from "node:path"
 import {
+  createBashToolDefinition,
+  createEditToolDefinition,
+  createWriteToolDefinition,
   type ExtensionAPI,
   type ExtensionContext,
   ExtensionRunner,
   type MessageStartEvent,
   type MessageUpdateEvent,
   type ToolCallEventResult,
-  createBashToolDefinition,
-  createEditToolDefinition,
-  createWriteToolDefinition,
 } from "@earendil-works/pi-coding-agent"
 import type { AutocompleteItem } from "@earendil-works/pi-tui"
 import { Effect } from "effect"
@@ -353,6 +353,9 @@ function lintProposedText(
   previousText?: string,
 ): ToolCallEventResult | undefined {
   const classification = classifyPath(path)
+  if (classification.skipped) {
+    return undefined
+  }
   const report = lint(classification.kind, text, {
     ...state.config,
     dictionary: state.dictionary,

package/src/schema/parse-error.ts

@@ -0,0 +1,32 @@
+import { type Schema, SchemaIssue } from "effect"
+
+// This isolates the Effect v4 `SchemaIssue` formatter calls, so a later
+// Schema change touches only this file.
+
+export type ParseError = Schema.SchemaError
+
+export interface ParseErrorIssue {
+  readonly path: ReadonlyArray<string | number>
+  readonly message: string
+}
+
+const formatIssues = SchemaIssue.makeFormatterStandardSchemaV1()
+const formatTree = SchemaIssue.makeFormatterDefault()
+
+// A Standard Schema path segment is either a raw key or a `{ key }` wrapper,
+// and symbol keys never appear in this package's schemas.
+const pathSegments = (
+  path: ReadonlyArray<PropertyKey | { readonly key: PropertyKey }> | undefined,
+): ReadonlyArray<string | number> =>
+  (path ?? []).map((segment) => {
+    const key = typeof segment === "object" ? segment.key : segment
+    return typeof key === "number" ? key : String(key)
+  })
+
+export const formatParseErrorIssues = (error: ParseError): ParseErrorIssue[] =>
+  formatIssues(error.issue).issues.map((issue) => ({
+    path: pathSegments(issue.path),
+    message: issue.message,
+  }))
+
+export const formatParseErrorTree = (error: ParseError): string => formatTree(error.issue)

package/src/schema/primitives.ts

@@ -0,0 +1,7 @@
+import { Schema } from "effect"
+
+// Effect v4 has no NonEmptyTrimmedString schema.
+// Every call site imports this alias, so the definition stays in one file.
+export const NonEmptyTrimmedString = Schema.Trimmed.check(
+  Schema.isNonEmpty({ expected: "a non-empty string" }),
+)

package/src/tagger/wink.ts

@@ -31,7 +31,7 @@ export function makeWinkTagger(): Tagger {
   }
 }
 
-export class TaggerService extends Context.Tag("TaggerService")<TaggerService, Tagger>() {}
+export class TaggerService extends Context.Service<TaggerService, Tagger>()("TaggerService") {}
 
 const makeLazyWinkTagger = (): Tagger => {
   let tagger: Tagger | undefined