Context
packages/loopover-engine/src/governor/ holds nine fully-implemented, pure, side-effect-free governor primitives, every one re-exported wholesale through the package barrel (src/index.ts has nine consecutive export * from "./governor/*.js" lines):
rate-limit.ts — rolling-window rate limiting + jittered backoff (5 exports)
budget-cap.ts — spend/turn budget ceiling calculator (5 exports)
self-plagiarism.ts — duplicate-submission detector (11 exports)
reputation-throttle.ts — self-reputation-driven throttling (8 exports)
write-rate-limit.ts — write-action rate limiting (13 exports)
run-halt.ts — non-convergence/budget/termination halt calculator (8 exports)
kill-switch.ts — global + per-repo emergency halt detector (6 exports)
action-mode.ts — action-mode resolution (8 exports)
chokepoint.ts — composes the above into one fail-closed allow/deny verdict (5 exports)
That's ~70 exported symbols, none of which have any dedicated README section. packages/loopover-engine/README.md has exactly one governor-related heading, ## Governor ledger, which documents the append-only storage contract (normalizeGovernorLedgerEvent) and explicitly says it "does not wire into live governor enforcement yet" — but the nine governor/*.ts modules above ARE the enforcement-decision calculators themselves (each one is a decided, shipped, well-commented pure function — e.g. kill-switch.ts's own header: "DETECTOR ONLY — no IO, no persistence... the Governor chokepoint's job... which consults this module first"). This is the largest coherent exported surface in the package with zero README narrative.
Requirements
- Add a
## Governor primitives section to packages/loopover-engine/README.md giving each of the nine modules a short paragraph: what it decides, its key exported type(s) (e.g. LocalRateLimitConfig/LocalRateLimitDecision, MinerKillSwitchScope), and how chokepoint.ts composes the other eight into one verdict ("safest wins" precedence, per its own header comment).
- Scope this as a concise per-module overview (mirroring the README's existing "Metadata opportunity signals" section's bullet-list style), not exhaustive per-function API docs — the goal is making the surface discoverable and pointing a reader at the right source file, not duplicating every JSDoc comment.
- Cross-reference the existing "Governor ledger" section so a reader understands how the ledger (storage) and the primitives (decision) relate.
Deliverables
Test Coverage Requirements
Docs-only change to packages/loopover-engine/README.md — outside coverage.include per codecov.yml (coverage is collected over src/**, packages/loopover-engine/src/**, packages/loopover-miner/lib/**, not *.md). No Codecov gate applies.
Expected Outcome
A reader of the engine package's README can discover that the governor primitives exist, understand each one's role at a glance, and know which source file to open for the full API — without first reading src/index.ts's barrel exports to realize this surface exists at all.
Links & Resources
packages/loopover-engine/src/governor/{rate-limit,budget-cap,self-plagiarism,reputation-throttle,write-rate-limit,run-halt,kill-switch,action-mode,chokepoint}.ts
packages/loopover-engine/src/governor-ledger.ts — the existing "Governor ledger" README section to cross-reference
packages/loopover-engine/test/{chokepoint,kill-switch,action-mode,run-halt-enforcement,self-plagiarism,write-rate-limit-enforcement}.test.ts — existing tests for reference when writing summaries
Context
packages/loopover-engine/src/governor/holds nine fully-implemented, pure, side-effect-free governor primitives, every one re-exported wholesale through the package barrel (src/index.tshas nine consecutiveexport * from "./governor/*.js"lines):rate-limit.ts— rolling-window rate limiting + jittered backoff (5 exports)budget-cap.ts— spend/turn budget ceiling calculator (5 exports)self-plagiarism.ts— duplicate-submission detector (11 exports)reputation-throttle.ts— self-reputation-driven throttling (8 exports)write-rate-limit.ts— write-action rate limiting (13 exports)run-halt.ts— non-convergence/budget/termination halt calculator (8 exports)kill-switch.ts— global + per-repo emergency halt detector (6 exports)action-mode.ts— action-mode resolution (8 exports)chokepoint.ts— composes the above into one fail-closed allow/deny verdict (5 exports)That's ~70 exported symbols, none of which have any dedicated README section.
packages/loopover-engine/README.mdhas exactly one governor-related heading,## Governor ledger, which documents the append-only storage contract (normalizeGovernorLedgerEvent) and explicitly says it "does not wire into live governor enforcement yet" — but the ninegovernor/*.tsmodules above ARE the enforcement-decision calculators themselves (each one is a decided, shipped, well-commented pure function — e.g.kill-switch.ts's own header: "DETECTOR ONLY — no IO, no persistence... the Governor chokepoint's job... which consults this module first"). This is the largest coherent exported surface in the package with zero README narrative.Requirements
## Governor primitivessection topackages/loopover-engine/README.mdgiving each of the nine modules a short paragraph: what it decides, its key exported type(s) (e.g.LocalRateLimitConfig/LocalRateLimitDecision,MinerKillSwitchScope), and howchokepoint.tscomposes the other eight into one verdict ("safest wins" precedence, per its own header comment).Deliverables
## Governor primitivesREADME section covering all ninegovernor/*.tsmodules, each with a one-paragraph summary + key typeschokepoint.ts's composition role and its "safest wins" precedence over the other eightTest Coverage Requirements
Docs-only change to
packages/loopover-engine/README.md— outsidecoverage.includepercodecov.yml(coverage is collected oversrc/**,packages/loopover-engine/src/**,packages/loopover-miner/lib/**, not*.md). No Codecov gate applies.Expected Outcome
A reader of the engine package's README can discover that the governor primitives exist, understand each one's role at a glance, and know which source file to open for the full API — without first reading
src/index.ts's barrel exports to realize this surface exists at all.Links & Resources
packages/loopover-engine/src/governor/{rate-limit,budget-cap,self-plagiarism,reputation-throttle,write-rate-limit,run-halt,kill-switch,action-mode,chokepoint}.tspackages/loopover-engine/src/governor-ledger.ts— the existing "Governor ledger" README section to cross-referencepackages/loopover-engine/test/{chokepoint,kill-switch,action-mode,run-halt-enforcement,self-plagiarism,write-rate-limit-enforcement}.test.ts— existing tests for reference when writing summaries