Phase Hosted governance dashboard — Thinking freeze
Status: Reviewed → pass (HGD-r3). Hosted governance dashboard Thinking is spec-only and
now frozen; no dashboard server, no fetch client, no static UI, and no new CLI command land in this
phase. The Hosted governance dashboard Auto build ({step}b) is cleared to start mechanically
against this frozen contract; it is the only phase that writes hosted-dashboard runtime files. Do
not re-derive this contract during the Auto build. Do not merge scopes with Track Q
(docs/archive/phases/PHASE-TRACK-Q-Q0-OVERSEER-APP.md).
phase: HOSTED-GOV-DASH
outputs:
- id: hosted-governance-dashboard
path: docs/archive/phases/PHASE-HOSTED-GOVERNANCE-DASHBOARD.md
frozen: true
frozen_inputs:
- id: kit-spec-cli
path: docs/OVERSEER-KIT-SPEC.md#5
- id: freeze-ceremony
path: docs/OVERSEER-KIT-SPEC.md#6
- id: kit-boundary
path: AGENTS.md
- id: k7-musehub-optional
path: docs/archive/phases/PHASE-K7-MUSE-GIT-MIRROR-DOGFOOD.md
- id: track-q-q0-local-contrast
path: docs/archive/phases/PHASE-TRACK-Q-Q0-OVERSEER-APP.md
- id: kh1-handover
path: docs/archive/phases/PHASE-KH1-HANDOVER-RELAY-STANDARD.md
- id: p-deploy-boundary
path: docs/archive/phases/PHASE-TRACK-P-P-DEPLOY.md
- id: test-tiers
path: policy/test-tiers.yaml
- id: decision-tiers
path: policy/tiers.yaml
- id: roadmap-exploration
path: docs/ROADMAP.md
review_stamp:
reviewed_at: '2026-07-14T00:27:51Z'
verdict: pass
reviewer_mode: agent
reviewer_model: thinking-high
reviewer_provider: local
kit_version: 0.1.0
artifact_digest: sha256:af8419e15e206dbbbcee006ea5d852b103b349f58529df044f7484db1a247f57
Downstream edge: the Hosted governance dashboard Auto build treats this document as ground
truth without re-deriving it (SPEC §6 mandatory reviewed freeze). Track Q (ok app local UI) is
not an input and must not be rewritten from this freeze. P-deploy / deploy-verification remain
claim-recording gates only — this dashboard never deploys and never probes production product URLs.
Review record (§6.2): every freeze-review finding MUST cite file+line per SPEC §6; uncited
findings are invalid and are discarded. Fixes applied during the loop are Tier 1 (feature branch);
merge to main is Tier 3 and is never part of this loop.
| Round | Reviewer | Verdict | Resolution |
|---|---|---|---|
| HGD-r1 | Freeze-review loop (checklist + thinking, thinking-high) |
findings | CLI checklist dry-run pass (0 findings). Semantic review raised non-escalating completeness/consistency findings below. No security/irreversible/real_money/gates_tier3 escalation. |
| HGD-r1 fix | Author (cited items only) | — | R1-M1 fixed: §HGD.5.5–§HGD.5.7 freeze response field contracts. R1-M2 fixed: §HGD.4.2 discovery bounded to configured orgs + allowlist element shape. R1-M3 fixed: §HGD.6.1 table + preview auth = Bearer from env/startup. R1-M4 fixed: §HGD.11 upstream auth → HTTP 502 + token. R1-N1 fixed: §HGD.0 viewer-vs-preview wording. R1-N2 fixed: default ref = github_meta default_branch. R1-N3 fixed: §HGD.6.5 public anonymous policy deferred/off in v1. |
| HGD-r2 | Freeze-review loop (checklist + thinking, thinking-high) |
findings | R1 items confirmed addressed on re-read. Residual: SSRF status dual-coded; upstream host allowlist not frozen; UI viewer-token bootstrap unspecified. No escalation categories. |
| HGD-r2 fix | Author (cited items only) | — | R2-M1 fixed: §HGD.6.6 default upstream host allowlist. R2-N1 fixed: SSRF → HTTP 403. R2-N2 fixed: §HGD.6.7 UI Bearer paste bootstrap. |
| HGD-r3 | Freeze-review loop (checklist + thinking, thinking-high) |
pass | CLI checklist gate clean (0 findings, dry-run). Semantic re-read confirmed R1/R2 items RESOLVED: response field contracts; bounded allowlist/discovery; Bearer viewer auth + UI bootstrap; upstream host allowlist; HTTP 502/403 tokens locked; Track Q separation + rejection table; K7 baseline; seven-tier matrix complete; no security/irreversible/real_money/gates_tier3 escalation. Stamp written by ok review --freeze. |
§HGD.0 — Simple summary
Operators already keep ROADMAP and HANDOVER honest in each repo. Sometimes they want to see an
org's governance at a glance in a browser — without opening a local working tree, and without
giving a remote UI power to change git or muse. The viewer of a deployed hosted instance does
not need a kit install; the optional ok hosted-dashboard CLI is operator preview/dogfood
only (§HGD.10).
This freeze defines a hosted, read-only governance dashboard: it reads roadmap, handover, and
gate-related signals from GitHub and optional MuseHub APIs (or documented equivalents), and shows
them. It never mutates remote history, never runs the local ok engine against a checkout, and
never becomes a product data store or CD system. Track Q stays the local act-capable UI; this
dashboard stays remote and read-only.
Technical summary: freeze product identity vs Track Q; closed remote read surface; document-
derived gate view plus optional advisory CI checks; read-only credential scopes; K7-compatible
capability tiers; rejection table; Auto deliverables under tools/hosted_dashboard/; seven-tier
matrix. Spec-only — no code in Thinking.
§HGD.1 — Scope
In scope (freeze only — this phase writes no code):
- Product identity and Track Q contrast (§HGD.2).
- What exists now / verified baseline (§HGD.3).
- Data plane: remote APIs only (§HGD.4).
- Closed read surface (HTTP + parse contracts) (§HGD.5).
- Auth + credential scope rules for hosted exposure (§HGD.6).
- Gate-status semantics (document-derived vs advisory) (§HGD.7).
- Boundary + capability tiers (§HGD.8).
- Rejection table (§HGD.9).
- Auto build deliverables (§HGD.10).
- Fail-closed / error behavior (§HGD.11).
- Seven-tier test matrix for Auto (§HGD.12).
- Hard stops + tier linkage (§HGD.13).
- Definitions of Done (§HGD.14).
Out of scope (explicit non-goals — prevent creep):
- Any local git / muse / filesystem mutation of consumer or kit working trees.
- Any Track Q rewrite — no change to
ok app, loopback bind policy, Bearer/CSRF local auth, or the Q0 closedapi/*act surface. - CD / deploy / live product health probes — unchanged from P-deploy: kit never deploys and never HTTP-probes production product URLs; this dashboard is not a deploy console.
- Hosting product domain data stores (user content, wallets, media, vault blobs, agent transcripts as a service of record). Kit remains governance presentation, never a product runtime or primary store.
- Model hosting, agent dispatch, OpenRouter, Cursor SDK, worker/checker runtime.
- Write-capable GitHub/MuseHub tokens or endpoints (PRs, merges, content updates, webhooks that mutate).
- Re-implementing KH2/KH3/substrate hard gates inside the hosted process as authoritative
truth (those gates run in a local working tree via
ok). - Tier-3 merge, staging push, or live capability flips authorized by this freeze.
- Multi-tenant SaaS billing / real-money metering inside the kit Auto build.
§HGD.2 — Product identity vs Track Q (frozen)
| Concern | Track Q — ok app |
Hosted governance dashboard |
|---|---|---|
| Where it runs | Operator machine; loopback process | Operator- or org-hosted web surface (non-loopback expected when deployed) |
| Data plane | Local filesystem + local VCS adapters via Python engine | GitHub / MuseHub read APIs (or documented equivalents) |
| Authority | CLI parity for scoped read and gated acts | Read-only presentation; no remote write authority |
| Typical user | Operator with a checkout | Operator / reviewer without a local install |
| Mutate living docs / freeze stamp | Yes (inert-first, CLI parity) | Never |
| Relationship | Local frontend of governance | Remote glance surface of governance |
Frozen one-liner: Hosted governance dashboard is a read-only remote viewer of published governance artifacts, never a second engine, never a Track Q port, never a product runtime.
Scope separation rule (frozen): Auto must not import Track Q HTTP handlers as the hosted
data path, and must not teach ok app to bind non-loopback “for hosting.” Distinct modules;
distinct auth; distinct bind/deploy story.
§HGD.3 — What exists now (verified, do not redesign)
| Element | Current shape | Source |
|---|---|---|
| Local UI | ok app loopback stdlib server + static UI; closed act+read api/* |
Track Q Q0–Q3 |
| Living docs | ROADMAP + HANDOVER paths from .overseer/config.yaml |
KH1, K8 |
| Gate reminders | Pending-gates surfaces on ok status / governance-sync |
KH1b |
| Hard gates | Muse-sync + footprint self-integrity refuse certain CLI paths | KH2, KH3 |
| Public web today | Landing + scenario gallery only | K12 |
| Remote governance viewer | None | Exploration backlog row (this freeze) |
| Kit boundary | Repo-agnostic governance; not a product runtime | AGENTS.md |
| Deploy claims | Ledger/gate only; never deploy/probe | P-deploy |
This Thinking phase adds no runtime. Auto later adds a hosted read path without changing
existing ok app or CLI gate semantics.
§HGD.4 — Data plane (frozen)
§HGD.4.1 — Allowed sources (closed vocabulary)
| Source id | Role | Baseline? |
|---|---|---|
github_contents |
Read file bytes for living docs / marker files via GitHub Contents (or raw-content) API | Yes — baseline |
github_meta |
Read repo metadata needed for org/repo listing (name, default branch, visibility the token may see) | Yes — baseline |
github_checks_advisory |
Optional commit/check-run summaries labeled advisory only | Optional |
musehub_read |
Optional MuseHub (or Muse bridge) read API for canonical Muse-side doc bytes when configured | Optional deepen — never sole baseline (K7) |
No other source ids in Auto v1. Adding a source requires a later Thinking freeze.
§HGD.4.2 — Repo eligibility (frozen)
Allowlist element shape (frozen): each org_allowlist entry is a string owner/repo
matching ^[A-Za-z0-9._-]+/[A-Za-z0-9._-]+$. Org-only entries (owner without /repo) mean:
enumerate repositories visible to the credential under that owner, then apply the marker filter
below. Enumeration is capped at a documented bound (Auto MUST pick and test a finite cap,
default sketch 100 repos per org per refresh); never unbounded internet search.
Default ref (frozen): for each eligible repo, resolve ref = default_branch from
github_meta (fail closed if missing). No caller-supplied arbitrary ref query in Auto v1.
A repo appears in the org glance only when all of the following hold:
- Membership: the repo is listed explicitly as
owner/repoinorg_allowlist, or it was enumerated under an org-only allowlist entry and discovery finds kit marker file.overseer/config.yamlon the resolved default branch. - Readability: the credential can read the required paths (otherwise repo shows as
unreadable, never as fabricated green status). - Doc paths: ROADMAP / HANDOVER paths come from:
- Parsed
.overseer/config.yamlliving-doc keys when readable, else - Kit defaults
docs/ROADMAP.mdanddocs/OVERSEER-HANDOVER.md(documented fallback only).
- Parsed
If org_allowlist is empty → org summary returns zero repos (fail closed; no implicit “scan my
token’s entire universe”).
Arbitrary ?path= reads of any file in any repo are forbidden. Closed path set only
(§HGD.5).
§HGD.4.3 — Caching (frozen)
- In-memory or operator-configured ephemeral cache of fetched bytes + content sha256 is allowed for performance.
- The kit Auto build must not introduce a kit-owned durable multi-tenant database of consumer governance documents as a product store of record.
- Cached copies are never authoritative over the remote API response at refresh time.
- Cache must not store raw OAuth/PAT secrets.
§HGD.4.4 — Equivalence clause
Where MuseHub or a future Git host exposes a Contents-equivalent read API, Auto may implement an adapter behind the same closed source ids / response shapes. Behavior and fail-closed rules stay identical; Muse deepen remains optional.
§HGD.5 — Closed read surface (frozen)
URL paths below are written without a leading slash so the §K5.5 checklist absolute-path detector does not false-positive; Auto implements them as normal absolute URL paths (leading slash present on the wire).
§HGD.5.1 — Endpoint set (Auto v1)
| Method | Path | Purpose |
|---|---|---|
GET |
api/health |
Process liveness; no repo secrets; no doc bodies |
GET |
api/org/summary |
Allowlisted / discovered repos + high-level eligibility |
GET |
api/repos/{owner}/{repo}/roadmap |
ROADMAP text + sha256 + source id + ref |
GET |
api/repos/{owner}/{repo}/handover |
HANDOVER text + sha256 + source id + ref |
GET |
api/repos/{owner}/{repo}/gates |
Gate view per §HGD.7 |
GET |
api/repos/{owner}/{repo}/config-marker |
Redacted presence/parse summary of .overseer/config.yaml living-doc paths only — no secret values |
Static UI assets are served outside the api/ prefix.
§HGD.5.2 — Forbidden methods / routes (frozen)
- Any
POST/PUT/PATCH/DELETEthat mutates git, muse, GitHub, or MuseHub state. - Endpoints for:
init,sync,governance-sync,review --freezestamp write,ledger append, merge, mirror export, staging push, deploy, live gate flip. - Proxy endpoints that forward arbitrary upstream URLs (SSRF class).
- Track Q act endpoints (
api/review/freeze,api/governance-sync,api/ledger/append, etc.).
§HGD.5.3 — Success envelope (frozen)
{
"ok": true,
"result": {},
"meta": {
"source_id": "github_contents",
"ref": "main",
"fetched_at": "2026-07-13T00:00:00Z",
"content_sha256": "lowercase-hex",
"authoritative_workflow": "local"
}
}
Rules:
authoritative_workflowis always the stringlocal(reminder: dashboard is glance-only).- Doc endpoints’
resultMUST includepath(repo-relative),text(UTF-8),sha256(lowercase hex of raw bytes). - Unknown query keys → HTTP
400; no upstream call. - Path params
owner/repoMUST match^[A-Za-z0-9._-]+$(fail closed otherwise).
§HGD.5.4 — api/health result (frozen)
{ "status": "ok", "mode": "hosted-read-only" } — no tokens, no doc bodies, no org lists.
§HGD.5.5 — api/org/summary result (frozen)
result is an object:
| Field | Type | Rule |
|---|---|---|
repos |
array | Zero or more repo summary objects |
repos[].owner |
string | Owner login |
repos[].name |
string | Repo name |
repos[].full_name |
string | owner/name |
repos[].default_branch |
string | From github_meta |
repos[].eligibility |
string | Closed vocabulary: eligible | unreadable | no_marker |
repos[].marker_present |
bool | Whether .overseer/config.yaml was readable |
No living-doc bodies in this endpoint.
§HGD.5.6 — api/repos/{owner}/{repo}/gates result (frozen)
| Field | Type | Rule |
|---|---|---|
document_derived |
object | Always present |
document_derived.ok |
bool | false on parse failure |
document_derived.error |
string or null | Error token when ok is false; else null |
document_derived.phases |
array | Zero or more { "id": string, "status": "TODO\|WIP\|DONE\|BLOCKED" } when parse succeeds; empty array on failure |
document_derived.pending_gates_excerpt |
string or null | Optional short excerpt from HANDOVER pending-gates prose; null if absent |
advisory_checks |
object or null | Null when source disabled; else { "ok": bool, "label": "Advisory — not kit hard gates", "items": [ { "name": string, "conclusion": string } ] } |
§HGD.5.7 — api/repos/{owner}/{repo}/config-marker result (frozen)
| Field | Type | Rule |
|---|---|---|
present |
bool | Marker file readable |
roadmap_path |
string or null | Repo-relative path from parse or null |
handover_path |
string or null | Repo-relative path from parse or null |
vcs_regime |
string or null | Regime string if present in marker; else null |
raw_text |
— | Forbidden in Auto v1 (do not return full config YAML) |
§HGD.6 — Auth + credential scopes (frozen)
Hosted non-loopback exposure requires authentication. Anonymous public read of private org repos is forbidden.
§HGD.6.1 — Viewer session (Auto v1 primary path)
| Property | Rule |
|---|---|
| Mechanism (primary, frozen for Auto v1) | Authorization: Bearer <credential> where <credential> is the value of env OVERSEER_HOSTED_DASHBOARD_VIEWER_TOKEN (≥ 128 bits entropy; generated by operator or printed once at preview startup to stderr). OAuth App / GitHub App browser login is deferred to a later freeze; Auto v1 MUST NOT require OAuth to reach DONE. |
| Upstream read credential | Separate env OVERSEER_HOSTED_DASHBOARD_TOKEN (or documented synonym in the runbook) used only for GitHub/MuseHub read APIs — never returned in API JSON. |
| Persistence | Viewer + upstream secrets in process memory (and optionally httpOnly secure cookies mirroring the viewer Bearer on hosted TLS deploys); never committed into the kit repo, living docs, or version.lock. |
| CSRF | No mutating api/* methods in v1. If a session cookie mirrors the viewer Bearer, set Secure + HttpOnly + SameSite=Lax (or stricter) on non-loopback TLS deploys. |
§HGD.6.2 — Upstream credential scopes (frozen)
Allowed upstream scopes (conceptual; map to GitHub/MuseHub names in Auto docs):
- Repository metadata read
- Contents / file read
Rejected upstream scopes (non-exhaustive, fail closed if requested or detected):
contents:write/ any content mutationadministration/ org adminworkflowswrite- Deploy keys with write
- Mirror / push credentials
- Any scope that can open PRs, merge, or delete repos
Startup / config validation MUST refuse to run the hosted server when the configured credential advertises a rejected write class (when the host API can report granted scopes). If scopes cannot be introspected, the operator runbook MUST require read-only credentials and Auto tests MUST prove the code path never calls write HTTP verbs on upstream hosts.
§HGD.6.3 — Fail closed (auth)
| Condition | Behavior |
|---|---|
Missing / invalid viewer session on api/* except documented public api/health policy |
HTTP 401; no upstream call |
| Disallowed Origin (CORS allowlist from config) | HTTP 403 |
| Credential with rejected write scope | Refuse process start or refuse org routes with explicit error token write_scope_refused |
| SSRF / disallowed upstream host | HTTP 403; no connect |
api/health auth policy (frozen): may be unauthenticated for load-balancer probes only
when it returns the §HGD.5.4 body with no secrets. All other api/* routes require auth.
§HGD.6.4 — TLS / bind (frozen)
| Mode | Bind | TLS |
|---|---|---|
Local preview (ok hosted-dashboard or equivalent) |
Default 127.0.0.1; loopback-only unless operator opts into documented preview bind |
TLS not required on loopback |
| Hosted deploy | Non-loopback allowed only behind operator TLS terminator or in-process TLS | TLS required for non-loopback |
No hidden “disable auth” flag in Auto v1.
§HGD.6.5 — Public anonymous policy (frozen)
Anonymous unauthenticated read of public repos is off in Auto v1 (all api/* except
api/health still require the viewer Bearer). Enabling public anonymous glance requires a later
Thinking freeze (Tier-2 product decision).
§HGD.6.6 — Upstream host allowlist (frozen)
Default allowed upstream hosts for Auto v1:
api.github.comraw.githubusercontent.com
Optional Muse deepen may add exactly the hostnames documented in the operator runbook for
musehub_read (finite list; no wildcard *). Any other host → refuse with HTTP 403 /
write_scope_refused is not used here; use error token upstream_host_refused. Literal IP
literals and link-local/metadata addresses are always refused.
§HGD.6.7 — UI viewer bootstrap (frozen)
Static UI prompts once per browser load to paste the viewer Bearer credential (from stderr startup
banner or operator secret store) and holds it in a JS memory variable for Authorization headers.
Forbidden in Auto v1: persisting the viewer or upstream token in localStorage,
sessionStorage, or repo-tree files. Cookie mirror of the viewer Bearer is optional on hosted TLS
deploys only (§HGD.6.1).
§HGD.7 — Gate-status semantics (frozen)
The dashboard does not run ok status, KH2, or KH3 against a remote bare API as
authoritative truth.
§HGD.7.1 — Document-derived gates (primary)
GET api/repos/{owner}/{repo}/gates result.document_derived is built only from:
- Parsed HANDOVER tables / verified-snapshot / pending-gates prose already present in fetched bytes, and/or
- Parsed ROADMAP Build-status rows (phase id + Status tokens
TODO|WIP|DONE|BLOCKEDwhen present).
If parsing fails → document_derived.ok: false with error token; never invent DONE.
§HGD.7.2 — Advisory checks (optional)
When github_checks_advisory is enabled:
- Populate
result.advisory_checksfrom GitHub Checks / status APIs for the resolved ref. - UI MUST label these Advisory — not kit hard gates.
- Advisory red/green MUST NOT be shown as KH2/KH3 pass.
§HGD.7.3 — Honesty banner (mandatory in UI)
Every repo detail view MUST show: authoritative workflow remains local (ok CLI / Track Q);
this page is a glance surface only.
§HGD.8 — Boundary & capability tiers (frozen)
| Concern | Hosted governance dashboard | Not this product |
|---|---|---|
| Show org/repo ROADMAP + HANDOVER | Yes (remote read) | — |
| Show document-derived / advisory gates | Yes | Authoritative local hard gates |
| Mutate git / muse / GitHub / MuseHub | Never | Local ok / human Tier-3 |
| Local working-tree engine | Never | Track Q / CLI |
| Model / agent runtime | Never | Consumer runtimes |
| Product domain data store | Never | Consumer products |
| Deploy / CD / live product probes | Never | Operator / CI / P-deploy claims |
| Track Q loopback UI | Never merge scopes | Track Q Q0–Q3 |
| Capability | git-only (GitHub APIs) |
muse+git-mirror / muse-only |
|---|---|---|
Org glance + doc fetch via github_* |
Full (baseline) | Full (baseline still GitHub-visible mirror/docs as configured) |
Optional musehub_read deepen |
N/A / unused | Optional — never required for baseline glance |
| Authoritative hard gates | Not on this surface | Not on this surface |
| Remote write | Never | Never |
K7 guardrail restated: no core hosted-dashboard feature may be MuseHub-only. GitHub-baseline
read path must work for git-only orgs.
§HGD.9 — Rejection table (frozen)
| Proposal | Verdict |
|---|---|
| Port Track Q act endpoints to the hosted service | Reject |
Default-bind ok app to 0.0.0.0 “so it is hosted” |
Reject |
contents:write or PR/merge automation from the dashboard |
Reject |
| Kit-owned durable DB as store of record for all consumer roadmaps | Reject |
| Dashboard performs deploys or production HTTP health probes | Reject |
| Dashboard claims KH2/KH3 pass from remote advisory checks alone | Reject |
| Host product user/vault/wallet data in kit Auto modules | Reject |
| MuseHub-only baseline (no GitHub read path) | Reject (K7) |
| Thinking phase ships server/UI/fetch code | Reject |
This freeze authorizes merge to main |
Reject (Tier 3) |
Arbitrary file read API (path= escape) |
Reject |
| Open upstream URL proxy | Reject |
| Public anonymous org glance in Auto v1 | Reject (§HGD.6.5) |
| OAuth-required DONE for Auto v1 | Reject (deferred; Bearer viewer is primary) |
§HGD.10 — Auto build deliverables (frozen)
After freeze pass, the Auto build ships only:
- Library under
tools/hosted_dashboard/— source adapters (github_contents,github_meta, optionalgithub_checks_advisory, optionalmusehub_read), path allowlist, parsers for document-derived gates, envelope helpers, scope refuse helpers. - HTTP read server (stdlib preferred; new mandatory web framework needs Tier-2 confirm) that implements §HGD.5 only.
- Static UI — org summary + repo ROADMAP/HANDOVER/gates views with honesty banner (§HGD.7.3).
- CLI preview entry — exactly one new top-level command id
hosted-dashboardonok(compat shimoverseerunchanged aside from registration), flags frozen below. - Operator runbook —
docs/HOSTED-GOVERNANCE-DASHBOARD-OPERATOR-RUNBOOK.md(read-only credentials, TLS, CORS allowlist, K7 note). - Seven-tier tests per §HGD.12.
- SPEC §5 row additive mention of
ok hosted-dashboardas read-only remote preview (no redesign of other commands).
§HGD.10.1 — CLI flags (frozen)
ok hosted-dashboard [--port PORT] [--bind ADDRESS] [--config PATH] [--open]
| Flag | Default | Rule |
|---|---|---|
--port |
8766 |
Integer 1–65535; occupied → exit 2 (no silent port hop). Distinct from Track Q 8765. |
| --bind | 127.0.0.1 | Preview default loopback. Non-loopback only when config explicitly sets
hosted_dashboard.allow_non_loopback: true and auth + TLS rules in §HGD.6 hold; else refuse
exit 2. |
| --config | cwd .overseer/config.yaml if present, else explicit required in hosted mode | Path-confined |
| --open | off | Optional browser open to local preview URL |
Startup: load allowlist + credential env (OVERSEER_HOSTED_DASHBOARD_TOKEN upstream read;
OVERSEER_HOSTED_DASHBOARD_VIEWER_TOKEN viewer Bearer — generate ephemeral viewer token at
startup if unset in preview mode and print once to stderr); refuse write scopes; listen; block
until signal; clean exit 0. Never hardcode secrets.
Non-goals for the CLI process: no launchd/systemd unit, no background daemon install in Auto v1, no mutation of the preview host’s git/muse state.
§HGD.10.2 — Config block (frozen sketch — Auto fills schema tests)
Optional default-inert:
hosted_dashboard:
enabled: false
allow_non_loopback: false
cors_origins: []
org_allowlist: []
sources:
github_contents: true
github_meta: true
github_checks_advisory: false
musehub_read: false
Unrecognized keys fail closed at load (same family as other kit config blocks).
§HGD.11 — Fail-closed / errors (frozen)
| Condition | Behavior |
|---|---|
| Upstream 404 / missing living doc | ok: false, error token not_found; HTTP 404 |
| Upstream auth failure | error token upstream_unauthorized; HTTP 502 (viewer auth remains 401; do not conflate) |
| Parse failure for gates | document_derived.ok: false; do not fabricate DONE |
| Rate limit | error token upstream_rate_limited; bounded retry only if documented; never tight spin |
| Path / owner / repo validation fail | HTTP 400; no upstream call |
| Write verb attempted in client code | Must be unreachable; security tests assert allowlist of methods GET/HEAD only to upstream |
Process exit codes for the CLI preview:
| Code | Meaning |
|---|---|
0 |
Clean shutdown |
1 |
Usage / argument error |
2 |
Config / bind / scope / listen failure |
No new exit code number is allocated beyond existing kit conventions unless Auto discovers a collision — then Thinking amendment required before shipping a new code.
§HGD.12 — Seven-tier test matrix (Auto build must satisfy)
The Auto build ships all seven tiers green locally before DONE (policy/test-tiers.yaml).
| Tier | Proves |
|---|---|
| unit | Path/owner/repo validators; allowlist vs discovery marker rules; empty allowlist → zero repos; scope refuse helper rejects write-class scopes; upstream host allowlist accepts only frozen hosts; envelope builder sets authoritative_workflow: local; document-derived parser never invents DONE on garbage input; default port 8766; bind refuse without allow_non_loopback; endpoint allowlist rejects unknown routes and all mutating methods; config unknown-key refuse; source-id closed vocabulary; viewer Bearer required except api/health. |
| integration | Fixture HTTP upstream (no real network required) serves Contents-shaped payloads; each §HGD.5 GET returns expected envelope; missing doc → not_found; write-scope config → start refuse or route refuse; CORS deny for non-allowlisted Origin; disallowed upstream host → upstream_host_refused / HTTP 403; api/health body matches §HGD.5.4; Track Q paths not registered. |
| e2e | Start ok hosted-dashboard against fixture upstream → authenticate with viewer Bearer (OVERSEER_HOSTED_DASHBOARD_VIEWER_TOKEN or startup-printed ephemeral) → org summary → open roadmap + handover + gates → honesty banner present in UI bytes → SIGINT exit 0; no files under the fixture repo’s .git / .muse mutated (mtime/hash invariant). |
| stress | Bounded concurrent GETs (≥ 20) against summary/doc routes do not corrupt process state; large ROADMAP/HANDOVER fixture stays bounded in memory (documented cap or streaming hash); org enumeration respects finite cap from §HGD.4.2; no unbounded org crawl beyond allowlist/discovery rules. |
| data-integrity | Twin fetch of same ref → identical content_sha256; cache (if enabled) does not alter sha; refresh replaces stale bytes; secrets/token values never appear in result JSON, UI, or logs under default sanitization. |
| performance | Documented bound for single-repo doc fetch + parse on fixture; startup listen bound; no full-history clone. |
| security | Mutating HTTP methods on hosted api/* → 405 or 404; upstream client method allowlist is GET/HEAD only; rejected scopes refuse; SSRF: disallowed host/IP refused with HTTP 403; path traversal in path params refused; no credential in repo after e2e; no auth-disable flag; no Track Q act routes; no deploy/probe URLs called; no localStorage persistence of viewer token; MuseHub-only baseline impossible (github_contents still required for baseline tests). |
§HGD.13 — Hard stops + tier linkage (frozen)
| Action | Tier | Rule |
|---|---|---|
| Feature-branch commits for this freeze / Auto | Tier 1 | SD-1 / SD-17 |
git push feature branch / open PR |
Tier 1 | No merge |
| Confirm new mandatory web framework dependency | Tier 2 | Recommend once + ADR if not stdlib |
Merge to main |
Tier 3 | Human only — not authorized here |
| Staging push / live capability flip | Tier 3 | Human only |
| Real-money billing for hosted SaaS | Tier 3 / out of kit Auto | Not in this freeze |
Escalation categories for freeze review remain: security, irreversible, real_money,
gates_tier3.
§HGD.14 — Definitions of Done
§HGD.14.1 — Thinking freeze (this phase)
- [x] This document reviewed →
passvia/freeze-review-loop+ok review --freeze - [x] Review-record table stamped;
review_stampfilled - [x]
docs/ROADMAP.md— exploration row promoted / Build queue row → Thinking DONE; Auto TODO - [x]
docs/OVERSEER-HANDOVER.mdNEXT regenerated for Hosted governance dashboard Auto (SD-17) - [x] No dashboard / fetch / UI / CLI code landed in Thinking
- [x] No Tier-3 merge performed
§HGD.14.2 — Auto build (later)
- [x] Mechanical implementation matches §§HGD.4–HGD.11 and §HGD.10
- [x] Seven-tier matrix §HGD.12 green
- [x]
/build-verification-review→passbefore ROADMAP Auto → DONE - [x] Governance sync (ROADMAP + HANDOVER) in the closing commit
- [x] Feature-branch push / PR only; merge remains Tier 3
- [x] Track Q surfaces unchanged (no scope merge)