Epic: Mandatory read-the-room and upstream-canonical gates before code changes

[primeinc]

Goal

Create a dedicated epic for repo rules, checklists, gates, and implementation discipline around mandatory @read-the-room before writing code.

This is the hard anti-bot-slop rule:

Before any code change, the implementer must run/read through @read-the-room over the relevant local refs and upstream canonical sources.

Canonical ONLY:
  find the shape upstream
  find how upstream tests it
  read why they do it that way
  map local change to upstream pattern
  then write code

Parent: #69
Related: #42, #54, #71, #73, #74

Why this exists

The repo is now moving from ad hoc workflow repair into a TypeScript control-plane, app-auth, classifier, privacy, and generated-artifact system. That creates high leverage and high failure risk.

Bots must not write local cleverness from vibes.

Required sequence:

read local refs
  -> read local issue/acceptance context
  -> find upstream canonical implementation shape
  -> find upstream tests/fixtures
  -> understand why upstream chose the shape
  -> map upstream shape to local constraints
  -> write smallest coherent patch
  -> prove with tests/gates

Skipping this is how we get YAML taxidermy, fake TypeScript architecture, and another month-long hole dug by a bot that thought a filename was evidence.

Hard Repo Rule

No implementation PR is acceptable unless it includes an explicit @read-the-room evidence block.

Minimum required block:

## @read-the-room evidence

### Local refs read
- [ ] AGENTS.md
- [ ] relevant issue body and comments
- [ ] relevant workflow/source/test files
- [ ] relevant docs under docs/ or .github-stars/docs/
- [ ] relevant .sisyphus proofs/plans if present

### Upstream canonical refs read
- [ ] first-party docs
- [ ] upstream source implementation
- [ ] upstream tests/fixtures/examples
- [ ] upstream rationale/design note/changelog if available

### Mapping
- local requirement -> upstream shape -> local adaptation -> proof

### Evidence labels
- direct evidence:
- weak inference:
- unsupported/blockers:

No block, no merge.

Scope

This epic governs every implementation surface touched by the control-plane work:

GitHub App auth
PAT replacement
public/private repo privacy policy
setup doctor / primeinc-stars-yoshi-doctor
bot naming doctrine
permission capability ledger
classifier validation
model/prompt input construction
generated artifact registry
workflow summaries
issue/PR/agent routing
artifact provenance
TypeScript gate command

Mandatory Local Read Set

Before changing code in this repo, read the relevant local context.

Baseline local refs:

