Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 6 additions & 6 deletions .agents/docs/architecture/release-channels.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
| --------- | ------------------------------------------------------------------------- |
Expand Down Expand Up @@ -65,7 +65,7 @@ major once the next major ships from `main`, and released only by
`gh workflow run Release --ref release/<major>`. 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.
Expand Down
8 changes: 8 additions & 0 deletions .agents/docs/architecture/testing-strategy.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
16 changes: 8 additions & 8 deletions .agents/docs/playbooks/cut-a-release.md
Original file line number Diff line number Diff line change
Expand Up @@ -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/<major>`, 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/<major>`, 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.
Expand All @@ -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.
Expand Down
22 changes: 11 additions & 11 deletions .agents/skills/finishing-changes/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
2 changes: 1 addition & 1 deletion .agents/skills/troubleshooting/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Loading
Loading