From 4056442f579f0bb138fc32505cb353562e3b4c7f Mon Sep 17 00:00:00 2001 From: Braden Seaborn Date: Tue, 25 Aug 2026 21:33:07 -0500 Subject: [PATCH] Lead the README with what the tool is, and fix the stale attribution text Three changes, all needed before the first tagged release. Rewrite the top of the README. It opened with a wall of prose that made a reader work to find out what the tool does and offered no route to the two non-CLI ways of running it. It now leads with a centred title block and tagline, a Mermaid diagram of the six tests, a worked example, and a three-column table covering the CLI, the Claude/agent skill and the HELVE JSON-RPC tool -- so whichever way a reader arrived, their entry point is above the fold. The worked example is real output. Only the indented source-snippet line under each finding is removed, and the text says so rather than quietly reformatting the tool's output to look tidier than it is. Fix the attribution paragraph (closes #20). #13 described the attribution situation accurately when it was written; #15 then merged and changed it, leaving the README claiming the T2/T3/T6 tables "record no source at all, per entry or per table". They now carry a table-level `sources` block. The paragraph now states what is true: per-entry sources remain T1-only, the other tables carry provenance per table, and `--explain` surfaces neither yet -- linking #10, where that gap is tracked. Also drops the "where the repository root carries one" hedge on THIRD-PARTY-LICENSES.md, which is unconditionally present now. Add the 0.1.0 CHANGELOG section, covering the work that landed after the Unreleased block was written: the attribution files, the contributor docs, the wrapping regression suite, and the hard-wrap atomicity fix. Point the release workflow's environment URL at pypi.org/p/ste100-linter. The package is named ste100-linter in pyproject.toml; the URL said ste100, which is a different (also unclaimed) name. Cosmetic -- it only affects the link shown on the deployment -- but wrong. Verified: all eight suites pass, and `ste_lint.py README.md` now exits 0 with zero error-tier findings. Two findings this rewrite introduced were fixed rather than tolerated. Co-Authored-By: Claude Opus 5 --- .github/workflows/release.yml | 2 +- CHANGELOG.md | 24 +++++ README.md | 176 +++++++++++++++++++++++++++------- 3 files changed, 165 insertions(+), 37 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index a6389b3..b9455bf 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -58,7 +58,7 @@ jobs: # Settings -> Environments before relying on it as a real gate. environment: name: release - url: https://pypi.org/p/ste100 + url: https://pypi.org/p/ste100-linter permissions: # Required for PyPI Trusted Publishing (OIDC). Do not add a # PYPI_API_TOKEN secret -- Trusted Publishing replaces it. diff --git a/CHANGELOG.md b/CHANGELOG.md index b0fa8cb..1eaf8db 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,10 @@ once the first tagged release ships. ## [Unreleased] +## [0.1.0] - 2026-08-25 + +First tagged release. Everything below shipped in it. + ### Added - The ASD-STE100 writing-quality linter, split out of the Veistra monorepo's @@ -44,6 +48,17 @@ once the first tagged release ships. - `tests/run_wrapping_tests.py`: regression tests pinning the invariant that a paragraph lints identically whether it is hard-wrapped or on one line. +- Third-party attribution for the redistributed word lists: `NOTICE` and + `THIRD-PARTY-LICENSES.md` at the repository root, plus a `sources` block + inside `hedges.json`, `filler.json`, `vague.json` and `ai_tells.json` + recording the upstream project, URL, copyright holder and licence for each + shipped table. Both files ship in the wheel under `.dist-info/licenses/`. +- Contributor documentation: `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, + `SECURITY.md`, issue and pull-request templates, and a Dependabot + configuration for GitHub Actions. +- `tests/run_wrapping_tests.py`: a regression suite pinning the invariant that + a paragraph lints the same when hard-wrapped and when left on one line. + ### Changed - **Rule IDs are now `STE-*` rather than `VEI-*`.** `VEI` stood for Veistra, @@ -97,6 +112,15 @@ once the first tagged release ships. - `--format`, `--fix`, `--explain`, `--baseline`, `--stats` and `--today` had no `--help` text, or leaked an internal specification reference. +- **Hard-wrapped Markdown defeated the T5 atomicity analysis.** Sentence units + were built from each physical line, so a sentence spanning a line break was + analysed as several fragments. `STE-T5-MULTI-0001` and the sentence word + budget stopped firing entirely, `STE-T5-NOSHAL-0001` and `STE-T5-EARS-0001` + produced false positives on the fragments, and a five-sentence paragraph was + counted as nine. Units are now built per paragraph, and a `spans` table maps + each offset back to its true source line and column so `--fix` and the VS + Code `problemMatcher` still navigate correctly. + ### Known issues - The shipped rule tables were calibrated for strict specification writing diff --git a/README.md b/README.md index f8f33e4..f042d32 100644 --- a/README.md +++ b/README.md @@ -1,57 +1,159 @@ +
+ # STE-Linter +### Catch ambiguity before your readers do. + +A writing linter for technical documentation, in the spirit of
+**[ASD-STE100 Simplified Technical English](https://www.asd-ste100.org/)**. + [![CI](https://img.shields.io/github/actions/workflow/status/Firelight-Innovations/STE-Linter/ci.yml?branch=main&label=CI)](https://github.com/Firelight-Innovations/STE-Linter/actions/workflows/ci.yml) [![PyPI](https://img.shields.io/pypi/v/ste100-linter.svg)](https://pypi.org/project/ste100-linter/) [![Python](https://img.shields.io/badge/python-3.9%20%7C%203.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue.svg)](https://www.python.org/downloads/) +[![Dependencies](https://img.shields.io/badge/dependencies-none-brightgreen.svg)](#install) [![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE) -A writing linter for technical documentation, in the spirit of [ASD-STE100 Simplified Technical English](https://www.asd-ste100.org/). +**[Install](#install)** · **[Quick start](#quick-start)** · **[Rule catalogue](docs/rules.md)** · **[Wiki](https://github.com/Firelight-Innovations/STE-Linter/wiki)** -A spell-checker asks whether a word is a word. This asks whether a sentence can be misread by someone who has to act on it. +
-It reads Markdown and CSV and reports the words and sentence shapes that make technical writing imprecise. Hedges that let a rule mean anything. References with no antecedent. Sentences carrying three demands at once. Filler that survives deletion without loss. +--- -No dependencies. No build step. One command. +A spell-checker asks whether a word is a word. +**STE-Linter asks whether a sentence can be misread by someone who has to act on it.** -Given a file like this: +It reads Markdown and CSV and reports the words and sentence shapes that make technical +writing imprecise. Hedges that let a rule mean anything. References with no antecedent. +Sentences carrying three demands at once. Filler that survives deletion without loss. -```markdown -# Shutdown +**No dependencies. No build step. No network. One command.** + +## What it catches + +Every finding belongs to one of six tests. Each asks a different question about a sentence. + +```mermaid +flowchart LR + A["Markdown / CSV"] --> B["Mask code, URLs,
tables and links"] + B --> C["Split into
real sentences"] + C --> D{"Six tests"} + + D --> T1["T1 · Replaceable
utilize, in order to"] + D --> T2["T2 · Unfalsifiable
robust, appropriate"] + D --> T3["T3 · Optional
should, as required"] + D --> T4["T4 · Referentially open
It, this, faster"] + D --> T5["T5 · Non-atomic
two shalls, and/or"] + D --> T6["T6 · Zero-information
filler, weasel, AI tells"] + + T1 --> E["error · warning · review"] + T2 --> E + T3 --> E + T4 --> E + T5 --> E + T6 --> E + + style A fill:#1f6feb,stroke:#1f6feb,color:#ffffff + style D fill:#8250df,stroke:#8250df,color:#ffffff + style E fill:#1a7f37,stroke:#1a7f37,color:#ffffff +``` + +## See it work -The operator shall utilize the panel in order to shut the reactor down. +Three sentences of ordinary-looking documentation: -The system shall be robust and shall handle errors as appropriate. +```markdown +# Recovery -It responds faster when the cache is warm. +The operator should utilize the appropriate procedure to restore the system +as required. It is important to note that the system will handle errors and +the controller shall reset the link and it shall log the event. ``` +Every one of the six tests fires. This is the real output, with only the indented source-snippet line under each finding removed for length: + ```console -$ ste100 requirements.md -ste100: 1 files, 6 errors, 4 warnings, 1 review -smell_density=3.3333 ari_grade=5.71 passive_ratio=0.0 budget_violations=0 -requirements.md:3:20 ERROR T1 STE-T1-SUB-0104 -- Replaceable: 'utilize' -> 'use'. - ...operator shall utilize the panel in o... -requirements.md:3:38 ERROR T1 STE-T1-SUB-0122 -- Replaceable: 'in order to' -> 'to'. - ...lize the panel in order to shut the react... -requirements.md:5:1 ERROR T5 STE-T5-MULTI-0001 -- Non-atomic: 2 'shall' imperatives in one sentence. - The system shall be robust and shall handle e... -requirements.md:5:21 WARNING T2 STE-T2-VAG-0059 -- Unfalsifiable: 'robust' with no number, unit, or named acceptance condition. - ...ystem shall be robust and shall hand... -requirements.md:5:21 ERROR T6 STE-T6-FILL-0251 -- Zero-information (filler/intensifier): 'robust'. - ...ystem shall be robust and shall hand... -requirements.md:5:52 ERROR T3 STE-T3-ESC-0002 -- Optional (escape clause): 'as appropriate'. - ...handle errors as appropriate. -requirements.md:5:55 ERROR T1 STE-T1-SUB-0233 -- Replaceable: 'appropriate' -> 'proper'. - ...ndle errors as appropriate. -requirements.md:5:55 WARNING T2 STE-T2-VAG-0015 -- Unfalsifiable: 'appropriate' with no number, unit, or named acceptance condition. - ...ndle errors as appropriate. -requirements.md:7:1 WARNING T4 STE-T4-PRO-0008 -- Referentially open: pronoun 'It' with no clear antecedent in this unit. - It responds faste... -requirements.md:7:13 WARNING T4 STE-T4-COMP-0003 -- Referentially open: comparative 'faster' with no stated baseline. - It responds faster when the cache... +$ ste100 --profile spec guide.md +ste100: 1 files, 9 errors, 4 warnings, 1 review +smell_density=6.5 ari_grade=10.66 passive_ratio=0.0 budget_violations=0 +guide.md:3:14 ERROR T3 STE-T3-HDG-0106 -- Optional (hedge): 'should'. +guide.md:3:21 ERROR T1 STE-T1-SUB-0104 -- Replaceable: 'utilize' -> 'use'. +guide.md:3:33 ERROR T1 STE-T1-SUB-0233 -- Replaceable: 'appropriate' -> 'proper'. +guide.md:3:33 WARNING T2 STE-T2-VAG-0015 -- Unfalsifiable: 'appropriate' with no number, unit, or named acceptance condition. +guide.md:4:1 ERROR T3 STE-T3-ESC-0006 -- Optional (escape clause): 'as required'. +guide.md:4:14 ERROR T1 STE-T1-SUB-0328 -- Replaceable: 'It is' -> ''. +guide.md:4:14 WARNING T4 STE-T4-PRO-0008 -- Referentially open: pronoun 'It' with no clear antecedent in this unit. +guide.md:4:14 ERROR T5 STE-T5-MULTI-0001 -- Non-atomic: 2 'shall' imperatives in one sentence. +guide.md:4:14 ERROR T6 STE-T6-AI-0004 -- Zero-information (AI tell, hedging_opener): 'It is important to note that'. +guide.md:4:38 WARNING T4 STE-T4-PRO-0017 -- Referentially open: pronoun 'that' with no clear antecedent in this unit. +guide.md:4:54 ERROR T3 STE-T3-HDG-0143 -- Optional (hedge): 'will'. +guide.md:5:37 ERROR T5 STE-T5-COMB-0001 -- Non-atomic: second combinator 'and' in one sentence (spec profile). +guide.md:5:41 WARNING T4 STE-T4-PRO-0008 -- Referentially open: pronoun 'it' with no clear antecedent in this unit. ``` -Three sentences, all six tests. Try it now, with nothing installed: +Every finding carries a file, a line, a column, a stable rule ID, and a reason. +`--explain` tells you where a rule comes from; `--fix` applies the unambiguous ones. + +## Three ways to run it + + + + + + + + + + + + +
⌨️ Command line🤖 AI agent skill🔌 HELVE tool
+ +For humans, editors and CI. + +```bash +pipx install ste100-linter +ste100 docs/ +``` + +Exit `0` clean, `1` on error-tier +findings, `2` on tool failure — +so it drops straight into CI. + +[CLI Reference →](https://github.com/Firelight-Innovations/STE-Linter/wiki/CLI-Reference) + + + +Lets Claude lint and rewrite prose +before it hands work back. + +```bash +mkdir -p ~/.claude/skills +cp -r .claude/skills/ste100-lint \ + ~/.claude/skills/ste100-lint +``` + +Works in Claude Code and any agent +that reads `SKILL.md`. + +[Agent Skill →](https://github.com/Firelight-Innovations/STE-Linter/wiki/Agent-Skill) + + + +Newline-delimited JSON-RPC over +stdio, for tool hosts. + +```bash +ste100-helve --helve-rpc +``` + +Declared by `helve-tool.toml`. +stdout stays protocol-pure. + +[Integrations →](https://github.com/Firelight-Innovations/STE-Linter/wiki/Integrations) + +
+ +Try it right now, with nothing installed: ```bash git clone https://github.com/Firelight-Innovations/STE-Linter.git @@ -99,9 +201,11 @@ Those citations name the INCOSE requirements guides, the NASA Systems Engineerin The bulk word tables come from a different lineage, and their attribution is coarser. **Only the T1 substitution table carries a per-entry `source` field.** `--explain` reports it for a T1 rule. -The T2 vague-term, T3 hedge, and T6 filler and AI-tell tables record no source at all, per entry or per table. Their provenance is documented for the table as a whole in [docs/rules.md](docs/rules.md) — not in the data, and not in `--explain` output. +The T2 vague-term, T3 hedge, and T6 filler and AI-tell tables carry their provenance at the table level instead. Each file has a `sources` block naming the upstream project, its URL, copyright holder and licence, and which shipped table it feeds. That is real attribution, though coarser than T1's: it tells you where a table came from, not which upstream contributed an individual word. A prose summary of the same ground is in [docs/rules.md](docs/rules.md). + +`--explain` does not yet surface either kind of source for these tests — it prints the raw table entry, which for T2, T3 and T6 is an ID and a pattern. That gap is tracked in [#10](https://github.com/Firelight-Innovations/STE-Linter/issues/10). -Third-party attribution for the upstream word lists is in [NOTICE](NOTICE), and in `THIRD-PARTY-LICENSES.md` where the repository root carries one. +Third-party attribution for the upstream word lists is in [NOTICE](NOTICE) and [THIRD-PARTY-LICENSES.md](THIRD-PARTY-LICENSES.md). Both ship in the wheel under `.dist-info/licenses/`. **This is not a grammar checker and not a style guide.** It will not catch a factual error or an awkward paragraph. It catches a bounded, well-defined set of ambiguity patterns, and stays quiet about everything else.