Upstream COMMANDS.md is trusted as source, but it can disagree with the command class it documents

[dmccoystephenson]

Promoted from kingdom-community/kfe-docs-dev-loop#37, which is being retired. That loop served three repos from one file; it has been split into one loop per repo (kfe-staff-dev-loop, kfe-server-ops-dev-loop, kfe-player-guide-dev-loop), so a rule that belongs in the template no longer has a single loop to live in.

Labelled template-rule there: the finding is general, and the fix belongs in create-dev-loop.md rather than in any one loop.

---

What happened

A Stage A sweep this cycle documented three plugins' commands (kingdom-community/kfe-docs#90). Following #26's suggestion, the upstream COMMANDS.md and plugin.yml of each plugin were read as the source. Both claims that later failed the Phase 4 rubric came from COMMANDS.md being less precise than the code, not from it being wrong in a way a reader would notice:

• Dans-Plugins/AlternateAccountFinder documents a hard privacy rule (no address is ever surfaced) that AafAccountsCommand partially breaks by design: it prints "Accounts for " + ip.getHostAddress(), echoing the address the operator supplied. A doc written from the privacy rule alone states something false.
• Dans-Plugins/Activity-Tracker describes /at list as "the 10 most recent player sessions with login times and duration". ListCommand aggregates across every activity record — so it is server-wide, not per-player — and prints a duration only for ended sessions; an active session prints Active instead.

Both were caught only because the command classes were opened during the self-review, after the first draft had already been written from the upstream documentation.

Why this is not covered by an existing issue

#26 establishes that plugin repos are a source of truth and lists COMMANDS.md, CONFIG.md, USER_GUIDE.md, and plugin.yml alongside the source, without ranking them. #33 covers upstream drifting after a sweep. Neither says what to do when two upstream artifacts disagree, which is the case here — the upstream documentation is not stale, just coarser than the behaviour being documented.

Suggested instruction text

Phase 3, appended to the plugin-source grounding step:

Upstream prose (COMMANDS.md, USER_GUIDE.md, a project's own CLAUDE.md) is a map, not the territory. Where a claim being written concerns what a command outputs, rejects, persists, or scopes over, open the executor class before writing it — the upstream doc is authoritative for the usage string and permission node, and the code is authoritative for everything else. A behavioural claim that no upstream doc states, and that has not been read in code, is not written.

Phase 4, added to the No inventions rubric item:

A behavioural claim sourced only from upstream prose scores FAIL until the class implementing it has been read.

The same precedence would have caught both defects before they reached the diff rather than during the rubric.

This issue was drafted during a Gardener session (https://github.com/Stephenson-Software/gardener).

---

drafted by Claude on behalf of Daniel Stephenson