feat(standard): board-commissioning field reports - links rule, commissioning handoff, status-options correction

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

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.

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.

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}}

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
 

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.

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.

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`).

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*).