From 20fb8bf1b0159dce78ab6589a60eff4d49809133 Mon Sep 17 00:00:00 2001
From: TzuHsuan <96853116+TzuH-Hsu@users.noreply.github.com>
Date: Mon, 7 Sep 2026 00:12:43 +0800
Subject: [PATCH] feat: retire the agent-ok and by-agent label mechanism
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Both labels were write-only: agent-ok had one producer (the issue labeler
copying a form checkbox) and no consumer; by-agent had neither. Nothing
gated, routed, or recorded on them, and provenance already lives in the
Co-Authored-By trailer and the PR author account.

- Drop both entries from labels.yml, the Agent eligibility checkbox from
  the three issue forms, and the agent-ok sync + isFormManaged clause from
  issue-labeler.yml (priority/area/type sync unchanged). This also removes
  the silent stripping of a hand-added agent-ok on issue edit.
- AGENTS.md: start-work rule is explicit human assignment; provenance is
  the commit trailer. README, design principle 7, PROJECT_FIELDS,
  project-views (Agent queue view removed), bootstrap Ready description
  and view count updated to match.
- Skills agent-workflow, pr-authoring, issue-writing, anti-patterns,
  code-review reworded; no reference to either label remains.
- ADR-0007 records the decision and rejected alternatives; ADR-0003 left
  untouched as history.

Retires agent-ok, by-agent — no successor.

Closes #36

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .github/ISSUE_TEMPLATE/bug_report.yml      |  7 ----
 .github/ISSUE_TEMPLATE/feature_request.yml |  7 ----
 .github/ISSUE_TEMPLATE/task.yml            |  7 ----
 .github/PROJECT_FIELDS.md                  |  2 --
 .github/labels.yml                         |  8 -----
 .github/workflows/issue-labeler.yml        | 14 ++------
 AGENTS.md                                  |  6 ++--
 README.md                                  |  2 +-
 docs/adr/ADR-0007-retire-agent-labels.md   | 37 ++++++++++++++++++++
 docs/adr/README.md                         |  1 +
 docs/setup/project-views.md                | 15 +--------
 docs/template/design-principles.md         |  2 +-
 scripts/bootstrap.sh                       |  4 +--
 skills/agent-workflow/SKILL.md             | 39 +++++++++++-----------
 skills/anti-patterns/SKILL.md              |  4 +--
 skills/code-review/SKILL.md                |  2 +-
 skills/issue-writing/SKILL.md              | 16 +++------
 skills/pr-authoring/SKILL.md               |  9 +----
 18 files changed, 77 insertions(+), 105 deletions(-)
 create mode 100644 docs/adr/ADR-0007-retire-agent-labels.md

diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml
index f76cad5..243ed90 100644
--- a/.github/ISSUE_TEMPLATE/bug_report.yml
+++ b/.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)"
diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml
index 4edeec6..ce1e2a8 100644
--- a/.github/ISSUE_TEMPLATE/feature_request.yml
+++ b/.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)"
diff --git a/.github/ISSUE_TEMPLATE/task.yml b/.github/ISSUE_TEMPLATE/task.yml
index 4e788cb..784bbed 100644
--- a/.github/ISSUE_TEMPLATE/task.yml
+++ b/.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)"
diff --git a/.github/PROJECT_FIELDS.md b/.github/PROJECT_FIELDS.md
index fe38ccf..924aff7 100644
--- a/.github/PROJECT_FIELDS.md
+++ b/.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 |
 
diff --git a/.github/labels.yml b/.github/labels.yml
index fb6488b..0c28a63 100644
--- a/.github/labels.yml
+++ b/.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
diff --git a/.github/workflows/issue-labeler.yml b/.github/workflows/issue-labeler.yml
index ad9e559..6875883 100644
--- a/.github/workflows/issue-labeler.yml
+++ b/.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:')
               );
             }
 
