How should the automation suite model repo ownership for non-org (single-repo / user-account) adopters?

[rubambiza]

TL;DR — decisions I need from the team

1. Do we support single-repo / user-account adopters as first-class, or is org-scoped the boundary?
2. If first-class: rename/redocument ORG as OWNER, add a light ACCOUNT_TYPE, or make the ambiguous defaults fail-loud? (details below)
3. Should the suite match the within-owner boundary agent-skills#32 just set, or widen it?

Everything below is the reasoning; skip to Options and Questions if you just want to weigh in.

Context

The automation suite is designed to be pointed at any GitHub target by swapping a
profile file (config/org.env / config/org.<name>.env). Today the whole identity
model hangs off a single variable, ORG, resolved in scripts/org.sh
(load_org_profile). Every downstream reference is built by interpolating it:

• get_core_repos emits "$ORG/$name" for each bare name in config/core-repos.txt
• MAIN_REPO ($ORG/$ORG) — the hub repo referenced in report bodies and escalation hints
• REPOS_DIR ($HOME/$ORG) — local dir the fixers iterate for cloned repos
• SOURCE_REPO ($ORG/automation) — attribution links in scanner/fixer/dashboard reports
• the weekly-report generator (report.py) rebuilds every gh call as -R "$ORG/$name"

The observation

ORG is functionally just the owner namespace in an OWNER/REPO slug — and GitHub
treats a user login identically to an org login in that position (gh -R alice/tool
works whether alice is a user or an org). So the mechanism is already owner-agnostic:
someone maintaining their own repos can set PROFILE_ORG=<their-username> and the core
loop works.

Where it gets leaky is three org-shaped defaults (scripts/org.sh). A user-account
adopter who copies config/org.env and changes only PROFILE_ORG inherits:

• MAIN_REPO = $OWNER/$OWNER → alice/alice. For a user, a repo whose name matches the
  login is GitHub's special profile-README repo — its README renders on the profile
  page (github.com/alice). So the suite's "hub" silently points at a cosmetic bio repo.
  (For an org, alice/alice is just an unusual repo; the org equivalent of that special
  repo is .github, not owner/owner.)
• SOURCE_REPO = $OWNER/automation → alice/automation, assuming they forked the whole
  suite into a repo literally named automation. This one is the most invisible: our own
  config/org.env never sets it, so it is always derived.
• REPOS_DIR = $HOME/$OWNER → $HOME/alice (least harmful; validate_repos_dir at least
  fails loud if the dir is missing).

None of the first two error out — they resolve to plausible-but-wrong values silently, the
same failure class we just tightened on the --repos flow in rossoctl/agent-skills#32.

Why raise it now

This is broader than any single PR, and it changes how we onboard someone who just wants
to maintain one repo (their own, or one they contribute to). It also has a concrete
precedent: rossoctl/agent-skills#32 just settled the --repos flow on within-a-single-owner
validation — which means a contributor maintaining one repo they do not own is already
out of scope there. Worth deciding whether the rest of the suite should match that boundary
or deliberately widen it.

Options I can see (not decisions — looking for input)

1. Re-document / rename ORG as OWNER. Keep the mechanism, make the naming honest,
   and document that a user login is a valid owner. Cheapest; leaves the org-shaped
   defaults as the remaining footgun.

2. Add a light ACCOUNT_TYPE (org | user). Changes only how defaults are derived
   (e.g. a user account does not default MAIN_REPO to $OWNER/$OWNER), not the core
   mechanism. More explicit onboarding for single-repo users.

3. Make defaults fail-loud instead of guessing. Drop the $ORG/$ORG-style derived
   defaults for the ambiguous fields and require the profile to set them explicitly, so a
   misconfigured single-repo profile errors rather than silently mis-targets.

(The three decisions are in the TL;DR. One extra: is there appetite to rename ORG →
OWNER suite-wide, or is the churn not worth it?)

Assisted-By: Claude Code

[jimcadden]

Org-scope didn't really work for us since we quickly had to restrict the agent to just a few "core" repos. Question, how is that implemented today? The solution could be as simple repo-list.txt which contains a list of URLs to target.

[rubambiza]

@jimcadden We do indeed have such a solution already under core-repos.txt that scopes it (and it's growing, see #63 for example). The discussion here is whether we want to support such repos that are owned by individuals vs orgs only (our current mode). Lots of trade-offs and gotcha to consider in The observation section above.

[jimcadden]

Ah, well the vein of keeping things simple, what if we supported both individuals and orgs, both via a list of repos in core-repos.txt. If the PAT doesn't have access to the given repo the job should fail gracefully. Am I thinking about this right?

[rubambiza]

🤔 Let me investigate and get back to you.

[rubambiza]

@jimcadden I did some digging with Rosso-concierge on DAM, and your instinct is right.

Two concrete blockers today:

• get_core_repos() unconditionally prepends **$ORG** to bare names, so alice/tool becomes rossoctl/alice/tool.
• normalize_repo_args() in report.py hard-exits on cross-owner entries, which was the agent-skills#32 fix.

Neither is fundamental, but both need the data model to carry {owner, name} per-repo instead of deriving the owner from a single global.

The deeper point your proposal surfaces is that ORG is doing two unrelated jobs today. It scopes which repos to act on, and it gets prepended to build every slug. If we move to full owner/repo slugs those separate cleanly, and gh -R alice/tool already works whether alice is a user or an org.

On graceful PAT failure, agreed. This connects to automation#39 as well. Capability checks should be scoped to what each program actually needs and surfaced before anything runs rather than failing mid-run.

One related thing worth noting: SOURCE_REPO (the attribution link in PR bodies) should become skill-native metadata rather than a suite-level config variable. Each skill knows its own canonical source and version. On DAM that version is a git commit SHA tracked at install time, so a PR body can say "generated by link-health-scanner@85449beb" with a pinned link rather than a blob/main pointer. That's a stronger audit trail and it stays accurate when skills are updated independently.

This direction makes the original three options moot since they were all premised on a global ORG. I am sketching concrete architectural changes while we align as a group.