Roadmap: self-hosted review-stack enhancements (gittensory orb)

[JSONbored]

Summary

ORB = One-shot Review Brain. The self-hosted maintainer review engine already goes by "orb" everywhere (the check-run is "Gittensory Orb Review Agent," releases tag orb-v*) — this formalizes it as a backronym: it renders a one-shot merge-or-close verdict with no back-and-forth, and it's the shared "Brain" the Autonomous Miner System's own roadmap already describes reusing (~80% of the miner's brain = this engine).

A multi-phase roadmap to deepen ORB: better review output, richer analysis depth, an interactive control surface, real maintainer analytics, and self-host-native differentiators. This epic is the umbrella for a wave of focused, config-driven improvements — each child issue is an independently shippable unit of work.

Scope: gittensory is purely self-hosted. Every item targets the self-hosted orb engine (Docker) and its operator/maintainer. No central or managed service is assumed; where cross-instance features appear they are strictly opt-in and operator-controlled.

Guiding principles (apply to every child issue)

• Modular & config-driven — every behavior is toggled per repo via .gittensory.yml (review.* / gate.* / settings.* / features:), never hard-coded for one repo. Follow the FocusManifestReviewConfig wiring pattern in src/signals/focus-manifest.ts.
• Default-OFF & byte-identical when off — a new knob left unset means the engine behaves exactly as it does today.
• Fail-safe — any new path degrades gracefully and never affects the gate on error.
• Precision-first — additions must reduce noise, not add it. Prefer deterministic signals; gate AI additions behind confidence/verification.
• Deterministic-first — prefer pure, groundable computation over AI where possible.
• Respect the one-shot gate — nothing turns the auto-merge/auto-close disposition into an advisory back-and-forth.
• Respect the contributor boundary — no contributor source upload and no contributor-supplied AI keys; contributor-side actions run on the contributor's own machine/agent via the local-write-action-spec pattern (src/mcp/local-write-tools.ts).

Baseline (already shipped — build on, don't rebuild)

Auto-merge/auto-close gate with measured precision + circuit-breakers (src/rules/advisory.ts, src/review/auto-tune.ts); config-as-code (review.profile/path_instructions/instructions/exclude_paths/pre_merge_checks, src/signals/focus-manifest.ts); inline review comments (src/review/inline-comments.ts); grounding — CI truth + full-file context (src/review/grounding-wire.ts); codebase RAG (src/review/rag.ts); the review-enrichment service (review-enrichment/); deterministic slop scoring (src/signals/slop.ts); the outcomes/accuracy ledger (review_audit + src/review/parity.ts + src/review/ops.ts); and the self-host MCP + CLI (src/mcp/, packages/gittensory-mcp).

Phases & child issues

Phase 1 — Review output, noise & trust (deterministic, small PRs)

• Auto-review eligibility filters (skip drafts, bot authors, WIP titles, base-branch scope, auto-pause) #1954 — Auto-review eligibility filters (skip drafts, bot authors, WIP titles, base-branch scope, auto-pause)
• Deterministic review-effort / complexity score + review-time ROI signal #1955 — Deterministic review-effort / complexity score + review-time ROI signal
• One-click suggested-change blocks on inline review comments #1956 — One-click suggested-change blocks on inline review comments
• Changed-files summary table in the unified review comment #1957 — Changed-files summary table in the unified review comment
• Finding category taxonomy on AI review findings #1958 — Finding category taxonomy on AI review findings
• feat(review): review.shared_config — operator-level base manifest overlay #1959 — Config-as-code parity fills (path filters, tone, labeling rules, shared config)

Phase 1b — Content-lane genericity (make the registry-review engine usable by any self-hosted registry, not just our own)

• refactor(content-lane): stop naming/exporting metagraphed-specific symbols as if they're generic #2433 — Stop naming/exporting metagraphed-specific symbols as if they're generic
• refactor(content-lane): inject registry validators via RegistryLaneSpec instead of hardcoded imports #2434 — Inject registry validators via RegistryLaneSpec instead of hardcoded imports (blocked by refactor(content-lane): stop naming/exporting metagraphed-specific symbols as if they're generic #2433)
• feat(content-lane): resolve RegistryLaneSpec per-repo from .gittensory.yml config #2435 — Resolve RegistryLaneSpec per-repo from .gittensory.yml config (blocked by refactor(content-lane): inject registry validators via RegistryLaneSpec instead of hardcoded imports #2434)

Phase 2 — Interactive control & issue intelligence

• PR command surface — @gittensory review / pause / resume / resolve / help / configuration / explain #1960 — PR command surface (@gittensory review / pause / resume / resolve / help / configuration / explain)
• AI linked-issue satisfaction assessment #1961 — AI linked-issue satisfaction assessment
• Agent fix-handoff blocks + follow-up-issue suggestions #1962 — Agent fix-handoff blocks + follow-up-issue suggestions
• Maintainer review recap digest (Discord / Slack) #1963 — Maintainer review recap digest (Discord / Slack)
• Review memory — repeat false-positive suppression #1964 — Review memory (repeat false-positive suppression)

Phase 3 — Analysis depth, analytics & developer experience

• REES depth — the config-driven linters/SAST tool-runner (was Review tool-runner — config-driven linters / SAST as grounded review inputs #1965) and custom AST-grep rules (was Custom AST-grep deterministic rule layer #1966) — is consolidated into the established REES epic epic(enrichment): REES modular analyzer runtime roadmap #1499.
• Maintainer analytics dashboard (gate precision, calibration, acceptance rate) #1967 — Maintainer analytics dashboard (gate precision, calibration, acceptance rate)
• Local pre-PR review via the contributor's own agent #1968 — Local pre-PR review via the contributor's own agent

Phase 4 — Self-host-native differentiators

• Plagiarism / copycat detection #1969 — Plagiarism / copycat detection
• Opt-in federated fleet intelligence across self-hosted instances #1970 — Opt-in federated fleet intelligence across self-hosted instances
• Deterministic architecture / impact map #1971 — Deterministic architecture / impact map
• Boundary-safe test generation #1972 — Boundary-safe test generation
• feat(review): infer a cached per-repo quality-culture profile as AI-review grounding context #2995 — Infer a cached per-repo quality-culture profile as AI-review grounding context
• fix(review): reconcile AI verdicts against hard structured state before rendering #2996 — Reconcile AI verdicts against hard structured state before rendering
• fix(review): add order-swapped stability check to the dual-AI tie-break pass #2997 — Order-swapped stability check on the dual-AI tie-break pass
• test(review): add adversarial prompt-injection regression fixtures for the AI reviewer #2998 — Adversarial prompt-injection regression fixtures for the AI reviewer

Phase 5 — Repo-doc generation

• Roadmap: repo-specific CLAUDE.md/AGENT.md + skills generation & maintenance #2993 — Roadmap: repo-specific CLAUDE.md/AGENT.md + skills generation & maintenance (own sub-epic, 6 children: feat(review): extract a codebase-grounded repo profile from RAG + signals #2999-fix(review): make repo-doc refresh diff-aware and preserve manual edits #3004)

Phase 6 — Keep the docs site from drifting

• feat(ci): add a docs-drift check for GITTENSORY_REVIEW_* flags, @gittensory commands, and gate-mode dimensions #3047 — feat(ci): add a docs-drift check for GITTENSORY_REVIEW_* flags, @gittensory commands, and gate-mode dimensions
• feat(ci): verify docs JSON examples against their real Zod schemas #3045 — feat(ci): verify docs JSON examples against their real Zod schemas
• feat(docs): generate the @gittensory command reference from src/github/commands.ts instead of hand-copying #3046 — feat(docs): generate the @gittensory command reference from src/github/commands.ts instead of hand-copying
• feat(selfhost): scheduled docs-drift audit sweep for claims the mechanical lint can't check #3048 — feat(selfhost): scheduled docs-drift audit sweep for claims the mechanical lint can't check

Out of scope / explicitly avoid

• Any feature that requires a central or managed service; contributor AI-key BYOK; contributor source upload.
• Noise for its own sake (verbose nitpicking, decorative comment flourishes).
• Diff-only reasoning regressions — invest in grounding/RAG/enrichment depth, not verbosity.
• Third-party tracker integrations unless an operator explicitly requests one.

Sequencing

Ship Phase 1 first (deterministic, low risk, immediate noise/trust wins), then Phase 1b (content-lane genericity — small, sequential, each blocked by the last), then Phase 2 (control + issue intelligence), then Phase 3 (the marquee depth + analytics work), then Phase 4 (the differentiators). Each item ships as its own small, green, config-driven PR.

[linear-code]

JSO-2033