diff --git a/AGENTS.md b/AGENTS.md
index 5c82357..9c99398 100644
--- a/AGENTS.md
+++ b/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. |
diff --git a/README.md b/README.md
index 5a1d954..0792705 100644
--- a/README.md
+++ b/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.
diff --git a/docs/adr/ADR-0007-retire-agent-labels.md b/docs/adr/ADR-0007-retire-agent-labels.md
new file mode 100644
index 0000000..ffa8682
--- /dev/null
+++ b/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.
diff --git a/docs/adr/README.md b/docs/adr/README.md
index 8d67ad7..cf70038 100644
--- a/docs/adr/README.md
+++ b/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 |
diff --git a/docs/setup/project-views.md b/docs/setup/project-views.md
index 4984333..e2da9ae 100644
--- a/docs/setup/project-views.md
+++ b/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
diff --git a/docs/template/design-principles.md b/docs/template/design-principles.md
index 76efb7f..548ab83 100644
--- a/docs/template/design-principles.md
+++ b/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/`).
diff --git a/scripts/bootstrap.sh b/scripts/bootstrap.sh
index e906ce4..c8bb11c 100755
--- a/scripts/bootstrap.sh
+++ b/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"
 }
diff --git a/skills/agent-workflow/SKILL.md b/skills/agent-workflow/SKILL.md
index 154920e..a2281bf 100644
--- a/skills/agent-workflow/SKILL.md
+++ b/skills/agent-workflow/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: agent-workflow
-description: Use when an AI agent picks up, executes, or hands off repository work — queue, boundaries, audit.
+description: Use when an AI agent picks up, executes, or hands off repository work — assignment, boundaries, honest reporting.
 category: ai-collaboration
 ---
 
@@ -9,29 +9,31 @@ category: ai-collaboration
 ## Purpose
 
 Defines the contract that lets an AI agent operate here without a human
-babysitting every step: what it may claim unasked, where its authority stops,
+babysitting every step: when it may start, where its authority stops,
 and how its work stays auditable. Trust is granted one issue at a time, never
 blanket across the repository.
 
 ## Rules
 
-1. **Self-serve only the queue.** An issue is claimable without asking iff it
-   carries the `agent-ok` label AND its Project `Status` is `Ready`. Everything
-   else needs an explicit human request naming the work.
+1. **Work only what a human handed you.** An issue is yours 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". Anything
+   you were not given needs an explicit human request naming the work.
 2. **Claim before working.** Claiming = set Status `In Progress` and comment on
    the issue that you are taking it. No silent claims; two agents must never
    discover mid-flight they grabbed the same issue.
-3. **Grant `agent-ok` only when the work is safe to hand off.** Crisp scope,
-   testable acceptance criteria, non-destructive. Withhold it for ambiguous
-   scope, security-sensitive changes, destructive operations, or any judgment
-   call the human has not yet made — labelling those `agent-ok` is the bug.
+3. **Refuse work that is not safe to hand off.** Ambiguous scope, untestable
+   acceptance criteria, security-sensitive or destructive changes, or a
+   judgment call the human has not yet made — push those back to the issue
+   before starting, rather than guessing.
 4. **Stay inside capability boundaries.** Free via `gh`: issues, labels,
    milestones, Project items, branches, PRs. Forbidden without in-conversation
    human approval: force-push, history rewrite, deleting Project fields or
    labels repo-wide, repo settings changes, cutting releases.
-5. **Leave an audit trail.** Label every agent-authored PR `by-agent` and state
-   in the body exactly what you validated (see rule 6). Reviewers read agent
-   success as a *claim*, not a fact.
+5. **Leave an audit trail.** Provenance is the commit trailer
+   (`Co-Authored-By`) and the PR author account — no labels, no attribution
+   line in the PR body. What the body must carry is exactly what you validated
+   (see rule 6). Reviewers read agent success as a *claim*, not a fact.
 6. **Report honestly, including what you did not do.** Never over-claim success
    — that is the canonical agent failure. A skipped validation level is a
    `RISK:` line, never silence.
@@ -42,13 +44,12 @@ blanket across the repository.
 
 ## How
 
-Claim from the queue:
+Start on an issue you were handed:
 
 ```bash
-gh issue list --label agent-ok --json number,title   # find candidates
-# confirm Status is Ready on the Project board, then:
+gh issue view 42 --json title,body,labels,assignees   # confirm scope and acceptance criteria
 gh issue comment 42 --body "Claiming — starting work on a feat/42 branch."
