From 84d48c6e675fcb0c81a61cfb4fec32db048a0288 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Thomas=20M=C3=BCller?= Date: Tue, 15 Sep 2026 13:39:58 +0000 Subject: [PATCH] :memo: Make the rule/rationale split explicit AGENTS.md and CONTRIBUTING.md now state that a decision, its rejected alternatives and its known issues belong in development/.md, that the actionable rule stays in CONTRIBUTING.md, and that both change in the same commit. development/README.md names library.md in the category list and spells out that the sync runs in both directions. --- AGENTS.md | 1 + CONTRIBUTING.md | 5 +++++ development/README.md | 7 ++++--- 3 files changed, 10 insertions(+), 3 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 54a6364..bc94353 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -12,6 +12,7 @@ first-action facts. Do not restate evolving prose here — it will drift. - **Optional code intelligence:** this repo installs `@spences10/pi-lsp` (pinned in `.pi/settings.json`) as a project-local pi extension. It talks to the repo's own TypeScript 7 via `tsc --lsp --stdio` and exposes **read-only** tools — `lsp_hover`, `lsp_definition`, `lsp_references`, `lsp_find_symbol`, `lsp_document_symbols`, `lsp_diagnostics(_many)`. Prefer `lsp_references` over `grep -w` for widely-colliding identifiers (`matches`, `type`, …); use `lsp_hover` to read inferred types on generic-heavy code. It has no rename / code-action / apply-edit surface — the write side is pi's `edit` tool + `check:tsc`. Treat empty LSP output as _inconclusive_, not success: **`npm run test` / `npm run verify` remain the sole authoritative gate** (see the next bullet). The server keeps running across that gate with a ~5 min idle timeout and registers no file watchers, so if you change `tsconfig.json` / `package.json` mid-session its diagnostics can be stale — when LSP output disagrees with `check:tsc`, trust `check:tsc` and restart pi (or wait out the idle timeout) before concluding the LSP is wrong. - **Definition of done — run this before you call the work finished:** `npm run verify`. If all green, commit. If red, look at the output, fix the root cause, and re-run. - **On commit:** write a good message (see [CONTRIBUTING.md § Commit messages](./CONTRIBUTING.md#commit-messages)). Lefthook's pre-commit hook already runs the fast, offline, staged-file checks — don't run them by hand. If the hook fails on style, `npm run fix`, restage, recommit. +- **Document decisions where the next maintainer will look:** rationale, rejected alternatives and known issues go in `development/.md` (see [development/README.md](./development/README.md)); the actionable rule stays in [CONTRIBUTING.md](./CONTRIBUTING.md) and links to it. Change both in the same commit. - **`npm run maintain` is NOT part of the feature loop.** Its scans are advisory, never a gate; run them only on an explicit maintenance / update-deps branch. ```sh diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7f92ae3..2d26bc5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -125,6 +125,11 @@ reaches for by default: - **There is no local `npm run publish`, and `publish:publint` / `publish:attw` don't go in `check`.** (why: [development/publishing.md](./development/publishing.md#ci-only-publishing)) +- **A decision or its rationale belongs in `development/`, not here.** This file + holds the actionable rule; `development/.md` holds why, the rejected + alternatives and the known issues. When you change a rule, update its category + file in the same commit and cross-link the two. (why: + [development/README.md](./development/README.md)) ## Branching model diff --git a/development/README.md b/development/README.md index b52a3ce..c731e90 100644 --- a/development/README.md +++ b/development/README.md @@ -76,10 +76,11 @@ of downloading per job. ## Adding to these docs -1. Pick the category file for the area you are changing: `workflow`, `tooling`, - `testing`, `ci`, or `publishing`. +1. Pick the category file for the area you are changing: `library`, `workflow`, + `tooling`, `testing`, `ci`, or `publishing`. 2. Add or update a decision block. Keep the existing text unless the decision actually changed. 3. If the change alters an actionable rule, update [CONTRIBUTING.md](../CONTRIBUTING.md) in the same commit and cross-link the - two. + two. The reverse also holds: never change a rule in CONTRIBUTING.md without + updating its rationale here.