From 9c268de987d9eaca8e5d294348e422fe013989a1 Mon Sep 17 00:00:00 2001 From: joshunrau Date: Fri, 13 Nov 2026 11:31:06 -0500 Subject: [PATCH 1/5] chore: update writing-skills-for-agents --- .../skills/writing-normative-prose/SKILL.md | 51 ++++++ .../skills/writing-skills-for-agents/SKILL.md | 154 +++++++++++++++++- skills-lock.json | 16 +- 3 files changed, 215 insertions(+), 6 deletions(-) create mode 100644 .agents/skills/writing-normative-prose/SKILL.md diff --git a/.agents/skills/writing-normative-prose/SKILL.md b/.agents/skills/writing-normative-prose/SKILL.md new file mode 100644 index 000000000..7f67e9d7b --- /dev/null +++ b/.agents/skills/writing-normative-prose/SKILL.md @@ -0,0 +1,51 @@ +--- +name: writing-normative-prose +description: Sentence, list and literal-text rules for a document that states rules or decisions as fact for a reader who builds from it, such as a specification or an implementation plan. Use when another skill names this one. Not for documentation, reports, emails or other prose. +--- + +# Writing Normative Prose + +Normative prose states rules and decisions as fact, for a reader who builds from them. "The document" below is the text being written, and "the reader" is whoever builds from it. + +## Sentences + +- Short declarative sentences in the present tense that state behavior as fact: "is", not "should". No RFC 2119 keywords. +- One idea per sentence. Commas, colons and periods in place of em dashes. +- The subject of a sentence is the thing the rule governs, such as an input, a stored item, a message or an actor, not the system that the document describes. The passive is allowed, and is the usual form when the actor is the system. The system is the subject only of a sentence about the system as a whole. +- A sentence names the set it governs. A quantifier with no noun ("everything", "anything", "whatever") or a clause standing in for a set ("what the input contains", "whichever applies") is a defect unless that sentence or the one before it enumerates the set. +- Choose the exact word over the approximate one: "within five seconds", not "quickly"; "rounded to the nearest cent", not "rounded". +- Use a technical term when it says something more precisely than plain words and the reader would know it without looking it up: "case-insensitive", not "ignoring capital letters"; "every read returns the most recently saved value", not "reads are linearizable". + +## Cases + +A rule with a fixed set of cases is a lead sentence that names the set, then one list item per case: a bold label, the condition, and the outcome last. Two cases are still a list. + +## Once + +A rule is written once. A sentence elsewhere that relies on it cites it and may name the rule in a few words, but never restates its content. The skill that loads this one gives the form of the citation. + +## Literal Text + +A code span marks literal text: anything that appears exactly as written in code, a file, a command line or a message the software sends or receives, such as an identifier, a flag, a header or a literal value. + +## Anti-Patterns + +Each pair shows text these rules reject and the text that replaces it. All are from a fictional document about a job scheduler with an HTTP API: a job has a schedule, and each scheduled time starts a run. + +**A quantifier over an unnamed set.** + +- Rejected: "Everything a request carries is validated before it is acted on." +- Accepted: "Every request body is parsed with the JSON Schema of its endpoint before the handler runs. A body the schema rejects is refused with status 400." + +**The system as subject.** + +- Rejected: "The scheduler checks the schedule expression. The scheduler rejects an expression with a field out of range." +- Accepted: "A `schedule` with a field out of its range is refused with status 400." + +**A fixed set of cases in prose.** + +- Rejected: "After a run fails, a new run is queued when the job's retry limit is not reached, no run is queued when the job is paused or deleted, and otherwise the job waits for its next scheduled time." +- Accepted: "After a run fails, one of three things follows: + - **Retry.** The job's `retryLimit` is not reached: a new run is queued. + - **Cancel.** The job is paused or deleted: no run is queued. + - **Wait.** Otherwise: the job waits for its next scheduled time." diff --git a/.agents/skills/writing-skills-for-agents/SKILL.md b/.agents/skills/writing-skills-for-agents/SKILL.md index fc5031b5a..3c10705c4 100644 --- a/.agents/skills/writing-skills-for-agents/SKILL.md +++ b/.agents/skills/writing-skills-for-agents/SKILL.md @@ -140,6 +140,158 @@ After: Rerun once before triaging. In one week of runs, a single rerun cut false failures from 31 to 12. ``` +## Anti-Pattern: Writing for a Less Capable Reader + +### The Reader + +The agent you are writing for is also highly capable. It knows the domain, its tools, and general good practice, and it does competent work unprompted. What it lacks is what it cannot infer: the user's preferences, the conventions of the project, and each choice that departs from what it would do by default. A skill supplies those and nothing else. + +### The Deletion Test + +For each line, ask: would that reader produce a worse result with this line deleted? If not, delete it. + +Run this test after the three overfitting tests. Their fixes add text, such as a definition or the source of a piece of evidence, and that text is tested too. + +The test sets no target length. A long skill whose every line passes is the right length. + +### Four Ways a Line Pads + +A line can pad in more than one way. + +#### 1. Known to the reader + +The line tells the reader something it knows or would do anyway. + +Tells: + +- General good practice for the domain, such as "handle errors" or "write a clear commit message". +- A definition of a term the domain already defines. +- The steps of a routine operation, spelled out one by one. +- An instruction to do what the reader does by default, such as reading a file before editing it. +- A description of the reader's role or expertise, or of how much the skill matters. + +Fix: delete the line. When part of it departs from the default, keep that part alone. "Write a clear commit message, prefixed with the job name" becomes "Prefix the commit message with the job name." + +#### 2. Over-explained rationale + +The line gives a reason the reader already holds, or a reason longer than the work it does. + +A reason does work in two cases. It lets the reader decide a case the rule does not cover, or the rule looks wrong without it and the reader might override the rule. Evidence that the noun test keeps is exempt from this test and stays. + +Tells: + +- A reason that restates the benefit of good practice: "because this saves time", "to ensure quality". +- "This is important because", "the reason for this is". +- A reason attached to every rule in a list. +- A paragraph of reasoning that a clause would carry. + +Fix: delete a reason that does neither kind of work. Cut one that does to a clause. + +#### 3. Repetition + +The line says what another line of the skill already says. + +Tells: + +- An overview that lists what the sections below it say. +- A summary, recap, or closing checklist that restates the body. +- A rule stated in the body and again under a heading such as "Important" or "Notes". +- An opening paragraph that restates the description. +- An example that shows only what its rule states. An example earns its place by showing something the rule cannot state, such as a format, a tone, or the boundary between two cases. One example for each such thing is enough. + +Fix: keep the statement where the reader needs it and delete the others. + +#### 4. Defensive padding + +The line guards against a mistake the reader is unlikely to make, or pushes harder on a rule than the rule needs. + +Tells: + +- A list of cases that tries to be exhaustive, where the rule or its reason already covers them. +- A caveat for a situation that the skill's scope makes rare. +- A hedge on a line that is meant as a rule: "generally", "where appropriate", "consider". +- Emphasis in capitals or bold, or words such as "IMPORTANT", "NEVER", and "critical". +- "Be careful", "double-check", or "make sure", with nothing named to check. + +Fix: state the rule once, plainly. Keep an edge case only when the reader would get it wrong without the line. + +### Examples + +All excerpts come from the same fictional skill, `triage-ci-failures`. + +#### Known to the reader + +Before: + +```markdown +Start by reading the job's log carefully to understand what failed. Look for error messages and stack traces. Once you understand the failure, check whether the test is in the quarantine file before investigating further. +``` + +The reader reads the log and finds the error unprompted. The quarantine check is the one step it could not guess. + +After: + +```markdown +Check the quarantine file before investigating a failure. +``` + +#### Over-explained rationale + +Before: + +```markdown +File one issue per failing job. This matters because well-scoped issues are easier to track and resolve. + +Do not rerun a deploy job. The reason for this is that deploy jobs are not like test jobs: when a deploy job runs a second time it carries out the deployment again, which can cause problems in the target environment. +``` + +The reader already holds the first reason. The second settles cases the rule does not name, such as a job that publishes a package, so it stays, cut to a clause. + +After: + +```markdown +File one issue per failing job. + +Do not rerun a deploy job, since a rerun repeats its side effects. +``` + +#### Repetition + +Before: + +```markdown +Title each issue with the classification and the job name. + +For example, if the `lint` job failed and you classified the failure as flaky, the title names the classification, flaky, and the job, `lint`. +``` + +The example shows only what the rule states. What the rule cannot state is the format, so the example that stays is the format. + +After: + +```markdown +Title each issue with the classification and the job name, as in `[flaky] lint`. +``` + +#### Defensive padding + +Before: + +```markdown +**IMPORTANT:** NEVER close a failure without a classification. Generally, be very careful with timeouts, which may be caused by slow runners, network issues, resource limits, deadlocks, or other factors. +``` + +The emphasis adds nothing to a rule that is stated plainly. "Be very careful" names nothing to do, and the reader could produce the list of causes itself. + +After: + +```markdown +Classify every failure before closing it. +``` + ## Verifying -Have a subagent verify the skill. Give it the skill under review and this skill, tell it to assume only the committed files, and have it apply the three tests to every line. It reports each failing line with the tests it failed. Done when it reports none. +Have a subagent verify the skill. Give it the skill under review and this skill, and tell it to assume it holds only the skill under review and the files committed in the repo. It makes two reports, the second once the first is empty: + +1. **Overfitting.** Each line that fails one of the three overfitting tests, with the tests it failed. Fix the lines and repeat until it reports none. +2. **Padding.** Each line it would delete under the deletion test, with the ways the line pads. Accept or reject each candidate yourself, in one round. A verifier asked for lines to delete finds some in any skill, so do not re-run it to reach an empty report. diff --git a/skills-lock.json b/skills-lock.json index eda48bc43..75495c9c4 100644 --- a/skills-lock.json +++ b/skills-lock.json @@ -1,29 +1,35 @@ { - "version": 1, + "version": 2, "skills": { "agent-browser": { "source": "vercel-labs/agent-browser", "sourceType": "github", "skillPath": "skills/agent-browser/SKILL.md", - "computedHash": "ecc7641aea05f85ca3b11e7759d32aaf52fe05946ab4b63739c7bf78a41237a2" + "computedHash": "" }, "diagnosing-bugs": { "source": "mattpocock/skills", "sourceType": "github", "skillPath": "skills/engineering/diagnosing-bugs/SKILL.md", - "computedHash": "fd6c99466b7ba43be624e6e66ed6d7af2796ded7218f24c83820823977819e22" + "computedHash": "" }, "interview": { "source": "joshunrau/skills", "sourceType": "github", "skillPath": "skills/interview/SKILL.md", - "computedHash": "6cf86ca51424350f10880c3a2fd3dd018c6682c90dfb81baf66e91615df4a0fa" + "computedHash": "92f32340ae3ac0f6b7f345ed07279c60306138b5d12005b2aa2186f8fd1d97f6" + }, + "writing-normative-prose": { + "source": "joshunrau/skills", + "sourceType": "github", + "skillPath": "skills/writing-normative-prose/SKILL.md", + "computedHash": "adb93967d22da0c4e676f08163658c849251f44e0084e956f22899c7ccb203a0" }, "writing-skills-for-agents": { "source": "joshunrau/skills", "sourceType": "github", "skillPath": "skills/writing-skills-for-agents/SKILL.md", - "computedHash": "692102f9ab7e6dc148240a3f6255aa9856b7bea177133d4241ca0906e67d7be6" + "computedHash": "ec98316925e2f0590bd75b17e2276b899cc18f2cd2d40e441cbf2056bdbb4701" } } } From f28ca1b4eff1a41fe832f7a2cf6f2708793b91c3 Mon Sep 17 00:00:00 2001 From: joshunrau Date: Fri, 13 Nov 2026 11:39:17 -0500 Subject: [PATCH 2/5] chore: rename skill for consistency --- .agents/skills/finishing-changes/SKILL.md | 22 +++--- .agents/skills/troubleshooting/SKILL.md | 2 +- .agents/skills/writing-agent-docs/SKILL.md | 69 ------------------ .../skills/writing-docs-for-agents/SKILL.md | 72 +++++++++++++++++++ .../agents/openai.yaml | 2 +- .claude/skills/writing-agent-docs | 1 - .claude/skills/writing-docs-for-agents | 1 + 7 files changed, 86 insertions(+), 83 deletions(-) delete mode 100644 .agents/skills/writing-agent-docs/SKILL.md create mode 100644 .agents/skills/writing-docs-for-agents/SKILL.md rename .agents/skills/{writing-agent-docs => writing-docs-for-agents}/agents/openai.yaml (67%) delete mode 120000 .claude/skills/writing-agent-docs create mode 120000 .claude/skills/writing-docs-for-agents diff --git a/.agents/skills/finishing-changes/SKILL.md b/.agents/skills/finishing-changes/SKILL.md index 922d023cf..beee58640 100644 --- a/.agents/skills/finishing-changes/SKILL.md +++ b/.agents/skills/finishing-changes/SKILL.md @@ -25,23 +25,23 @@ with `.agents/skills/opening-issues/SKILL.md` and name the issue in your reply. existing spec reaches: the suite is kept small on purpose. 5. **Finish the second file.** Each row is a pair that must agree, where the second is easy to forget: - | You touched | What must follow | Owner | - | ----------------------------------------- | ------------------------------------------------------------------------ | ---------------------------------------------- | - | a file under `apps/web/src/routes/` | `route-tree.ts` (the user's) and `testing/src/generated/route.d.ts` | `.agents/docs/playbooks/add-web-route.md` | - | a new folder under `packages/schemas/src` | its subpath in that package's `exports` — there is no `.` export | `packages/schemas/AGENTS.md` | - | a new instrument directory | its import _and_ `create` call in `apps/api/src/demo/demo.service.ts` | `.agents/docs/playbooks/add-instrument.md` | - | a wrapper under `vendor/` | `runtime/v1/package.json` devDependencies _and_ `runtime.config.js` | `.agents/docs/playbooks/add-vendor-package.md` | - | an environment variable | the rest of the chain, in the playbook's order | `.agents/docs/playbooks/add-env-var.md` | - | a `packages/react-core` component | `src/index.ts` — the barrel is the public API, there are no deep imports | `packages/react-core/AGENTS.md` | - | a request or response shape in `apps/api` | `cli/odc-cli`, which nothing links to the API | `cli/AGENTS.md` | - | a new workspace or vitest project | the tables in `workspace-map.md` and `testing-strategy.md` | `.agents/skills/writing-agent-docs/SKILL.md` | + | You touched | What must follow | Owner | + | ----------------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------- | + | a file under `apps/web/src/routes/` | `route-tree.ts` (the user's) and `testing/src/generated/route.d.ts` | `.agents/docs/playbooks/add-web-route.md` | + | a new folder under `packages/schemas/src` | its subpath in that package's `exports` — there is no `.` export | `packages/schemas/AGENTS.md` | + | a new instrument directory | its import _and_ `create` call in `apps/api/src/demo/demo.service.ts` | `.agents/docs/playbooks/add-instrument.md` | + | a wrapper under `vendor/` | `runtime/v1/package.json` devDependencies _and_ `runtime.config.js` | `.agents/docs/playbooks/add-vendor-package.md` | + | an environment variable | the rest of the chain, in the playbook's order | `.agents/docs/playbooks/add-env-var.md` | + | a `packages/react-core` component | `src/index.ts` — the barrel is the public API, there are no deep imports | `packages/react-core/AGENTS.md` | + | a request or response shape in `apps/api` | `cli/odc-cli`, which nothing links to the API | `cli/AGENTS.md` | + | a new workspace or vitest project | the tables in `workspace-map.md` and `testing-strategy.md` | `.agents/skills/writing-docs-for-agents/SKILL.md` | 6. **If the diff touches `apps/api`, account for every Prisma query, not a sample**: each `where` names `accessibleQuery` or your reply says why it is unscoped, and every handler calling a scoped service forwards `@CurrentUser('ability')` (`apps/api/AGENTS.md`). 7. **Re-read the `AGENTS.md` of every package or app you modified** and confirm your change does not contradict it. If it does, revise the change, or propose the smallest `AGENTS.md` edit and wait for the - user's approval (root `AGENTS.md` hard rule); `.agents/skills/writing-agent-docs/SKILL.md` has the house format. + user's approval (root `AGENTS.md` hard rule); `.agents/skills/writing-docs-for-agents/SKILL.md` has the house format. 8. **Before opening a PR, or pushing a follow-up that adds code to one, run `.agents/skills/adversarial-review/SKILL.md`** on the green branch. Fix, or decline with a reason, every confirmed finding, then repeat from step 1; review again only when the fixes added code beyond what the findings named. diff --git a/.agents/skills/troubleshooting/SKILL.md b/.agents/skills/troubleshooting/SKILL.md index 3e25f5d25..7b638419c 100644 --- a/.agents/skills/troubleshooting/SKILL.md +++ b/.agents/skills/troubleshooting/SKILL.md @@ -48,5 +48,5 @@ The last row is usually the database: `NODE_ENV=test` gives the API an in-memory `testing/src/global/setup.spec.ts`, while development uses a real Mongo that nothing resets, and JWT expiry is ignored in development. -When no row matches and you find the cause, land the missing fact where `.agents/skills/writing-agent-docs/SKILL.md` +When no row matches and you find the cause, land the missing fact where `.agents/skills/writing-docs-for-agents/SKILL.md` says it belongs — this table is a candidate. diff --git a/.agents/skills/writing-agent-docs/SKILL.md b/.agents/skills/writing-agent-docs/SKILL.md deleted file mode 100644 index 33287eba9..000000000 --- a/.agents/skills/writing-agent-docs/SKILL.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -name: writing-agent-docs -description: Write or correct this repo's agent documentation — a workspace AGENTS.md (or its CLAUDE.md symlink), a playbook under .agents/docs/playbooks, an architecture doc, the workspace map, or a skill. Use when a documented rule is wrong or missing, when a change contradicts an AGENTS.md, or when another skill needs the house format for these files. Architectural decisions land in .agents/docs/architecture; there is no ADR flow. ---- - -`.agents/` is neither shipped nor linted, so nothing reports a fact in the wrong file or a second copy going -stale. **Every fact has one home.** - -## Find the home before you write - -Grep for a distinctive token of the fact across docs and code -(`grep -rn "accessibleQuery(undefined" --exclude-dir=node_modules .`). No hits: place it by the table below. -One hit: that is the home; point at it by path. Two or more: pick the home and cut the rest to one-line -pointers in the same change. - -| The fact is | Home | -| ------------------------------------------------------------------ | ------------------------------------------------------------------ | -| a rule that binds every directory | root `AGENTS.md` | -| a convention or invariant of one workspace | that workspace's `AGENTS.md` | -| an ordered procedure where a skipped step fails silently | `.agents/docs/playbooks/-.md` — verb first, kebab-case | -| structure spanning workspaces — a pipeline, a permission model | `.agents/docs/architecture/.md` | -| what a workspace is, what it builds, who depends on it | `.agents/docs/workspace-map.md` | -| the API or local status of a consumed `@douglasneuroinformatics/*` | `.agents/docs/packages/.md` | -| agent behaviour with a trigger of its own | a skill, `.agents/skills//SKILL.md` | - -## House format - -**Playbook** — `add-web-route.md` is the template. Title, then a line saying where the conventions live and -that this file is only the ordering. The expected failure, or the one step that fails silently, before step 1. -Numbered steps, each opening with the action in bold and stating the cost of skipping it. Name a canonical file -to copy by path. Close on `## Verify`: a fenced `sh` block of real commands and what a given failure means. If -you cannot write the Verify block, it is reference and belongs in an `AGENTS.md` or architecture doc. - -**AGENTS.md** — title is the workspace path (`# apps/web`). A few lines of identity: what it is, who consumes -it, whether it builds. Stakes in a blockquote where a mistake is expensive. Traps before conventions. Name the -canonical file for each recurring task. Close on how the work is checked (`## Tests` with -`pnpm exec vitest --project `, or what covers it instead). Point down, not up: root `AGENTS.md` is -always loaded. - -**A new `AGENTS.md` needs a sibling `CLAUDE.md` symlink** (`ln -s AGENTS.md CLAUDE.md`, committed at git mode -`120000`). Never author or edit a `CLAUDE.md`. The one exception is the published -`packages/instrument-guidelines/AGENTS.md`, which is not this repo's conventions. - -**A skill nothing symlinks is never loaded.** Add `ln -s ../../.agents/skills/ .claude/skills/` -(git mode `120000`) and an `agents/openai.yaml` sidecar with `interface.display_name` and -`interface.short_description` (copy `.agents/skills/review-pr/agents/openai.yaml`). - -## Prose rules - -- **Bold lead-in on every rule**, so the bold text alone is the summary. -- **State the failure, not the exhortation**: "a story written anywhere else is silently not picked up", not - "be careful where you put stories". -- **Every non-obvious claim carries its path**; a decision carries the commit SHA that made it. -- **State a count only beside the command that reproduces it**; prose counts go stale, tables count themselves. -- **Write the fact, not the process that found it.** Match the line wrap of the file you edit. - -## Tables that move together - -| You changed | These move with it | -| --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | -| a workspace added, renamed or moved | `workspace-map.md` (section table, Built vs source-only, Published to npm), `.agents/docs/index.md` "Where to look", the new `AGENTS.md` and its symlink | -| a vitest project added or removed | `testing-strategy.md` Vitest projects table, its count and its "no unit tests" list; `workspace-map.md` `Vitest project` column; `## Tests` | -| a new playbook | `.agents/docs/index.md` "Step-by-step playbooks" | -| a new architecture doc | `.agents/docs/index.md` "Deeper reference, read on demand" | -| a new `.agents/docs/packages/.md` | `.agents/docs/packages/index.md` (`Docs` link, fidelity table) | - -**Done when** a grep for each fact you wrote finds one statement and any number of pointers, every path you -cited resolves, every table in the row you triggered is updated, and any `AGENTS.md` your change contradicts -is revised in the same commit — or your reply names what you skipped. diff --git a/.agents/skills/writing-docs-for-agents/SKILL.md b/.agents/skills/writing-docs-for-agents/SKILL.md new file mode 100644 index 000000000..db153714d --- /dev/null +++ b/.agents/skills/writing-docs-for-agents/SKILL.md @@ -0,0 +1,72 @@ +--- +name: writing-docs-for-agents +description: Write or correct this repo's agent documentation — a workspace AGENTS.md (or its CLAUDE.md symlink), a playbook under .agents/docs/playbooks, an architecture doc, the workspace map, or a skill. Use when a documented rule is wrong or missing, when a change contradicts an AGENTS.md, or when another skill needs the house format for these files. Architectural decisions land in .agents/docs/architecture; there is no ADR flow. +--- + +`.agents/` is neither shipped nor linted, so nothing reports a fact in the wrong file or a second copy going +stale. **Every fact has one home.** + +## Find the home before you write + +Search tracked files for a distinctive token of the fact (`git grep -n ''`). No hits: place it by the +list below. One hit: that is the home; point at it by path. Two or more: pick the home and cut the rest to +one-line pointers in the same change. + +- **A rule that binds every directory:** root `AGENTS.md`. +- **A convention or invariant of one workspace:** that workspace's `AGENTS.md`. +- **An ordered procedure where a skipped step fails silently:** `.agents/docs/playbooks/-.md`, + verb first, kebab-case. +- **Structure spanning workspaces, such as a pipeline or a permission model:** + `.agents/docs/architecture/.md`. +- **What a workspace is, what it builds, who depends on it:** `.agents/docs/workspace-map.md`. +- **Which consumed `@douglasneuroinformatics/*` package does what:** `.agents/docs/packages/index.md`. Never + its API; agents read the source. +- **Agent behaviour with a trigger of its own:** a skill, `.agents/skills//SKILL.md`. + +## House format + +**Playbook** — `add-web-route.md` is the template. Title, then a line saying where the conventions live and +that this file is only the ordering. The expected failure, or the one step that fails silently, before step 1. +Numbered steps, each opening with the action in bold and stating the cost of skipping it. Name a canonical file +to copy by path. Close on `## Verify`: a fenced `sh` block of real commands and what a given failure means. If +you cannot write the Verify block, it is reference and belongs in an `AGENTS.md` or architecture doc. + +**AGENTS.md** — title is the workspace path (`# apps/web`). A few lines of identity: what it is, who consumes +it, whether it builds. Stakes in a blockquote where a mistake is expensive. Traps before conventions. Name the +canonical file for each recurring task. Close on how the work is checked (`## Tests` with +`pnpm exec vitest --project `, or what covers it instead). Point down, not up: root `AGENTS.md` is +always loaded. + +**A new `AGENTS.md` needs a sibling `CLAUDE.md` symlink** (`ln -s AGENTS.md CLAUDE.md`, committed at git mode +`120000`), except the published `packages/instrument-guidelines/AGENTS.md`, which is not this repo's +conventions. Never author or edit a `CLAUDE.md`. + +**Skill** — the body follows `.agents/skills/writing-skills-for-agents/SKILL.md`. **A skill nothing symlinks +is never loaded:** add `ln -s ../../.agents/skills/ .claude/skills/` (git mode `120000`) and an +`agents/openai.yaml` sidecar with `interface.display_name` and `interface.short_description`. + +## Prose rules + +- **Bold lead-in on every rule**, so the bold text alone is the summary. +- **State the failure, not the exhortation**: "a story written anywhere else is silently not picked up", not + "be careful where you put stories". +- **Every non-obvious claim carries its path**; a decision carries the commit SHA that made it. +- **State a count only beside the command that reproduces it**; prose counts go stale, tables count themselves. +- **Write the fact, not the process that found it.** + +## Docs that move together + +- **A workspace added, renamed or moved:** `.agents/docs/workspace-map.md` ("Who depends on what", "Built vs + source-only", "Published to npm"), `.agents/docs/index.md` "Where to look", and the new `AGENTS.md` and its + symlink. +- **A vitest project added or removed:** `.agents/docs/architecture/testing-strategy.md` "Vitest projects" + (the table, the count in its first line, and the "Everything else has no unit tests" paragraph), and the + workspace `AGENTS.md` `## Tests`. +- **A consumed `@douglasneuroinformatics/*` package added or removed:** the table and its count in + `.agents/docs/packages/index.md`, and the count in `.agents/docs/index.md` "Deeper reference, read on + demand". +- **A new playbook:** `.agents/docs/index.md` "Step-by-step playbooks". +- **A new architecture doc:** `.agents/docs/index.md` "Deeper reference, read on demand". + +**Done when** every path you cited resolves and any `AGENTS.md` your change contradicts is revised in the same +commit with the user's approval — or your reply names what you skipped. diff --git a/.agents/skills/writing-agent-docs/agents/openai.yaml b/.agents/skills/writing-docs-for-agents/agents/openai.yaml similarity index 67% rename from .agents/skills/writing-agent-docs/agents/openai.yaml rename to .agents/skills/writing-docs-for-agents/agents/openai.yaml index 40887d469..e14025b32 100644 --- a/.agents/skills/writing-agent-docs/agents/openai.yaml +++ b/.agents/skills/writing-docs-for-agents/agents/openai.yaml @@ -1,3 +1,3 @@ interface: - display_name: 'Writing Agent Docs' + display_name: 'Writing Docs for Agents' short_description: 'Where a repo fact belongs, and the house doc format' diff --git a/.claude/skills/writing-agent-docs b/.claude/skills/writing-agent-docs deleted file mode 120000 index a0770d0a9..000000000 --- a/.claude/skills/writing-agent-docs +++ /dev/null @@ -1 +0,0 @@ -../../.agents/skills/writing-agent-docs \ No newline at end of file diff --git a/.claude/skills/writing-docs-for-agents b/.claude/skills/writing-docs-for-agents new file mode 120000 index 000000000..08a6cc05c --- /dev/null +++ b/.claude/skills/writing-docs-for-agents @@ -0,0 +1 @@ +../../.agents/skills/writing-docs-for-agents \ No newline at end of file From 0a04cd0b86b953338d6353845634921514445e7d Mon Sep 17 00:00:00 2001 From: joshunrau Date: Fri, 13 Nov 2026 12:43:25 -0500 Subject: [PATCH 3/5] ci: label each open pull request with its review status A workflow gives every open pull request exactly one Status: label, recomputed from what GitHub reports: draft, needs rebase, CI failing, waiting on author, waiting on review or ready to merge. Only reviews from accounts with write access approve or block, and a check is read from its newest run, so a failure that passed on a re-run does not read as CI failing. Co-Authored-By: Claude Fable 5.2 --- .agents/docs/architecture/testing-strategy.md | 8 + .github/scripts/__tests__/pr-status.test.ts | 286 +++++++++++++++++ .github/scripts/pr-status.ts | 292 ++++++++++++++++++ .github/workflows/pr-status.yaml | 38 +++ scripts/label-pr-status.ts | 38 +++ tsconfig.json | 4 +- 6 files changed, 663 insertions(+), 3 deletions(-) create mode 100644 .github/scripts/__tests__/pr-status.test.ts create mode 100644 .github/scripts/pr-status.ts create mode 100644 .github/workflows/pr-status.yaml create mode 100644 scripts/label-pr-status.ts diff --git a/.agents/docs/architecture/testing-strategy.md b/.agents/docs/architecture/testing-strategy.md index 7e9ed657d..3c9bab04e 100644 --- a/.agents/docs/architecture/testing-strategy.md +++ b/.agents/docs/architecture/testing-strategy.md @@ -131,6 +131,14 @@ hook, which formats rather than verifies. tests before a release build.** `.github/workflows/commitlint.yaml` (`pull_request` to any branch) lints the commits the PR adds against `commitlint.config.ts`. +The `main: pull requests only` ruleset requires `lint-and-test`, `commitlint` and `check` (from +`.github/workflows/pr-body.yaml`) to pass before a merge, each pinned to the GitHub Actions app. Renaming +one of those jobs blocks every pull request until the ruleset is updated to match. + +`.github/workflows/pr-status.yaml` gates nothing. It gives each open pull request exactly one `Status:` +label, recomputed from GitHub's state by `.github/scripts/pr-status.ts`. Never set those labels by hand, +because the next run overwrites them. + ## Known warts Flag these rather than fixing them in passing; each is load-bearing somewhere. diff --git a/.github/scripts/__tests__/pr-status.test.ts b/.github/scripts/__tests__/pr-status.test.ts new file mode 100644 index 000000000..577b3d22d --- /dev/null +++ b/.github/scripts/__tests__/pr-status.test.ts @@ -0,0 +1,286 @@ +import { describe, expect, it } from 'vitest'; + +import { planStatusLabels, PULL_REQUESTS_QUERY, STATUS_JOB_NAME } from '../pr-status.ts'; + +const HEAD = 'a'.repeat(40); + +const EARLIER = 'b'.repeat(40); + +const AUTHOR = 'contributor'; + +const REVIEWER = 'maintainer'; + +const FIRST_RUN = '2026-01-01T00:00:00Z'; + +const RERUN = '2026-01-01T00:05:00Z'; + +type ReviewNode = { + author: null | { __typename: 'Bot' | 'User'; login: string }; + commit: null | { oid: string }; + state: string; +}; + +type CheckRunParts = { + name?: string; + startedAt?: null | string; + status?: string; +}; + +type ContextNode = + | { __typename: 'CheckRun'; conclusion: null | string; name: string; startedAt: null | string; status: string } + | { __typename: 'StatusContext'; context: string; createdAt: string; state: string }; + +type PullRequestParts = { + author?: null | { login: string }; + contexts?: ContextNode[] | null; + isDraft?: boolean; + labels?: string[]; + latestOpinionatedReviews?: ReviewNode[]; + mergeable?: string; + number?: number; + reviewRequestCount?: number; + reviews?: ReviewNode[]; + threads?: boolean[]; +}; + +function review(state: string, commit = HEAD, login = REVIEWER): ReviewNode { + return { author: { __typename: 'User', login }, commit: { oid: commit }, state }; +} + +function botReview(state: string, commit = HEAD): ReviewNode { + return { author: { __typename: 'Bot', login: 'copilot-pull-request-reviewer' }, commit: { oid: commit }, state }; +} + +function checkRun( + conclusion: null | string, + { name = 'lint-and-test', startedAt = FIRST_RUN, status = 'COMPLETED' }: CheckRunParts = {} +): ContextNode { + return { __typename: 'CheckRun', conclusion, name, startedAt, status }; +} + +function statusContext(state: string, createdAt = FIRST_RUN): ContextNode { + return { __typename: 'StatusContext', context: 'deploy/preview', createdAt, state }; +} + +function connection(nodes: T[]) { + return { nodes, totalCount: nodes.length }; +} + +function pullRequestNode({ + author = { login: AUTHOR }, + contexts = [checkRun('SUCCESS')], + isDraft = false, + labels = [], + latestOpinionatedReviews = [], + mergeable = 'MERGEABLE', + number = 1, + reviewRequestCount = 0, + reviews = latestOpinionatedReviews, + threads = [] +}: PullRequestParts = {}) { + return { + author, + commits: { nodes: [{ commit: { statusCheckRollup: contexts && { contexts: connection(contexts) } } }] }, + headRefOid: HEAD, + isDraft, + labels: connection(labels.map((name) => ({ name }))), + latestOpinionatedReviews: connection(latestOpinionatedReviews), + mergeable, + number, + reviewRequests: { totalCount: reviewRequestCount }, + reviews: { nodes: reviews }, + reviewThreads: connection(threads.map((isResolved) => ({ isResolved }))) + }; +} + +function pages(...pullRequestPages: unknown[][]): string { + return JSON.stringify(pullRequestPages.map((nodes) => ({ data: { repository: { pullRequests: { nodes } } } }))); +} + +function statusOf(parts: PullRequestParts = {}) { + return planStatusLabels(pages([pullRequestNode(parts)]))[0]?.add; +} + +describe('planStatusLabels', () => { + describe('status', () => { + it('should mark a draft as a draft whatever else holds, since no one acts on it yet', () => { + expect(statusOf({ contexts: [checkRun('FAILURE')], isDraft: true, mergeable: 'CONFLICTING' })).toBe( + 'Status: Draft' + ); + }); + + it('should ask for a rebase before anything else, since a conflict blocks the merge outright', () => { + expect(statusOf({ contexts: [checkRun('FAILURE')], mergeable: 'CONFLICTING' })).toBe('Status: Needs Rebase'); + }); + + it.each([ + ['a failed check run', checkRun('FAILURE', { name: 'commitlint' })], + ['a timed-out check run', checkRun('TIMED_OUT', { name: 'commitlint' })], + ['an errored status', statusContext('ERROR')] + ])('should mark CI failing on %s', (_, context) => { + expect(statusOf({ contexts: [checkRun('SUCCESS'), context] })).toBe('Status: CI Failing'); + }); + + it.each([ + ['listed after the failed run', [checkRun('FAILURE'), checkRun('SUCCESS', { startedAt: RERUN })]], + ['listed before the failed run', [checkRun('SUCCESS', { startedAt: RERUN }), checkRun('FAILURE')]] + ])('should not mark CI failing when a check passed on a re-run %s', (_, contexts) => { + expect(statusOf({ contexts })).toBe('Status: Waiting on Review'); + }); + + it('should mark CI failing when the newest run of a check failed after an earlier pass', () => { + expect(statusOf({ contexts: [checkRun('SUCCESS'), checkRun('FAILURE', { startedAt: RERUN })] })).toBe( + 'Status: CI Failing' + ); + }); + + it('should read a status from its newest report, so an error that later succeeded is not CI failing', () => { + expect(statusOf({ contexts: [statusContext('ERROR'), statusContext('SUCCESS', RERUN)] })).toBe( + 'Status: Waiting on Review' + ); + }); + + it('should count a check run with no start time as the oldest of its name', () => { + expect(statusOf({ contexts: [checkRun('SUCCESS'), checkRun('FAILURE', { startedAt: null })] })).toBe( + 'Status: Waiting on Review' + ); + }); + + it("should ignore the status job's own check run, so a failed labelling run does not label itself", () => { + expect(statusOf({ contexts: [checkRun('SUCCESS'), checkRun('FAILURE', { name: STATUS_JOB_NAME })] })).toBe( + 'Status: Waiting on Review' + ); + }); + + it('should wait on review when nobody has reviewed yet', () => { + expect(statusOf()).toBe('Status: Waiting on Review'); + }); + + it('should wait on the author when changes were requested on the head', () => { + expect(statusOf({ latestOpinionatedReviews: [review('CHANGES_REQUESTED')] })).toBe('Status: Waiting on Author'); + }); + + it('should wait on the author when a comment on the head left a thread unresolved', () => { + expect(statusOf({ reviews: [review('COMMENTED')], threads: [true, false] })).toBe('Status: Waiting on Author'); + }); + + it('should not count resolved threads as open feedback', () => { + expect(statusOf({ reviews: [review('COMMENTED')], threads: [true] })).toBe('Status: Waiting on Review'); + }); + + it('should be ready to merge when the head is approved over unresolved threads, since approving closes them', () => { + expect(statusOf({ latestOpinionatedReviews: [review('APPROVED')], threads: [false] })).toBe( + 'Status: Ready to Merge' + ); + }); + + it("should keep requested changes open over another reviewer's approval of the head", () => { + const latestOpinionatedReviews = [review('CHANGES_REQUESTED'), review('APPROVED', HEAD, 'second-reviewer')]; + expect(statusOf({ latestOpinionatedReviews })).toBe('Status: Waiting on Author'); + }); + + it("should not count a bot's review of the head as a person having seen the push", () => { + const changesRequested = review('CHANGES_REQUESTED', EARLIER); + const reviews = [changesRequested, botReview('COMMENTED')]; + expect(statusOf({ latestOpinionatedReviews: [changesRequested], reviews })).toBe('Status: Waiting on Review'); + }); + + it("should not count a bot's approval of the head", () => { + expect(statusOf({ latestOpinionatedReviews: [botReview('APPROVED')] })).toBe('Status: Waiting on Review'); + }); + + it('should wait on review once the author pushes after the requested changes', () => { + expect(statusOf({ latestOpinionatedReviews: [review('CHANGES_REQUESTED', EARLIER)] })).toBe( + 'Status: Waiting on Review' + ); + }); + + it('should wait on review once the author requests a review again', () => { + expect(statusOf({ latestOpinionatedReviews: [review('CHANGES_REQUESTED')], reviewRequestCount: 1 })).toBe( + 'Status: Waiting on Review' + ); + }); + + it("should not count the author's thread replies as a review of the head", () => { + const changesRequested = review('CHANGES_REQUESTED', EARLIER); + const reviews = [changesRequested, review('COMMENTED', HEAD, AUTHOR)]; + expect(statusOf({ latestOpinionatedReviews: [changesRequested], reviews })).toBe('Status: Waiting on Review'); + }); + + it("should still read a review of the head when the pull request's author deleted their account", () => { + expect(statusOf({ author: null, latestOpinionatedReviews: [review('CHANGES_REQUESTED')] })).toBe( + 'Status: Waiting on Author' + ); + }); + + it('should wait on review when feedback comes from a deleted account on an unknown commit', () => { + const ghost: ReviewNode = { author: null, commit: null, state: 'CHANGES_REQUESTED' }; + expect(statusOf({ latestOpinionatedReviews: [ghost] })).toBe('Status: Waiting on Review'); + }); + + it('should be ready to merge when the head is approved and every check passes', () => { + const contexts = [checkRun('SUCCESS'), checkRun('NEUTRAL', { name: 'commitlint' }), statusContext('SUCCESS')]; + expect(statusOf({ contexts, latestOpinionatedReviews: [review('APPROVED')] })).toBe('Status: Ready to Merge'); + }); + + it('should not be ready to merge on an approval of an earlier commit, so a later push is reviewed', () => { + expect(statusOf({ latestOpinionatedReviews: [review('APPROVED', EARLIER)] })).toBe('Status: Waiting on Review'); + }); + + it.each([ + ['a check run is in progress', [checkRun(null, { status: 'IN_PROGRESS' })]], + ['a status is pending', [statusContext('PENDING')]], + ['no check has reported', null] + ])('should not be ready to merge while %s', (_, contexts) => { + expect(statusOf({ contexts, latestOpinionatedReviews: [review('APPROVED')] })).toBe('Status: Waiting on Review'); + }); + }); + + describe('changes', () => { + it('should change nothing when the pull request already carries its status alone', () => { + expect(planStatusLabels(pages([pullRequestNode({ labels: ['Bug', 'Status: Waiting on Review'] })]))).toEqual([]); + }); + + it('should swap a stale status for the current one and leave other labels alone', () => { + const node = pullRequestNode({ isDraft: true, labels: ['Bug', 'Status: Waiting on Review'], number: 7 }); + expect(planStatusLabels(pages([node]))).toEqual([ + { add: 'Status: Draft', number: 7, remove: ['Status: Waiting on Review'] } + ]); + }); + + it('should remove extra statuses while keeping the current one', () => { + const node = pullRequestNode({ labels: ['Status: CI Failing', 'Status: Waiting on Review'] }); + expect(planStatusLabels(pages([node]))).toEqual([{ add: null, number: 1, remove: ['Status: CI Failing'] }]); + }); + + it('should plan every pull request across pages', () => { + const changes = planStatusLabels(pages([pullRequestNode({ number: 1 })], [pullRequestNode({ number: 2 })])); + expect(changes.map(({ number }) => number)).toEqual([1, 2]); + }); + }); + + describe('query', () => { + it('should ask only for opinionated reviews from accounts with write access, so a passer-by cannot approve or block', () => { + expect(PULL_REQUESTS_QUERY).toContain('latestOpinionatedReviews(first: 100, writersOnly: true)'); + }); + }); + + describe('response', () => { + it('should refuse a truncated connection rather than label from part of the facts', () => { + const node = { ...pullRequestNode(), reviewThreads: { nodes: [], totalCount: 101 } }; + expect(() => planStatusLabels(pages([node]))).toThrow( + 'Expected pages[0].data.repository.pullRequests.nodes[0].reviewThreads to fit in one page of 0' + ); + }); + + it.each([ + ['a non-array response', '{}', 'Expected pages to be an array'], + ['a missing field', pages([{}]), 'nodes[0].author to be an object'], + ['a non-boolean', pages([{ ...pullRequestNode(), isDraft: 'no' }]), 'nodes[0].isDraft to be a boolean'], + ['a non-number', pages([{ ...pullRequestNode(), number: '1' }]), 'nodes[0].number to be a number'], + ['a non-string', pages([{ ...pullRequestNode(), headRefOid: 1 }]), 'nodes[0].headRefOid to be a string'] + ])('should name the path of %s', (_, pagesJson, message) => { + expect(() => planStatusLabels(pagesJson)).toThrow(message); + }); + }); +}); diff --git a/.github/scripts/pr-status.ts b/.github/scripts/pr-status.ts new file mode 100644 index 000000000..e22d51539 --- /dev/null +++ b/.github/scripts/pr-status.ts @@ -0,0 +1,292 @@ +const STATUS_LABELS = [ + 'Status: Draft', + 'Status: Needs Rebase', + 'Status: CI Failing', + 'Status: Waiting on Author', + 'Status: Waiting on Review', + 'Status: Ready to Merge' +] as const; + +type StatusLabel = (typeof STATUS_LABELS)[number]; + +type StatusLabelChange = { + add: null | StatusLabel; + number: number; + remove: StatusLabel[]; +}; + +type CheckOutcome = 'failing' | 'passing' | 'pending'; + +type Check = { + name: string; + outcome: CheckOutcome; + startedAt: string; +}; + +type Review = { + authorLogin: null | string; + commitOid: null | string; + state: string; +}; + +type PullRequest = { + authorLogin: null | string; + checkOutcomes: CheckOutcome[]; + hasConflicts: boolean; + hasReviewRequest: boolean; + headRefOid: string; + isDraft: boolean; + labels: string[]; + latestOpinionatedReviews: Review[]; + number: number; + reviews: Review[]; + unresolvedThreadCount: number; +}; + +type JsonReader = { + boolean: () => boolean; + field: (key: string) => JsonReader; + list: () => JsonReader[]; + nullable: () => JsonReader | null; + number: () => number; + path: string; + string: () => string; +}; + +// The job in .github/workflows/pr-status.yaml. A run dispatched from a pull request's branch is a check on +// that pull request, and one cancelled by a newer run would otherwise read as CI failing. +const STATUS_JOB_NAME = 'label-pr-status'; + +const PASSING_CONCLUSIONS = new Set(['NEUTRAL', 'SKIPPED', 'SUCCESS']); + +const PENDING_STATES = new Set(['EXPECTED', 'PENDING']); + +// `writersOnly` keeps an approval or a change request from an account that cannot merge out of the label. +const PULL_REQUESTS_QUERY = ` +query ($owner: String!, $name: String!, $endCursor: String) { + repository(owner: $owner, name: $name) { + pullRequests(states: OPEN, first: 50, after: $endCursor) { + pageInfo { hasNextPage endCursor } + nodes { + number + isDraft + mergeable + headRefOid + author { login } + labels(first: 100) { totalCount nodes { name } } + reviewRequests(first: 1) { totalCount } + latestOpinionatedReviews(first: 100, writersOnly: true) { totalCount nodes { state author { __typename login } commit { oid } } } + reviews(last: 100) { nodes { state author { __typename login } commit { oid } } } + reviewThreads(first: 100) { totalCount nodes { isResolved } } + commits(last: 1) { + nodes { + commit { + statusCheckRollup { + contexts(first: 100) { + totalCount + nodes { + __typename + ... on CheckRun { name status conclusion startedAt } + ... on StatusContext { context state createdAt } + } + } + } + } + } + } + } + } + } +}`; + +function isRecord(value: unknown): value is { [key: string]: unknown } { + return typeof value === 'object' && value !== null; +} + +function readJson(value: unknown, path: string): JsonReader { + const fail = (expected: string) => new Error(`Expected ${path} to be ${expected}`); + return { + boolean: () => { + if (typeof value !== 'boolean') { + throw fail('a boolean'); + } + return value; + }, + field: (key) => { + if (!isRecord(value)) { + throw fail('an object'); + } + return readJson(value[key], `${path}.${key}`); + }, + list: () => { + if (!Array.isArray(value)) { + throw fail('an array'); + } + return value.map((item, index) => readJson(item, `${path}[${index}]`)); + }, + nullable: () => (value === null ? null : readJson(value, path)), + number: () => { + if (typeof value !== 'number') { + throw fail('a number'); + } + return value; + }, + path, + string: () => { + if (typeof value !== 'string') { + throw fail('a string'); + } + return value; + } + }; +} + +// A truncated connection would label from part of the facts, so it fails instead. +function completeNodes(connection: JsonReader): JsonReader[] { + const nodes = connection.field('nodes').list(); + if (connection.field('totalCount').number() > nodes.length) { + throw new Error(`Expected ${connection.path} to fit in one page of ${nodes.length}`); + } + return nodes; +} + +function readLogin(actor: JsonReader): null | string { + return actor.nullable()?.field('login').string() ?? null; +} + +// A bot's review, such as Copilot's, says nothing about whether a person has seen the change. +function readPersonReviews(reviews: JsonReader[]): Review[] { + return reviews.flatMap((review) => { + const author = review.field('author').nullable(); + if (author?.field('__typename').string() === 'Bot') { + return []; + } + return [ + { + authorLogin: author?.field('login').string() ?? null, + commitOid: review.field('commit').nullable()?.field('oid').string() ?? null, + state: review.field('state').string() + } + ]; + }); +} + +function readCheckOutcome(context: JsonReader): CheckOutcome | null { + if (context.field('__typename').string() === 'StatusContext') { + const state = context.field('state').string(); + if (state === 'SUCCESS') { + return 'passing'; + } + return PENDING_STATES.has(state) ? 'pending' : 'failing'; + } + if (context.field('name').string() === STATUS_JOB_NAME) { + return null; + } + if (context.field('status').string() !== 'COMPLETED') { + return 'pending'; + } + return PASSING_CONCLUSIONS.has(context.field('conclusion').string()) ? 'passing' : 'failing'; +} + +// A check run with no start time counts as the oldest of its name. +function readCheck(context: JsonReader): Check | null { + const outcome = readCheckOutcome(context); + if (outcome === null) { + return null; + } + if (context.field('__typename').string() === 'StatusContext') { + return { name: context.field('context').string(), outcome, startedAt: context.field('createdAt').string() }; + } + return { + name: context.field('name').string(), + outcome, + startedAt: context.field('startedAt').nullable()?.string() ?? '' + }; +} + +// GitHub keeps every run of a check on the head: a re-run sits beside the run it replaced, and PR Body runs +// again on each edit of a body. The newest run of each name is where that check stands, which is also how +// the ruleset's required checks read it. +function latestOutcomes(checks: Check[]): CheckOutcome[] { + const outcomeByName = new Map( + checks + .toSorted((left, right) => left.startedAt.localeCompare(right.startedAt)) + .map((check): [string, CheckOutcome] => [check.name, check.outcome]) + ); + return [...outcomeByName.values()]; +} + +function readPullRequest(pullRequest: JsonReader): PullRequest { + return { + authorLogin: readLogin(pullRequest.field('author')), + checkOutcomes: latestOutcomes( + pullRequest + .field('commits') + .field('nodes') + .list() + .flatMap((node) => { + const rollup = node.field('commit').field('statusCheckRollup').nullable(); + return rollup ? completeNodes(rollup.field('contexts')).map(readCheck) : []; + }) + .filter((check) => check !== null) + ), + hasConflicts: pullRequest.field('mergeable').string() === 'CONFLICTING', + hasReviewRequest: pullRequest.field('reviewRequests').field('totalCount').number() > 0, + headRefOid: pullRequest.field('headRefOid').string(), + isDraft: pullRequest.field('isDraft').boolean(), + labels: completeNodes(pullRequest.field('labels')).map((label) => label.field('name').string()), + latestOpinionatedReviews: readPersonReviews(completeNodes(pullRequest.field('latestOpinionatedReviews'))), + number: pullRequest.field('number').number(), + reviews: readPersonReviews(pullRequest.field('reviews').field('nodes').list()), + unresolvedThreadCount: completeNodes(pullRequest.field('reviewThreads')).filter( + (thread) => !thread.field('isResolved').boolean() + ).length + }; +} + +// Feedback stays open until a reviewer clears it, so whose turn it is comes from what happened after it: +// a push the reviewer has not seen, or a review requested again, hands the pull request back to review. +// The pull request's author replying in a thread is a review too, so only other people's reviews count. +function statusOf(pullRequest: PullRequest): StatusLabel { + if (pullRequest.isDraft) { + return 'Status: Draft'; + } + if (pullRequest.hasConflicts) { + return 'Status: Needs Rebase'; + } + if (pullRequest.checkOutcomes.includes('failing')) { + return 'Status: CI Failing'; + } + // An approval of an earlier commit does not cover what was pushed after it. + const isHeadApproved = pullRequest.latestOpinionatedReviews.some( + (review) => review.state === 'APPROVED' && review.commitOid === pullRequest.headRefOid + ); + // Reviewers approve over their own threads rather than resolving them, so an approval of the head + // closes the threads; requested changes stay open until their reviewer approves or is dismissed. + const hasOpenFeedback = + pullRequest.latestOpinionatedReviews.some((review) => review.state === 'CHANGES_REQUESTED') || + (pullRequest.unresolvedThreadCount > 0 && !isHeadApproved); + if (hasOpenFeedback) { + const lastReview = pullRequest.reviews.findLast((review) => review.authorLogin !== pullRequest.authorLogin); + const isHeadReviewed = lastReview?.commitOid === pullRequest.headRefOid; + return isHeadReviewed && !pullRequest.hasReviewRequest ? 'Status: Waiting on Author' : 'Status: Waiting on Review'; + } + const areChecksPassing = + pullRequest.checkOutcomes.length > 0 && pullRequest.checkOutcomes.every((outcome) => outcome === 'passing'); + return isHeadApproved && areChecksPassing ? 'Status: Ready to Merge' : 'Status: Waiting on Review'; +} + +export { PULL_REQUESTS_QUERY, STATUS_JOB_NAME }; + +export function planStatusLabels(pagesJson: string): StatusLabelChange[] { + return readJson(JSON.parse(pagesJson), 'pages') + .list() + .flatMap((page) => page.field('data').field('repository').field('pullRequests').field('nodes').list()) + .map(readPullRequest) + .flatMap((pullRequest) => { + const status = statusOf(pullRequest); + const add = pullRequest.labels.includes(status) ? null : status; + const remove = STATUS_LABELS.filter((label) => label !== status && pullRequest.labels.includes(label)); + return add === null && remove.length === 0 ? [] : [{ add, number: pullRequest.number, remove }]; + }); +} diff --git a/.github/workflows/pr-status.yaml b/.github/workflows/pr-status.yaml new file mode 100644 index 000000000..80110b6f1 --- /dev/null +++ b/.github/workflows/pr-status.yaml @@ -0,0 +1,38 @@ +name: PR Status +# These triggers attach no run to a pull request, so this job stays out of its checks unless dispatched +# from its branch. CI runs on every open and push, so those relabel at once; a review, a resolved thread +# or a draft toggle starts no workflow that can write to a fork's pull request, so the schedule catches them. +on: + workflow_run: + workflows: [CI, Commitlint, PR Body] + types: [completed] + schedule: + - cron: '*/15 * * * *' + workflow_dispatch: +permissions: + checks: read + contents: read + pull-requests: write + statuses: read +# every run relabels every open pull request, so only the latest run matters +concurrency: + group: pr-status + cancel-in-progress: true +jobs: + label-pr-status: + runs-on: ubuntu-latest + steps: + # the job runs main's code with a write token and reads pull requests only through the API; it + # never checks out or runs a pull request's code + - name: Checkout Code + uses: actions/checkout@v7 + with: + ref: main + - name: Setup Node.js + uses: actions/setup-node@v7 + with: + node-version-file: '.nvmrc' + - name: Label Pull Requests by Status + env: + GH_TOKEN: ${{ github.token }} + run: node scripts/label-pr-status.ts diff --git a/scripts/label-pr-status.ts b/scripts/label-pr-status.ts new file mode 100644 index 000000000..b827ddb7b --- /dev/null +++ b/scripts/label-pr-status.ts @@ -0,0 +1,38 @@ +import { execFileSync } from 'node:child_process'; + +import { planStatusLabels, PULL_REQUESTS_QUERY } from '../.github/scripts/pr-status.ts'; + +function gh(...args: string[]): string { + return execFileSync('gh', args, { encoding: 'utf8' }); +} + +const repository = process.env.GITHUB_REPOSITORY ?? ''; +const [owner, name, ...rest] = repository.split('/'); +if (!owner || !name || rest.length > 0) { + throw new Error(`Expected GITHUB_REPOSITORY to be /, got '${repository}'`); +} + +const pagesJson = gh( + 'api', + 'graphql', + '--paginate', + '--slurp', + '-f', + `owner=${owner}`, + '-f', + `name=${name}`, + '-f', + `query=${PULL_REQUESTS_QUERY}` +); + +for (const { add, number, remove } of planStatusLabels(pagesJson)) { + for (const label of remove) { + gh('api', '--method', 'DELETE', `repos/${repository}/issues/${number}/labels/${encodeURIComponent(label)}`); + } + if (add) { + gh('api', '--method', 'POST', `repos/${repository}/issues/${number}/labels`, '-f', `labels[]=${add}`); + } + process.stdout.write( + `#${number}: ${[add && `+${add}`, ...remove.map((label) => `-${label}`)].filter(Boolean).join(', ')}\n` + ); +} diff --git a/tsconfig.json b/tsconfig.json index 0126ced6b..dcf25e3ad 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -13,9 +13,7 @@ "types": ["node"] }, "include": [ - ".github/scripts/__tests__/*.ts", - ".github/scripts/pr-body.ts", - ".github/scripts/release.cjs", + ".github/scripts/**/*", ".github/vitest.config.ts", "commitlint.config.ts", "knip.ts", From a6abb11aa491d512b046efe6b6eac4d4e153862c Mon Sep 17 00:00:00 2001 From: joshunrau Date: Fri, 13 Nov 2026 12:43:27 -0500 Subject: [PATCH 4/5] ci: plan the release from a typescript script instead of github-script release.cjs becomes .github/scripts/release.ts, and the configure job runs scripts/plan-release.ts with node, the way pr-body.yaml and pr-status.yaml run their scripts. The plan and its outputs are unchanged. Co-Authored-By: Claude Fable 5.2 --- .agents/docs/architecture/release-channels.md | 12 +- .agents/docs/playbooks/cut-a-release.md | 16 +- .github/scripts/__tests__/release.test.ts | 48 ++---- .github/scripts/release.cjs | 138 ------------------ .github/scripts/release.ts | 113 ++++++++++++++ .github/workflows/release.yaml | 15 +- knip.ts | 7 +- scripts/increment-version.ts | 2 +- scripts/plan-release.ts | 20 +++ 9 files changed, 167 insertions(+), 204 deletions(-) delete mode 100644 .github/scripts/release.cjs create mode 100644 .github/scripts/release.ts create mode 100644 scripts/plan-release.ts diff --git a/.agents/docs/architecture/release-channels.md b/.agents/docs/architecture/release-channels.md index 38550bec1..958ab5c91 100644 --- a/.agents/docs/architecture/release-channels.md +++ b/.agents/docs/architecture/release-channels.md @@ -11,11 +11,11 @@ is `.agents/docs/playbooks/cut-a-release.md`. This file is the model both act on ## The decision is `planRelease`, and it reads only the repository -`.github/scripts/release.cjs` exports `planRelease({ ref, tags, version })`. `release.yaml`'s -`configure` job calls it with the pushed or dispatched ref, every `v*` git tag and the root -`package.json` version, and every later job acts on its outputs. It never reads GHCR or npm: a deleted -image or package must not be able to wedge the next release, and the GHCR lookup an earlier version -made did exactly that. +`.github/scripts/release.ts` exports `planRelease({ ref, tags, version })`. `release.yaml`'s +`configure` job runs `scripts/plan-release.ts`, which calls it with the pushed or dispatched ref, every +`v*` git tag and the root `package.json` version, and every later job acts on its outputs. It never +reads GHCR or npm: a deleted image or package must not be able to wedge the next release, and the GHCR +lookup an earlier version made did exactly that. | Output | Meaning | | --------- | ------------------------------------------------------------------------- | @@ -65,7 +65,7 @@ major once the next major ships from `main`, and released only by `gh workflow run Release --ref release/`. A push to it publishes nothing. Changes land on it by a pull request, which `ci.yaml` gates as it gates one to `main`. -**A release branch takes fixes only.** `scripts/increment-version.ts` asks `release.cjs`'s +**A release branch takes fixes only.** `scripts/increment-version.ts` asks `release.ts`'s `isSupersededMajor` whether the current major is superseded; if it is, it offers and accepts a patch bump only, and refuses a breaking or `feat` commit in range outright. On `main`, once a breaking commit is in range, it accepts a major bump only. diff --git a/.agents/docs/playbooks/cut-a-release.md b/.agents/docs/playbooks/cut-a-release.md index f11740591..7ed9b8c6d 100644 --- a/.agents/docs/playbooks/cut-a-release.md +++ b/.agents/docs/playbooks/cut-a-release.md @@ -69,13 +69,13 @@ them. Never hand-edit a version field. 7. **Watch the run:** `gh run watch`, or `gh run list --workflow=Release --limit 1` for its id. - | Job | Does | Does not run when | - | ------------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | - | `configure` | derives the image matrix from `docker compose config`; `release.cjs` plans the run from the root version and the git tags | never; **fails** on any ref but `main` and `release/`, and on a branch dispatch the plan refuses | - | `validate` | `pnpm lint` | never | - | `build` | buildx `linux/amd64,linux/arm64` per image, pushing the tags the plan enables onto one manifest | `configure` or `validate` failed | - | `publish-npm` | builds each publishable package and publishes each version npm lacks, over OIDC in the `release` environment | `build` did not succeed, or the plan's `latest` is `false` (no release, or a release from a branch) | - | `release` | creates the GitHub release `v${version}` on the built commit from `scripts/changelog.ts section` | the plan's `release` is `false`, `build` did not succeed, or `publish-npm` ran and failed | + | Job | Does | Does not run when | + | ------------- | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------- | + | `configure` | derives the image matrix from `docker compose config`; `release.ts` plans the run from the root version and the git tags | never; **fails** on any ref but `main` and `release/`, and on a branch dispatch the plan refuses | + | `validate` | `pnpm lint` | never | + | `build` | buildx `linux/amd64,linux/arm64` per image, pushing the tags the plan enables onto one manifest | `configure` or `validate` failed | + | `publish-npm` | builds each publishable package and publishes each version npm lacks, over OIDC in the `release` environment | `build` did not succeed, or the plan's `latest` is `false` (no release, or a release from a branch) | + | `release` | creates the GitHub release `v${version}` on the built commit from `scripts/changelog.ts section` | the plan's `release` is `false`, `build` did not succeed, or `publish-npm` ran and failed | A `build` that fails or is cancelled shows `publish-npm` and `release` as **skipped**, not failed. On a push with no bump both are skipped by design; read `configure`'s `release` output first. @@ -90,7 +90,7 @@ them. Never hand-edit a version field. tags are bare; the `v` is on the GitHub tag only. `scripts/publish.sh` is wired to nothing and is not a substitute: it pushes your daemon's local `:latest` of all four over the CI-published ones. - **`release.cjs` refusing other refs stops accidents only**, since a dispatched ref supplies its + **`release.ts` refusing other refs stops accidents only**, since a dispatched ref supplies its own workflow. The hosted configuration that does the enforcing is listed in `release-channels.md` §Release branches and must stay. The `Release tags` ruleset cannot restrict tag creation, because GitHub refuses the Actions app as a bypass actor. diff --git a/.github/scripts/__tests__/release.test.ts b/.github/scripts/__tests__/release.test.ts index 00079aa96..d79a11bc8 100644 --- a/.github/scripts/__tests__/release.test.ts +++ b/.github/scripts/__tests__/release.test.ts @@ -1,10 +1,6 @@ -import fs from 'node:fs'; +import { describe, expect, it } from 'vitest'; -import { afterEach, describe, expect, it, vi } from 'vitest'; - -import release from '../release.cjs'; - -const { planRelease } = release; +import { planRelease, planReleaseOutputs } from '../release.ts'; const MAIN = 'refs/heads/main'; const RELEASE_2 = 'refs/heads/release/2'; @@ -93,42 +89,16 @@ describe('planRelease', () => { }); }); -describe('release', () => { - afterEach(() => { - vi.restoreAllMocks(); - }); - - function run(ref: string, version: string, tags: string) { - const readFileSync = vi.spyOn(fs, 'readFileSync').mockReturnValue(JSON.stringify({ version })); - const core = { notice: vi.fn(), setOutput: vi.fn() }; - const exec = { getExecOutput: vi.fn(() => Promise.resolve({ stdout: tags })) }; - return { core, done: release({ context: { ref }, core, exec }), exec, readFileSync }; - } - - it('should plan from the root package.json and every v* tag in the repository', async () => { - const { done, exec, readFileSync } = run(MAIN, '2.6.0', 'v2.5.2\n'); - await done; - expect(readFileSync).toHaveBeenCalledWith('package.json', 'utf-8'); - expect(exec.getExecOutput).toHaveBeenCalledWith('git', ['tag', '--list', 'v*']); - }); - - it('should expose the plan for the root version and the git tags as workflow outputs', async () => { - const { core, done } = run(MAIN, '2.6.0', 'v2.5.1\nv2.5.2\n'); - await done; - expect(Object.fromEntries(core.setOutput.mock.calls)).toEqual({ - edge: 'true', - latest: 'true', - major: '2', - release: 'true', - version: '2.6.0' +describe('planReleaseOutputs', () => { + it('should expose the plan for the root version and every listed tag as workflow outputs', () => { + expect(planReleaseOutputs({ ref: MAIN, tagList: 'v2.5.1\nv2.5.2\n', version: '2.6.0' })).toEqual({ + githubOutput: 'edge=true\nlatest=true\nmajor=2\nrelease=true\nversion=2.6.0\n', + notice: null }); - expect(core.notice).not.toHaveBeenCalled(); }); - it('should say that a release of a superseded major skips npm, so the missing publish is not a surprise', async () => { - const { core, done } = run(RELEASE_2, '2.6.1', 'v2.6.0\nv3.0.0\n'); - await done; - expect(core.notice).toHaveBeenCalledWith( + it('should say that a release of a superseded major skips npm, so the missing publish is not a surprise', () => { + expect(planReleaseOutputs({ ref: RELEASE_2, tagList: 'v2.6.0\nv3.0.0\n', version: '2.6.1' }).notice).toBe( 'Skipping npm: 2.6.1 releases the superseded 2 line, and npm publishes from main only' ); }); diff --git a/.github/scripts/release.cjs b/.github/scripts/release.cjs deleted file mode 100644 index aac29c9ce..000000000 --- a/.github/scripts/release.cjs +++ /dev/null @@ -1,138 +0,0 @@ -// @ts-check -const fs = require('node:fs'); - -// What each field makes the workflow do: .agents/docs/architecture/release-channels.md. -/** - * @typedef {object} ReleasePlan - * @property {boolean} edge - * @property {boolean} latest - * @property {string} major - * @property {boolean} release - * @property {string} version - */ - -/** @typedef {readonly [number, number, number]} ParsedVersion */ - -const RELEASE_BRANCH_PATTERN = /^refs\/heads\/release\/(\d+)$/; -const VERSION_PATTERN = /^(\d+)\.(\d+)\.(\d+)$/; - -/** - * @param {string} version - * @returns {ParsedVersion | null} - */ -function parseVersion(version) { - const match = VERSION_PATTERN.exec(version); - return match && [Number(match[1]), Number(match[2]), Number(match[3])]; -} - -/** - * @param {string} tag - * @returns {ParsedVersion | null} - */ -function parseTag(tag) { - return tag.startsWith('v') ? parseVersion(tag.slice(1)) : null; -} - -/** - * A major with a higher major tagged is superseded: it takes fixes only, from its `release/` - * branch. `scripts/increment-version.ts` asks the same question, so it imports this. - * - * @param {number} major - * @param {readonly string[]} tags - */ -function isSupersededMajor(major, tags) { - return tags.some((tag) => { - const parsedTag = parseTag(tag); - return parsedTag !== null && parsedTag[0] > major; - }); -} - -/** - * @param {ParsedVersion} left - * @param {ParsedVersion} right - */ -function compareVersions(left, right) { - return left[0] - right[0] || left[1] - right[1] || left[2] - right[2]; -} - -/** - * Decide what a run of the Release workflow publishes. - * - * `main` always builds `edge`, and releases only when its version has no `v*` tag yet. A - * `release/` branch exists only for a superseded major, so it can never move `latest`, and - * npm, whose trusted publisher trusts `main` alone, skips it. - * - * The decision reads only the repository — the version file and the git tags — never a registry: a - * deleted image or package must not be able to wedge the next release. It is only as fresh as the - * tag snapshot, which is why `release.yaml` runs one Release at a time across every ref. - * - * @param {{ ref: string; tags: readonly string[]; version: string }} input - * @returns {ReleasePlan} - */ -function planRelease({ ref, tags, version }) { - const parsedVersion = parseVersion(version); - if (!parsedVersion) { - throw new Error(`The root package.json version '${version}' is not ..`); - } - const major = String(parsedVersion[0]); - const isMain = ref === 'refs/heads/main'; - const releaseBranch = RELEASE_BRANCH_PATTERN.exec(ref); - if (!isMain && !releaseBranch) { - throw new Error(`Releases are cut from refs/heads/main or refs/heads/release/, not ${ref}`); - } - const release = !tags.includes(`v${version}`); - if (releaseBranch) { - if (releaseBranch[1] !== major) { - throw new Error(`Version ${version} does not belong on ${ref}`); - } - if (!isSupersededMajor(parsedVersion[0], tags)) { - throw new Error(`No major above ${major} is tagged, so ${major}.x is still released from refs/heads/main`); - } - if (!release) { - throw new Error(`v${version} is already released; bump the version on ${ref} first`); - } - } - const blockingTag = tags.find((tag) => { - const parsedTag = parseTag(tag); - return ( - parsedTag !== null && - compareVersions(parsedTag, parsedVersion) > 0 && - (isMain || parsedTag[0] === parsedVersion[0]) - ); - }); - if (release && blockingTag) { - throw new Error(`${version} is older than ${blockingTag}; bump past it first`); - } - return { edge: isMain, latest: isMain && release, major, release, version }; -} - -/** - * Expose the release plan as workflow outputs. - * - * The dispatched ref supplies this file too, so the ref check here stops accidents only. The - * `release` environment's branch policy and the npm trusted publisher are what enforce it. - * - * @param {{ - * context: { ref: string }; - * core: { notice: (message: string) => void; setOutput: (name: string, value: string) => void }; - * exec: { getExecOutput: (command: string, args: string[]) => Promise<{ stdout: string }> }; - * }} args - */ -module.exports = async ({ context, core, exec }) => { - /** @type {string} */ - const version = JSON.parse(fs.readFileSync('package.json', 'utf-8')).version; - const { stdout } = await exec.getExecOutput('git', ['tag', '--list', 'v*']); - const plan = planRelease({ ref: context.ref, tags: stdout.split('\n').filter(Boolean), version }); - if (plan.release && !plan.latest) { - core.notice( - `Skipping npm: ${version} releases the superseded ${plan.major} line, and npm publishes from main only` - ); - } - for (const [name, value] of Object.entries(plan)) { - core.setOutput(name, String(value)); - } -}; - -module.exports.isSupersededMajor = isSupersededMajor; -module.exports.parseVersion = parseVersion; -module.exports.planRelease = planRelease; diff --git a/.github/scripts/release.ts b/.github/scripts/release.ts new file mode 100644 index 000000000..909edb3be --- /dev/null +++ b/.github/scripts/release.ts @@ -0,0 +1,113 @@ +// What each field makes the workflow do: .agents/docs/architecture/release-channels.md. +type ReleasePlan = { + edge: boolean; + latest: boolean; + major: string; + release: boolean; + version: string; +}; + +type ParsedVersion = readonly [number, number, number]; + +type ReleaseState = { + ref: string; + tags: readonly string[]; + version: string; +}; + +type ReleaseRun = { + ref: string; + tagList: string; + version: string; +}; + +type ReleaseOutputs = { + githubOutput: string; + notice: null | string; +}; + +const RELEASE_BRANCH_PATTERN = /^refs\/heads\/release\/(\d+)$/; +const VERSION_PATTERN = /^(\d+)\.(\d+)\.(\d+)$/; + +function parseVersion(version: string): null | ParsedVersion { + const match = VERSION_PATTERN.exec(version); + return match && [Number(match[1]), Number(match[2]), Number(match[3])]; +} + +function parseTag(tag: string): null | ParsedVersion { + return tag.startsWith('v') ? parseVersion(tag.slice(1)) : null; +} + +// A major with a higher major tagged is superseded: it takes fixes only, from its `release/` +// branch. `scripts/increment-version.ts` asks the same question, so it imports this. +function isSupersededMajor(major: number, tags: readonly string[]): boolean { + return tags.some((tag) => { + const parsedTag = parseTag(tag); + return parsedTag !== null && parsedTag[0] > major; + }); +} + +function compareVersions(left: ParsedVersion, right: ParsedVersion): number { + return left[0] - right[0] || left[1] - right[1] || left[2] - right[2]; +} + +// `main` always builds `edge`, and releases only when its version has no `v*` tag yet. A +// `release/` branch exists only for a superseded major, so it can never move `latest`, and +// npm, whose trusted publisher trusts `main` alone, skips it. +// +// The decision reads only the repository — the version file and the git tags — never a registry: a +// deleted image or package must not be able to wedge the next release. It is only as fresh as the +// tag snapshot, which is why `release.yaml` runs one Release at a time across every ref. +function planRelease({ ref, tags, version }: ReleaseState): ReleasePlan { + const parsedVersion = parseVersion(version); + if (!parsedVersion) { + throw new Error(`The root package.json version '${version}' is not ..`); + } + const major = String(parsedVersion[0]); + const isMain = ref === 'refs/heads/main'; + const releaseBranch = RELEASE_BRANCH_PATTERN.exec(ref); + if (!isMain && !releaseBranch) { + throw new Error(`Releases are cut from refs/heads/main or refs/heads/release/, not ${ref}`); + } + const release = !tags.includes(`v${version}`); + if (releaseBranch) { + if (releaseBranch[1] !== major) { + throw new Error(`Version ${version} does not belong on ${ref}`); + } + if (!isSupersededMajor(parsedVersion[0], tags)) { + throw new Error(`No major above ${major} is tagged, so ${major}.x is still released from refs/heads/main`); + } + if (!release) { + throw new Error(`v${version} is already released; bump the version on ${ref} first`); + } + } + const blockingTag = tags.find((tag) => { + const parsedTag = parseTag(tag); + return ( + parsedTag !== null && + compareVersions(parsedTag, parsedVersion) > 0 && + (isMain || parsedTag[0] === parsedVersion[0]) + ); + }); + if (release && blockingTag) { + throw new Error(`${version} is older than ${blockingTag}; bump past it first`); + } + return { edge: isMain, latest: isMain && release, major, release, version }; +} + +// The dispatched ref supplies this file too, so the ref check in `planRelease` stops accidents only. The +// `release` environment's branch policy and the npm trusted publisher are what enforce it. +function planReleaseOutputs({ ref, tagList, version }: ReleaseRun): ReleaseOutputs { + const plan = planRelease({ ref, tags: tagList.split('\n').filter(Boolean), version }); + return { + githubOutput: Object.entries(plan) + .map(([name, value]) => `${name}=${String(value)}\n`) + .join(''), + notice: + plan.release && !plan.latest + ? `Skipping npm: ${version} releases the superseded ${plan.major} line, and npm publishes from main only` + : null + }; +} + +export { isSupersededMajor, parseVersion, planRelease, planReleaseOutputs }; diff --git a/.github/workflows/release.yaml b/.github/workflows/release.yaml index ca3de53f8..da185469e 100644 --- a/.github/workflows/release.yaml +++ b/.github/workflows/release.yaml @@ -2,12 +2,12 @@ name: Release on: push: branches: ['main'] - # A release/ branch releases on dispatch only; release.cjs refuses any other ref. + # A release/ branch releases on dispatch only; release.ts refuses any other ref. workflow_dispatch: permissions: contents: write packages: write -# One Release at a time across every ref: release.cjs plans from a tag snapshot, so a run on another +# One Release at a time across every ref: release.ts plans from a tag snapshot, so a run on another # ref must not overlap it (.agents/docs/architecture/release-channels.md). concurrency: group: ${{ github.workflow }} @@ -29,19 +29,20 @@ jobs: - name: Checkout Repository uses: actions/checkout@v7 with: - fetch-depth: 0 # release.cjs reads every v* tag + fetch-depth: 0 # release.ts reads every v* tag - name: Derive Build Matrix id: matrix run: | matrix=$(docker compose config --no-interpolate --format json \ | jq -c '{include:[.services|to_entries[]|select(.value.build and .value.image)|{image:(.value.image|split(":")[0]),dockerfile:.value.build.dockerfile}]}') echo "matrix=$matrix" >> "$GITHUB_OUTPUT" + - name: Setup Node + uses: actions/setup-node@v7 + with: + node-version-file: '.nvmrc' - name: Plan Release id: plan - uses: actions/github-script@v9 - with: - script: | - await require('./.github/scripts/release.cjs')({ context, core, github, exec, glob, io }) + run: node scripts/plan-release.ts validate: runs-on: ubuntu-latest steps: diff --git a/knip.ts b/knip.ts index d6de81925..499f3c85a 100644 --- a/knip.ts +++ b/knip.ts @@ -5,8 +5,6 @@ import runtimeConfig from './runtime/v1/runtime.config.js'; const config: KnipConfig = { ignoreBinaries: ['env-cmd!'], ignoreIssues: { - // module.exports is the function actions/github-script require()s in .github/workflows - '.github/scripts/*.cjs': ['exports'], // reached through the /runtime/v1/* tsconfig paths; vendor wrappers resolve their peers from runtime/v1 'vendor/**': ['unlisted'] }, @@ -15,10 +13,9 @@ const config: KnipConfig = { includeEntryExports: true, workspaces: { '.': { - entry: ['scripts/increment-version.ts', '.github/scripts/*.cjs'], + entry: ['scripts/increment-version.ts'], ignoreBinaries: ['turbo'], - // the JSDoc type of the arguments actions/github-script injects, not an npm package - ignoreDependencies: ['github-script', '@astrojs/starlight'], + ignoreDependencies: ['@astrojs/starlight'], // docs/**/*.mdx is outreach content, compiled through the aliases in its astro.config.ts paths: { '@/components/*': ['apps/outreach/src/components/*'] }, project: ['**/*.{cjs,js,ts}', '!.agents/**'] diff --git a/scripts/increment-version.ts b/scripts/increment-version.ts index 4fbfcc4e0..3780f2b3e 100755 --- a/scripts/increment-version.ts +++ b/scripts/increment-version.ts @@ -8,7 +8,7 @@ import { parseArgs, styleText } from 'node:util'; import { format } from 'prettier'; -import release from '../.github/scripts/release.cjs'; +import * as release from '../.github/scripts/release.ts'; // The menu offers the bumps in this order, so they live in a tuple: perfectionist/sort-objects // alphabetizes object literals and would silently reorder the prompt. diff --git a/scripts/plan-release.ts b/scripts/plan-release.ts new file mode 100644 index 000000000..4b9ceb780 --- /dev/null +++ b/scripts/plan-release.ts @@ -0,0 +1,20 @@ +import { execFileSync } from 'node:child_process'; +import fs from 'node:fs'; + +import { planReleaseOutputs } from '../.github/scripts/release.ts'; +import rootPackage from '../package.json' with { type: 'json' }; + +const { GITHUB_OUTPUT: githubOutputPath, GITHUB_REF: ref } = process.env; +if (!githubOutputPath || !ref) { + throw new Error('Expected GITHUB_OUTPUT and GITHUB_REF, which a workflow step sets'); +} + +const { githubOutput, notice } = planReleaseOutputs({ + ref, + tagList: execFileSync('git', ['tag', '--list', 'v*'], { encoding: 'utf8' }), + version: rootPackage.version +}); +if (notice) { + process.stdout.write(`::notice::${notice}\n`); +} +fs.appendFileSync(githubOutputPath, githubOutput); From bc341ed5104e9e266d4dd39b5b4a89c929f7ff80 Mon Sep 17 00:00:00 2001 From: joshunrau Date: Fri, 13 Nov 2026 12:43:27 -0500 Subject: [PATCH 5/5] chore: add a skill for working the issue backlog in batches Co-Authored-By: Claude Fable 5.2 --- .agents/skills/working-the-backlog/SKILL.md | 174 ++++++++++++++++++ .../working-the-backlog/agents/openai.yaml | 3 + .claude/skills/working-the-backlog | 1 + 3 files changed, 178 insertions(+) create mode 100644 .agents/skills/working-the-backlog/SKILL.md create mode 100644 .agents/skills/working-the-backlog/agents/openai.yaml create mode 120000 .claude/skills/working-the-backlog diff --git a/.agents/skills/working-the-backlog/SKILL.md b/.agents/skills/working-the-backlog/SKILL.md new file mode 100644 index 000000000..fd7eb5813 --- /dev/null +++ b/.agents/skills/working-the-backlog/SKILL.md @@ -0,0 +1,174 @@ +--- +name: working-the-backlog +description: Turn one bounded batch of the open issue backlog into pull requests — tend the operator's open PRs, pick low-difficulty issues and medium-difficulty bugs that share no file with any open PR, wait for a go-ahead, and stop at five PRs in flight. Use only when the user invokes it by name. +disable-model-invocation: true +--- + +A maintainer reads and merges every pull request, so review is the bottleneck: a PR that conflicts with +another, or that settles a question the maintainers should have settled, costs more review than its issue was +worth. + +- **The operator** is whoever invoked this skill: a competent engineer, short of time, assumed to know + neither this codebase nor its issues, and not assumed to be a maintainer. +- **The maintainers** decide direction and merge. They are reached only through GitHub. +- **Every `gh` call takes `--repo DouglasNeuroInformatics/OpenDataCapture`**; `origin` is the operator's fork. +- **The cap is 5 open PRs authored by the operator**, drafts included. + +## 1. Tend the open PRs + +```sh +gh pr list --author @me --state open --json number,title,headRefName,labels +``` + +`.github/workflows/pr-status.yaml` gives every open PR exactly one `Status:` label. Read the labels once, +here: the workflow relabels on a schedule and when CI, Commitlint or PR Body completes, so the label of a PR +you have just acted on is stale. A `Status: Draft` PR is the operator's unfinished work: it holds a slot and +is left alone. Three labels mean the PR needs tending, and each is cleared before any new work: + +- **`Status: CI Failing`.** Fix the check on the branch. A failure the PR did not cause is filed instead, as + `.agents/skills/finishing-changes/SKILL.md` says, and the PR is not cleared. +- **`Status: Needs Rebase`.** Rebase the branch onto `upstream/main` and push with `--force-with-lease`. A + conflict resolved by hand adds code, so `.agents/skills/finishing-changes/SKILL.md` runs again from its + first step. +- **`Status: Waiting on Author`.** A reviewer requested changes or left a thread unresolved. Make the change, + or reply with why not; when it leaves open a decision that belongs to the maintainers (see Decisions), reply + with the options and the one you recommend. After a reply that pushes nothing, request the review again + (`gh pr edit --add-reviewer `), since the label moves on a push or a new request and never on a + reply. A PR where your reply is already the last word is cleared, whatever its label says. + +Every push follows "Follow-up pushes" in `.agents/skills/opening-pr/SKILL.md`: a push whose new head the body +does not already name closes the PR. + +The batch has as many slots as the cap less your open PRs. It has none when a PR is left that you could not +clear: go to step 6 and name the PR and what blocks it. + +## 2. List the candidates + +```sh +gh issue list --state open --limit 500 --json number,title,labels,createdAt \ + --search 'no:assignee -label:"Needs Decision" -label:Discussion -label:"Needs Info" -label:Upstream' +``` + +Keep an issue labelled `Difficulty: Low`, whatever its type, or `Difficulty: Medium` together with `Bug`. +Order by priority label from `Priority: Critical` to `Priority: Low`, oldest first within one priority. Then +drop an issue when: + +- **An open PR closes or mentions it** + (`gh pr list --state open --limit 200 --json number,title,body,closingIssuesReferences,files`; step 3 reads + `files` from the same output). +- **A comment on it says someone is working on it.** +- **A closed, unmerged PR of yours references it** + (`gh pr list --author @me --state closed --json number,mergedAt,closingIssuesReferences`), unless a + maintainer has since asked for another attempt. + +## 3. Pick for zero conflicts + +A file is **taken** when an open PR changes it, whoever opened that PR and draft or not, or when an issue +already picked will change it. + +Walk the candidates in order. Read each issue and the code until you can name its **footprint**: every file +the fix will change, counting the unit tests beside the source and any `testing/src/specs/` file. One of three +things follows: + +- **Clear.** No file in the footprint is taken: pick the issue, and its footprint becomes taken. +- **Shares a file with a pick.** Fold it into that pick's PR when both issues are `Difficulty: Low` and the PR + as a whole still fits that label's description (`gh label list` prints it). The issues need not be related; + the shared file is the reason. Otherwise skip it. +- **Shares a file with an open PR.** Skip it; it returns when that PR merges. + +A pick with the issues folded into it fills one slot. Stop walking when the slots are full. Then read on only +for candidates that concern the same screen, form or module as a pick, and fold those that qualify, since +nothing else can touch them until that PR merges. A slot no candidate fills stays empty: the filter is never +relaxed to fill it. + +Reading an issue can end in Decisions or in Issues that need no PR instead of a pick. + +## 4. Present the plan and wait + +One message to the operator: + +- **Each planned PR**: its issue numbers, and one to three sentences on what will be different for a user, an + administrator or an instrument author. No file names and no implementation. +- **Each question that Decisions gives to the operator.** + +Change no code before the operator's go-ahead, even when there are no questions. The operator may strike a +planned PR. A slot emptied by a strike, or by anything after the go-ahead, stays empty, since a replacement is +work the operator did not approve. + +## 5. Work each planned PR + +- **One worktree per PR, outside the checkout, on a branch cut from `upstream/main`** after + `git fetch upstream main`. Copy the checkout's `.env` into the worktree. +- **Parallel work stops at `pnpm check`.** It runs in one worktree at a time: its e2e stage starts servers on + the ports in `.env` (`testing/playwright.config.ts`), and a second run fails on the occupied ports. When + sub-agents write the PRs, each brief names its issues, their footprint, the operator's answers and this + file. +- **One commit per issue**, in a folded PR too, since each `fix`, `feat` or `perf` commit is one changelog + entry. The body gives every issue its own keyword (`Closes #1. Closes #2.`); GitHub links only the number + directly after one. +- **A file outside the footprint is checked before it is touched.** Query the open PRs again. Not taken: go + on, and it joins the footprint. Taken: discard the branch and leave the issue for a later batch. +- **Finish with `.agents/skills/finishing-changes/SKILL.md`**, which ends by opening the PR. An issue whose + `pnpm check` cannot be brought green gets no PR: discard the branch and say why in the report. +- **Confirm the PR is still open a minute after opening it** (`gh pr view --json state`). + `.github/workflows/pr-body.yaml` closes a PR whose body it rejects, with a comment saying why. +- **Remove the worktree once the PR is open and keep the branch**; step 1 of a later batch needs it. +- **Merging is the maintainers'.** Another author's PR or branch is never pushed to, even to clear a conflict + with one of yours. + +## 6. Report + +One line per item, then stop. + +- **PR opened**: its URL and the issues it closes. +- **PR tended**: what was done, or why it could not be cleared. +- **Issue closed**: the evidence. +- **Issue sent to the maintainers, commented on or relabelled**: why, and any label GitHub refused. +- **Issue or PR abandoned or struck, and each empty slot**: why. + +## Decisions + +A choice a reviewer could disagree with goes under `Decisions` in the PR body +(`.agents/skills/opening-pr/SKILL.md`). Four kinds of choice are never made here: + +- **Data and contracts.** A Prisma schema change or migration, a changed API request or response, a changed + `packages/schemas` shape, a new environment variable, or a change to what instrument authors build against + (`packages/runtime-core`, `runtime/v1`, `packages/instrument-guidelines`). +- **Access.** A change to who can see or do what: CASL abilities, `@RouteAccess`, group scoping, login or + sessions. A bug fixed within the existing rules is not one. +- **Two reasonable fixes.** The issue can be resolved in ways its user would experience differently and does + not say which, or you believe the issue itself is wrong. +- **An outgrown label.** The fix needs a refactor first, spreads into a second workspace, or changes behaviour + the issue did not ask about. + +**The operator decides** a choice of the last two kinds that a competent engineer who has never seen this +codebase could settle well from the question alone. **The maintainers decide** the rest: every choice of the +first two kinds, and whatever turns on how the product is deployed, used or meant to evolve. + +**A question to the operator stands alone.** Give, in this order: what this part of the product does and for +whom, what the issue reports, the options and what each means for that person, and the option you recommend +with its reason. Enough detail to decide and no more. An invented issue shows the size: + +> **#N, date-range filter.** Clinicians narrow a subject's records to a date range. Choosing one day as both +> start and end returns nothing, because the range stops at the midnight that begins the end date. (a) Make +> the end date inclusive: one day returns that day's records, and every existing range gains its last day. +> (b) Keep it exclusive and refuse a one-day range with a message: existing ranges are unchanged, but a single +> day cannot be selected. I recommend (a): an end date reads as included. + +Questions found before step 4 go in its message. A question found after the go-ahead parks that PR; ask all of +those together once the other PRs are open, then finish the parked ones. Record each answer under `Decisions` +in the PR body. + +**A decision for the maintainers ends work on the issue.** Discard the branch, comment on the issue with what +you found, the options and the one you recommend, and add `Needs Decision` +(`gh issue edit --add-label "Needs Decision"`), which keeps the issue out of step 2 until they answer. +When GitHub refuses the label, say so in the comment and in the report. + +## Issues that need no PR + +- **Already fixed.** You can name the merged commit or PR that fixed it: close the issue with that reference. +- **Duplicate.** It duplicates an open issue: close it with `gh issue close --duplicate-of `. +- **Anything softer**, such as a bug you could not reproduce: comment once with what you tried, add + `Needs Info`, and leave it open. +- **Wrong difficulty.** Correct the label by the rule in `.agents/skills/opening-issues/SKILL.md` and say why + in a comment; step 2 then decides whether the issue is still a candidate. diff --git a/.agents/skills/working-the-backlog/agents/openai.yaml b/.agents/skills/working-the-backlog/agents/openai.yaml new file mode 100644 index 000000000..989e1947f --- /dev/null +++ b/.agents/skills/working-the-backlog/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: 'Working the Backlog' + short_description: 'Turn one conflict-free batch of backlog issues into pull requests' diff --git a/.claude/skills/working-the-backlog b/.claude/skills/working-the-backlog new file mode 120000 index 000000000..3b55d8bb4 --- /dev/null +++ b/.claude/skills/working-the-backlog @@ -0,0 +1 @@ +../../.agents/skills/working-the-backlog \ No newline at end of file