Track main rather than a release tag

[lwaldron]

@v0 resolved to 7f1beb7 — a commit from before the Python rewrite, 22 behind main. So both content-repo workflows were running the R tooling:

validate-protocols@v0  →  Rscript .../validate-protocol.R
generate-index@v0      →  Rscript .../generate-protocols-yaml.R

The Pydantic validator merged in #39 was validating nothing. Every pull request in agent-protocols was checked by the old R validator, and CI was green throughout. That is the failure mode of a moving tag that nobody moves: silent, not loud.

Why drop the tag rather than cut a release

The tag exists to decouple content repositories from a release cadence — ADR 0006 §3's argument. That assumes consumers outside your control. There is one content repository, the same person owns both, and nothing external consumes either, so the tag wasn't decoupling anyone. It was a pointer someone had to remember to move, whose failure mode is invisible.

But there's a better reason than expedience, and it's the one worth arguing:

Pinning is the ordinary answer for a library. It is a stranger answer for a standard. A consumer freezing a library dependency is behaving sensibly. A node validating against a snapshot of a standard is conforming to a version nobody publishes any more — and reporting success while it does. "Conformance to last year's spec" is not obviously conformance.

The README states this as a live question rather than a settled one, and asks a node that genuinely needs to pin to say why, so the answer comes from what federated nodes actually need rather than from a default chosen before any existed. If it settles, it warrants an ADR amending 0006 §3.

Changes

• template/.github/workflows/{generate-index,validate}.yml → @main, with the reasoning in a comment where someone editing the file will see it
• README.md — the pinning paragraph rewritten; a node with a reason to pin is told to pin a commit SHA, since a tag can itself be retargeted

What this gives up

A breaking change to main breaks adopters' CI immediately, with no buffer. With one repository, a 77-test suite gating main, and a spec that is 0.y.z and says anything may change — that's the right trade. It's also the conclusion ADR 0011 reached about @v1: a loud break beats silent staleness.

Companion: waldronlab/agent-protocols#41, which this unblocks — its committer-name/committer-email inputs don't exist at @v0, and the R generator would have partially reverted #40 by re-flattening database_urls.

🤖 Generated with Claude Code

---

Considered and declined

Pinning actions/create-github-app-token@v1 to a commit SHA. It is a mutable ref on an external action that receives the App private key, which is a long-lived credential — a real distinction from the refs below. But it is GitHub's own action, and the same argument would have us pin actions/checkout and actions/setup-python too. Left on the tag deliberately.

Pinning generate-index@main / validate-protocols@main to a commit SHA. This is the decision in #42, not an oversight: a node validating against a snapshot conforms to a version of the standard nobody publishes any more, and does so silently. The trust boundary here is internal — both repositories have the same owner.

Protecting tags on agent-protocol-standard. The escalation path needs write access to that repository, which is the same set of people who already have write access to this one.

Automatic reconciliation when the generator changes upstream. Tracking @main means the next run uses the new generator, but a generator change raises no event in a content repository, so the index can sit stale until an unrelated local change. workflow_dispatch is added as a manual escape hatch; a schedule: or a repository_dispatch from the standard repo would close it properly. Deferred until it is an actual problem rather than a theoretical one — there is one content repository and one person merging.

Rebase-and-retry on a non-fast-forward push. Tried, then removed. To be correct it must regenerate the index after each rebase — the intervening commit may have touched protocols/ — which puts a second generator invocation into a shared action every federated node runs. The race needs a merge inside a one-minute generation window in a repository where one person merges. A single push fails loudly and is re-runnable from the Actions tab or by workflow_dispatch; a loud failure beats a silently stale index, which is the argument this whole change set rests on.

[Copilot]

🟡 Changes recommended

Unresolved workflow trigger, security, and documentation/ADR issues remain.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

Updates template workflows to track tooling from @main instead of @v0, with revised guidance on SHA pinning.

Changes:

• Updates validation and index-generation action references.
• Documents live tracking rationale and immutable SHA alternatives.

File summaries

File	Review findings
template/.github/workflows/validate.yml	Nit (1 vote): The workflow conflicts with ADR 0011; amend or supersede the ADR and release guidance.
template/.github/workflows/generate-index.yml	Moderate (2 votes): No trigger regenerates the index when standard tooling changes. Critical (1 vote): Mutable @main executes with write access; retain an immutable default or controlled SHA updates.
README.md	Nit (3 votes): Earlier guidance and ADR 0011 still recommend release tags/@v0; reconcile or explicitly scope this policy.

Review details

Suppressed comments (1)

template/.github/workflows/validate.yml:16

• This changes the template away from the accepted decision in docs/adr/0011-pre-release-tags-for-the-tooling.md:40-42,59-61, which says consumers must use @v0 and that the template starts with that reference. Please amend or supersede that ADR and its release guidance with this policy change; otherwise the repository retains an authoritative decision that contradicts this workflow.

      - uses: waldronlab/agent-protocol-standard/actions/validate-protocols@main

• Files reviewed: 3/3 changed files
• Comments generated: 3
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🟡 Changes recommended

