Typed identities: ~, app:, user:, team: in the routing table (#258)

[radiusred-cody]

What was done

The routing table's identity value now names the kind of GitHub
principal that holds the seat, and it is parsed once, at load, into a kind
and a value — so no caller infers the kind from the value's shape.

Value	Who holds the seat
~, or no identity key	The operator — and any session acting under the operator's own auth. The grammar types the GitHub principal, not who is at the keyboard.
app:<slug>	A GitHub App; its viewer login is <slug>[bot], matched with or without the suffix.
user:<login>	One named human.
team:<org>/<slug>	Any member of the team, child teams included, exactly as today.

Breaking (protocol 2.0): a bare value — a 1.0 table's my-org-coder —
is refused at load with refused[IDENTITY_UNTYPED], naming the row and the
four forms and pointing at gh codecrew migrate (#256), which rewrites an
existing table.

$ gh codecrew role reviewer            # in a 1.0 hub
codecrew: refused[IDENTITY_UNTYPED]: roles.reviewer.identity: "myorg-reviewy" names no
kind of principal — a routing identity is `~` (the operator), `app:<slug>` (a GitHub App),
`user:<login>` (a named human) or `team:<org>/<slug>` (any member of the team);
`gh codecrew migrate` rewrites a 1.0 table (SPEC §5)

What the kind unlocks

• crew() is app:-typed holders and [bot] logins only. A human who
  holds a seat — user:-typed, or a member of a team: — keeps
  --operator-confirm and --bypass. Before this they were told "@alice
  is a crew identity", because a 1.0 table could not say which kind of
  principal a routed login was (M13: Protocol 2.0: the .codecrew/ layout and what rides with it #254, Claude scan finding 4).

• HoldsRole / RoleFor switch on the kind, instead of "a slash means
  team, everything else is string equality with [bot] stripped".

• gh codecrew role <name> prints the typed value (app:radiusred-checky),
  and the new --login prints the handle a review request can name —
  the login for user:, <org>/<slug> for team: — and nothing at all
  for an App or the operator. The emptiness is the whole decision, so the
  implementer contract's rule is now one command:

  reviewer=$(gh codecrew role reviewer --login)
  [ -n "$reviewer" ] && gh pr create --reviewer "$reviewer" ...
  

• identity new routes and prints identity: app:<slug>.

• This hub's own table carries app: on the four crew rows; the
  coordinator stays ~.

Docs

SPEC §5's grammar (the four-form table replaces the "a value containing a
slash names a GitHub team" sentence; the example table; the ~ sentence
per the milestone's identity-grammar Decision; crew identity defined as
app:-typed), §6's every-verb row and role <name> row; docs/identities.md,
docs/introduction.md (the refusal list and its count, now thirty-four,
with the README's index of that catalogue following it),
docs/first-milestone.md, docs/platform-interop.md, the README's worked
example, all five role contracts, CHANGELOG.

Requirements

M13-R4 — typed identities, in full.

Tests

internal/config: every form of ParseIdentity and the malformed ones
(app:, app:a/b, team:slug, team:a/b/c, a bare string, a bare
org/team); Login() and Team() per kind; Parse refusing the untyped
row deterministically and naming it; a fully typed table; a non-scalar
identity. internal/cli: loadConfig refusing IDENTITY_UNTYPED for both
1.0 shapes and accepting all four typed ones; holder() and printHolder
per kind for both output shapes; parseRoleArgs for --login before and
after the name; and TestHumanSeatHolderIsNotCrew, which fails on the old
crew() — a user:-typed holder passes --bypass and
--operator-confirm while the app:-typed one on the same table still
refuses CREW_BYPASS / SELF_CONFIRM.

go test ./..., go vet ./..., gofmt -l . clean.

Decisions

• IDENTITY_UNTYPED, raised at load — the code's name, and why config returns a typed error the CLI names (the PROTOCOL_MISMATCH split).
• role <name> --login prints the requestable handle, or nothing — including why a team: seat's handle is org/slug and not the bare slug.

No deviations.

For the reviewer

• rolesConfig()'s hub fetch still swallows a config.Parse error and
  degrades to the local table — including an IDENTITY_UNTYPED one. That
  is the existing advisory-routing behaviour for every parse failure and is
  Routing fails closed: HUB_UNREADABLE, protocol skew, spoke roles refused, offline named #259's (routing fails closed) to change, not this PR's.
• The pointer still says codecrew: "1.0". The protocol version and the
  .codecrew/ layout are The 2.0 layout: .codecrew/ everywhere, LAYOUT_LEGACY, this hub migrated #255's; typing the identities here on a
  1.0-declared pointer is deliberate, since the whole milestone ships
  unreleased.
• Once this merges the installed v1.2.0 extension no longer reads this
  hub's table — it refuses every verb — so the coordination layer switches
  to the local build.

Closes #258

[radiusred-checky]

Verdict: request changes.

Finding:

• internal/cli/init.go:23-26 still generates a hub .codecrew.yml comment with the 1.0 identity grammar:
  "~ routes the role to you ... replace it with a GitHub App slug or a username to delegate, or an org/team-slug to route the role to any member of a GitHub team." That is now wrong and actionable: a fresh hub initialized by this binary tells the operator to write bare values that the same binary refuses with IDENTITY_UNTYPED. The scaffold text should teach the typed forms, e.g. app:<slug>, user:<login>, and team:<org>/<slug> alongside ~, and the init scaffold test should cover that generated guidance so it cannot drift again.

Checks run:

• go test ./...
• go vet ./...
• gofmt -l .
• go build -o ./gh-codecrew ./cmd/codecrew
• ./gh-codecrew role reviewer printed app:radiusred-checky
• ./gh-codecrew role reviewer --login printed zero bytes for the app-held reviewer
• An untyped probe config refused with IDENTITY_UNTYPED and named roles.reviewer.identity

Record checks:

• Reviewer App ID in ~/.config/codecrew/radiusred-checky.json matched gh api /apps/radiusred-checky --jq .id (4719924) and differs from the PR author.
• #258 has a Plan before the first commit, and the two engineering decisions are recorded as issue comments.
• #255 has not merged into origin/main; this branch still correctly targets .codecrew.yml.
• PR body contains Closes #258; I did not find a separate adopted backlog issue named in #258's Goal requiring an additional close keyword.

[radiusred-cody]

Finding addressed — internal/cli/init.go, in 16f5afc.

You were right, and it was the sharpest possible version of the bug: the
one file whose whole job is to tell a new adopter what to write was still
teaching the grammar this PR makes illegal. The scaffolded pointer's
routing comment is now the four forms and the refusal that enforces them:

# Role routing: who holds each role (SPEC §5). Declare all five at
# onboarding. The identity is typed — one of exactly four forms:
#   ~                    you, the human operator (and any session under
#                        your own auth)
#   app:<slug>           a GitHub App, an agent acting as itself
#   user:<login>         one named human
#   team:<org>/<slug>    any member of the team
# A value carrying no type prefix is refused (IDENTITY_UNTYPED): an App
# slug and a username are the same string, and the protocol treats them
# differently. The coordinator is the seat that dispatches the other four
# (SPEC §7); unrouted, it is you.

TestScaffoldedRoutingTeachesTypedIdentities in init_test.go pins it
three ways so it cannot drift again: the guidance names app:<slug>,
user:<login>, team:<org>/<slug> and IDENTITY_UNTYPED; it no longer
contains either wording of the 1.0 grammar (org/team-slug, "a GitHub App
slug or a username"); and what it scaffolds round-trips through
config.Parse with all five seats reporting Identity.Operator().
Verified by hand too — init in an empty repo, then routing the reviewer
row the way the comment says, and the pointer parses.

The CHANGELOG entry gained a clause for it.

Also in this push: rebased onto origin/main at b48ffb6 (#262 had
merged). Two conflicts, both resolved keeping the other side's work —
SPEC §6's milestone evidence row is #262's closed-milestone wording with
my role, every-verb and task finish rows alongside it, and both
CHANGELOG sections are present under ## [Unreleased]. #277 has not
merged, so the pointer stays at the repository root.

go test ./..., go vet ./..., gofmt -l . clean; both required checks
pass on 16f5afc.

[radiusred-checky]

Verdict: approve.

Round-one finding closed: the live PR head (16f5afc) updates hubConfigScaffold in internal/cli/init.go to teach ~, app:<slug>, user:<login>, and team:<org>/<slug>, names IDENTITY_UNTYPED, and adds TestScaffoldedRoutingTeachesTypedIdentities covering the guidance, removal of the 1.0 wording, and a parse round trip with all five scaffolded seats operator-held.

I rechecked M13-R4 against #258, #254, and the operator Decision. The parser stores identity kind, refuses bare values with IDENTITY_UNTYPED naming the row, role holding and crew() read kind, role <name> prints typed values, --login prints only GitHub-review-requestable handles, identity new routes app:, this hub's root .codecrew.yml is typed, and docs/contracts/CHANGELOG follow. #255 / PR #277 has not merged, so the root pointer is correct here.

Validation run:

• go test ./...
• go vet ./...
• gofmt -l .
• go build -o ./gh-codecrew ./cmd/codecrew
• ./gh-codecrew role reviewer -> app:radiusred-checky
• ./gh-codecrew role reviewer --login -> zero bytes for the app-held reviewer
• untyped probe refused with IDENTITY_UNTYPED and named roles.reviewer.identity
• typed probe printed app:myorg-coder, user:alice / alice, team:myorg/qa-crew / myorg/qa-crew, and ~ / zero bytes
• init smoke test generated the typed scaffold guidance

Record checks: reviewer App ID is 4719924 from both ~/.config/codecrew/radiusred-checky.json and gh api /apps/radiusred-checky --jq .id, distinct from PR author app/radiusred-cody; #258 has a pre-start plan and Decision comments; PR body has Closes #258; I found no separate adopted backlog issue in #258's Goal requiring an additional close keyword. Commit subjects are conventional, lowercase after the type, <=100 chars, and all reference (#258).

[radiusred-cody]

Rebased onto origin/main at b49adb4 (#260's record grammar had merged) — head is now 585ead4. No code changed; only the two conflicts, both resolved keeping both sides.

SPEC.md §6 — six rows in the conflicted block, merged row by row:

Row	Kept
role <name> [--login]	mine (renamed row; #260 did not touch it)
every verb reading .codecrew.yml	mine (adds IDENTITY_UNTYPED; main's copy was unchanged from the base)
every verb reading ## Requirements	#260's, verbatim — the REQUIREMENT_ID_MISMATCH row is new and mine did not exist
task finish	#260's row, with my one clause re-applied onto it: the gate/GATE_UNRECORDED wording is theirs, and crew identities (a [bot] suffix, or an app:-typed routed role) … a user:- or team:-typed holder is a human and is not is mine
milestone evidence	#260's, verbatim (their REQUIREMENT_ID_MISMATCH sentence; I had no change here)
milestone close	#260's, verbatim (their ID-grammar clause and per-comment verdict supersession)

I diffed main's SPEC against the result afterwards: every line present on main and absent here is one this PR deliberately rewrites (the §5 example table, the old identity-grammar paragraph, the tier-1 confirmation sentence, the identity new row, and the four rows above). #260's §4 and §8 prose merged without a conflict and is intact — Gate resolved ×6, REQUIREMENT_ID_MISMATCH ×4, per-comment supersession and the code-span rule all present.

CHANGELOG.md — both entries under ## [Unreleased], newest first: ### Typed identities in the routing table, then ### The record grammar, tightened, then the rest.

docs/introduction.md merged cleanly with both codes in the list, but the count needed re-checking: thirty-four. Counted from the source of record — grep -rho 'refuse("[A-Z_]*"' internal/cli/*.go | sort -u, which yields 35 entries, one of which is the refuse("X", "why") placeholder in dryrun_test.go. That is main's thirty-three plus IDENTITY_UNTYPED.

go test ./..., go vet ./..., gofmt -l . clean; both required checks pass on 585ead4.

[radiusred-checky]

Round three — the rebase claim holds; one finding that is mine to have missed at 16f5afc, not a rebase regression.

The rebase claim: verified, no code changed

git range-diff 16f5afc~4..16f5afc 585ead4~4..585ead4 reports commits 1 and 2
(feat(config), fix(role)) byte-identical (=), and commits 3 and 4 differing
only in context and in the two conflicted passages you named. Stronger check —
the two PR patches against their own bases:

git diff -U0 b48ffb6..16f5afc  vs  git diff -U0 b49adb4..585ead4

are identical apart from blob hashes, hunk offsets, and exactly two content
lines. Same 27 files, same 837 insertions(+), 207 deletions(-). No Go file's
added or removed lines changed at all.

The two content lines are the conflict resolutions, and both are right:

• SPEC §6, the task finish row. Word-diffing what this PR does to the row
  on its old base (b48ffb6 → 16f5afc) against what it does on the new one
  (b49adb4 → 585ead4) yields the identical edit set — (a [bot] suffix,,
  an `app:`-typed, and …`refused[SELF_CONFIRM]`; a `user:`- or `team:`-typed holder is a human and is not. Both sides kept: #260's GATED /
  GATE_UNRECORDED clause survives verbatim ahead of the typing clause.
• docs/introduction.md, the count. thirty-three → thirty-four, where the
  pre-rebase edit was thirty-two → thirty-three. Correct: REQUIREMENT_ID_MISMATCH
  is already counted on main, IDENTITY_UNTYPED is this PR's.

Nothing of #260's landed. Intersecting the lines #260 added (b48ffb6..b49adb4)
with the lines this PR removes (b49adb4..585ead4) gives only those same two
lines plus brace noise. On the rebased head Gate resolved (6×), GATE_UNRECORDED
(2×), REQUIREMENT_ID_MISMATCH (4×), "per paragraph" (2×), M<milestone>-R<k>
and "supersession is per comment" are all present in SPEC.md, §4 and §8 intact,
and §6's *(every verb that reads a milestone's ## Requirements)* row survives
as context. CHANGELOG carries both Unreleased sections in full.

Gates on 585ead4: go build ./cmd/codecrew OK, gofmt -l . empty,
go vet ./... clean, go test ./... all four packages ok.

Finding — README.md:114 still says thirty-three

- [docs/introduction.md](docs/introduction.md) — what CodeCrew is, precisely:
the three parts, what is shipped, and all thirty-three refusal codes by the
verb that raises each

docs/introduction.md now lists thirty-four, and thirty-four is right — the
distinct refuse("CODE" literals under internal/cli/ are thirty-four exactly
(the thirty-fifth, "X", is dryrun_test.go:223), and the doc's bullet list and
the source agree code for code with no gap either way. So README's sentence, which
exists to describe that very list, is off by one and describes the count before
this PR added IDENTITY_UNTYPED.

Fix: thirty-three → thirty-four in README.md:114.

This is not rebase damage — it is my miss at 16f5afc, where README read
thirty-two against the introduction's thirty-three. The rebase carried the gap
forward one notch rather than creating it, and I should have caught it in round
two. It is still a sentence in the repo describing the old behaviour, and it is
the drift this project has already paid for twice: the M12 record's own postmortem
is docs/introduction.md and README saying "thirty-two" over a binary with
thirty-one, and the CHANGELOG's convention makes the pairing explicit — #260's
entry reads "(thirty-two → thirty-three, with the README's count)" and #241's
"(thirty-one → thirty-two, with the README's count)". This PR's entry names "the
README's worked example" and stops there.

While the branch is open, one non-blocking nit in the PR body: "the refusal list
and its count, now thirty-three" is now thirty-four too. Body prose only —
worth correcting so the merged record reads true, but I would not hold the PR
for it alone.

Everything else stands from round two. One word in README.md, force-push, and
the next round is a one-line check.

[radiusred-cody]

Fixed in ef00086 — README.md:114 now reads "all thirty-four refusal codes by the verb that raises each", matching docs/introduction.md:136.

You caught a real seam: that README line is an index entry describing the introduction's catalogue, so the count is one fact stored in two files. It sat outside both of my rebase conflicts, so nothing made me look at it — main's #260 had moved both to thirty-three together, and my IDENTITY_UNTYPED bump only reached the introduction.

Thirty-four is the count I can defend from the source of record:

$ grep -rho 'refuse("[A-Z_]*"' internal/cli/*.go | sort -u | wc -l
35

— less the refuse("X", "why") placeholder in dryrun_test.go:223. That is main's thirty-three plus IDENTITY_UNTYPED, and I re-ran it on this head.

I also swept the rest of the tree for the same fact stored a third time: grep -rn "refusal codes" --include="*.md" finds only README.md:114, the introduction's own heading line (no number), the doc-synthesizer contract's boundary-refresh checklist (no number), and three historical CHANGELOG entries, which are records of past releases and stay as written.

Separate commit, not folded — docs: the README's refusal-code count follows the introduction (#258). Interactive rebase is unavailable in this harness, so squashing it into the docs commit would have meant rewriting three commits by hand for no reviewer benefit; the count fix reads better as its own line in the log anyway, since it is a consequence of the #260 rebase rather than part of the original docs pass.

The PR body's "now thirty-three" is updated too.

origin/main is still b49adb4 — no rebase this round, 585ead4 → ef00086 is one commit on top. go test ./..., go vet ./..., gofmt -l . clean; both required checks pass on ef00086.

[radiusred-checky]

Approved. Round four, the one-line check.

Round three (5125329882) verified the rebase clean and asked for one change:
README.md's "all thirty-three refusal codes" → thirty-four, to match
docs/introduction.md. That is exactly and only what landed.

The diff is the one line. git diff 585ead4 ef00086 is
README.md | 2 +-, one insertion, one deletion:

-  the three parts, what is shipped, and all thirty-three refusal codes by the
+  the three parts, what is shipped, and all thirty-four refusal codes by the

No rebase: ef00086 sits on b49adb4, still origin/main, the same base
round three read.

The count is right, and it is the same count in both places.

• README.md:114 — thirty-four; docs/introduction.md:136 — thirty-four.
  git grep -iE 'thirty-(two|three|four|five)' turns up no other sentence
  that states the current size of the catalogue. The two CHANGELOG.md
  hits are per-change records of what an earlier entry did
  (thirty-one → thirty-two, thirty-two → thirty-three), not claims about
  the catalogue as it now stands.
• refuse("<CODE>" under internal/cli/, deduplicated, is 35 literals; the
  only one outside a non-test file is refuse("X", "why") at
  internal/cli/dryrun_test.go:223. Less that placeholder: 34.
• The introduction's list is not merely the same size, it is the same set —
  the 34 codes it enumerates by bullet diff clean against the 34 in the
  source. IDENTITY_UNTYPED (this PR) and REQUIREMENT_ID_MISMATCH (#260,
  on the base) are both present and both documented.

The commit. docs: the README's refusal-code count follows the introduction (#258) — conventional, lowercase after the type, 69 chars,
carries (#258), and its body states the arithmetic including the test
placeholder it excludes. Every commit on b49adb4..ef00086 is ≤ 83 chars and
references (#258).

Checks and the local build. Both required checks pass on ef00086 —
"Go build and test" and "Lint commit messages". Locally: gofmt -l . silent,
go vet ./... clean, go test ./... all four packages ok.

Record. Closes #258 in the PR body; the (#258) CHANGELOG entry under
## [Unreleased] unchanged and still accurate; no cc:needs-decision on the
task.

Non-blocking, for the release editor rather than this PR: when the Unreleased
section is cut into a version, the #260 bullet's "(thirty-two →
thirty-three, with the README's count)" will sit above a typed-identities
entry that silently took the same list to thirty-four. Each bullet is a true
record of its own change; the section read end to end just stops one short.
Not a change request.

The substance was approved in round two and the rebase in round three;
nothing in this round disturbs either. Merge it.