Add bot naming doctrine and permission capability ledger for app control-plane

[primeinc]

Goal

Add the extra control-plane documentation and conventions discussed after #69 without expanding the first PAT-replacement PR.

This issue covers only the pieces not already forced into #69:

bot/app naming doctrine
primeinc-stars-yoshi-doctor subsystem name
permission capability ledger
permission proof/prune plan
subsystem naming map

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

Scope Boundary

This is not the first implementation PR.

First implementation PR should stay boring:

replace preferred repo-write PAT behavior with GitHub App installation token
preserve fallback modes
prove app token can mint / checkout / write or PR
report auth mode in workflow summary

This issue is the separate follow-up PR for naming and governance documentation around the app/control-plane surface.

Do not delay PAT replacement on this issue. Do not turn the PAT replacement PR into a doctrine cathedral. We already have enough architecture sludge trying to cosplay as progress.

Direct Evidence

• Installed GitHub App name: primeinc-github-stars.
• App description: repo-scoped automation app for primeinc/github-stars, mints short-lived installation tokens, writes generated star catalog artifacts, supports auth diagnostics, and replaces long-lived PATs where possible.
• App is installed only on selected repo: primeinc/github-stars.
• GitHub docs say GitHub App names should be clear/short, must be unique, max 34 characters, and are normalized for UI display when the app acts.
• GitHub docs say API requests made by an app installation are attributed to the app.
• Build Juvenal-grade TypeScript control plane with full GitHub App auth support #69 already owns the larger Juvenal-grade TypeScript control-plane shape.
• Fix AI classification workflow using legacy prompt/simple inference with no grounded validation #71 already owns the concrete legacy/simple AI classification failure.

Required Naming Doctrine

Add repo documentation for bot/app/subsystem names.

Recommended file path:

docs/automation/bot-naming.md

or, if docs are not yet structured:

.github-stars/docs/bot-naming.md

Required naming rules:

GitHub App identity:
  primeinc-github-stars

Subsystem/check prefix:
  primeinc-stars-*

Pattern:
  <scope>-<surface>-<role>

Rules:
  lowercase kebab-case
  clear audit-log meaning
  provider-neutral unless truly provider-specific
  no cute name at the cost of traceability
  GitHub App names stay <= 34 chars

Required Bot / Subsystem Names

Document these names:

Name	Type	Role
primeinc-github-stars	GitHub App identity	Installed repo-scoped app identity. Used for attribution and installation-token auth.
primeinc-stars-yoshi-doctor	setup doctor subsystem/check	Super Mario World helper/companion reference. Performs auth/config/permission diagnostics.
primeinc-stars-auth	subsystem	Auth-mode resolver and token-source reporting.
primeinc-stars-classifier	subsystem	AI classification parsing, validation, evidence checks.
primeinc-stars-router	subsystem	Failure -> issue/PR/agent-task routing.
primeinc-stars-provenance	subsystem	Generated artifact proof, checks, summaries, attestations if used.
primeinc-stars-guard	subsystem	Security/dependency watch surface if implemented later.

Yoshi Doctor intent

primeinc-stars-yoshi-doctor should be the name for the setup doctor/check/report, not the installed GitHub App identity.

Reason:

installed app identity must be boring and auditable
setup doctor can carry the Super Mario World helper reference
Yoshi = helper/companion that carries the run through hostile terrain

This gives the repo a memorable diagnostic surface without making the GitHub App actor name look like a toy in audit logs. Apparently this is what maturity looks like now: controlled whimsy with a changelog.

Required Permission Capability Ledger

Add a machine-readable or Markdown permission ledger.

Preferred file:

.github-stars/control-plane/permissions.yml

Acceptable doc-first fallback:

docs/automation/app-permissions.md

Minimum schema:

permissions:
  contents:
    access: write
    phase: runtime
    capability: commit generated catalog artifacts and update control-plane source
    proof_required:
      - app-token checkout succeeds
      - commit or PR created with app installation token
    prune_rule: keep unless direct-write is replaced by PR-only flow

  workflows:
    access: write
    phase: bootstrap
    capability: repair and migrate GitHub Actions workflow files during #69 work
    proof_required:
      - PR modifies .github/workflows through app-backed flow
    prune_rule: downgrade after workflow migration stabilizes

  variables:
    access: write
    phase: bootstrap/runtime
    capability: configure auth mode, app client id, source user, feature flags
    proof_required:
      - setup doctor reports required variables present without leaking values
    prune_rule: keep if used by auth resolver; otherwise remove

  secrets:
    access: read
    phase: bootstrap
    capability: setup doctor verifies required secrets exist without printing values
    proof_required:
      - redacted secret-presence report
    prune_rule: reduce/remove if setup doctor can operate without secrets permission

