feat(config): add review.shared_config operator base-manifest overlay (#2046)

[claytonlin1110]

Summary

• Adds review.shared_config support for self-host operators: the container-private shared base at GITTENSORY_REPO_CONFIG_DIR/_shared/.gittensory.yml overlays per-repo review: config field-by-field (repo wins when set; shared fills gaps; absent shared base stays byte-identical).
• Introduces parsed overlayReviewConfig merge logic and runtime review.sharedConfigSource provenance on the loaded manifest; malformed shared bases warn and are ignored without blocking review.
• Documents overlay precedence and private-config placement in .gittensory.yml.example and config/examples/README.md.

Closes #2046

Scope

• The PR title follows type(scope): short summary Conventional Commit format, for example fix(api): restore profile access checks.
• This PR is focused and does not mix unrelated backend, UI, MCP, docs, dependency, and deploy changes.
• This follows CONTRIBUTING.md and does not reintroduce GitHub Pages, VitePress, site/, or CNAME.
• I linked a currently open issue this PR resolves (e.g. Closes #123) — a linked open issue is required for every contributor PR.

Validation

• git diff --check
• npm run actionlint — not run locally; no workflow files changed; CI will confirm.
• npm run typecheck
• npm run test:coverage locally on affected suites (test/unit/private-config.test.ts, test/unit/focus-manifest.test.ts, test/unit/focus-manifest-loader.test.ts, test/unit/selfhost-config-examples.test.ts) with coverage scoped to changed src/** files (97%+ statements/branches on the diff). Full unsharded npm run test:coverage hit unrelated Windows-environment failures in self-host shell script tests; CI Linux runners will run the complete gate.
• npm run test:workers — not run locally; no Workers-runtime code touched.
• npm run build:mcp — not run locally; no MCP package changes.
• npm run test:mcp-pack — not run locally; no MCP package changes.
• npm run ui:openapi:check — not applicable; no API/OpenAPI schema changes.
• npm run ui:lint — not applicable; no UI source changes.
• npm run ui:typecheck — not applicable; no UI source changes.
• npm run ui:build — not applicable; no UI source changes.
• npm audit --audit-level=moderate — not run locally; no dependency changes.
• New or changed behavior has unit/integration tests for new branches, fallback paths, and sanitizer boundaries

If any required check was skipped, explain why:

• Skipped UI/MCP/Workers/audit checks because this PR only touches manifest parsing, private-config loading, tests, and docs — CI will run the full gate on Linux.

Safety

• No secrets, wallet details, hotkeys, coldkeys, user PATs, private keys, raw trust scores, private rankings, or private maintainer evidence are exposed.
• Public GitHub text stays sanitized, low-noise, and does not imply compensation guarantees or optimization tactics.
• Auth, cookie, CORS, GitHub App, Cloudflare, or session changes include negative-path tests. — not applicable; no auth/session surface touched.
• API/OpenAPI/MCP behavior is updated and tested where needed. — not applicable.
• UI changes use live API data or real empty/error/loading states, not production mock/demo fallbacks. — not applicable.
• Visible UI changes include a UI Evidence section below with JPG/JPEG or PNG screenshots arranged as organized, captioned, clickable thumbnails. — not applicable; no visible UI change.
• Public docs/changelogs are updated where needed; changelogs are only edited for release-prep PRs.

UI Evidence

Not applicable — backend/docs-only change.

Notes

• Builds on the existing _shared/.gittensory.yml private-config layer from feat(review): review.shared_config — operator-level base manifest overlay #1959; this slice adds parsed review overlay helpers, sharedConfigSource provenance, malformed-shared warnings, and maintainer docs for review.shared_config.

[superagent-security]

Superagent didn't find any vulnerabilities or security issues in this PR.

[loopover-orb]

Caution

🟥🟥🟥🟥🟥🟥🟥🟥🟥🟥🟥🟥

🛑 Gittensory review result - reject/close recommended

_{Review updated: 2026-07-07 09:37:23 UTC}

11 files · 1 AI reviewer · 1 blocker · readiness 100/100 · CI pending · unknown

🛑 Suggested Action - Reject/Close

• AI reviewers agree on a likely critical defect: `overlayReviewConfig`/`parseReviewConfigMapping`/`computeReviewConfigPresent` in packages/gittensory-engine/src/focus-manifest.ts (~2018-2170) are exported and unit-tested directly in test/unit/focus-manifest.test.ts, but `src/selfhost/private-config.ts`'s `combineConfigLayersWithMeta` never calls them — it merges the shared/global/repo `review:` blocks with the pre-existing untyped `mergeConfigOverlay` instead, so this new typed overlay is dead code on the actual load path despite the PR description presenting it as the overlay mechanism (description≠diff). — Resolve the flagged defect, or override if the AI reviewers are mistaken, then re-run the gate.

Review summary
This PR adds a container-private shared-base overlay for `review:` config with runtime provenance (`review.sharedConfigSource`), threading a new `LocalManifestLoadResult` shape through `private-config.ts` and `focus-manifest-loader.ts`, and it introduces a parallel typed overlay function (`overlayReviewConfig`/`parseReviewConfigMapping`) in `focus-manifest.ts`. The provenance plumbing itself is correctly wired: `combineConfigLayersWithMeta` in `src/selfhost/private-config.ts` folds the shared review block via the pre-existing raw-JSON `mergeConfigOverlay`, then re-parses the merged text so `sharedConfigSource`/warnings flow through faithfully, and the malformed-shared-base-warns-without-blocking path is tested end to end. However, the newly-added ~150-line `overlayReviewConfig` typed merge in `focus-manifest.ts:2018+` — which the PR description frames as the actual overlay mechanism — is never called from the real load path; production merging still goes through the old untyped `mergeConfigOverlay` at the raw-mapping layer, so the new function is exercised only by its own direct unit tests, not the pipeline that actually serves shared-config to a repo.

Blockers

• `overlayReviewConfig`/`parseReviewConfigMapping`/`computeReviewConfigPresent` in packages/gittensory-engine/src/focus-manifest.ts (~2018-2170) are exported and unit-tested directly in test/unit/focus-manifest.test.ts, but `src/selfhost/private-config.ts`'s `combineConfigLayersWithMeta` never calls them — it merges the shared/global/repo `review:` blocks with the pre-existing untyped `mergeConfigOverlay` instead, so this new typed overlay is dead code on the actual load path despite the PR description presenting it as the overlay mechanism (description≠diff).

Nits — 5 non-blocking

• private-config.ts:combineConfigLayersWithMeta parses the shared layer's text twice — once via `parseConfigMapping(sharedLayer.text)` to check for the malformed-warning, and again inside the `parsedLayers` loop — consider reusing the first parse result.
• focus-manifest-loader.ts's `content = content.content` branch (handling a fetcher returning `LocalManifestLoadResult`) has no test exercising the non-local `fetcher` path returning an object; only `setLocalManifestReader` is exercised in the new tests.
• `RepoFocusManifestFetcher`'s type was widened to `Promise<string | LocalManifestLoadResult | null>` even though only the local/self-host reader ever returns the object shape — consider a narrower type for the public GitHub fetcher to avoid every caller needing the `typeof content === "object"` check.
• `.gittensory.yml.example`'s new comment block documents `review.sharedConfigSource` as a runtime-only field, but doesn't call out that there is no actual `review.shared_config` YAML key — worth an explicit one-line clarification to avoid contributors trying to set it directly.
• Either wire `overlayReviewConfig` into `combineConfigLayersWithMeta` as the actual merge for the `review:` sub-block (replacing the generic `mergeConfigOverlay` call for that key), or drop the new typed-overlay function and its dedicated tests if the raw-JSON merge is intentionally the long-term mechanism — shipping both is confusing for the next contributor who has to figure out which one is authoritative.

Why this is blocked

• `overlayReviewConfig`/`parseReviewConfigMapping`/`computeReviewConfigPresent` in packages/gittensory-engine/src/focus-manifest.ts (~2018-2170) are exported and unit-tested directly in test/unit/focus-manifest.test.ts, but `src/selfhost/private-config.ts`'s `combineConfigLayersWithMeta` never calls them — it merges the shared/global/repo `review:` blocks with the pre-existing untyped `mergeConfigOverlay` instead, so this new typed overlay is dead code on the actual load path despite the PR description presenting it as the overlay mechanism (description≠diff).

Signal	Result	Evidence
Code review	❌ 1 blocker	1 reviewer
Linked issue	✅ Linked	#2046, #123
Related work	✅ No active overlap found	No same-issue or scoped active PR overlap found.
Change scope	✅ 20/20	Low review scope from cached public metadata (2 linked issues).
Validation posture	✅ 25/25	PR body includes validation/test evidence.
Contributor workload	✅ 10/10	Author activity: 437 registered-repo PR(s), 299 merged, 102 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	claytonlin1110; Gittensor profile; 437 PR(s), 102 issue(s).
Gate result	❌ Blocking	Repo-configured hard blocker found.

Review context

• Author: claytonlin1110
• Role context: outside_contributor
• Public audience mode: oss maintainer
• Lane context: Repository is configured for direct PR review.
• Public profile languages: Python, JavaScript, TypeScript, Rust
• Official Gittensor activity: 437 PR(s), 102 issue(s).
• PR-specific overlap: none found.

Contributor next steps

• Keep the PR focused and include validation evidence before maintainer review.

Signal definitions

• Related work = same linked issue, overlapping active PRs, or title/path similarity.
• Change scope = cached public metadata such as size labels, draft state, and review-burden hints.
• Validation posture = whether the PR provides enough public validation/test evidence for maintainer review.
• Contributor workload = public contributor activity and cleanup pressure, not a repo-wide quality failure.
• Contributor context = public GitHub/Gittensor identity context; non-Gittensor status is not a blocker.

_{🟩 Safe / merged · 🟦 Advisory · 🟨 Held for review · 🟥 Blocked / closed}

---

💰 Earn for open-source contributions like this. Gittensor lets GitHub contributors earn for the work they already do — register to start earning →.

Checked by Gittensory, a quiet PR intelligence layer for OSS maintainers.

• Re-run Gittensory review

[JSONbored]

Hold off on opening further PRs for maybe 30m while i fix main, some issues leaked into main that are causing failing CI.

[codecov]

❌ 5 Tests Failed:

Tests completed	Failed	Passed	Skipped
11144	5	11139	7

View the top 1 failed test(s) by shortest run time

test/unit/config-templates.test.ts > config/examples review templates (#1682) > gittensory.full.yml body matches .gittensory.yml.example from WHERE IT LIVES onward

Stack Traces | 0.0238s run time

AssertionError: expected '# WHERE IT LIVES (first match wins):\…' to be '# WHERE IT LIVES (first match wins):\…' // Object.is equality

- Expected
+ Received

@@ -326,17 +326,10 @@
  # All values shown are the safe defaults; delete any line to inherit it.
  #
  # Review output controls. These tune review output without changing the
  # deterministic gate policy above. Omit the block to keep the byte-identical
  # defaults.
- #
- # SELF-HOST ONLY (`review.shared_config`, #2046): when `GITTENSORY_REPO_CONFIG_DIR` is mounted,
- # place a shared review base at `${GITTENSORY_REPO_CONFIG_DIR}/_shared/.gittensory.yml` (see
- # `config/examples/shared.gittensory.yml`). Per-repo `review:` keys overlay it field-by-field —
- # repo value wins when set, shared fills gaps, defaults stay byte-identical. Absent shared base is
- # the common case and changes nothing. A malformed shared base warns and is ignored (never blocks a
- # review). The loader records provenance at runtime in `review.sharedConfigSource` (not a YAML key).
  review:
    # Deterministic AI review eligibility filters (`review.auto_review`, #1954 / #2038–#2065). Each knob quietly
    # skips the advisory AI review for matching PRs — never a gate failure. When the Orb review check is enabled,
    # skipped PRs complete as "skipped" with a human-readable reason (see `evaluateAutoReviewSkipReason` in
    # `src/signals/focus-manifest.ts` and the public-surface `SKIP_SUMMARY.ignored_author` mapping in

 ❯ test/unit/config-templates.test.ts:36:57

View the full list of 4 ❄️ flaky test(s)

test/unit/moderation-config-db.test.ts > global moderation config DB round-trip (#selfhost-mod-engine) > REGRESSION (gate-flagged): violationDecayDays above MAX_MODERATION_VIOLATION_DECAY_DAYS is CLAMPED, not passed through raw -- an unbounded value overflows Date arithmetic on the live close path

Flake rate in main: 100.00% (Passed 0 times, Failed 1 times)

Stack Traces | 0.383s run time

AssertionError: expected 100 to be 3650 // Object.is equality

- Expected
+ Received

- 3650
+ 100

 ❯ test/unit/moderation-config-db.test.ts:91:41

test/unit/moderation-config-db.test.ts > global moderation config DB round-trip (#selfhost-mod-engine) > a raw DB row with an over-max violation_decay_days is also clamped on READ (not just on write)

Flake rate in main: 100.00% (Passed 0 times, Failed 1 times)

Stack Traces | 0.374s run time

AssertionError: expected 100 to be 3650 // Object.is equality

- Expected
+ Received

- 3650
+ 100

 ❯ test/unit/moderation-config-db.test.ts:108:41

test/unit/moderation-config-db.test.ts > global moderation config DB round-trip (#selfhost-mod-engine) > a violationDecayDays AT the max is preserved unclamped (boundary, not just strictly-under)

Flake rate in main: 100.00% (Passed 0 times, Failed 1 times)

Stack Traces | 0.374s run time

AssertionError: expected 100 to be 3650 // Object.is equality

- Expected
+ Received

- 3650
+ 100

 ❯ test/unit/moderation-config-db.test.ts:101:41

test/unit/queue.test.ts > queue processors > a #1960 action-command verb with no dispatch handler wired yet (e.g. pause) is bailed out of the Q&A answer-card path, not misrendered as help (#2160)

Flake rate in main: 100.00% (Passed 0 times, Failed 1 times)

Stack Traces | 0.916s run time

AssertionError: expected 1 to be +0 // Object.is equality

- Expected
+ Received

- 0
+ 1

 ❯ test/unit/queue.test.ts:22807:28

To view more test analytics, go to the Test Analytics Dashboard
_{📋 Got 3 mins? Take this short survey to help us improve Test Analytics.}