docs(governance): add contributor onboarding process (#1565)

[MerlinTheWhiz]

PR Description

docs(governance): add contributor onboarding process

closes #1565

Summary

Adds Governance/processes/ONBOARDING.md, closing a governance gap: the
Governance/ folder documented the offboarding half of the contributor
lifecycle but had no onboarding counterpart, so contributors and maintainers
lacked a versioned reference for how a new contributor is brought into the
project.

The new document defines who owns onboarding, the phased onboarding
steps, and the resources a new contributor receives, and records why
regression tests are not applicable to this change. It is linked from the
Governance README process index alongside the existing offboarding entry.

Background

Governance/processes/OFFBOARDING.md defines access revocation and knowledge
handover for a departing contributor, but nothing defines the entry path. The
consequences:

• A new contributor cannot find, in one place, the prerequisites, setup steps,
  and quality gates needed to open a first pull request.
• Ownership of onboarding is undefined, so a stalled onboarding is invisible
  rather than surfacing as an escalation.
• Governance/README.md already advertises an "onboarding/offboarding
  lifecycle" under Roles & membership, but the Processes index linked only the
  offboarding document — the promise was not kept.

Related existing documents this deliberately does not duplicate:
CONTRIBUTING.md (authoritative for branch strategy, commits, PR requirements,
review SLA, and CI), policies/FIRST_TIME_CONTRIBUTOR.md (support and
mentorship expectations), and roles/CONTRIBUTOR.md (the role reached by a
merged PR).

What the document covers

Requirement from #1565	Where	Substance
Who owns onboarding	§3 Ownership	Maintainer team owns the process. A buddy is assigned from the maintainer/reviewer pool per issue. Buddy is support, not authority — only an authorised maintainer approves and merges. Declining a buddy is allowed and must not affect review priority. Escalation point is the lead maintainer.
Onboarding steps	§4 Onboarding Steps	Four phases: 0 orientation (read CONTRIBUTING.md §1–3/§8, Code of Conduct, communication norms, enable 2FA, claim a reserved issue) → 1 local environment (prerequisites, npm ci, .env from .env.example, PostgreSQL/Redis, migrations, four quality gates) → 2 first contribution (branch from develop, Conventional Commits, PR requirements, testing standards) → 3 after the first merge (contributor status, recognition, promotion is separate and never automatic).
Resources a new contributor receives	§5 Resources Provided	16-row table mapping each resource to its location and purpose — CONTRIBUTING.md, docs/setup.md, .env.example, docs/testing-standards.md, openapi-spec.json, docs/api/, README architecture sections, docs/RUNBOOKS.md, docs/troubleshooting.md, CODEOWNERS as documented in §9, and seven governance documents. States explicitly that onboarding grants no additional access or credentials.
Regression tests	§7 Regression Tests Where Applicable	Not applicable, with justification (see Verification). Also records the four checks that are verifiable, in place of tests.
Document the change	§8 Documenting Changes + changelog	Amendment route (PR confined to Governance/, ≤2 files), substantive changes under ASYNC_DECISIONS, recording in DECISION_LOG.md, plus a 1.0.0 · 2026-09-30 change-log row.

Also included: §1 Purpose, §2 Scope (with explicit exclusions for privileged
and production access, deferred to domains/ACCESS_CONTROL.md §3), §6
Expected Timelines (labelled community norms, not SLAs), §9 Related Documents.

Regression tests

Not applicable — documentation-only change. The PR adds Markdown and
modifies no TypeScript, configuration, schema, or dependency. Governance/ is
outside the Jest root (jest.config.js sets rootDir: 'src'), outside the
TypeScript build (tsconfig.build.json includes src/**/*), and excluded from
container images by the *.md rule in .dockerignore.

No test asserting on the prose of a process document was added: such a test
would have no value and would become maintenance debt. No other document in
Governance/ has one either. What must hold is that the existing suites keep
passing, which is verified below.

Verification performed

Static checks on the new document

• 93 relative links across both changed files were resolved against the
  filesystem — 0 missing.
• All 10 CONTRIBUTING.md section references (§1, §2, §3, §5, §7, §8, §9,
  §10, §11, §13) were checked against the current file and the titles match.
• All 4 quality-gate commands named in Phase 1 were confirmed to exist in
  package.json scripts.
• The 5 prerequisite versions in Phase 1 were compared against the table in
  CONTRIBUTING.md §5 — identical.

Quality gates (run against the branch, exit code 0)

Gate	Result
npm run format:check	pass
npm run typecheck	pass
npm run lint:ci	pass

Test suite — no regression

npx jest was run on this branch and on a pristine HEAD checkout in the same
environment, and the set of failing suites is byte-identical between the
two. No suite fails on this branch that did not already fail at HEAD.

Two caveats a reviewer should know:

1. The suite is currently red for reasons unrelated to this PR. 22 of 221
   suites fail on both HEAD and this branch, with errors such as
   SyntaxError: Unexpected token 'export' from jwks-rsa. The total varies by
   one suite between runs, which indicates pre-existing flakiness.
2. Dependencies could not be installed cleanly. npm ci fails
   (Missing: multer@2.1.1 from lock file) and
   pnpm install --frozen-lockfile fails (overrides config mismatch). Gates
   were therefore run in a throwaway copy outside the working tree, installed
   with --no-frozen-lockfile. That forced a different transitive dependency
   resolution (notably jwks-rsa 3.x → 4.0.1, an ESM-only release) which is the
   likely cause of the failures above. CI, which installs the intended
   dependency tree, may well be green where this environment is not.

Neither lockfile was modified, since doing so would breach the two-file scope.

Acceptance criteria

• Governance requirement implemented — Governance/processes/ONBOARDING.md created with steps, resources, and ownership defined.
• Scope limited to a maximum of two files — exactly 2 (git show --stat: 2 files, 287 insertions, 0 deletions).
• No changes outside the Governance folder — both paths are under Governance/.
• No regression in existing functionality — failing-suite set identical to HEAD; no .ts file touched.
• Tests pass and code follows project standards — format:check, typecheck, lint:ci all exit 0.
• Change is documented — §8 Documenting Changes, the document's own change-log row, plus a new row in the Governance README change-log table.

Files changed

• Governance/processes/ONBOARDING.md (new — 283 lines)
• Governance/README.md (modified — +4 lines: process index entry and change-log row)

The Governance/README.md diff is purely additive (4 insertions, 0 deletions),
and the new document is Prettier-clean so the commit hook will not rewrite it.

Breaking API changes

None. Documentation only; no runtime, schema, or interface change.

Observations for maintainers (not addressed here)

Found while following the contribution process. Each would breach the
two-file scope, so they are raised rather than fixed:

1. There is no develop branch. CONTRIBUTING.md §3 says all non-hotfix
   PRs target develop, but only main exists locally and on origin, and all
   recent governance PRs were merged into main. This PR therefore targets
   main.
2. Both lockfiles are out of sync with package.json — npm ci and
   pnpm install --frozen-lockfile both fail out of the box.
3. governance is not a documented commit scope. CONTRIBUTING.md §7 lists
   module names only, yet roughly 15 recent commits use
   docs(governance): ….
4. commitlint is not enforced. commitlint.config.cjs exists but there is
   no .husky directory and no commit-msg hook, and lint-staged.config.js
   runs only Prettier and ESLint. The §7 rules are currently self-enforced.
5. Documented branch naming is not followed in practice. CONTRIBUTING.md
   §3 specifies <prefix>/issue-<N>-<slug>, but recent branches use
   docs/1584-meeting-cadence, governance/add-credits-policy, and similar.
   This PR follows the documented form.

Checklist

• Linked issue (#1565, Closes #1565 in the commit message)
• Branch follows CONTRIBUTING.md §3 — chore/issue-1565-contributor-onboarding
• Commit follows CONTRIBUTING.md §7 — docs(governance): …, 60 chars, imperative, issue number in parentheses
• PR description complete
• Two maintainer approvals expected before merge (CONTRIBUTING.md §4 and §9)

[drips-wave]

@MerlinTheWhiz Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

[RUKAYAT-CODER]

Thank you for contributing to the project.