Resolve the README/ADR inconsistencies, workflow rationale contradiction, and mutable-main write-permission concern.

Get a fresh assessment by requesting another Copilot review.

Review details

Suppressed comments (3)

README.md:92

• This new guidance conflicts with the repository's remaining release guidance: README.md:39 still tells adopters to pin both actions to a release tag, README.md:118-125 still presents @v0 as the moving tag, and ADR 0011:59-61 says consumers must reference @v0. The result is contradictory instructions about whether @main, @v0, or a release tag is canonical. Please update/remove those legacy statements (and the ADR if this is the new policy), or explicitly scope this paragraph to the template default.

This is a live question rather than a settled one. Pinning is the ordinary answer for a *library*,
where a consumer reasonably freezes a dependency; it is a stranger answer for a *standard*, where
conforming to last year's version is not obviously conformance at all. If you have a reason to pin —
a node you cannot update promptly, say — pin a commit SHA rather than a tag, since a tag can itself
be retargeted, and tell us, because the answer should be driven by what federated nodes actually

template/.github/workflows/generate-index.yml:57

• This action now resolves from mutable main while the job grants contents: write (generate-index.yml:16-17), so any standard-main change—including a compromise or accidental push—can run arbitrary generator code and commit to the content repository. Either pin this write-capable action to a full SHA or change the write path to a reviewed PR and explicitly accept the resulting tradeoff.

      - uses: waldronlab/agent-protocol-standard/actions/generate-index@main

template/.github/workflows/validate.yml:16

• This changes the shipped template contrary to accepted ADR-0011, which says consumers must reference @v0 and new repositories start on it; ADR-0006 also still specifies release-tag consumption. Please add a superseding/amending ADR (and update its index) or keep the workflow and normative docs consistent.

      - uses: waldronlab/agent-protocol-standard/actions/validate-protocols@main

• Files reviewed: 3/3 changed files
• Comments generated: 1
• Review effort level: Lite

[Copilot]

🟡 Changes recommended

The index-generation workflow has unresolved push-safety, stale-output, and silent attribution failures; the README also has two documentation nits.

Get a fresh assessment by requesting another Copilot review.

Review details

Suppressed comments (5)

README.md:83

• The new README link points at an anchor that is never created: this text is a bold paragraph, not a Markdown heading, so GitHub will not generate #the-template-references-main-not-a-release-tag-and-that-is-deliberate. Make this line a heading (or point the link at an existing heading) so the navigation works.

**The template references `@main`, not a release tag, and that is deliberate.** A node validating

README.md:125

• v0 is the moving major tag (this file says it moves on each release), so it is not a pin. As written, this contradicts the preceding instruction to pin a commit SHA and could send consumers to a mutable ref; distinguish the versioned v0.x.y release tags from the moving v0 tag.

`@main`, so nothing is waiting on a tag to move. `v0` is kept for anyone who has a reason to pin, and
because the drift it accumulates is a useful signal of how far behind a pinned consumer would be.

template/.github/workflows/generate-index.yml:79

• The public committer-email input still documents the prefix as <app-id>+... in actions/generate-index/action.yml:29-30, while this workflow now correctly supplies the bot user ID and explicitly says the App registration ID is wrong. Update that action metadata/documentation with this change; otherwise other callers will follow the documented contract and lose GitHub bot attribution.

          committer-email: ${{ steps.bot.outputs.id && format('{0}+{1}[bot]@users.noreply.github.com', steps.bot.outputs.id, steps.app-token.outputs.app-slug) || 'github-actions[bot]@users.noreply.github.com' }}

template/.github/workflows/generate-index.yml:74

