docs: Add org portability design spec

[rubambiza]

Summary

Adds the design spec for the org portability refactor — a single source of org truth so the
scanner/fixer suite can be pointed at any org by touching one file, with the rossoctl rename
(Phase 6) as the first consumer.

Docs-only. Committed to docs/specs/ for traceability of major design decisions.

Design in brief

• One committed profile file (config/org.env) + a program-lib.sh loader that resolves
  ORG, FORK_OWNER, MAIN_REPO, REPOS_DIR by precedence (--flag > env > profile > default).
• All scripts derive repo refs, fork targets, clone paths, and dashboard PR targets from those
  vars — no script carries an org literal.
• config/core-repos.txt becomes bare names (owner derived from $ORG); one shared list.
• Fork name = canonical name (Option B): FORK_OWNER/<canonical>, one-time rename of
  clawgenti/kagenti → clawgenti/rossoctl.
• Transitional REMAP (clone-dir basename → canonical) lives in the profile and self-retires
  once host dirs are renamed (chore: Rename clone dirs to canonical names and retire the remap shim #37).

Rollout

Staged to protect the live report/dashboard write paths: fork rename (with a precondition to drain
the open fork→main report PRs first) → add the seam with zero behavior change → rewire scripts
(this is Phase 6, Fixes #30, closes #31) → dry-run parity + controlled live run → deploy.

Scope

This PR is the spec only; implementation lands in follow-up PRs (natural boundary: seam vs. rewire).

Related: epic #32, #35, #37, #39.

Assisted-By: Claude Code

[clawgenti]

Docs-only spec for the org portability refactor. The design is thorough: the four-fact identity model is well-decomposed, the precedence chain (flag > env > profile > default) is clear, and the staged rollout correctly sequences the fork rename before the script rewire to avoid broken write targets. All checks pass. Ready for human review.

---

Reviewed by clawgenti using github:pr-review

[cwiklik]

Strong, thorough design spec. The problem statement accurately captures the half-migrated ORG= inconsistency (scanner on rossoctl, fixer/dashboard on kagenti, literals bypassing $ORG), the identity model + precedence rule are clean, and the Step-0 fork-rename ordering analysis (drain report PRs → rename → deploy Step-2 scripts, minimizing the 404 window) is careful and correct. Coherent with the #38 allowlist work.

Two non-blocking design-refinement notes inline — worth nailing during implementation, but nothing blocks recording the spec:

1. The PROFILE_* capture mechanism is under-specified and precedence correctness hinges on it (sourcing a profile with literal ORG= would clobber env before resolution).
2. REPOS_DIR/REMAP lack the --flag tier the universal precedence statement implies — clarify if intentional.

Docs-only, DCO green, both commits signed, no .claude/.vscode. LGTM.

Assisted-By: Claude Code