diff --git a/CHANGELOG.md b/CHANGELOG.md index 1eae712..62c1310 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +### Added + +- `standard/doc-style.md` gains a **Links** section (#22): code formatting means "paste this", + a link means "go here"; the scope explicitly includes the agent's own chat output, with a + construction table for the chat and cross-repo cases where `#NN` and relative links silently + fail. Referenced from `agent-collaboration.md`, enforced by a new links-resolve pre-PR item, + and named in the scaffolded `AGENTS.md`. +- A **Commissioning handoff** rule in `standard/agent-collaboration.md` (#21): when an agent + commissions shared infrastructure, one assigned, checkboxed issue in the review column owns + the manual residue — each step naming why it is manual — instead of end-of-session chat + prose. The session-end checklist gains the matching tripwire, and the org-migration + board-rebuild checklist routes views/auto-add click-through to the handoff issue (ADR-0008). + +### Fixed + +- `standard/org-migration-checklist.md`: the status-options landmine is corrected (#23) — a + Project's status options *can* be edited via API without breaking the built-in workflows by + echoing existing option ids (`ProjectV2SingleSelectFieldOptionInput.id`, verified against the + live schema); only a full id-less replacement dangles workflows and item values. + ## [0.4.0] - 2026-07-20 ### Added diff --git a/docs/CHECKPOINT.md b/docs/CHECKPOINT.md index f1c7b43..f797a51 100644 --- a/docs/CHECKPOINT.md +++ b/docs/CHECKPOINT.md @@ -5,8 +5,9 @@ pre-commit checklist has the tripwire, and stale entries are worse than none. - Last updated: 2026-07-20 - Status: IN PROGRESS -- In progress: nothing — retrospective batch #10 fully landed and closed; release 0.4.0 cut - (retrospective workflow standards) -- Next step: paused — nothing pending +- In progress: board-commissioning batch (#21–#23) on branch + `feat/board-commissioning-standards`, PR open for review (ADR-0008) +- Next step: Peter reviews/merges the PR, verifies and closes #21–#23, then decide whether + `[Unreleased]` warrants cutting 0.5.0 One line per fact, current state only — history lives in `CHANGELOG.md` and git. diff --git a/docs/adr/0008-board-commissioning-standard-improvements.md b/docs/adr/0008-board-commissioning-standard-improvements.md new file mode 100644 index 0000000..c9d6a31 --- /dev/null +++ b/docs/adr/0008-board-commissioning-standard-improvements.md @@ -0,0 +1,51 @@ +# ADR-0008: Board-commissioning batch — adopt all three field-report findings + +- **Status:** accepted +- **Date:** 2026-07-20 + +## Context + +An agent-run project-board commissioning (private repo, 2026-07-20) produced three field +reports against the standard (issues #21–#23): a documented landmine that was overstated and +therefore blocked a safe operation, a correct rule that was buried inside one pattern and so +fired only there, and a gap — the standard said nothing about what an agent owes the human when +commissioning leaves steps only a human can perform. As with the retrospective batch (ADR-0007), +the triage options per issue were accept, adapt, or decline. + +## Decision + +Accept all three, landed as one batch (one commit per issue, `Refs #NN`): + +- **#23** The org-migration checklist's status-options landmine is corrected: the failure is + specific to an **id-less replacement**, not to any API edit. + `ProjectV2SingleSelectFieldOptionInput` accepts an optional `id` (re-verified against the + live GraphQL schema at adoption time, on top of the issue's 75-item live-board evidence); + echoing ids for kept/renamed options preserves built-in workflows and item values. Rewritten + in the checklist's symptom → cause → fix form with the verification step included. +- **#22** The links-not-code-formatting rule moves from an Option B aside in + `agent-collaboration.md` to a deterministic **Links** section in `doc-style.md`: the + paste-this/go-here test, scope explicitly including the agent's own chat output, and a + construction table for the chat/cross-repo cases where `#NN` and relative links silently + fail. `agent-collaboration.md` references it, the pre-PR checklist gains a links-resolve + item, and the scaffolded `AGENTS.md` names the chat-output half — a behaviour an agent must + be told, not a file it can lint. +- **#21** `agent-collaboration.md` gains a **Commissioning handoff** section: when an agent + commissions shared infrastructure, exactly one assigned, checkboxed issue in the + review/verify column owns the manual residue, opened before the work is reported done; each + step names why it is manual (*no API*, *permission/scope withheld*, *plan-gated*, + *interactive auth*, *deliberately human*) because the reason expires and must be + re-evaluable. The session-end checklist gains the matching tripwire, and the org-migration + board-rebuild checklist routes its click-through to the handoff issue. The known + project-board residue is listed in the section so the handoff issue is generated, not + remembered. + +Issues are **not** auto-closed — the human verifies each after merge (#14's rule). + +## Consequences + +The standard now permits an operation it previously forbade in effect (API edits to a +Project's status options), with the safety condition stated instead of the operation banned. +Two behavioural rules bind agent chat output — linking and residue handoff — which no linter +can enforce; they live in the docs an agent loads (`doc-style.md`, `agent-collaboration.md`, +the scaffolded `AGENTS.md`) and in the session-end/pre-PR tripwires. No new required +artifacts; the reference set grows by zero docs. diff --git a/plugins/repokit/skills/new-repo/templates/core/AGENTS.md.tmpl b/plugins/repokit/skills/new-repo/templates/core/AGENTS.md.tmpl index 5ae56d1..a7ad47b 100644 --- a/plugins/repokit/skills/new-repo/templates/core/AGENTS.md.tmpl +++ b/plugins/repokit/skills/new-repo/templates/core/AGENTS.md.tmpl @@ -20,4 +20,7 @@ checklists, use the `repo-standard` skill (RepoKit: `/plugin marketplace add PBN - Humans + agents sharing an issue board: follow the `repo-standard` skill's `standard/agent-collaboration.md` — cards move when state changes, run the session preflight before board work, sign agent-authored output. +- Link, don't just name: in docs, issues, and your own chat output to the human, anything they + might open is a clickable markdown link; code formatting is only for paste-material (the + `repo-standard` skill's `standard/doc-style.md`, *Links*). {{LIVING_DOCS_RULES}} diff --git a/plugins/repokit/skills/repo-standard/standard/agent-collaboration.md b/plugins/repokit/skills/repo-standard/standard/agent-collaboration.md index c78d3b8..111de5f 100644 --- a/plugins/repokit/skills/repo-standard/standard/agent-collaboration.md +++ b/plugins/repokit/skills/repo-standard/standard/agent-collaboration.md @@ -56,8 +56,40 @@ parallel options plus one shared verify section: - **Option C — CLI fallback:** the exact commands, code-fenced, for whoever prefers them. - **Verify (shared):** observable checks that hold regardless of the option taken. -Formatting rule of thumb: code formatting only for genuine paste-material (commands, literal -values); markdown links for everything navigable. +Formatting follows the linking rule in [`doc-style.md`](doc-style.md) (*Links*): code +formatting only for genuine paste-material; markdown links for everything navigable. Option B +is that rule applied to a GUI audience — and remember the rule's scope includes the agent's own +chat output, not just the issue body. + +## Commissioning handoff — an issue owns the manual residue + +An agent commissioning shared infrastructure (a project board, CI, DNS, an org policy) can +usually do almost everything through the CLI/API — and almost never everything. What remains is +the **manual residue**: steps the agent cannot complete with the tools it holds. Chat is a +delivery mechanism, not a record — residue delivered only as end-of-session prose is +unsearchable, unassignable, invisible to anyone else working the board, and gone when the +session closes, while the work stands reported "done". + +This is the session-end checklist's branch rule ("merge it, delete it, or open an issue that +owns it — no silent survivors") applied to infrastructure: + +1. **One issue owns the residue** — opened, or kept open, *before* the work is reported done. +2. **Assigned to the human who owns the resource, sitting in the review/verify column.** The + agent does not close it (the closing-force rule above), so an incomplete commissioning is + visible on the board rather than asserted complete in a transcript. +3. **The body uses the three-audience format** (Options A/B/C plus shared Verify), with each + residual step as a **checkbox** so partial progress is visible. +4. **Each step names *why* it is manual** — one of: *no API*, *permission/scope withheld*, + *plan-gated*, *interactive auth*, *deliberately human* (irreversible or judgement-bearing). + Reasons expire — "no API" becomes a one-line script when the platform ships the endpoint — + and a labelled reason can be re-evaluated where a bare "do this in the UI" cannot. +5. **It links what was commissioned** — the board, pipeline, or environment — and every doc the + commissioning changed, per the linking rule in [`doc-style.md`](doc-style.md) (*Links*). + +Known project-board residue — generate the handoff issue from this list, don't re-remember it: +project **views** by layout (no create API; a finished board still shows a default table), the +**auto-add workflow** and its plan cap, and re-verification of the built-in workflows after any +status-option edit (see [`org-migration-checklist.md`](org-migration-checklist.md)). ## Signatures on agent output diff --git a/plugins/repokit/skills/repo-standard/standard/doc-style.md b/plugins/repokit/skills/repo-standard/standard/doc-style.md index 8f078db..bcf5c3c 100644 --- a/plugins/repokit/skills/repo-standard/standard/doc-style.md +++ b/plugins/repokit/skills/repo-standard/standard/doc-style.md @@ -33,6 +33,37 @@ substitute emoji for them: | `PLANNED` / `IN PROGRESS` / `BLOCKED` / `DONE` | work items, milestones | | `OK` / `DEGRADED` / `DOWN` | operational health of a running thing | +## Links — code formatting means "paste this", a link means "go here" + +Code-format only genuine paste-material (commands, literal values, identifiers with no +destination — an ARN, a hash, an option id). Everything navigable — repos, boards, issues, PRs, +files, milestones, releases, workflow runs — is a markdown link. Anything the reader might want +to open, they should be able to click. + +**Scope:** docs, issue and PR bodies, review comments, ADRs, release notes — **and the agent's +own chat/session output to the human**. A closing report that names a board, six issues, and +five changed files as code-formatted text forces the human to copy-paste identifiers into a +browser to reach their own artifacts. + +The correct construction depends on where the text will be read: + +| Referring to | In a repo-hosted file or issue body | In chat output, or cross-repo | +|---|---|---| +| An issue or PR | `#12` (autolinks) | `[owner/repo#12](https://github.com/owner/repo/issues/12)` | +| A file in this repo | relative link: `[docs/RUNBOOK.md](docs/RUNBOOK.md)` | blob URL pinned to a ref | +| A board, milestone, release, workflow run | markdown link (full URL) | markdown link (full URL) | +| A command, literal value, or destination-less identifier | code formatting | code formatting | + +Why the split matters: `#12` autolinks only inside its own repo — it is dead text in a chat +transcript and ambiguous cross-repo. A relative link resolves in a repo-hosted markdown file and +in an issue body, but not in chat, a release note, or an email. A file link that must keep +meaning after the branch moves needs a ref-pinned blob URL. + +- A path that is both openable and paste-material is a link whose text is the code-formatted + path: `` [`docs/RUNBOOK.md`](docs/RUNBOOK.md) ``. +- Counter-case — this is not a link-spam mandate: first mention in a section wins; don't + re-link the same artifact on every mention. + ## Headings - One `#` title per file; sections are `##`, subsections `###`; never skip a level. diff --git a/plugins/repokit/skills/repo-standard/standard/org-migration-checklist.md b/plugins/repokit/skills/repo-standard/standard/org-migration-checklist.md index e0f14dd..445479b 100644 --- a/plugins/repokit/skills/repo-standard/standard/org-migration-checklist.md +++ b/plugins/repokit/skills/repo-standard/standard/org-migration-checklist.md @@ -36,10 +36,17 @@ is a non-event. Format: symptom → cause → fix. Plan-dependent limits carry a ## Board rebuild -- [ ] **Replacing a Project's status options breaks the built-in workflows silently.** A new - column set via API leaves every default workflow ("item closed → status X", "auto-close", - "PR merged") pointing at deleted option ids — they show a warning icon and dangle until each - is re-edited by hand in the UI. Budget the click-through. +- [ ] **Status options replaced via API, and now the built-in workflows dangle?** → The option + list was sent *without* ids, so GitHub minted new option ids and every default workflow + ("item closed → status X", "auto-close", "PR merged") — and every item's stored value — still + refers to the old, now-deleted options. → `ProjectV2SingleSelectFieldOptionInput` accepts an + optional `id`: read the current options first + (`field(name: "Status") { ... on ProjectV2SingleSelectField { options { id name } } }`), echo + the id back for every option you keep **or rename**, and omit `id` only for genuinely new + options. Options render in array order, so mid-list inserts and automation-preserving renames + work in one mutation. Then verify — `workflows(first: 20) { nodes { name enabled } }` plus a + re-read of item values — before trusting it. Only a full id-less replacement needs the manual + UI click-through. - [ ] **Auto-add is per-repo and plan-capped:** each auto-add workflow targets a single repository, with a maximum of **1 workflow on Free, 5 on Pro/Team, 20 on Enterprise** — a multi-repo board on Free gets exactly one auto-added repo; the rest is manual/agent adds or @@ -48,3 +55,8 @@ is a non-event. Format: symptom → cause → fix. Plan-dependent limits carry a - [ ] **Re-enable and re-check board automations against the agent rules** — if "status = Done auto-closes" is on, the closing-force rules apply (see [`agent-collaboration.md`](agent-collaboration.md)). +- [ ] **Views and auto-add are UI-only residue.** Project views have no create API, and + auto-add is plan-capped (above) — an agent-built board still needs human clicks to be usable. + That click-through gets written down as a commissioning-handoff issue on the board itself, + assigned and checkboxed (see [`agent-collaboration.md`](agent-collaboration.md), + *Commissioning handoff*) — never delivered only as chat prose. diff --git a/plugins/repokit/skills/repo-standard/standard/pre-pr-checklist.md b/plugins/repokit/skills/repo-standard/standard/pre-pr-checklist.md index 134e755..ae0df0a 100644 --- a/plugins/repokit/skills/repo-standard/standard/pre-pr-checklist.md +++ b/plugins/repokit/skills/repo-standard/standard/pre-pr-checklist.md @@ -12,6 +12,8 @@ Run through this before opening a pull request. - [ ] **`CHANGELOG.md`** has the user-visible changes under `## [Unreleased]`. - [ ] **Release due?** — if `[Unreleased]` describes more than one shippable unit, cut a version (see `commit-conventions.md`, *When to cut a release*). +- [ ] **Links resolve** — no `](#` placeholders, no links to deleted branches; references + follow the linking rule in `doc-style.md` (*Links*). - [ ] **Doc consistency** *(living-docs repos)* — `pwsh scripts/check-docs.ps1` passes, and the runbook is current-state-only: no superseded sections, no dated journal prose (see `living-docs.md`). diff --git a/plugins/repokit/skills/repo-standard/standard/session-end-checklist.md b/plugins/repokit/skills/repo-standard/standard/session-end-checklist.md index 458cb17..03f4dc6 100644 --- a/plugins/repokit/skills/repo-standard/standard/session-end-checklist.md +++ b/plugins/repokit/skills/repo-standard/standard/session-end-checklist.md @@ -14,3 +14,6 @@ a minute; a session doesn't end "clean" with any box undecided. - [ ] **Working tree clean** — `git status --short` shows nothing stranded. - [ ] **(Board repos) cards match reality** — positions and assignees reflect actual state (see `agent-collaboration.md`). +- [ ] **No manual residue delivered only in chat** — every step the human still has to perform + is owned by an assigned, checkboxed issue (see `agent-collaboration.md`, *Commissioning + handoff*).