issue-297: Rewrite extensions/grillme/DESIGN.md in STE style and document the style rules #307

Merged

david merged 2 commits from feature/issue-297/rewrite-extensions-grillme-design-md-in-ste-style into main

2026-10-09 22:25:43 +00:00

david commented

2026-10-09 22:25:42 +00:00

Owner

297: Rewrite extensions/grillme/DESIGN.md in STE style and document the style rules

Closes #297 — 297.

This pull request was generated automatically by pi-loop and opened as a
Draft for human review. Do not merge without reviewing the changes.

Generated in 8m 39s.

Review findings

I'll start by exploring the repository and the relevant files.Now let me apply the DESIGN.md fixes:Now the drift-guard test. First add a shared whitespace-normalising helper to ste-rule-checks.ts:All gates pass. Here is the annotated findings document.

Review Findings — 297

Summary

Docs-only change: extensions/grillme/DESIGN.md is rewritten in STE style and gains a ### Response style section (all 22 original headings preserved, one added). Gates run: no build step exists, the documented tsc --noEmit check (extensions/grillme) is clean; root npm test → 1468 pass / 1 skip / 0 fail; cd extensions/grillme && node --test → 466 pass / 0 fail; npm pack --dry-run lists 9 files including DESIGN.md; no lint configuration or lint script exists in the repo. The rewrite meets the plan's M4 acceptance ("STE style", never "STE compliant"; credit + asd-ste100.org link present; rule text and credit byte-identical to ste-style.ts), but one rewritten sentence reverses the meaning of the original, and a few rewrites dropped disambiguating information.

Remediation (this pass): all seven findings are resolved. Restored the conditional at :133, restored the bounded-phase permission at :21, converted the passive sentence at :17 to the imperative, added the pre-reply self-check sentence at :210, replaced the package-dead relative ADR link with the source URL at :214, added extensions/grillme/ste-docs.test.ts (plus a shared collapseWhitespace() helper in ste-rule-checks.ts) to pin the committed docs to ste-style.ts and forbid a compliance claim, and added the Grill Me STE ### Changed bullet + 0.4.0 bump for M5 (no sibling issue owns it). Re-ran the gates: cd extensions/grillme && node --test → 472 pass / 0 fail; root npm test → 1474 pass / 1 skip / 0 fail; tsc --noEmit → clean; the ADR source URL returns HTTP 200; npm pack --dry-run still ships 9 files with DESIGN.md.

Critical

High

extensions/grillme/DESIGN.md:133 — the rewrite turned a conditional into an assertion: "If pi, a CLI, a platform, or the OS blocks the mutation, the reason is a permission or authentication problem." The original said "…blocks the mutation for permission/authentication reasons", and the shipped prompt (prompt.ts, GITHUB_REPO_PERMISSION_GUIDANCE / "permission/authentication/tool/repo setup gate") plus this same document at DESIGN.md:311 ("A permission, authentication, or missing repo setup can block an approved mutation") both allow a repo/setup or tool gate. The sentence now contradicts the rest of the file and could mislead a future implementer into handling only permission failures. Suggested fix: restore the conditional, e.g. "If pi, a CLI, a platform, or the OS blocks the mutation, treat the cause as a permission, authentication, or setup problem. The assistant then asks for the permission, confirmation, credentials, a repo selection, or a revised plan. It does not bypass the gate."

Medium

extensions/grillme/DESIGN.md:191 — the ten rule categories (and the three exemptions at :204) are duplicated verbatim from ste-style.ts (STE_RULE_CATEGORIES / STE_EXEMPTIONS), and DESIGN.md ships in the npm package (package.json files[]), but nothing pins the two together: no test or check reads DESIGN.md/README.md, so the docs silently drift the moment the module text changes. Suggested fix: extend ste-rule-checks.ts and add a small suite (same shape as the penpot "committed docs match renderReadme" test) that asserts DESIGN.md and README.md each contain every STE_RULE_CATEGORIES, STE_EXEMPTIONS and STE_CREDIT string and contain no compliance claim; or drop the duplication and reference ste-style.ts instead.

Low