• Switching this reference to @main only affects the next execution. The workflow still triggers only for local protocols/** or workflow-file changes, so a generator change on agent-protocol-standard can leave PROTOCOLS.yaml published from the old generator indefinitely; that contradicts the claim that tracking main prevents stale generated output. Add a standard-to-node dispatch/scheduled reconciliation, or document an explicit regeneration trigger for generator changes.

      # Deliberately @main rather than a release tag. A generator that has fallen behind produces an
      # index that disagrees with the standard it claims to follow, and does so silently — CI stays
      # green while running the wrong code. Tracking `main` means a breaking change reaches you
      # loudly instead, which is the trade this project wants while the spec is 0.y.z.
      - uses: waldronlab/agent-protocol-standard/actions/generate-index@main

template/.github/workflows/generate-index.yml:68

• Because the lookup is embedded in echo and the step has no set -e, a failed gh api still leaves the step successful and writes an empty id. With the App configured, line 79 then silently selects the github-actions[bot] fallback even though the App token performs the push, losing the intended attribution. Capture and validate the lookup and fail on error instead of allowing the no-App fallback in this path.

        run: echo "id=$(gh api "/users/${SLUG}[bot]" --jq .id)" >> "$GITHUB_OUTPUT"

• Files reviewed: 4/4 changed files
• Comments generated: 1
• Review effort level: Lite

[Copilot]

🟡 Changes recommended

Workflow consistency and documentation issues remain unresolved.

Get a fresh assessment by requesting another Copilot review.

Review details

Suppressed comments (2)

docs/adr/0011-pre-release-tags-for-the-tooling.md:8

• This amendment only qualifies ADR-0011's old consequence, but ADR-0006 §3 still states that consumers consume these actions pinned to a release tag. With the shipped template now using @main, the accepted architecture record is contradictory; please add an amendment note to ADR-0006 (even if the broader pinning question remains open) or explicitly mark that sentence as historical.

> **Amended by the template's move to `@main` (2026-09-14).** The consequence below that "consumers must reference `@v0`" no longer describes the shipped template, which references `@main` so that a node cannot validate against a standard older than the one it claims to follow. `@v0` still exists and still moves on release. Whether a federated node should ever pin is deliberately left open; if it settles, it warrants an ADR superseding this consequence and ADR 0006 §3.

template/.github/workflows/generate-index.yml:27

• This concurrency setting only serializes workflow runs; it does not make the checkout and the later git push atomic. If main advances after this checkout—especially via a change outside the paths filter, which queues no follow-up run—the composite action still pushes from a stale base, gets a non-fast-forward error, and leaves PROTOCOLS.yaml stale. Add a fetch/rebase-and-retry path around the commit/push (or otherwise reconcile against the latest main) before relying on this as the race fix.

# Two merges in quick succession would otherwise run concurrently, and the second push would be
# rejected as non-fast-forward: its checkout predates the first run's index commit. Queue rather
# than cancel — a cancelled run leaves the index describing the previous commit.
concurrency:
  group: generate-index

• Files reviewed: 5/5 changed files
• Comments generated: 2
• Review effort level: Lite

[Copilot]

🟡 Changes recommended

Unresolved critical and moderate findings remain.

Get a fresh assessment by requesting another Copilot review.

Review details

Suppressed comments (3)

README.md:128

• v0 does not move on every release: the release workflow deliberately skips pre-releases, non-vX.Y.Z tags, and releases that are not highest on their line (as documented below). Please describe it as retargeted only for qualifying releases so the fixed-version guidance is accurate.

to reference if you have a reason to hold a fixed version — `v0` itself is not one, since it moves on
every release and is therefore no more fixed than `main`. Note that a release tag is only fixed by

actions/generate-index/action.yml:88

• When the caller checks out a SHA or another detached ref, git rev-parse --abbrev-ref HEAD returns the literal HEAD. The first push then uses HEAD:HEAD, potentially creating/updating a branch named HEAD instead of the caller's target; before this retry logic, the detached push failed rather than targeting the wrong ref. Require a symbolic branch (or accept an explicit target-branch input) before constructing this refspec.

        branch="$(git rev-parse --abbrev-ref HEAD)"
        for attempt in 1 2 3; do
          if git push origin "HEAD:$branch"; then

template/.github/workflows/generate-index.yml:93

• GITHUB_REF_NAME is a reserved GitHub Actions default variable and cannot be overwritten by a step-level env. A manual dispatch from a branch or tag will therefore still make the generator see that ref, while checkout is pinned to main, so the committed protocol_url values can point at a non-main ref and 404. Pass the target ref through a non-GITHUB_* input/environment variable and have the generator consume that explicitly.

          GITHUB_REF_NAME: main

• Files reviewed: 5/5 changed files
• Comments generated: 2
• Review effort level: Lite

[Copilot]

🔵 Needs a closer look

The ADRs contain contradictory guidance that should be reconciled with the shipped @main configuration.

Review details

Suppressed comments (2)

docs/adr/0006-separate-standard-from-protocol-content.md:8

• The new amendment says the template no longer pins release tags, but §3 still states that content repositories consume these actions with YAML pinned to a release tag (lines 51–53). That leaves the ADR internally inconsistent and can mislead readers about the supported integration; please revise §3 or clearly label that paragraph as historical.

> **Amended by the template's move to `@main` (2026-09-14).** §3 below describes content repositories consuming the actions pinned to a release tag. The shipped template references `@main` instead, so that a node cannot validate against a standard older than the one it claims to follow. The argument for distributing the tooling rather than vendoring it is unaffected. Whether a federated node should ever pin is deliberately left open; see the matching note on ADR 0011.

docs/adr/0011-pre-release-tags-for-the-tooling.md:8

• This amendment leaves the ADR's own decision and consequences contradictory: lines 42–44 still tell consumers to use @v0/a release tag, and lines 61–63 still say consumers must reference @v0, while the shipped template now uses @main. Please update those sections (or explicitly mark them historical) so the ADR does not direct new nodes to the superseded behavior.

> **Amended by the template's move to `@main` (2026-09-14).** The consequence below that "consumers must reference `@v0`" no longer describes the shipped template, which references `@main` so that a node cannot validate against a standard older than the one it claims to follow. `@v0` still exists and still moves on release. Whether a federated node should ever pin is deliberately left open; if it settles, it warrants an ADR superseding this consequence and ADR 0006 §3.

• Files reviewed: 8/8 changed files
• Comments generated: 0 new
• Review effort level: Lite