-# set Project Status -> In Progress, branch feat/42-<slug>, open PR with by-agent
+# set Project Status -> In Progress, branch feat/42-<slug>, open the PR
 ```
 
 The honesty ladder in a PR body — claim only the rung you actually reached:
@@ -69,8 +70,8 @@ then rebase and land PR B. Two agents force-pushing one branch is chaos.
 
 ## Pitfalls
 
-- Claiming an issue that lacks `agent-ok` because it "looks easy" — the label is
-  the gate, not your read of difficulty.
+- Starting on an issue nobody handed you because it "looks easy" — the human's
+  assignment is the gate, not your read of difficulty.
 - Setting Status `In Progress` but never commenting, so a human cannot tell a
   live claim from a stale one.
 - Burying a skipped validation level instead of writing the `RISK:` line — a
@@ -83,7 +84,7 @@ then rebase and land PR B. Two agents force-pushing one branch is chaos.
 ## Related
 
 - `AGENTS.md` — canonical agent conventions
-- `` `.github/PROJECT_FIELDS.md` `` — where `agent-ok`/`by-agent`/`Status` live
+- `` `.github/PROJECT_FIELDS.md` `` — where `Status` and the other metadata live
 - `` `skills/context-handoff/SKILL.md` `` — pausing and resuming work across sessions
 - `` `skills/pr-authoring/SKILL.md` `` — PR body and `RISK:` conventions
 - `` `skills/validation-ladder/SKILL.md` `` — the L0–L4+ validation levels
diff --git a/skills/anti-patterns/SKILL.md b/skills/anti-patterns/SKILL.md
index e0df43c..ee1f189 100644
--- a/skills/anti-patterns/SKILL.md
+++ b/skills/anti-patterns/SKILL.md
@@ -33,7 +33,7 @@ Each entry: symptom → why it happens → the fix (this repo's mechanism).
 | Documentation drift | Docs describe the system that used to exist | Code changed; the doc two folders away didn't | One-home-per-fact linking, CI link checks, delete-in-obsoleting-PR (`docs-hygiene`) |
 | Silent validation skip | "tests didn't apply" said nowhere | Skipping is quiet; declaring feels like admitting fault | `RISK:` line convention — every skipped level is stated (`validation-ladder`) |
 | Deadline refactor cramming | Big refactor jammed into a release under pressure | "While we're in here" scope-creep near a cut | Refactors get their own milestone; timebox kills scope, not the deadline (`milestone-planning`) |
-| Agent over-trust | Merging agent PRs on the agent's own success claim | Green-looking summary reads like proof | `by-agent` label + claims-are-claims review + cross-family review (`agent-workflow`) |
+| Agent over-trust | Merging agent PRs on the agent's own success claim | Green-looking summary reads like proof | Commit trailers + claims-are-claims review + cross-family review (`agent-workflow`) |
 | Inherited-licence leak | The delivered repo's `LICENSE` still names the template author | Templates ship a licence; setup scripts rewrite docs and never touch it | Bootstrap phase 9 forces an explicit choice; `--yes` files it as the first MANUAL step; attribution moves to `NOTICE` (ADR-0004) |
 
 Reading an entry in the wild:
@@ -46,7 +46,7 @@ Fix     : delete the Project Priority field; label is the single home (ADR-0003)
 
 Agent over-trust is the one that scales with agent adoption — the same model
 that wrote the code is the worst judge of whether it works. The counter is
-structural: a `by-agent` label flags provenance, review treats the PR body as
+structural: commit trailers and the PR author flag provenance, review treats the PR body as
 claims to verify, and a *different* agent family (or a human) does the check.
 
 ## Pitfalls
diff --git a/skills/code-review/SKILL.md b/skills/code-review/SKILL.md
index 497d5e5..9c7fa52 100644
--- a/skills/code-review/SKILL.md
+++ b/skills/code-review/SKILL.md
@@ -75,6 +75,6 @@ gh pr merge <PR#> --squash
 ## Related
 
 - `CONTRIBUTING.md` — solo-maintainer self-merge policy
-- `AGENTS.md` — agent capability boundaries and audit trail conventions
+- `AGENTS.md` — agent capability boundaries and provenance conventions
 - `` `skills/pr-authoring/SKILL.md` `` — the RISK convention this review practice depends on
 - `` `skills/branch-and-commit/SKILL.md` `` — commit hygiene that makes diffs reviewable
diff --git a/skills/issue-writing/SKILL.md b/skills/issue-writing/SKILL.md
index e5c4c50..d4f619e 100644
--- a/skills/issue-writing/SKILL.md
+++ b/skills/issue-writing/SKILL.md
@@ -29,12 +29,7 @@ safe to hand to an AI agent without a live conversation.
 5. Express dependencies with native blocked-by/blocking relationships, not a
    `blocked` label or a sentence buried in the description. Express epics with native
    sub-issues, not an `epic:*` label.
-6. Only check "AI agents may pick this up" (`agent-ok`) when the issue is genuinely
-   self-service: scope is unambiguous, acceptance criteria are fully testable, no
-   destructive operation is implied, and no step requires human judgment calls not
-   already resolved in the issue text. Leave it unchecked for anything ambiguous,
-   irreversible, or interpretive — an agent will otherwise guess.
-7. Triaging an existing issue means tightening it to meet rules 1–6, not just
+6. Triaging an existing issue means tightening it to meet rules 1–5, not just
    re-labeling it. If acceptance criteria are missing or untestable, add them before
    moving status off `Backlog`.
 
@@ -46,9 +41,6 @@ gh issue create --repo <owner>/<repo>
 
 # Inspect an issue's current metadata footprint before triaging
 gh issue view 42 --repo <owner>/<repo> --json title,labels,milestone,body
-
-# List issues that are agent-ready right now
-gh issue list --repo <owner>/<repo> --label agent-ok --search "status:Ready"
 ```
 
 Good acceptance criteria read like a test plan:
@@ -60,7 +52,7 @@ Good acceptance criteria read like a test plan:
 ```
 
 Bad acceptance criteria ("works correctly", "improve performance") give an agent or a
-reviewer nothing to check against — rewrite before requesting `agent-ok`.
+reviewer nothing to check against — rewrite before handing the issue to anyone.
 
 ## Pitfalls
 
@@ -68,8 +60,8 @@ reviewer nothing to check against — rewrite before requesting `agent-ok`.
   — now there are two sources and they can disagree.
 - Writing acceptance criteria as a restatement of the summary instead of a checklist
   a reviewer can tick off one by one.
-- Checking `agent-ok` on an issue whose "acceptance criteria" is really "figure out
-  the right approach" — that is a human-judgment task, not a self-service one.
+- Handing an agent an issue whose "acceptance criteria" is really "figure out the
+  right approach" — that is a human-judgment task; resolve it in the issue first.
 - Using an `epic:*` label or a "blocked by #12" sentence instead of native sub-issues
   and blocked-by links — invisible to automation and easy to let go stale.
 - Opening a blank issue to "save time" — it skips native type assignment and the
diff --git a/skills/pr-authoring/SKILL.md b/skills/pr-authoring/SKILL.md
index 5e15974..0ab004f 100644
--- a/skills/pr-authoring/SKILL.md
+++ b/skills/pr-authoring/SKILL.md
@@ -40,9 +40,7 @@ human reviewer and for an agent reviewing another agent's work.
    list and the RISK lines.
 5. Use `Closes #N` to link the issue — one issue per PR. Don't bundle unrelated
    changes just because they happened to be worked on together.
-6. Agents label their own PRs `by-agent` for the audit trail. This is separate from
-   `agent-ok` on the issue (eligibility to pick up work vs. authorship record).
-7. Re-run `make verify` after every revision to the PR, not just before the first
+6. Re-run `make verify` after every revision to the PR, not just before the first
    push. A review comment that changes code invalidates the previous green run.
 
 ## How
@@ -52,9 +50,6 @@ human reviewer and for an agent reviewing another agent's work.
 gh pr create --title "feat: add label sync phase to bootstrap" \
   --body-file .github/PULL_REQUEST_TEMPLATE.md
 
-# Label agent authorship
-gh pr edit <PR#> --add-label "by-agent"
-
 # Re-verify before each push after review feedback
 make verify && git push
 ```
@@ -79,8 +74,6 @@ Rollback: revert this PR; no migrations or external state changed
   new issue instead, keep the PR mapped to one `Closes #N`.
 - Pushing a fix in response to review and calling the ladder still green from the
   first run — re-run `make verify` after every revision.
-- Forgetting the `by-agent` label on agent-authored PRs — breaks the audit trail this
-  repo relies on in place of a heavier review gate.
 
 ## Related