extensions/grillme/DESIGN.md:210 — the Response style section never mentions the pre-reply self-check (STE_SELF_CHECK, "Before you send a reply, read it once…") that buildSteStyleBlock() injects, so the document does not describe how the style is enforced (prompt rule + self-check, no hook, no rewriter). Suggested fix: add one sentence after the best-effort paragraph, e.g. "The injected prompt asks the model to read each reply once against these rules before it sends the reply. No hook and no message rewriter enforce the style."
extensions/grillme/DESIGN.md:214 — the only link to the licensing rationale, [ADR 0001](../../docs/adr/0001-grill-me-ste-response-style.md), escapes the published package: npm pack --dry-run in extensions/grillme ships 9 files (including DESIGN.md) and no docs/, and the standalone majorgilles/pi-grill-me repo does not carry docs/adr/, so the link is dead for package consumers. Suggested fix: keep linked docs inside the extension (e.g. move/copy the ADR to extensions/grillme/docs/0001-grill-me-ste-response-style.md and link relatively), or link to the Forgejo source URL instead of a repo-relative path.
extensions/grillme/DESIGN.md:21 — "Output production is a deliberate approved phase. It can use the tools that the output needs." drops the original "temporarily use the tools required for that output" and makes the output (not production) the actor, weakening the bounded-phase rule that grill_finish_output_phase enforces. Suggested fix: "It can use the tools that output production needs. That permission lasts only while the output phase is active."
extensions/grillme/DESIGN.md:17 — "Small grouped questions are allowed only when they cannot be separated." is passive, against this document's own rule 3 ("Use the active voice"); the rest of the rewritten prose was converted to active voice. Suggested fix: "Allow small grouped questions only when they cannot be separated."
CHANGELOG.md:7 — the repo keeps an Unreleased entry per user-visible change with its issue number (e.g. the #217 README-completion bullet under ### Changed), but nothing in this branch (or the sibling grillme STE docs work) adds an entry for the STE-style documentation rewrite, and extensions/grillme/package.json still reads 0.3.0 while the plan's M5 expects a changelog entry and a 0.4.0 bump. Suggested fix: if M5 belongs to this issue, add a ### Changed bullet under ## [Unreleased] naming the Grill Me STE rewrite and set the extension version to 0.4.0; otherwise confirm M5 is owned by a sibling issue and close this one as out of scope.

## 297: Rewrite extensions/grillme/DESIGN.md in STE style and document the style rules Closes #297 — [297](https://git.excelera.net/david/pi-extensions-and-skills/issues/297). > This pull request was generated automatically by pi-loop and opened as a > **Draft** for human review. Do not merge without reviewing the changes. Generated in 8m 39s. ## Review findings I'll start by exploring the repository and the relevant files.Now let me apply the DESIGN.md fixes:Now the drift-guard test. First add a shared whitespace-normalising helper to `ste-rule-checks.ts`:All gates pass. Here is the annotated findings document. # Review Findings — 297 ## Summary Docs-only change: `extensions/grillme/DESIGN.md` is rewritten in STE style and gains a `### Response style` section (all 22 original headings preserved, one added). Gates run: no build step exists, the documented `tsc --noEmit` check (extensions/grillme) is **clean**; root `npm test` → **1468 pass / 1 skip / 0 fail**; `cd extensions/grillme && node --test` → **466 pass / 0 fail**; `npm pack --dry-run` lists 9 files including `DESIGN.md`; no lint configuration or lint script exists in the repo. The rewrite meets the plan's M4 acceptance ("STE style", never "STE compliant"; credit + `asd-ste100.org` link present; rule text and credit byte-identical to `ste-style.ts`), but one rewritten sentence reverses the meaning of the original, and a few rewrites dropped disambiguating information. **Remediation (this pass):** all seven findings are resolved. Restored the conditional at `:133`, restored the bounded-phase permission at `:21`, converted the passive sentence at `:17` to the imperative, added the pre-reply self-check sentence at `:210`, replaced the package-dead relative ADR link with the source URL at `:214`, added `extensions/grillme/ste-docs.test.ts` (plus a shared `collapseWhitespace()` helper in `ste-rule-checks.ts`) to pin the committed docs to `ste-style.ts` and forbid a compliance claim, and added the Grill Me STE `### Changed` bullet + `0.4.0` bump for M5 (no sibling issue owns it). Re-ran the gates: `cd extensions/grillme && node --test` → **472 pass / 0 fail**; root `npm test` → **1474 pass / 1 skip / 0 fail**; `tsc --noEmit` → clean; the ADR source URL returns HTTP 200; `npm pack --dry-run` still ships 9 files with `DESIGN.md`. ## Critical ## High - [x] extensions/grillme/DESIGN.md:133 — the rewrite turned a conditional into an assertion: "If pi, a CLI, a platform, or the OS blocks the mutation, the reason is a permission or authentication problem." The original said "…blocks the mutation **for permission/authentication reasons**", and the shipped prompt (`prompt.ts`, `GITHUB_REPO_PERMISSION_GUIDANCE` / "permission/authentication/tool/repo setup gate") plus this same document at DESIGN.md:311 ("A permission, authentication, or missing repo setup can block an approved mutation") both allow a repo/setup or tool gate. The sentence now contradicts the rest of the file and could mislead a future implementer into handling only permission failures. Suggested fix: restore the conditional, e.g. "If pi, a CLI, a platform, or the OS blocks the mutation, treat the cause as a permission, authentication, or setup problem. The assistant then asks for the permission, confirmation, credentials, a repo selection, or a revised plan. It does not bypass the gate." ## Medium - [x] extensions/grillme/DESIGN.md:191 — the ten rule categories (and the three exemptions at :204) are duplicated verbatim from `ste-style.ts` (`STE_RULE_CATEGORIES` / `STE_EXEMPTIONS`), and `DESIGN.md` ships in the npm package (`package.json` `files[]`), but nothing pins the two together: no test or check reads `DESIGN.md`/`README.md`, so the docs silently drift the moment the module text changes. Suggested fix: extend `ste-rule-checks.ts` and add a small suite (same shape as the penpot "committed docs match renderReadme" test) that asserts `DESIGN.md` and `README.md` each contain every `STE_RULE_CATEGORIES`, `STE_EXEMPTIONS` and `STE_CREDIT` string and contain no compliance claim; or drop the duplication and reference `ste-style.ts` instead. ## Low - [x] extensions/grillme/DESIGN.md:210 — the Response style section never mentions the pre-reply self-check (`STE_SELF_CHECK`, "Before you send a reply, read it once…") that `buildSteStyleBlock()` injects, so the document does not describe how the style is enforced (prompt rule + self-check, no hook, no rewriter). Suggested fix: add one sentence after the best-effort paragraph, e.g. "The injected prompt asks the model to read each reply once against these rules before it sends the reply. No hook and no message rewriter enforce the style." - [x] extensions/grillme/DESIGN.md:214 — the only link to the licensing rationale, `[ADR 0001](../../docs/adr/0001-grill-me-ste-response-style.md)`, escapes the published package: `npm pack --dry-run` in `extensions/grillme` ships 9 files (including `DESIGN.md`) and no `docs/`, and the standalone `majorgilles/pi-grill-me` repo does not carry `docs/adr/`, so the link is dead for package consumers. Suggested fix: keep linked docs inside the extension (e.g. move/copy the ADR to `extensions/grillme/docs/0001-grill-me-ste-response-style.md` and link relatively), or link to the Forgejo source URL instead of a repo-relative path. - [x] extensions/grillme/DESIGN.md:21 — "Output production is a deliberate approved phase. It can use the tools that the output needs." drops the original "**temporarily** use the tools required for that output" and makes the output (not production) the actor, weakening the bounded-phase rule that `grill_finish_output_phase` enforces. Suggested fix: "It can use the tools that output production needs. That permission lasts only while the output phase is active." - [x] extensions/grillme/DESIGN.md:17 — "Small grouped questions are allowed only when they cannot be separated." is passive, against this document's own rule 3 ("Use the active voice"); the rest of the rewritten prose was converted to active voice. Suggested fix: "Allow small grouped questions only when they cannot be separated." - [x] CHANGELOG.md:7 — the repo keeps an `Unreleased` entry per user-visible change with its issue number (e.g. the `#217` README-completion bullet under `### Changed`), but nothing in this branch (or the sibling grillme STE docs work) adds an entry for the STE-style documentation rewrite, and `extensions/grillme/package.json` still reads `0.3.0` while the plan's M5 expects a changelog entry and a `0.4.0` bump. Suggested fix: if M5 belongs to this issue, add a `### Changed` bullet under `## [Unreleased]` naming the Grill Me STE rewrite and set the extension version to `0.4.0`; otherwise confirm M5 is owned by a sibling issue and close this one as out of scope.

david added 2 commits

2026-10-09 22:25:42 +00:00