Skip to content

Commit 84dc28b

Browse files
cliffhallclaude
andcommitted
docs: shebang-aware headers, non-closing merge-PR reference, fast test split, pin scope
- The purpose header is the first comment after any shebang - The release merge PR (to main) uses a non-closing reference, so the release issue stays open until the Release is published - S3 splits each TS workspace's test from coverage - verify:action-pins covers credentialed jobs and the producers they download from, not every artifact upload Co-Authored-By: Claude Opus 5.5 <[email protected]>
1 parent d02c815 commit 84dc28b

1 file changed

Lines changed: 15 additions & 7 deletions

File tree

‎docs/agent-guidance-inception.md‎

Lines changed: 15 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -74,7 +74,7 @@ The **Sub-issue** column points into [§9](#9-proposed-sub-issues).
7474
| Header: rules vs procedures | States that `AGENTS.md` holds the rules and skills hold the recipes | Transfer | — | S1 |
7575
| Skills index | Table of every skill, what it covers, how it loads | Transfer | Our skill list (§9) | S1, then each skill PR |
7676
| Project Structure | Annotated tree of the repo | Adapt | 7 servers × 2 languages; package name and registry for each server | S1 |
77-
| Every file carries a purpose header | Each source file opens with a comment stating its purpose and rationale, so `AGENTS.md` never duplicates it | Adapt | Our source files don't follow this today (e.g. `src/filesystem/index.ts`, `src/time/src/mcp_server_time/server.py`). The adaptation is **no bulk migration**: new files, and files a PR substantially rewrites, get a header. It spreads as the refactor in #4857 touches each server | S1 |
77+
| Every file carries a purpose header | Each source file opens with a comment stating its purpose and rationale, so `AGENTS.md` never duplicates it | Adapt | Our source files don't follow this today (e.g. `src/filesystem/index.ts`, `src/time/src/mcp_server_time/server.py`). The adaptation is **no bulk migration**: new files, and files a PR substantially rewrites, get a header: the first comment in the file, **after any shebang** (`#!/usr/bin/env node` must stay on line 1 of an executable entry point). It spreads as the refactor in #4857 touches each server | S1 |
7878
| Development setup | Root `npm install`, build, dev loop | Adapt | npm workspaces for TS, `uv sync` per Python server. Node 22, Python ≥ 3.10 | S1 |
7979
| Dependency placement (+ its rationale in `local-dev`) | Rules for a non-workspace multi-install repo: root-only runtime deps, bundler externals, vitest pin trio, lockstep | N/A | This repo **is** an npm workspace for its four TS servers, each with its own `package.json`. The three Python servers use `pyproject.toml`, and every server publishes independently. The few general rules survive as S1 rules: pin transitive deps with `overrides`, never `npm audit fix`; one version of a shared devDependency across workspaces | S1 (the survivors), S11 (`local-dev`) |
8080
| Dependency updates are issue-driven | Dependabot PRs off; scheduled sweeps file issues | Adapt | npm **and** uv/PyPI **and** Actions ecosystems. Dependabot security-fix PRs are currently **on** here (§8) | S13 |
@@ -456,7 +456,10 @@ W6 S13 dependency & SDK sweeps replace Dependabot PRs; closing factory overview
456456
`format:check`; a root ESLint flat config, type-aware, `--max-warnings 0`,
457457
`no-floating-promises` at error, build output ignored. A **per-workspace
458458
`validate`** script in each TS server (`format:check` → `lint` → `build` →
459-
`test`, for that package only), and a root `validate` that **aggregates**
459+
`test`, for that package only). Today every TS workspace's `test` runs
460+
`vitest run --coverage`, so S3 **splits it**: `test` becomes the fast run,
461+
and a separate `coverage` script keeps the instrumented one (#4854 then
462+
adds its per-file thresholds to that script). A root `validate` that **aggregates**
460463
them (`npm run validate --workspaces`) plus any root-only guards.
461464
`verify:format-coverage` and `verify:typecheck-coverage` adapted.
462465
`typescript.yml` keeps its per-package matrix, and each leg runs **only its
@@ -613,9 +616,12 @@ is more than one PR.
613616
#4472, S10, S11; the ledger uses S11's `client-smoke`)
614617
- Scope:
615618
- **A release issue per milestone** (`Release vX.Y.Z`), filed through
616-
`issue-create`, that every preparation PR and the merge PR reference with
617-
`Closes #N` on the first line. It closes by hand once the merge lands on
618-
`main` and the Release is published. This is what keeps release PRs
619+
`issue-create`. Every preparation PR (on `v2/main`, where closing
620+
keywords don't fire) opens with `Closes #N`. The **merge PR targets
621+
`main`, the default branch**, where `Closes #N` would auto-close the
622+
issue before the Release is published, so it uses a **non-closing
623+
reference** (`Part of #N`) instead. The issue closes by hand once the
624+
Release is published. This is what keeps release PRs
619625
inside "every PR references an issue" after S13 removes the Dependabot
620626
exception. The one bot-authored PR, changesets' "Version Packages", gets
621627
the reference added to its body after the bot opens it. If the action
@@ -643,8 +649,10 @@ is more than one PR.
643649
- The `release` skill (name-only).
644650
- `RELEASING.md` rewritten for the merged state.
645651
- Acceptance:
646-
- `verify:action-pins` passes, and fails on a tag-pinned action in any
647-
credentialed or artifact-producing job.
652+
- `verify:action-pins` passes, and fails on a tag-pinned action in a
653+
credentialed job or in a job whose artifact a credentialed job downloads.
654+
Unrelated artifact uploads (e.g. `python.yml`'s CI `dist` upload) stay
655+
out of scope, as in the Inspector's guard.
648656
- One milestone released end to end through the skill.
649657
- The ledger is linked from the merge PR.
650658

0 commit comments

Comments
 (0)