feat: retire the agent-ok and by-agent label mechanism

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -66,10 +66,3 @@ body:
       placeholder: Paste output, logs, or attach files (optional)
     validations:
       required: false
-
-  - type: checkboxes
-    id: agent_eligibility
-    attributes:
-      label: Agent eligibility
-      options:
-        - label: "AI agents may pick this up (adds agent-ok)"

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -63,10 +63,3 @@ body:
         - label: "area:skills — Skills knowledge modules"
         - label: "area:ci — CI workflows and automation"
         - label: "area:governance — Labels, templates, metadata contract, process"
-
-  - type: checkboxes
-    id: agent_eligibility
-    attributes:
-      label: Agent eligibility
-      options:
-        - label: "AI agents may pick this up (adds agent-ok)"

.github/ISSUE_TEMPLATE/task.yml

@@ -68,10 +68,3 @@ body:
         - label: "area:skills — Skills knowledge modules"
         - label: "area:ci — CI workflows and automation"
         - label: "area:governance — Labels, templates, metadata contract, process"
-
-  - type: checkboxes
-    id: agent_eligibility
-    attributes:
-      label: Agent eligibility
-      options:
-        - label: "AI agents may pick this up (adds agent-ok)"

.github/PROJECT_FIELDS.md

@@ -13,8 +13,6 @@ Every issue/PR attribute lives in **exactly one place**. Never dual-write the sa
 | Workflow status | **Project `Status` field** | `Backlog` / `Ready` / `In Progress` / `In Review` / `Blocked` / `Done` |
 | Target version | **Milestone** | `vX.Y.Z` releases, `gov-*` process phases; **no milestone = backlog** |
 | Effort | **Project `Effort` field** | `S` (≤ half a day) / `M` (≤ 2 days) / `L` (must be decomposed first) |
-| Agent eligibility | `agent-ok` **label** | present = AI agents may self-serve when Status is `Ready` |
-| Agent authorship | `by-agent` **label** | on PRs authored by an AI agent (audit trail) |
 | Dependencies | **Native issue relationships** | GitHub blocked-by / blocking |
 | Epic membership | **Native sub-issues** | parent issue with sub-issues; no `epic:*` labels |
 

.github/labels.yml

@@ -86,14 +86,6 @@ labels:
     color: c5def5
     description: Nice to have / polish
 
-  - name: agent-ok
-    color: 7057ff
-    description: AI agents may pick this up self-service when status is Ready
-
-  - name: by-agent
-    color: bfd4f2
-    description: Authored by an AI agent (audit trail)
-
   - name: area:docs
     color: 1d76db
     description: Documentation and guides

.github/workflows/issue-labeler.yml

@@ -1,6 +1,6 @@
 name: Issue labeler
 
-# Syncs priority:*, area:*, agent-ok and the four type:* SUBTYPE labels from
+# Syncs priority:*, area:* and the four type:* SUBTYPE labels from
 # the issue form fields on open/edit. The issue body is untrusted input — it is
 # only ever read inside the actions/github-script JS sandbox
 # (context.payload.issue.body), never interpolated into a shell `run:` step.
@@ -36,7 +36,7 @@ jobs:
           script: |
             // Parses the GitHub issue-form markdown body (### <Label> headings)
             // and syncs the form-managed labels to match. Only ever touches
-            // priority:*, area:*, agent-ok and the four type:* subtypes listed
+            // priority:*, area:* and the four type:* subtypes listed
             // in FORM_MANAGED_TYPES — every other label on the issue is left
             // alone, including any type:* label OUTSIDE that list (a coarse
             // type:bug/type:feature, or an adopter's own). The four form-owned
@@ -123,13 +123,6 @@ jobs:
               }
             }
 
-            // ### Agent eligibility -> agent-ok (single checkbox)
-            const agentText = sectionText('Agent eligibility');
-            if (agentText) {
-              const checked = agentText.split(/\r?\n/).some((line) => /^-\s*\[[xX]\]/.test(line));
-              if (checked) desired.add('agent-ok');
-            }
-
             // Only these labels are form-managed; every other label is left
             // untouched. area: stays a prefix match on purpose — that is what
             // cleans up a stale area:old label after an adopter renames their