The exact final schema can differ. The invariant cannot: every permission gets a purpose, phase, proof, and prune rule.

Required Permission Classification

Classify granted permissions into these buckets:

runtime core
runtime proof
bootstrap/self-config
agent orchestration
publish/provenance
security/dependency watch
speculative/remove-unless-proven

Required table columns:

permission
current access
capability enabled
phase
first workflow/subsystem expected to use it
proof artifact
keep/reduce/remove decision
reduce-after milestone

Required Relationship to #69

Add a short note to #69 or AGENTS.md that says:

#69 owns the TypeScript control-plane implementation.
This issue owns naming doctrine and permission capability ledger.
The first PAT replacement PR should not wait for this issue.

Acceptance Criteria

• Bot/app/subsystem naming doctrine exists in repo docs.
• primeinc-stars-yoshi-doctor is documented as the setup doctor/check/report name.
• Installed app identity remains documented as primeinc-github-stars.
• Permission capability ledger exists with purpose/proof/prune fields.
• Broad app permissions are classified by phase, not treated as a flat scary blob.
• Docs clearly state this issue does not block the first PAT replacement PR.
• Build Juvenal-grade TypeScript control plane with full GitHub App auth support #69 can link this issue as the scope for extra naming/permission-governance work not already in its body.

Proof Required

Completion comment must include:

• PR URL.
• File paths added/updated.
• Excerpt showing primeinc-stars-yoshi-doctor.
• Excerpt showing the permission ledger schema/table.
• Confirmation that PAT replacement remains separately scoped.

Evidence Labels for Implementer

Use these labels in the completion report:

• Direct evidence: repo file diff, GitHub App install summary, GitHub docs citation, PR URL.
• Weak inference: why a permission supports a future subsystem before the subsystem uses it.
• Unsupported: claiming a permission is permanently required without workflow or setup-doctor proof.
• Contradicted: docs say permission is used but no workflow/subsystem can exercise it.

Non-Goals

• Do not implement the full TypeScript control plane here.
• Do not implement the PAT replacement here unless this issue is explicitly merged into that PR scope later.
• Do not remove existing fallback modes.
• Do not change app permissions yet based only on this documentation pass.

Definition of Done

The repo has a documented bot/subsystem naming scheme and a permission capability ledger that explains why the broad one-repo app authority exists, how each permission will be proven, and when unused permissions should be reduced.

[primeinc]

Closing — naming doctrine + permission ledger shipped in 6f9d9ca9 (PR #79).

Files added:

• docs/automation/bot-naming.md — every actor + subsystem with role
• .github-stars/control-plane/permissions.yml — machine-readable ledger

Direct evidence:

1. primeinc-stars-yoshi-doctor documented as the diagnostic name, distinct from the App identity:

   primeinc-stars-yoshi-doctor: setup doctor subsystem
   Auth + config + permission diagnostics.
   The Super Mario World helper reference is intentional and scoped
   to the diagnostic surface — it does NOT bleed into the app
   identity, which stays boring for audit-log clarity.
   

2. Installed App identity remains primeinc-github-stars (App ID 3663316, Client ID Iv23liRZxVz4rlcQnAKt). Recorded in the table.

3. Permission ledger schema matches the issue's spec — every entry has access, phase, capability, proof_required, prune_rule. Plus bucket classification at the bottom (runtime_core / bootstrap_self_config / speculative_remove_unless_proven).

4. Speculative permission flagged — issues: write is currently granted but not exercised by any workflow. The ledger explicitly classifies it as speculative_remove_unless_proven and documents that it should be downgraded to none until the router subsystem actually opens issues. This is the least-privilege evidence the issue asked for.

5. Permissions deliberately NOT granted are enumerated in the ledger as a comment block — evidence that omissions are intentional, not gaps.

Scope boundary respected: the PR #79 modernization sprint owns the auth implementation. This issue's scope was governance docs only — no PAT replacement work landed in this commit.