AGENTS.md
package.json
tsconfig.json
vitest.config.ts
.github/workflows/00-ci.yml
.github/workflows/01-fetch-stars.yml
.github/workflows/02-sync-stars.yml
.github/workflows/03-classify-repos.yml
queries/*.graphql
schemas/repos-schema.json
src/manifest/*
.github-stars/data/* when relevant
.sisyphus/proofs/* when relevant

Mandatory issue refs by topic:

Topic	Issues to read
TypeScript control plane	#69
AI classifier validation	#71
bot naming / permission ledger	#73
public/private repo privacy hard block	#74
final acceptance / parent program	#42, #54
old auth failures / PAT history	#21, #23, #46

Do not treat issue titles as proof. Read bodies/comments where needed.

Mandatory Upstream Canonical Rule

For every feature, find upstream canonical shape before local implementation.

Canonical source priority:

1. first-party docs
2. first-party source code
3. first-party tests/fixtures/examples
4. first-party changelog/rationale/design note
5. widely accepted upstream package docs
6. practitioner references only after first-party sources are exhausted

Forbidden sources as primary authority:

random blog post
StackOverflow answer
old Copilot suggestion
LLM-generated explanation
unread search result snippet
local convention with no source

The implementer must record why the upstream shape was chosen and where local constraints require deviation.

Required Upstream Research by Feature Area

GitHub App auth / PAT replacement

Required upstream refs:

GitHub App installation token docs
GitHub App permissions docs
actions/create-github-app-token docs/examples
GitHub Actions checkout token behavior
GitHub REST/GraphQL endpoint permission docs for endpoints used

Required tests/gates:

app token minted
checkout with app token succeeds
write/PR path uses app identity
fallback modes still work or are explicitly gated
summary reports auth mode and token source without leaking secrets

Privacy hard block: private repos in public output

Required upstream refs:

GitHub repository visibility field docs/API behavior
GitHub stars/user starred repo API docs if used
GitHub Actions log/artifact behavior docs if relevant

Required tests/gates:

sentinel private repo fixture
public output repo blocks private identifiers
classifier input excludes private records
logs/summaries/artifacts/issues/PR payloads scanned for sentinel
unknown output visibility fails closed

AI classification / model output validation

Required upstream refs:

actions/ai-inference docs if still used
GitHub Models / inference docs if used
schema validation library docs if used
upstream examples for structured output or typed parser strategy

Required tests/gates:

invalid JSON rejected
wrong repo returned rejected
unknown taxonomy rejected
contradicted language tag rejected or needs_review
raw model output cannot directly mutate repos.yml

TypeScript control-plane shape

Required upstream refs:

package docs for tsx/typescript/vitest used by repo
Vitest test patterns for fixtures and snapshot/inline assertions if used
schema validation package docs if introduced
existing Juvenal repo shape as local inspiration, not blind copy

Required tests/gates:

pnpm typecheck
pnpm test
pnpm gate
privacy sentinel tests
auth resolver tests
classifier parser tests
generated artifact registry tests

Workflow summaries / artifacts / provenance

Required upstream refs:

GitHub Actions job summaries docs
artifact upload/download docs
attestations docs if used
checks/status API docs if used

Required tests/gates:

summary builder unit tests
artifact registry public-safety tests
no private sentinel in summaries/artifacts
checks/status payloads cite run/commit/artifact evidence

Required @read-the-room Checklist For Every PR

Every implementation PR must include:

## @read-the-room checklist

- [ ] I read the relevant local refs.
- [ ] I read the relevant issue bodies/comments, not just titles.
- [ ] I found the upstream canonical implementation shape.
- [ ] I found how upstream tests or validates this shape.
- [ ] I read upstream rationale or inferred the rationale from first-party code/tests/docs and labeled it.
- [ ] I mapped upstream shape to local constraints.
- [ ] I documented deviations from upstream.
- [ ] I added/updated local tests matching the invariant.
- [ ] I ran the relevant gate.
- [ ] I included evidence labels in the PR body or completion comment.

Required Evidence Table

Every PR must include this table:

Local change	Local refs read	Upstream canonical source	Upstream test/fixture read	Local adaptation	Proof/gate

Required Evidence Labels

Use these labels in PRs and completion comments:

Direct evidence: exact local file, issue, upstream doc/source/test, command output, workflow run, or artifact.
Weak inference: plausible mapping from direct evidence but not literally proven.
Unsupported: claim not grounded in read evidence.
Blocked: required source/file/tool unavailable.
Contradicted: direct evidence conflicts with the implementation claim.

Repo Rules To Add

Add these to AGENTS.md or equivalent repo instruction file:

Mandatory @read-the-room rule:
  Before writing code, read local refs and upstream canonical sources.
  Search hits, file names, snippets, and issue titles are candidate evidence only.
  No full read, no material claim.
  No upstream canonical shape, no implementation claim.
  No tests/gates, no done claim.

Canonical-only rule:
  Prefer first-party docs/source/tests over blogs, snippets, or LLM memory.

Privacy rule:
  Public output repo must never surface private repo identifiers or metadata.

Evidence rule:
  Every material claim must be labeled direct evidence, weak inference, unsupported, blocked, or contradicted.

Gate Ideas

Add automated gates where feasible:

PR template contains @read-the-room checklist
PR body includes evidence table
PR mentions upstream canonical refs for certain touched paths
privacy sentinel tests run for public-output surfaces
workflow grep blocks implicit STARS_TOKEN || GITHUB_TOKEN fallback
workflow grep blocks raw model JSON mutation path

Possible path-based enforcement:

Changed path	Required evidence
.github/workflows/**	GitHub Actions upstream docs and workflow test/summary proof
src/auth/**	GitHub App/auth docs and auth resolver tests
src/privacy/**	visibility/API docs and sentinel leak tests
src/classifier/**	structured output/parser docs and classifier fixtures
src/generated/**	artifact/provenance docs and generated registry tests
AGENTS.md	linked issue and canonical doctrine mapping

Milestone Shape

Suggested milestone name:

Control Plane: Evidence-Gated Implementation

Suggested epic checklist:

- [ ] Add PR template with @read-the-room checklist
- [ ] Add AGENTS.md repo rule for mandatory local/upstream reads
- [ ] Add evidence table requirement
- [ ] Add path-based PR guidance
- [ ] Add privacy sentinel gate from #74
- [ ] Add auth resolver/app token proof gate from #69
- [ ] Add classifier raw-output rejection gate from #71
- [ ] Add bot naming/permission ledger docs from #73
- [ ] Add CI check that refuses obvious missing PR checklist fields if feasible
- [ ] Add examples of valid and invalid PR evidence blocks

Acceptance Criteria

• Dedicated docs/rules exist requiring @read-the-room before code changes.
• PR template or equivalent requires local refs, upstream canonical refs, upstream tests, mapping, deviations, and proof.
• AGENTS.md tells agents not to code before read-the-room evidence exists.
• Upstream-first canonical rule is documented.
• Path-based implementation guidance exists for auth/privacy/classifier/workflow/generated-artifact work.
• The privacy sentinel gate from Hard block private repo surfacing from public github-stars runs #74 is listed as a mandatory start-to-finish surface gate.
• The first PAT replacement PR remains scoped to app-token replacement but must include the @read-the-room evidence block.
• No future PR can claim done from snippets, issue titles, search hits, or local vibes.

Proof Required

Completion comment must include:

• PR URL.
• Files added/changed.
• Excerpt from PR template or docs showing mandatory @read-the-room checklist.
• Excerpt from AGENTS.md or repo rules showing canonical-only/upstream-first instruction.
• Example evidence table.
• CI/gate output if any automation is added.

Non-Goals

• Do not use this epic to implement every feature in Build Juvenal-grade TypeScript control plane with full GitHub App auth support #69.
• Do not block the first app-token PAT replacement on full automation of every gate.
• Do not accept generic "read docs" language without requiring actual refs and evidence labels.
• Do not let agents cite their memory as upstream canonical source.

Definition of Done

github-stars has an enforceable repo rule: every implementation begins with @read-the-room over local refs and upstream canonical sources, every material claim is evidence-labeled, and every PR maps local changes to upstream shape, upstream tests, local adaptation, and gate proof before code is accepted.

[primeinc]

Closing — read-the-room evidence rule shipped in 45ee42a0 (PR #79).

Files added/modified:

• AGENTS.md §0 — new top-of-file section
• .github/PULL_REQUEST_TEMPLATE.md — new

Acceptance criteria check:

• ✅ Dedicated docs/rules exist requiring read-the-room before code changes.
  AGENTS.md §0 opens with: "No implementation begins without first-party canonical evidence." The required reading sequence is stated as a sequential pipeline (local refs → upstream canonical → rationale → mapping → patch → gate).

• ✅ PR template requires local refs, upstream canonical refs, upstream tests, mapping, deviations, and proof.
  See .github/PULL_REQUEST_TEMPLATE.md "Read-the-room evidence" section. The mapping table covers Local change | Local refs read | Upstream canonical source | Upstream test/fixture | Local adaptation | Proof / gate.

• ✅ AGENTS.md tells agents not to code before read-the-room evidence exists.
  AGENTS.md §0 closes with: "Every PR must include the read-the-room evidence block specified in .github/PULL_REQUEST_TEMPLATE.md. No block, no merge."

• ✅ Upstream-first canonical rule is documented.
  AGENTS.md §0 specifies the priority chain: ../refs/* first, first-party docs second, first-party source third, first-party tests/fixtures fourth. Forbidden as primary authority: blog posts, StackOverflow answers, LLM memory, unread search-result snippets.

• ✅ Path-based implementation guidance exists for auth/privacy/classifier/workflow/generated-artifact work.
  See PR template "Path-based gates that must pass" section — covers .github/workflows/**, src/auth/**, src/manifest/**, src/telemetry/**, src/host-io/**, src/cli/**, web/**, docs/security.md, plus future-gate hooks for Hard block private repo surfacing from public github-stars runs #74 (privacy) and Fix AI classification workflow using legacy prompt/simple inference with no grounded validation #71 (classifier).

• ✅ Privacy sentinel gate from Hard block private repo surfacing from public github-stars runs #74 is listed as a mandatory start-to-finish surface gate.
  Listed in PR template under "Path-based gates" with the parenthetical "(when Hard block private repo surfacing from public github-stars runs #74 lands)" — the hook is in place; the gate fires once Hard block private repo surfacing from public github-stars runs #74 ships.

• ✅ First PAT replacement PR remains scoped to app-token replacement but must include the read-the-room evidence block.
  AGENTS.md §0 makes the rule unconditional. The PAT replacement PR (chore: modernization sprint — bun 1.3.13 + ts 6 + zod 4 + host-io + telemetry #79) is required to fill out the template like any other PR.

• ✅ No future PR can claim done from snippets, issue titles, search hits, or local vibes.
  AGENTS.md §0 names each forbidden authority class explicitly. The PR template's evidence-labels field requires the author to flag Unsupported claims rather than leave them silent.

Evidence labels (per the issue's required vocabulary):

• Direct evidence: file diffs in commit 45ee42a0 (AGENTS.md §0, .github/PULL_REQUEST_TEMPLATE.md).
• Weak inference: none.
• Unsupported: none.
• Blocked: CI-side enforcement of the template-content checklist is a future enhancement — out of scope for this issue per the issue's "Gate Ideas" non-mandatory section.

Non-goals respected:

• Did not implement every feature in Build Juvenal-grade TypeScript control plane with full GitHub App auth support #69 (out of scope).
• Did not block PR chore: modernization sprint — bun 1.3.13 + ts 6 + zod 4 + host-io + telemetry #79 on full automation of every gate.
• Did not accept generic "read docs" language — the doctrine names specific source priorities and forbidden authority classes.
• Did not let agents cite memory as upstream canonical.