@@ -138,8 +131,7 @@ jobs:
               return (
                 label.startsWith('priority:') ||
                 FORM_MANAGED_TYPES.includes(label) ||
-                label.startsWith('area:') ||
-                label === 'agent-ok'
+                label.startsWith('area:')
               );
             }
 

AGENTS.md

@@ -52,8 +52,8 @@ The Makefile is the only executable contract in this repository. CI calls make t
 
 ## AI agent conventions
 
-- **Work queue**: issues labeled `agent-ok` with Project status `Ready` are self-service — an agent may pick one up without asking. Anything not labeled `agent-ok` needs an explicit human request.
-- **Audit trail**: label PRs you author with `by-agent`.
+- **Starting work**: an agent starts on an issue only when a human assigns it or names it in the conversation. There is no self-service queue; Project status `Ready` means "scoped", not "claimable by agents".
+- **Provenance**: commit trailers (`Co-Authored-By`) and the PR author account are the audit trail. No provenance labels, no attribution line in the PR body.
 - **Capability boundaries**: agents may manage issues, labels, milestones, and Project items via `gh`; agents must NOT perform destructive operations (deleting Project fields, force-pushing, rewriting history, changing repo settings) without explicit human approval in the conversation.
 - **Session handoff**: long-running work may keep exactly one gitignored `HANDOVER.local.md` (hard cap ~150 lines, rewrite — don't append — at session end). Durable knowledge gets promoted to issues, ADRs, or skills, then deleted from the handoff file. See `skills/context-handoff/`.
 
@@ -63,7 +63,7 @@ Load a skill only when its "load when" condition matches your current task.
 
 | Skill | Load when |
 | --- | --- |
-| [agent-workflow](skills/agent-workflow/SKILL.md) | An AI agent picks up, executes, or hands off repository work — queue, boundaries, audit. |
+| [agent-workflow](skills/agent-workflow/SKILL.md) | An AI agent picks up, executes, or hands off repository work — assignment, boundaries, honest reporting. |
 | [anti-patterns](skills/anti-patterns/SKILL.md) | Reviewing repository health or designing process — named failure modes and their fixes. |
 | [context-handoff](skills/context-handoff/SKILL.md) | Pausing, resuming, or handing off work across sessions — handoff file discipline. |
 | [branch-and-commit](skills/branch-and-commit/SKILL.md) | Starting work — branch naming, Conventional Commits, issue linkage. |

README.md

@@ -12,7 +12,7 @@ This is **not** a language or framework starter. It is the layer underneath: con
 ## What you get
 
 - **Governance as code** — declarative labels, issue forms that set native issue types, a metadata single-home contract (`.github/PROJECT_FIELDS.md`), branch ruleset, PR template with a validation ladder.
-- **AI collaboration layer** — a canonical `AGENTS.md` hub (Claude, Gemini, Copilot and others all point to it), an agent work queue convention (`agent-ok`), and session-handoff rules that keep context from rotting.
+- **AI collaboration layer** — a canonical `AGENTS.md` hub (Claude, Gemini, Copilot and others all point to it), explicit agent capability boundaries and honest-reporting rules, and session-handoff rules that keep context from rotting.
 - **Skills** — focused, vendor-neutral knowledge modules under `skills/` that both humans and agents load on demand: issue writing, PR standards, release management, ADRs, anti-patterns, and more.
 - **Automation without sprawl** — a small set of workflows (CI, issue labeling, link maintenance, release PRs) that call `make` targets, so you customize the Makefile and never touch the workflows.
 - **A bootstrap script** — `scripts/bootstrap.sh` applies everything a template can't ship as files: labels, milestone, GitHub Project fields, repo settings, branch ruleset.

docs/adr/ADR-0007-retire-agent-labels.md

@@ -0,0 +1,37 @@
+# ADR-0007: Retire the `agent-ok` / `by-agent` label mechanism
+
+- **Status**: Accepted
+- **Date**: 2026-09-07
+
+## Context
+
+The template shipped two labels for its AI-collaboration layer: `agent-ok` ("AI agents may pick this up self-service when Status is Ready") and `by-agent` ("authored by an AI agent, audit trail"). ADR-0003 listed agent eligibility among the facts labels own, and `AGENTS.md`, four skills, the issue forms, the labeler, and a hand-built "Agent queue" Project view all referred to them.
+
+Two months of dogfooding showed both labels were write-only:
+
+- `agent-ok` had exactly one producer — `issue-labeler.yml` copying a form checkbox — and no consumer. No workflow, ruleset, or Project automation read it. The queue view it fed cannot be created by bootstrap and was never verified to exist. In practice every piece of agent work was dispatched explicitly by a human; nothing was ever self-served from the queue.
+- `by-agent` had neither producer nor consumer. It relied on the agent remembering a manual `gh pr edit --add-label` after opening the PR, which `skills/pr-authoring` itself named as the most common omission. Provenance already existed twice elsewhere: the `Co-Authored-By` commit trailer and the PR author account.
+
+The labeler's ownership of `agent-ok` also had a side effect: because form-managed labels are removed when the form no longer selects them, a human who granted `agent-ok` by hand during triage lost it silently on the next issue edit — contradicting the skill text that described post-hoc granting.
+
+## Decision
+
+1. **Remove both labels with no successor.** They leave `.github/labels.yml`, the labeler, the issue forms, `PROJECT_FIELDS.md`, and every doc and skill that referenced them. The "Agent queue" view is dropped from `docs/setup/project-views.md`.
+2. **The start-work rule is explicit human assignment.** An agent works an issue when a human assigns it or names it in the conversation. Project `Status` `Ready` means "scoped"; it no longer implies "claimable by agents".
+3. **Provenance is the commit trailer and the PR author.** No label, and no attribution line in the PR body — the body carries validation claims, not authorship.
+4. **ADR-0003 is not edited.** Its line listing "agent eligibility" among label-owned facts is historical; this ADR supersedes that clause only.
+
+Principle 7 in `docs/template/design-principles.md` ("AI agents are first-class, humans stay in control") survives reworded: agents share the same issue, PR, and validation contract as humans and load the same skills; humans decide what agents work on and gate merges, releases, and destructive operations.
+
+## Consequences
+
+- Six downstream repositories carry the labels. They pick up the change by cherry-picking the template commit and then deleting the two labels with `gh label delete`. `scripts/bootstrap.sh --prune` is **not** the sync path: it deletes every label absent from `labels.yml`, including ones a downstream repo added by hand.
+- Existing Projects keep the old `Ready` option description ("agent-ok issues are self-service here") until bootstrap is re-run against them; the text is cosmetic.
+- The silent-removal bug in the labeler disappears with the label; `isFormManaged` now covers only `priority:*`, `area:*`, and the four form-owned `type:*` subtypes.
+- The template no longer promises a self-service queue it never operated. Whoever later needs one has a clean slate and this record of why the label form of it failed.
+
+## Alternatives considered
+
+- **Keep both, fix the bugs** (remove `agent-ok` from `isFormManaged`, add a `by-agent` checkbox to the PR template). Rejected: fixing producers does not create a consumer; the labels would still gate nothing and record nothing another mechanism does not already record.
+- **Replace `agent-ok` with a Project single-select field.** Rejected: a field has the same zero-consumer problem and adds a dual-home risk with `Status`. There is no self-service scenario to serve; YAGNI.
+- **Replace `by-agent` with a fixed provenance line in the PR body.** Rejected: duplicates the commit trailer, and conflicts with the repository's rule that PR bodies carry no AI attribution.

docs/adr/README.md

@@ -28,3 +28,4 @@ Routine choices (a library patch bump, a wording tweak) do not get ADRs. When in
 | [ADR-0004](ADR-0004-adopter-licence-choice.md) | The adopter's licence is an explicit bootstrap decision | Accepted |
 | [ADR-0005](ADR-0005-runner-selection-variable.md) | Runner selection is an adopter variable, not a workflow edit | Accepted |
 | [ADR-0006](ADR-0006-coarse-type-fallback.md) | Coarse Type on accounts without native issue types | Accepted |
+| [ADR-0007](ADR-0007-retire-agent-labels.md) | Retire the `agent-ok` / `by-agent` label mechanism | Accepted |

docs/setup/project-views.md

@@ -73,19 +73,7 @@ Use **+ (new view)** at the top of the Project for each of these.
 - Purpose: release/phase planning — what's committed to `vX.Y.Z` or `gov-*`
   versus sitting in the backlog (no milestone).
 
-### View 3 — "Agent queue"
-
-- Layout: **Table** (or **Board** grouped by `Status`, either works)
-- Filter: `label:agent-ok status:Ready`
-- Sort: by `priority:*` label (`p0` first) — GitHub sorts labels
-  alphabetically by default, so a manual sort or a saved custom sort by
-  label name gets `priority:p0` ahead of `priority:p1`, etc.
-- Purpose: this is the literal work queue described in `AGENTS.md` — "issues
-  labeled `agent-ok` with Project status `Ready` are self-service". An agent
-  should be able to open this view and know exactly what it may pick up
-  without asking.
-
-### View 4 — "Stakeholder" (optional)
+### View 3 — "Stakeholder" (optional)
 
 - Layout: **Table**
 - Filter: current milestone (e.g. `milestone:"v0.1.0"`)
@@ -101,7 +89,6 @@ Use **+ (new view)** at the top of the Project for each of these.
 - [ ] `Effort`: S / M / L (no other custom fields)
 - [ ] View: Board (grouped by Status)
 - [ ] View: Milestones (table, grouped by Milestone)
-- [ ] View: Agent queue (`label:agent-ok status:Ready`, sorted by priority)
 - [ ] View: Stakeholder (optional, current-milestone filter, minimal columns)
 
 ## See also

docs/template/design-principles.md

@@ -10,5 +10,5 @@ These principles decided every file in this repository. When proposing a change
 4. **One home per fact.** Metadata (ADR-0003), documentation (`skills/docs-hygiene/`), configuration — duplicate homes always drift.
 5. **Logic in the Makefile, not workflows.** Adopters customize `make` targets; workflow YAML stays untouched and upgradable.
 6. **The template obeys its own rules.** Its CI is the CI it ships; its issues use its own forms; its releases use its own flow. Dogfooding is the drift detector.
-7. **AI agents are first-class, humans stay in control.** Agents get a self-service queue (`agent-ok`), clear capability boundaries, and an audit trail (`by-agent`); humans gate merges, releases, and destructive operations.
+7. **AI agents are first-class, humans stay in control.** Agents share the same issue, PR, and validation contract as humans and load the same skills; humans decide what agents work on and gate merges, releases, and destructive operations.
 8. **Ratchets over cleanup.** Label budgets, workflow-count budgets, handoff caps — prevention mechanisms, because every failure mode this template guards against is cheap to prevent and expensive to undo (see `skills/anti-patterns/`).

scripts/bootstrap.sh

@@ -724,7 +724,7 @@ phase_project() {
                 fieldId: $fieldId,
                 singleSelectOptions: [
                   {name: "Backlog", color: GRAY, description: "Not committed yet"},
-                  {name: "Ready", color: GREEN, description: "Scoped and claimable (agent-ok issues are self-service here)"},
+                  {name: "Ready", color: GREEN, description: "Scoped and claimable"},
                   {name: "In Progress", color: YELLOW, description: "Being worked"},
                   {name: "In Review", color: ORANGE, description: "PR open, awaiting review"},
                   {name: "Blocked", color: RED, description: "Waiting on dependency or decision"},
@@ -751,7 +751,7 @@ phase_project() {
     fi
   fi
 
-  manual "GitHub's API cannot create views — follow docs/setup/project-views.md for the 3 views"
+  manual "GitHub's API cannot create views — follow docs/setup/project-views.md for the 2 views (plus an optional Stakeholder view)"
 
   record_phase "4. Project" "ok"
 }