@loopover/miner 0.1.0

package/docs/config-precedence.md

@@ -0,0 +1,96 @@
+# Miner config precedence
+
+AMS does **not** have a single `config.js` resolver. Configuration is layered by concern across several modules under `packages/gittensory-miner/lib/` and `@loopover/engine`. This document states the order each layer **actually implements today** — not an idealized or corrected order.
+
+## Configuration layers
+
+| Layer | Source | Scope | Typical modules |
+| --- | --- | --- | --- |
+| **Per-target-repo file** | `.gittensory-miner.yml` (or `.github/gittensory-miner.yml`, JSON variants) | One cloned target repo | `lib/miner-goal-spec.js`, engine `parseMinerGoalSpecContent` |
+| **Operator env** | `GITTENSORY_MINER_*` / `MINER_*` | This miner process / fleet container | `lib/local-store.js`, `lib/governor-kill-switch.js`, `lib/attempt-cli.js`, … |
+| **CLI flags** | `gittensory-miner <cmd> …` argv | One invocation | `lib/attempt-cli.js`, `lib/discover-cli.js`, `lib/loop-cli.js`, … |
+| **Operator file (not goal spec)** | `~/.config/gittensory-miner/.gittensory-ams.yml` | Operator execution policy | `lib/ams-policy.js` |
+
+`.gittensory-miner.yml` is **maintainer-authored in the target repo**. Operator env and CLI flags are **never overridden by a target repo's goal spec** for operator-owned policy (see `lib/ams-policy.js` header).
+
+## `.gittensory-miner.yml` file discovery
+
+First existing file wins (engine `MINER_GOAL_SPEC_FILENAMES`):
+
+1. `.gittensory-miner.yml`
+2. `.github/gittensory-miner.yml`
+3. `.gittensory-miner.json`
+4. `.github/gittensory-miner.json`
+
+## Precedence by concern
+
+### Kill switch (halt miner writes)
+
+**Sources:** `GITTENSORY_MINER_KILL_SWITCH` (operator env) and `.gittensory-miner.yml` → `killSwitch.paused`.
+
+**Order (safest wins, engine `resolveMinerKillSwitch`):**
+
+1. Global env halt → scope `"global"` (always reported even when the repo yml also pauses).
+2. Else per-repo yml `killSwitch.paused: true` → scope `"repo"`.
+3. Else → scope `"none"`.
+
+There is **no CLI flag** for kill-switch today. `MINER_CODING_AGENT_PAUSED` is a separate axis (coding-agent spawn only) and does not change kill-switch scope.
+
+### Governor live write mode
+
+**Sources:** `GITTENSORY_MINER_LIVE_MODE=live` (operator env) and `.gittensory-miner.yml` → `execution.liveModeOptIn: live`.
+
+**Order (engine `resolveMinerActionMode`):**
+
+1. Kill switch active → `"paused"` (overrides any live opt-in).
+2. Else **both** operator env **and** repo yml must equal the exact string `"live"` → `"live"`.
+3. Else → `"dry_run"`.
+
+This is an **AND** requirement, not “last writer wins”. Either side missing or malformed → dry-run.
+
+There is **no CLI flag wired to governor live mode** today. `attempt --live` / `loop --live` affect coding-agent spawn mode only (below).
+
+### Coding-agent execution mode (spawn the driver?)
+
+**Sources:** `MINER_CODING_AGENT_PAUSED` (operator env) and `attempt|loop --live` (CLI, per invocation).
+
+**Order (engine `resolveCodingAgentExecutionMode`, wired in `lib/attempt-cli.js`):**
+
+1. Global env pause (`MINER_CODING_AGENT_PAUSED` truthy) → `"paused"`.
+2. Else CLI `--live` absent → `agentDryRun: true` → `"dry_run"` (`attempt-cli.js` enforces dry-run default for #2342).
+3. Else CLI `--live` present → `"live"`.
+
+There is **no `.gittensory-miner.yml` field** for coding-agent mode today.
+
+### Discover forge credential env var name
+
+**Sources:** `discover --token-env <VAR>` (CLI), programmatic `options.tokenEnv`, forge default (`GITHUB_TOKEN`).
+
+**Order (`lib/discover-cli.js`):**
+
+1. CLI `--token-env`
+2. Else programmatic `options.tokenEnv`
+3. Else `resolveForgeConfig(...).tokenEnvVar` (default `GITHUB_TOKEN`)
+
+There is **no `.gittensory-miner.yml` forge block** today; `--api-base-url` follows the same CLI → programmatic → default shape for the API host.
+
+### Local SQLite store paths
+
+**Sources:** per-store `GITTENSORY_MINER_*_DB` env var, then `GITTENSORY_MINER_CONFIG_DIR`, then XDG default (`lib/local-store.js`).
+
+Explicit per-store env **wins** over config dir; config dir **wins** over XDG. No CLI or goal-spec override.
+
+## Known gaps / inconsistencies
+
+- **No unified precedence** across yml + env + CLI for a single knob — each concern owns its resolver.
+- **Live execution** spans two independent gates: coding-agent `--live` (spawn) vs governor env+yml (writes). Both must allow live for a full live open-pr attempt.
+- **Forge tenant overrides** (`--api-base-url`, `--token-env`) are CLI/programmatic only; `.gittensory-miner.yml` cannot set them yet.
+- **Operator AMS policy** (`.gittensory-ams.yml`) is separate from per-repo goal spec; goal spec never overrides operator policy.
+
+If a future change adds yml or CLI for a setting documented here as env-only, update this file and extend `test/unit/miner-config-precedence.test.ts`.
+
+## See also
+
+- [`miner-goal-spec.md`](miner-goal-spec.md) — goal-spec field reference
+- [`env-reference.md`](env-reference.md) — generated operator env list
+- ORB `.loopover.yml` (or legacy `.gittensory.yml`, #4773) precedence (`yml > DB > defaults`) in the main app — analogous documentation style, different runtime

package/docs/cross-repo-discovery-phase1.md

@@ -0,0 +1,55 @@
+# Cross-repo discovery — Phase 1 scope (re-scoped from #1060)
+
+This document is the in-repo paper trail for [#2299](https://github.com/JSONbored/gittensory/issues/2299). It records the metadata-only, client-driven discovery model that supersedes the original [#1060](https://github.com/JSONbored/gittensory/issues/1060) wording (registered-repo aggregation and any retired global data layer). Maintainers should reopen #1060 and point its body at this file so the miner backlog has one canonical entry point.
+
+Part of [#1058](https://github.com/JSONbored/gittensory/issues/1058) (close-the-loop epic). Builds on / supersedes the intent of [#816](https://github.com/JSONbored/gittensory/issues/816).
+
+## Re-scoped discovery model
+
+Cross-repo opportunity discovery in Phase 1 is:
+
+- **Metadata-only** — GitHub search/listing APIs only; never source clone or upload.
+- **Client-driven** — the contributor supplies the repo list or search scope; no dependency on a Gittensory-registered-repos table or any retired central global data layer.
+- **Deterministic** — reuse existing per-repo signals; no new ML model and no raw reward/score/wallet/hotkey exposure.
+- **Read-only (`wave: "1"`)** — every deliverable in this Phase 1 batch performs GET/list/search only; no GitHub writes, no autonomous claiming, no PR submission.
+
+## Existing signal sources the ranker composes
+
+The cross-repo ranker is a **new join over existing signals**, not a new scoring model:
+
+| Source | Role |
+|--------|------|
+| [`src/services/issue-quality.ts`](../../../src/services/issue-quality.ts) | Loads or computes per-repo `IssueQualityReport` snapshots (actionable / needs-proof / stale / duplicate-prone / solved). |
+| [`src/signals/reward-risk.ts`](../../../src/signals/reward-risk.ts) → [`packages/gittensory-engine/src/reward-risk.ts`](../../../packages/gittensory-engine/src/reward-risk.ts) | Opportunity factors (`competitionFactor`, `freshnessFactor`) for repo-level ranking; backend shim delegates to the engine implementation. |
+| [`src/services/decision-pack.ts`](../../../src/services/decision-pack.ts) | Existing per-miner, per-repo opportunity pack (reactive baseline the Phase 1 tools extend). |
+
+Hosted and stdio MCP surfaces expose the composed shortlist via `gittensory_find_opportunities` (#2308 / #2309).
+
+## Phase 1 issue batch
+
+| Issue | Title |
+|-------|-------|
+| [#2299](https://github.com/JSONbored/gittensory/issues/2299) | Scope correction note (this document) |
+| [#2300](https://github.com/JSONbored/gittensory/issues/2300) | `.gittensory-miner.yml` MinerGoalSpec schema doc |
+| [#2301](https://github.com/JSONbored/gittensory/issues/2301) | MinerGoalSpec parser with safe-default fallback |
+| [#2302](https://github.com/JSONbored/gittensory/issues/2302) | Pure ranker — `potential × feasibility × laneFit × freshness × (1 − dupRisk)` |
+| [#2303](https://github.com/JSONbored/gittensory/issues/2303) | Ranker invariant test suite |
+| [#2304](https://github.com/JSONbored/gittensory/issues/2304) | Goal model — MinerGoalSpec → ranker weights |
+| [#2305](https://github.com/JSONbored/gittensory/issues/2305) | Per-repo AI-policy map (CONTRIBUTING / AI-USAGE hard-skip) |
+| [#2306](https://github.com/JSONbored/gittensory/issues/2306) | AI-policy fixture corpus + integration test |
+| [#2307](https://github.com/JSONbored/gittensory/issues/2307) | Cross-repo GitHub search/listing fan-out (metadata-only) |
+| [#2308](https://github.com/JSONbored/gittensory/issues/2308) | Hosted `gittensory_find_opportunities` MCP tool |
+| [#2309](https://github.com/JSONbored/gittensory/issues/2309) | Stdio `gittensory_find_opportunities` in `@loopover/mcp` |
+| [#2310](https://github.com/JSONbored/gittensory/issues/2310) | Miner package `test:miner-pack` / `build:miner` parity checks |
+| [#2311](https://github.com/JSONbored/gittensory/issues/2311) | End-to-end Phase 1 discovery pipeline fixture test |
+
+## Target feature issue (#1060)
+
+[#1060 — proactive cross-repo opportunity discovery](https://github.com/JSONbored/gittensory/issues/1060) remains the umbrella feature issue. It should be **reopened** with this Phase 1 scope (metadata-only fan-out + deterministic ranker + MCP tool) replacing the older “aggregate across all registered repos” deliverable list. Proactive alerting and notification filters are follow-on work outside this read-only Phase 1 batch.
+
+## Acceptance (Phase 1)
+
+- A miner can ask for a deterministic, metadata-only, cross-repo ranked shortlist via MCP (`gittensory_find_opportunities`).
+- AI-PR-banned repos are hard-skipped upstream and never appear in output.
+- No raw scores, rewards, hotkeys, wallet data, or source contents cross the public boundary.
+- All Phase 1 implementation issues stay read-only on GitHub (GET/search/list only).

package/docs/discovery-index-contract.md

@@ -0,0 +1,60 @@
+# Discovery-index API contract
+
+The **discovery-index contract** is the typed request/response shape a miner uses to query the *optional* hosted
+discovery-index service. It is defined in `@loopover/engine`
+(`packages/gittensory-engine/src/discovery-index-contract.ts`) so both sides — this repo's future server
+implementation ([#4250](https://github.com/JSONbored/gittensory/issues/4250), maintainer-only, explicitly blocked
+on this contract) and any client — build against one shape.
+
+This is **schema/shape only**: no server, no deployed endpoint, no client HTTP implementation (those are #4250 and
+the sibling soft-claim-coordination issue, respectively).
+
+## Why
+
+The plane mitigates the rate-limit incident already fixed once for the review stack
+([#1936](https://github.com/JSONbored/gittensory/issues/1936)): *one* shared GitHub-metadata crawler across the
+miner fleet instead of every miner instance independently hammering the same repos' search/listing endpoints. The
+existing single-instance client pipeline (`packages/gittensory-miner/lib/opportunity-fanout.js` +
+`opportunity-ranker.js`) is what a hosted version must stay compatible with, so the response candidate shape is
+field-for-field compatible with `opportunity-ranker.js`'s `normalizeCandidate` — a miner can swap a local fan-out
+for a hosted query without the ranker changing.
+
+## Boundary (Phase 1)
+
+The contract stays inside the Phase 1 discovery boundary
+([`cross-repo-discovery-phase1.md`](./cross-repo-discovery-phase1.md)): metadata-only, GET/list/search-only, and
+**no raw scores, rewards, wallet/hotkey data, or source contents** cross the public boundary. This is enforced in
+code, not just documented: `discoveryIndexBoundaryViolations` lists any forbidden field on a raw object, and
+`normalizeDiscoveryIndexCandidate` **rejects** (returns `null`) — rather than silently trimming — any candidate
+carrying one, so a misbehaving server cannot smuggle economic/identity/source data past the contract.
+`DISCOVERY_INDEX_FORBIDDEN_FIELDS` is the fragment list (`score`, `reward`, `wallet`, `hotkey`, `coldkey`,
+`mnemonic`, `payout`, `ranking`, `rawtrust`, `trustscore`, `sourcecontent`, `diff`, `patch`).
+
+## Request — `DiscoveryIndexQuery`
+
+Every field is optional; a malformed value degrades to a documented default with a warning rather than throwing
+(`normalizeDiscoveryIndexRequest`).
+
+- **`repos`** — canonical `owner/repo` targets. Non-string / non-`owner/repo` entries are skipped; deduplicated;
+  capped at 200. Default: `[]`.
+- **`orgs`** — bare `owner` (org/user) targets. Entries containing `/` are skipped; deduplicated; capped at 200.
+  Default: `[]`.
+- **`searchTerms`** — free-text GitHub issue-search terms. Blank entries skipped; deduplicated; capped at 200.
+  Default: `[]`.
+- **`limit`** — page size, floored and clamped to `[1, 200]`; a non-numeric value warns and falls back. Default:
+  `50`.
+- **`cursor`** — opaque forward pagination cursor from a previous response's `nextCursor`; a blank/non-string value
+  becomes `null`. Default: `null`.
+
+## Response — `DiscoveryIndexResponse`
+
+- **`candidates`** — a list of `DiscoveryIndexCandidate`. `normalizeDiscoveryIndexResponse` keeps only valid,
+  public-safe entries and drops invalid or boundary-violating ones with a warning.
+- **`nextCursor`** — forward cursor for the next page, or `null` when the result set is exhausted.
+- **`contractVersion`** — `DISCOVERY_INDEX_CONTRACT_VERSION` (currently `1`).
+
+### `DiscoveryIndexCandidate`
+
+Metadata-only, field-for-field compatible with `opportunity-ranker.js` `normalizeCandidate`:
+`owner`, `repo`, `repoFullName`, `issueNumber`, `title`, `labels`, `commentsCount`, `createdAt`, `updatedAt`,
+`htmlUrl`, `aiPolicyAllowed`, `aiPolicySource` (`"AI-USAGE.md" | "CONTRIBUTING.md" | "none"`).

package/docs/discovery-plane-operator-guide.md

@@ -0,0 +1,101 @@
+# Hosted discovery plane — operator guide (opt-in)
+
+Operator-facing guide for the **optional** Phase 6 hosted discovery-index plane ([#4250](https://github.com/JSONbored/gittensory/issues/4250)). This is the client/miner half of that roadmap item: how a `gittensory-miner` instance opts in, what it may send, and what never leaves the operator's machine.
+
+> **Placeholder scope:** the concrete env var names, HTTP paths, and telemetry event types below are **provisional** until the sibling contract/telemetry/client issues land. When those ship, update this file to match the real symbols — do not treat the TBD names as stable API yet.
+>
+> | Issue | What it defines |
+> |-------|-----------------|
+> | [#4300](https://github.com/JSONbored/gittensory/issues/4300) | Public-data-only discovery-index API contract (request/response shapes) |
+> | [#4301](https://github.com/JSONbored/gittensory/issues/4301) | Anonymized telemetry event schema for the optional hosted plane |
+> | [#4302](https://github.com/JSONbored/gittensory/issues/4302) | Client-side soft-claim coordination request builder |
+> | [#4250](https://github.com/JSONbored/gittensory/issues/4250) | Hosted discovery-index server (maintainer-operated counterpart) |
+
+Part of the Miner Wave 2 discovery plane ([#2353](https://github.com/JSONbored/gittensory/issues/2353) Phase 6). Distinct from Phase 1's **local-only** metadata fan-out documented in [`cross-repo-discovery-phase1.md`](cross-repo-discovery-phase1.md) — that path never phones home today.
+
+## Default posture: opt-in (not like Orb)
+
+Two telemetry/export surfaces exist in Gittensory, and they intentionally use **opposite defaults**:
+
+| Surface | Default | Operator action | Precedent |
+|---------|---------|-------------------|-----------|
+| **Orb fleet calibration** (`src/selfhost/orb-collector.ts`) | **ON** once a GitHub App is configured | Opt out only via `ORB_AIR_GAP=true` (air-gapped / send-nothing) | Review-stack self-host contract — export is always on unless air-gapped |
+| **Hosted discovery plane** (this guide) | **OFF** | Opt **in** explicitly before any hosted index query or plane telemetry | Hybrid, self-host-first miner deployment — participation in a shared hosted plane is never assumed |
+
+Do **not** copy Orb's wording for this plane. Orb's header comment is explicit: "Export is ALWAYS ON… there is no opt-out flag" aside from `ORB_AIR_GAP`. The discovery plane is the opposite: **no hosted traffic unless the operator turns it on.**
+
+## What the plane is for
+
+When enabled, a miner may query a **shared, metadata-only** discovery index instead of every fleet member independently fanning out GitHub search/listing calls against the same repos — mitigating cross-fleet rate-limit pressure (the same class of incident addressed for the review stack in [#1936](https://github.com/JSONbored/gittensory/issues/1936)).
+
+The plane:
+
+- Serves **public GitHub metadata only** (issue titles, labels, counts, timestamps, URLs — the same class of fields Phase 1 already uses locally).
+- May coordinate **soft claims** across the fleet (server-side dedup is [#4250](https://github.com/JSONbored/gittensory/issues/4250); client request shape is [#4302](https://github.com/JSONbored/gittensory/issues/4302)).
+- Never receives source trees, diffs, tokens, or write credentials.
+
+Local discovery (`opportunity-fanout` + `opportunity-ranker`) continues to work with **zero** hosted configuration.
+
+## Opt-in mechanism (names TBD — update when #4300/#4301 ship)
+
+Until the contract issue lands, treat these as **documentation placeholders** for the shape operators should expect:
+
+| Variable (provisional) | Default | Purpose |
+|------------------------|---------|---------|
+| `GITTENSORY_MINER_DISCOVERY_PLANE` | unset / `false` | Master opt-in. When not truthy (`1`, `true`, `yes`, `on`), the miner must not call the hosted index or emit discovery-plane telemetry. |
+| `GITTENSORY_MINER_DISCOVERY_INDEX_URL` | unset | Hosted index base URL. Required when the plane is enabled; ignored when opt-in is off. |
+| `GITTENSORY_MINER_DISCOVERY_TELEMETRY` | unset / `false` | Separate opt-in for anonymized operational telemetry ([#4301](https://github.com/JSONbored/gittensory/issues/4301)). Plane queries can stay on while telemetry stays off. |
+
+**Truthy-string convention** (when implemented): `/^(1|true|yes|on)$/i`, matching other `GITTENSORY_*` flags in this repo.
+
+**Operator checklist (enabled plane):**
+
+1. Set `GITTENSORY_MINER_DISCOVERY_PLANE=true` (exact name may change — see [#4300](https://github.com/JSONbored/gittensory/issues/4300)).
+2. Set `GITTENSORY_MINER_DISCOVERY_INDEX_URL` to the operator-trusted index endpoint ([#4250](https://github.com/JSONbored/gittensory/issues/4250)).
+3. Optionally set `GITTENSORY_MINER_DISCOVERY_TELEMETRY=true` if you want anonymized operational events for the hosted service — not required for index queries.
+4. Keep `GITHUB_TOKEN` (or equivalent) on the instance only; never configure tokens intended for the hosted plane to receive.
+
+With opt-in off (default), behavior is byte-identical to today: local SQLite ledgers, local fan-out, no hosted calls.
+
+## Contrast with local soft-claims today
+
+`packages/gittensory-miner/lib/claim-ledger.js` records soft claims **locally only** ("never uploads, syncs, or phones home"). Fleet-wide coordination before work starts is what [#4302](https://github.com/JSONbored/gittensory/issues/4302) + the hosted index ([#4250](https://github.com/JSONbored/gittensory/issues/4250)) add **on top of** that ledger — only after explicit opt-in.
+
+After-the-fact duplicate adjudication (`isDuplicateClusterWinnerByClaim` in `@loopover/engine`) remains separate; it resolves collisions by observing what publicly landed first, not by preventing overlap up front.
+
+## Invariants
+
+Mirrors [`DEPLOYMENT.md`](../DEPLOYMENT.md) tone — concrete guarantees for operators:
+
+- **Default OFF** — no hosted discovery-index traffic and no discovery-plane telemetry unless the operator opts in.
+- **Metadata-only index queries** — responses are issue/listing metadata compatible with local `normalizeCandidate` shape; no source upload, no clone, no repo archive.
+- **Read-only client posture** — the miner uses GET/list/search semantics toward GitHub directly (Phase 1) and toward the hosted index when enabled; the plane does not grant the miner new GitHub write capability.
+- **Credentials stay local** — GitHub tokens, PATs, and actor-capable secrets are injected at runtime on the operator's machine or secret store; they are **never** included in index or telemetry payloads.
+- **No compensation signals in the plane** — raw reward values, wallet addresses, hotkeys, trust scores, or private rankings never cross this boundary (same public boundary as [`cross-repo-discovery-phase1.md`](cross-repo-discovery-phase1.md) Acceptance).
+- **Telemetry is a second opt-in** — even with the plane enabled, anonymized telemetry ([#4301](https://github.com/JSONbored/gittensory/issues/4301)) remains separately gated.
+- **Anonymized identifiers only** — when telemetry ships, repo/issue correlation uses HMAC-hashed identifiers keyed by a **per-instance dedicated secret** the collector never holds (same posture as `getOrCreateAnonSecret` / `hmacField` in `src/selfhost/orb-collector.ts` — key separation from GitHub App / webhook secrets).
+- **Low-cardinality reason buckets** — any free-text-adjacent telemetry fields use bucketed categories (Orb's `bucketReasonCode` pattern), not raw maintainer or model prose.
+- **Core miner still works offline** — claims, plans, queues, and local ledgers do not require the hosted plane; `gittensory-miner doctor` / `status` remain no-network commands.
+
+### Never included (client → hosted plane)
+
+Inventory style matches `src/selfhost/orb-collector.ts:15-17` ("No diffs, no code…") adapted for discovery-plane domain ([#4301](https://github.com/JSONbored/gittensory/issues/4301)):
+
+- Source file contents, patches, or diffs
+- Full issue/PR bodies or review comments
+- GitHub tokens, PATs, App private keys, or any actor-capable credential
+- Commit SHAs, branch names tied to unpublished work, or CI log excerpts
+- Operator login identities, emails, or hostnames usable as PII
+- Raw gate reasons, model transcripts, or free-text maintainer notes
+- Reward amounts, wallet addresses, hotkeys, trust scores, or private rankings
+
+### Never retained by the hosted service (server-side — [#4250](https://github.com/JSONbored/gittensory/issues/4250))
+
+The server operating doc (maintainer-only) will restate the same boundary: **never holds source or actor-capable credentials.** This client guide does not define server retention policy; see #4250 deliverables.
+
+## Related docs
+
+- [`cross-repo-discovery-phase1.md`](cross-repo-discovery-phase1.md) — local, metadata-only Phase 1 discovery (no hosted plane).
+- [`operations-runbook.md`](operations-runbook.md) — SQLite concurrency, corruption recovery, multi-process collisions, post-upgrade migration ([#4875](https://github.com/JSONbored/gittensory/issues/4875)).
+- [`miner-goal-spec.md`](miner-goal-spec.md) — per-repo `.gittensory-miner.yml` targeting policy.
+- [`../DEPLOYMENT.md`](../DEPLOYMENT.md) — laptop vs fleet deployment and core miner invariants.

package/docs/env-reference.md

@@ -0,0 +1,30 @@
+# gittensory-miner environment variable reference
+
+Generated by `npm run miner:env-reference`. Do not edit manually.
+
+| Name | First reference | Default |
+| --- | --- | --- |
+| `GITTENSORY_MINER_AMS_POLICY_PATH` | `lib/ams-policy.js` | (none) |
+| `GITTENSORY_MINER_ATTEMPT_LOG_DB` | `lib/attempt-log.js` | (none) |
+| `GITTENSORY_MINER_CLAIM_LEDGER_DB` | `lib/claim-ledger.js` | (none) |
+| `GITTENSORY_MINER_CONFIG_DIR` | `lib/deny-hook-synthesis.js` | `""` |
+| `GITTENSORY_MINER_DENY_HOOK_SYNTHESIS_DB` | `lib/deny-hook-synthesis.js` | `""` |
+| `GITTENSORY_MINER_EVENT_LEDGER_DB` | `lib/event-ledger.js` | (none) |
+| `GITTENSORY_MINER_GOVERNOR_LEDGER_DB` | `lib/governor-ledger.js` | `""` |
+| `GITTENSORY_MINER_GOVERNOR_STATE_DB` | `lib/governor-state.js` | (none) |
+| `GITTENSORY_MINER_KILL_SWITCH` | `lib/config-precedence.js` | `""` |
+| `GITTENSORY_MINER_LOG_LEVEL` | `lib/logger.js` | `""` |
+| `GITTENSORY_MINER_NO_UPDATE_CHECK` | `lib/update-check.js` | `""` |
+| `GITTENSORY_MINER_ORB_EXPORT_DB` | `lib/orb-export.js` | `""` |
+| `GITTENSORY_MINER_PLAN_STORE_DB` | `lib/plan-store.js` | `""` |
+| `GITTENSORY_MINER_POLICY_DOC_CACHE_DB` | `lib/policy-doc-cache.js` | (none) |
+| `GITTENSORY_MINER_POLICY_VERDICT_CACHE_DB` | `lib/policy-verdict-cache.js` | (none) |
+| `GITTENSORY_MINER_PORTFOLIO_QUEUE_DB` | `lib/portfolio-queue.js` | (none) |
+| `GITTENSORY_MINER_PREDICTION_LEDGER_DB` | `lib/prediction-ledger.js` | `""` |
+| `GITTENSORY_MINER_REPLAY_SNAPSHOT_DB` | `lib/replay-snapshot.js` | (none) |
+| `GITTENSORY_MINER_REPO_CLONE_DIR` | `lib/repo-clone.js` | `""` |
+| `GITTENSORY_MINER_RUN_STATE_DB` | `lib/run-state.js` | (none) |
+| `GITTENSORY_MINER_VERSION` | `lib/version.js` | `""` |
+| `GITTENSORY_MINER_WORKTREE_ALLOCATOR_DB` | `lib/worktree-allocator.js` | `""` |
+| `GITTENSORY_MINER_WORKTREE_DIR` | `lib/worktree-allocator.js` | `""` |
+| `MINER_CODING_AGENT_PROVIDER` | `lib/laptop-init.js` | (none) |

package/docs/fleet-run-manifest.md

@@ -0,0 +1,50 @@
+# Fleet run-manifest
+
+The **fleet run-manifest** is the top-level config a *fleet operator* authors to run the miner across many repos
+at once: it declares which repos are in scope for a fleet run and how a finite worktree/concurrency budget is
+split between them. It is parsed by `parseFleetRunManifestContent` / `parseFleetRunManifest` in
+`@loopover/engine` (`packages/gittensory-engine/src/fleet-run-manifest.ts`).
+
+It is **not** the same file as `.gittensory-miner.yml` (see [`miner-goal-spec.md`](./miner-goal-spec.md)) — the
+naming is easy to conflate. Same tolerant-parser convention (every field optional, unknown keys ignored, a
+malformed field degrades to a documented default with a warning rather than throwing), but the opposite author
+and the opposite direction of intent:
+
+| | `.gittensory-miner.yml` (goal spec) | fleet run-manifest |
+|---|---|---|
+| **Author** | a target repo's maintainer | the miner (fleet) operator |
+| **Lives in** | the target repo | the operator's fleet-run config |
+| **Direction** | how this one repo wants to be approached | which repos to work across, and how to split the budget |
+| **Scope** | one repo | many repos in one run |
+| **Key fields** | `minerEnabled`, `wantedPaths`, `blockedPaths`, `preferredLabels`, `blockedLabels`, `maxConcurrentClaims`, `issueDiscoveryPolicy` | `repos` (each `owner/repo` + `maxConcurrentWorktrees`), `totalConcurrentWorktrees` |
+
+## Schema
+
+Every field is optional; unknown keys are ignored; a malformed field falls back to a documented default with a
+warning rather than hard-failing the run.
+
+- **`repos`** — a list of target repos. Each entry is either a bare `"owner/repo"` string (uses the default
+  per-repo budget) or a `{ repoFullName, maxConcurrentWorktrees }` mapping. Invalid or duplicate entries are
+  skipped with a warning. `repoFullName` is a canonical `owner/repo`, compatible with `opportunity-fanout.js`'s
+  target list. Default: `[]`.
+- **`repos[].maxConcurrentWorktrees`** — max concurrent worktrees (in-flight attempts) for that repo. A positive
+  integer (floored; sub-1 falls back to the default). Default: `1`.
+- **`totalConcurrentWorktrees`** — total concurrent worktrees across the whole fleet, regardless of per-repo
+  budgets. A positive integer. Default: `1`.
+
+## Wiring
+
+This module produces only the parsed, typed manifest. Driving the fleet concurrency allocator from it is the
+allocator's concern (sibling `feat(miner-concurrency): add git-worktree-per-attempt allocator` issue), and the
+cross-repo `portfolio-queue.js` backlog reads the same repo list — both *consume* this manifest; neither wiring
+lives here.
+
+## Example (`fleet-run.yml`)
+
+```yaml
+totalConcurrentWorktrees: 4
+repos:
+  - owner/repo-a
+  - repoFullName: owner/repo-b
+    maxConcurrentWorktrees: 2
+```

package/docs/miner-goal-spec.md

@@ -0,0 +1,76 @@
+# MinerGoalSpec (`.gittensory-miner.yml`)
+
+Per-repo configuration telling an autonomous Gittensory miner what to look for and how to behave when targeting a repo. Parsed by `@loopover/engine` (`parseMinerGoalSpec` / `parseMinerGoalSpecContent`); this document is the field reference. Machine-readable shape: [`../schema/miner-goal-spec.schema.json`](../schema/miner-goal-spec.schema.json). Copy [`.gittensory-miner.yml.example`](../../../.gittensory-miner.yml.example) to `.gittensory-miner.yml` and edit.
+
+Discovery order (first match wins):
+
+- `.gittensory-miner.yml`
+- `.github/gittensory-miner.yml`
+- `.gittensory-miner.json`
+- `.github/gittensory-miner.json`
+
+Every field is optional. Unknown keys are ignored; a malformed field falls back to its documented default with a warning — a broken file never hard-fails the miner.
+
+## Relationship to `.gittensory.yml`
+
+| File | Actor | Purpose |
+|------|-------|---------|
+| `.loopover.yml` (or legacy `.gittensory.yml`, dual-read indefinitely — #4773) | Review stack | How a maintainer's repo **reviews** incoming PRs (focus manifest, gate, scoring knobs). |
+| `.gittensory-miner.yml` | Miner runtime | How a miner **searches for and prioritizes** work in a target repo. Unrelated naming concern — not affected by the review-config rebrand above. |
+
+They are read by different components and do not conflict. A miner should still treat a target repo's public `.loopover.yml`/`.gittensory.yml` `wantedPaths` / `blockedPaths` as a hard floor when both files exist.
+
+## Fields
+
+### `minerEnabled` (boolean, default: `true`)
+
+Explicit opt-out: a public repo with no file remains minable. Set `false` to halt all miner targeting.
+
+### `wantedPaths` (string list, default: `[]`)
+
+Work areas the maintainer wants a miner to focus on. Glob list. Empty means no preference.
+
+### `blockedPaths` (string list, default: `[]`)
+
+Paths off-limits to a miner; candidates touching one should be skipped. Glob list. Mirrors `.gittensory.yml` `blockedPaths` semantics.
+
+### `preferredLabels` (string list, default: `[]`)
+
+Issue labels a miner should favor. Empty means no preference.
+
+### `blockedLabels` (string list, default: `[]`)
+
+Issue labels a miner must skip.
+
+### `maxConcurrentClaims` (integer `>= 1`, default: `1`)
+
+Maximum issues one miner may hold claimed on this repo at once.
+
+### `issueDiscoveryPolicy` (`encouraged` | `neutral` | `discouraged`, default: `neutral`)
+
+How strongly this repo encourages a miner to open discovery issues.
+
+### `feasibilityGate` (object, default: `{ enabled: true, suppressedReasons: [] }`)
+
+Per-repo tuning for the feasibility gate (`buildFeasibilityVerdict`) a miner consults before starting work. This is config-parsing surface only — a caller wiring the gate into a decision flow is responsible for reading and applying this policy.
+
+- `enabled` (boolean, default: `true`) — whether the feasibility gate is consulted at all before a miner starts work.
+- `suppressedReasons` (string list, default: `[]`) — specific avoid/raise reason codes (e.g. `duplicate_cluster_high`) this repo wants ignored.
+
+### `selfPlagiarism` (object, default: `{ similarityThreshold: 0.85 }`)
+
+Per-repo tuning for the Governor self-plagiarism throttle consulted before `open_pr` (#2345). Compares a prospective PR's diff fingerprint against the miner's own recent submission history.
+
+- `similarityThreshold` (number in `[0, 1]`, default: `0.85`) — Jaccard similarity at/above which two fingerprints read as near-duplicates across repos.
+
+### `killSwitch` (object, default: `{ paused: false }`)
+
+Per-repo kill-switch consulted by the Governor chokepoint before every write action (#2341). Distinct from `minerEnabled`: `minerEnabled` is a discovery-time opt-out (a miner never even considers the repo), while `killSwitch.paused` is a runtime halt of an already-in-flight queue — un-pausing resumes exactly where the queue left off. A separate, operator-controlled GLOBAL kill-switch (env var `GITTENSORY_MINER_KILL_SWITCH`) halts every repo at once and always wins over this per-repo flag.
+
+- `paused` (boolean, default: `false`) — halts all miner WRITE actions for this repo without deregistering it from targeting/discovery.
+
+### `execution` (object, default: `{ liveModeOptIn: null }`)
+
+Per-repo dry-run/live execution opt-in consulted by the Governor chokepoint (#2342). A freshly-configured miner always defaults to dry-run (observe/log only, never execute a write) — this field is the only per-repo path to live mode, and it alone is not sufficient: the miner's own operator must also separately opt in globally (env var `GITTENSORY_MINER_LIVE_MODE=live`) before writes actually execute. A repo that wants to guarantee it never receives live automated writes, regardless of any operator's global setting, should use `killSwitch.paused: true` instead — the kill-switch always takes precedence over any live-mode opt-in.
+
+- `liveModeOptIn` (string or `null`, default: `null`) — must equal EXACTLY the literal `"live"` to opt in. Any other value (a typo, `"yes"`, `"on"`, or a boolean `true` from a malformed file) is treated as not opted in — deliberately not a boolean flag, so a fat-fingered config can never accidentally enable live writes.

package/docs/miner-selfimprove-calibration.md

@@ -0,0 +1,105 @@
+# Miner self-improve — calibration, value-weighting, and the anti-farming boundary
+
+Phase 7's **contributor-safe** half — the drift detector, the calibration dashboard, the prediction ledger, the
+metrics exporter, the extension panel, and the confusion-matrix regression tests — is deliberately scoped to
+**read-only measurement and detection**. The half that actually *acts* on calibration data (bumps autonomy levels,
+tightens gate thresholds, adjusts per-contributor trust) is **maintainer-only** and lives behind a separate
+milestone.
+
+This note is for a contributor building against the contributor-safe tools. The single most important thing to
+understand is **where the line is and why** — because the natural instinct ("just wire the dashboard's accuracy
+number into an autonomy-level bump") is precisely the maintainer-only side of the phase, and a contributor-safe tool
+that could do it would defeat the safety it exists to provide.
+
+## What calibration measures
+
+The engine contract is `Phase7CalibrationLoopResult`
+([`packages/gittensory-engine/src/phase7-calibration-loop.ts`](../../gittensory-engine/src/phase7-calibration-loop.ts)):
+it combines the **historical-replay** composite score with the passive **`pr_outcome`** signal and tracks accuracy
+against the documented **`DOCUMENTED_CALIBRATION_BASELINE = 0.62`** (the 62% self-review baseline from the Phase 7
+roadmap). The engine owns the deterministic combine / freshness / threshold / hold-reason logic; the miner runtime
+owns scheduling replay runs and persisting ledger rows.
+
+The ground truth underneath is `computeGateEval`'s confusion matrix (`src/review/parity.ts`, `GateEvalRow`): per
+project, how many predictions were `wouldMerge` vs `wouldClose`, and how each resolved against the human decision —
+`mergeConfirmed` (predicted merge, human merged) vs **`mergeFalse` (predicted merge, human *closed* — the dangerous
+error)**, and symmetrically for close. `mergePrecision` / `closePrecision` are the headline accuracy numbers a
+dashboard renders.
+
+## The runner: wiring the replay scorer into the combine (#4248)
+
+`computePhase7CalibrationLoop` is a **pure combine contract** — by design it cannot schedule replay runs or read
+ledgers (the miner depends on the engine, not the reverse), so it waits for an external caller to feed it a real
+`historical_replay` composite. #3014 (PR #3225) shipped only that engine side; a 2026-07-08 audit found the closed
+issue claimed the two halves were "wired" when in fact **no miner-side runner ever called the replay scorer
+(`computeObjectiveAnchor`, #3012) and passed its result into the combine** — two finished pieces, never connected.
+
+[`lib/calibration-run.js`](../lib/calibration-run.js) (#4248) is that missing runner.
+`runHistoricalReplayCalibrationCycle` scores a completed replay run with the deterministic objective-anchor scorer,
+reduces the per-task scores to one composite `[0, 1]`, folds it into the `HistoricalReplayCalibrationInput` shape the
+engine expects, calls `computePhase7CalibrationLoop` with that **plus the existing `pr_outcome` signal**, and
+persists the combined snapshot as a `calibration_snapshot` event on the local append-only event ledger (the same
+typed-event-over-`event-ledger.js` pattern as `pr-outcome.js`). The persisted metric is queryable with
+`gittensory-miner ledger list --type calibration_snapshot` and via `readCalibrationSnapshots` /
+`latestCalibrationSnapshot`.
+
+Consistent with the boundary below, the runner is **read/measure-only**: it produces and persists the tracked
+metric but never acts on it (no autonomy bump, no threshold tune). Acting on the combined accuracy — the
+calibration-gated circuit-breaker — remains maintainer-only (#2352).
+
+## Value-weighting: durable correctness, not volume
+
+Raw merge/close precision is not the real objective, and a contributor reading a dashboard number should understand
+why. `GateEvalRow` also carries `weightedMergeConfirmed` / `weightedCloseConfirmed`: a prediction's credit is
+**discounted by `REVERSAL_DISCOUNT_WEIGHT` (currently `0` — full discount)** when its outcome was later reversed (a
+merge a human undid, or a bot-closed PR a contributor reopened). The denominator (`wouldMerge`) is unchanged — only
+the *credit* for a call that didn't hold up is removed. So the weighted precision measures **durable** correctness:
+a prediction that "won" on the day but was reverted a week later earns nothing. This is maintainer-owned prior work
+(#2348) that the contributor-safe tools *display*; they never recompute or re-weight it.
+
+## The maintainer-only line, and why it's drawn there
+
+Three maintainer-only concepts sit just past the boundary. A contributor-safe tool must never read or write any of
+them:
+
+- **Personalized tuning (#2349).** Per-actor confidence adjustment based on calibration history. A contributor-facing
+  surface that could *see or influence its own personalized-trust score* would defeat the entire point of it — so the
+  contributor-safe tools are, by construction, blind to it.
+- **Fleet anti-farming (#2350).** The whole phase is designed around gaming vectors from day one: inflating
+  merge-precision by only ever opening trivially-safe PRs, or farming duplicate-issue-claim elections. **Every
+  contributor-safe tool in this batch is read-only / local-only *because* a write-capable version of any of them
+  would be a farming vector** — the restriction is the design, not an arbitrary limitation. (The anonymization posture
+  for any telemetry that does leave an instance mirrors `src/selfhost/orb-collector.ts`'s HMAC-with-local-secret
+  approach.)
+- **Calibration-gated circuit-breaking (#2352).** `src/review/auto-tune.ts` already holds a self-tightening safety
+  breaker: when merge precision drops below a floor over a real sample, it **disables its own auto-merge (hold-only)
+  and alerts a human — it only ever makes itself MORE cautious, never loosens**, and a human clears it once fixed.
+  That breaker is the eventual consumer of miner-sourced calibration signal (via `computeGateEval`'s `source`
+  scoping), but the *enforcement* is maintainer-only. The contributor-safe tools only ever **produce read-only signal**
+  for that maintainer-owned system to act on.
+
+## What this phase does NOT do
+
+From any contributor-safe tool in this batch:
+
+- **No autonomy-level changes** — measuring accuracy never bumps an autonomy level (that gate is fail-closed and
+  maintainer-owned).
+- **No gate-threshold changes** — the dashboard/exporter/ledger surface numbers; they never tune the gate.
+- **No writes to maintainer-owned calibration or circuit-breaker state** — no touching personalized-trust scores, the
+  auto-tune hold-only flag, or any autonomy configuration.
+- **No de-anonymizing or write-capable telemetry** — local-only or HMAC-anonymized, read-only.
+
+## The neighborhood
+
+- Contributor-safe (this batch): drift detector, calibration dashboard + extension panel, prediction ledger, metrics
+  exporter, confusion-matrix regression tests — all read-only measurement.
+- Maintainer-only (cited for context, **not** to be reopened or reimplemented here): #2348 (value-weighted
+  calibration, merged), #2349 (personalized tuning), #2350 (fleet anti-farming), #2352 (wiring calibration accuracy
+  into the live auto-tune breaker).
+
+## References
+
+- [`packages/gittensory-engine/src/phase7-calibration-loop.ts`](../../gittensory-engine/src/phase7-calibration-loop.ts) — the calibration-loop contract + `DOCUMENTED_CALIBRATION_BASELINE`.
+- `src/review/parity.ts` — `GateEvalRow` (the confusion matrix) and `REVERSAL_DISCOUNT_WEIGHT` (value-weighting).
+- `src/review/auto-tune.ts` — the existing hold-only accuracy circuit-breaker (#2352's eventual consumer).
+- `src/selfhost/orb-collector.ts` — the anonymized HMAC-with-local-secret telemetry pattern.