docs: triage role vocabulary, agent-brief format, and a settled-questions KB

[juemerson-at-purestorage]

What this adds

Three documents under docs/. No source changes.

The issue labels became a machine interface when the status: / priority: / size: /
area: / source: taxonomy went on. A queue reads them to decide what is workable, and
automated issue-filing will read them to avoid duplicating itself. Nothing wrote down what
they mean, which transitions are legal, or the one-label-per-axis invariant that several of
those consumers already assume.

docs/TRIAGE-ROLES.md

The vocabulary, the state machine, the axes, and a snippet that asserts the invariant.

Two rules in it exist specifically because a machine reads the labels rather than a person:

• status:triage is not a scoring input. It means "nobody has assessed this". Twenty of
  the forty-three open issues sit there; a scorer treating them as workable would be wrong
  about half the backlog.
• status:agent-ready means a brief is attached, not that the issue looked small. The
  label points at a contract.

Deliberately no wontfix state — a GitHub closing reason is finer-grained, and
not planned misrepresents an issue describing a fix we want but cannot yet make (those stay
open with status:blocked and the blocker named).

docs/AGENT-BRIEF.md

The brief format, with a worked example taken from #136 rather than an invented one.

Two sections beyond the usual template, both earned by gates that are invisible from a clean
local run:

• a Verification: line — live-verified, not verified, or cannot-reach-the-wire;
• gate-aware acceptance criteria — the four derived-artifact pairs that move on a
  parameter-block change (not two), and the force-import BeforeAll a new test file needs.

docs/settled/

Questions closed against, so the reasoning outlives the closed issue. docs/design/ holds
questions we answered; this holds questions we settled against. It is also what automated
filing needs in order to deduplicate: matching against open issues is not enough, because the
finding declined last month is the one a scanner rediscovers next month.

Seeded with three — a false finding (#89), a rejected design (typed object model), and a
rejected approach (splitting #65 by family).

Every entry carries a Premise and a What would reopen this line. That is the part
worth arguing about: a rejection that outlives its reasoning becomes the thing that blocks
correct work, with the authority of a written decision behind it. If a Premise cannot be
written, the thing is a deferral and does not belong in the directory.

One rule stated explicitly in the README: an already-implemented feature must never be
recorded there. It would poison the deduplication with a false negative — a scanner would see
a match and stay silent about a real gap.

Live-testing

Exempt. Verdict produced mechanically by Test-PfbWireExemption.ps1, not by reading the
diff:

The diff leaves the module source and the manifest entirely untouched, so nothing here can
alter a request the module sends or a response it parses.

Notes for review

• docs/settled/ is a process imposition, not a code change. If you would rather not
  carry a directory for it, the same content collapses into a single docs/settled.md — say
  so and I will squash it. Your repo, your call.
• The vocabulary described here is already applied to all 43 open issues, so the document
  describes the current state rather than proposing a migration.
• Nothing here bumps a version or touches CHANGELOG.md.

🤖 Generated with Claude Code