Repository navigation
docs: AGENTS.md names docs/template-drift.md as the record of deliberate differences from the template - #111
Merged
Merged
Conversation
…ate differences from the template Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 6c7da38960
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
8 tasks done
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 46d0469170
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
…of restating it Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
TzuH-Hsu
added a commit
that referenced
this pull request
Sep 29, 2026
… Markdown (#113) <!-- markdownlint-disable-next-line MD041 --> ## Summary `scripts/pr-lint.js` decided which issues a PR closes by re-implementing CommonMark block parsing. Nine review rounds on #96 still left it disagreeing with GitHub whenever containers nest, and three more simple cases turned up after v0.5.7. GitHub already exposes the ground truth: the pull request's `closingIssuesReferences` field, read with `excludeUserLinked: true` so it lists exactly the issues the body closes, with keywords in prose as GitHub renders them. - `run()` reads that field over GraphQL. `lint()` checks the result: exactly one issue, in this repository, the branch's, and still open. Branch grammar and the bot exemptions are unchanged. - The Markdown scanner and its tests are gone (−260 lines net). - **The field lags a body edit.** I measured this by editing a PR body and polling: 1–9 s. The lint therefore reads until two reads 5 s apart agree, at most five times. Typical cost is one extra read and a 5 s wait. - Because the lint reads live state, "Re-run jobs" now re-checks the current body. The `ci.yml` comment that said it replays the old payload is corrected. - Messages follow GitHub's semantics. A number that is a pull request, or a deleted issue, now shows up as "closes no issue", because GitHub closes nothing for it. **Checking GitHub against CommonMark.** I put the three cases deferred to this issue into an open PR's body and read the field: | Body | GitHub | CommonMark | v0.5.7 scanner | | --- | --- | --- | --- | | `Heading\n=======\n Closes #104` | not closed | not closed | closed | | `- ```\n Closes #104\n ```` | not closed | not closed | closed | | `- item\n > quote\n # heading\n\n Closes #107` | closed | closed | not closed | **Sidebar links do not count.** Adding or removing an issue link in the PR's sidebar fires no `pull_request` event, so accepting it would let a green check go stale; the lint reads only what the body closes, and AGENTS.md step 4, `skills/pr-authoring` rule 5 and the architecture ledger say so. Before the first read, the lint also waits until the triggering edit is 15 s old, so two agreeing reads cannot both be stale. **Downstream:** the kit's `pr-lint.js` and `pr-lint.test.js` change shape completely; adopters replace both files whole. The workflow step is unchanged, and so are the job permissions: `issues: read` and `pull-requests: read` were already there. ## Related issue Closes #104 ## Validation Pick validation depth by blast radius. A level that applies but could not run becomes a `RISK:` line below. See AGENTS.md for the validation ladder. - [x] L0 static — `make lint` - [x] L1 unit — `make check` (`scripts/pr-lint.test.js`, 14 pass: lint rules, settle logic with a lagging and a flapping field, `run()` with a GraphQL stub, 403 and other failures) - [x] L2 integration — the real query through `closingRefs()` against live PRs here: #111 → [105], #112 → [107], #91 → [88, CLOSED], release PR #94 → [] - [x] L3 e2e / preview — this PR's own `ci` run executes the new lint against this PR ## Risk / rollback ```text RISK: L2 not run on a private repository — GraphQL under the ci job's issues/pull-requests read scopes is expected to work as the REST read did, but is untested; the first private adopter run will show it, and a refusal fails the check with the scopes named Rollback: revert this PR; the Markdown scanner returns ``` ## Checklist Before merging: - [x] Conventional Commit PR title (`<type>: <description>`) - [x] Linked issue using "Closes #N" - [x] No secrets, no `*.local.md` files committed - [x] Documentation updated where affected --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adopters who keep kit files in sync need one list of where they deliberately differ from the template and why, so a sync doesn't overwrite a local decision. Six downstream repositories now keep that list in
docs/template-drift.md. The rule "update the list in the PR that adds a deviation" lived only inside that file, though, where an agent starting from AGENTS.md never reads it. Adding a pointer to their own AGENTS.md would itself be a deviation.docs/template-drift.md(the file, what differs, why) and update it in the PR that adds or removes one. A template sync preserves what the list names. The template itself has no such file.The file is optional and the template ships none. The line only matters after an adopter creates the file.
Related issue
Closes #105
Validation
Pick validation depth by blast radius. A level that applies but could not run becomes a
RISK:line below. See AGENTS.md for the validation ladder.make lintmake check(skills index and AGENTS.md references still resolve)Risk / rollback
Checklist
Before merging:
<type>: <description>)*.local.mdfiles committed