devantler-tech / devantler-tech/ksail
docs(agents): AGENTS.md's Maintenance summary contradicts the contract on promotion, external PRs and trusted authors
- Dominant language
- Go
- Stars
- 165
- Forks
- 12
- Avg merge
- 5h 41m
- Merged PRs (30d)
- 337
Description
> 🤖 Generated by the Agentic Engineer
## Evidence
`AGENTS.md`'s `## Maintenance` section summarises the shared cross-repo conventions, and three of its claims now contradict the monorepo `AGENTS.md` they defer to. This matters because `AGENTS.md` is the file GitHub Copilot code review reads directly, and the one every agentic tool loads for this repo — a stale line here misleads every future agent and reviewer silently.
Read at `main`, `AGENTS.md` lines 359–364:
| `AGENTS.md` says | Superseded by |
|---|---|
| *"the maintainer's promotion to `ready` is the go-signal"* | Maintainer direction 2026-07-16 retired the human promotion gate. An agent self-promotes when it genuinely knows the change is ready: programmatically tested, green review at the current head, and tried/evaluated as a user. |
| *"**never merge external PRs**"* | Maintainer direction 2026-08-08: *"you are responsible to drive all prs to merge … Contribution PRs is also your responsibility just be careful!"* External PRs are now driven and merged; what stays forbidden is **running** their branch locally (review statically, let CI be the execution surface). |
| trusted authors are *"`devantler`, `ksail-bot`, `dependabot[bot]`, `github-actions[bot]`, and `renovate[bot]`"* | The portfolio trusted set also carries **`app/cursor`** (`cursor[bot]` on REST surfaces), added when Cursor Automation became a trusted PR author, plus the narrow path-scoped grant for the agent-skills updater App. |
The first two are the ones that change behaviour: read literally, an agent working in this repo would park every finished draft waiting for a human, and would refuse to merge an outside contribution it is now responsible for.
## Affected audience and impact
Any agent or reviewer operating from this file — the scheduled engineer lanes, Copilot code review, and any contributor pointing a tool at the repo. The failure is silent: the guidance reads authoritative and self-consistent, and nothing in CI notices that it disagrees with the contract it claims to summarise.
There is a second-order cost too. The section opens by saying the shared conventions are *"defined centrally in the devantler-tech monorepo `AGENTS.md`"* and that readers should *"follow that document rather than relying on the summary below"* — which is right, but the summary is what a tool with only this repo in context actually sees.
## Expected behaviour
The summary agrees with the contract it defers to, or it stops restating the parts that keep changing.
## Proposed direction
Two options, and the second is probably better:
1. **Correct the three claims in place.** Smallest diff, but it re-arms the same drift: this summary has now fallen behind three separate maintainer directions, so it will fall behind the next one too.
2. **Shrink the summary to the parts that are genuinely KSail-specific and link out for the rest.** The section already says the monorepo file is authoritative; leaning on that removes the copy that keeps going stale. Keep the KSail specifics that have no central home — the validate commands, the generated-artifact list, the experimental-gate mechanism, the task menu — and replace the restated cross-repo paragraph with a pointer.
Whichever is chosen, the same pass should check the other agent-instruction surfaces in this repo for the same three claims (`.github/instructions/**`, and the `CLAUDE.md`/`GEMINI.md` shims), since the portfolio convention is that a change to one updates every file that repeated the fact.
## Acceptance criteria
- [ ] No statement in `AGENTS.md` contradicts the monorepo contract on promotion, external-PR merging, or the trusted-author set.
- [ ] The execution guardrail stays explicit and unweakened: an external contributor's branch is never checked out, built, or run locally, whatever the merge policy says.
- [ ] Every other agent-instruction file in the repo repeating those facts is updated in the same PR.
- [ ] The result is either accurate or explicitly deferential — no restated cross-repo rule left without a source.
## Rough size
S. A prose change; the work is deciding between the two options and sweeping the sibling files.
Contributor guide
Research direction
Read the monorepo AGENTS.md contract first, then compare AGENTS.md lines 359–364 and inspect .github/instructions/** plus the CLAUDE.md and GEMINI.md shims for the same claims. Decide whether to correct or remove duplicated cross-repo guidance; done means all repeated statements are accurate or deferential and the external-branch execution guardrail remains explicit.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- github
- Domain
- developer-experience, documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 72/100