Manage · Governance
Verify governance evidence before reading the posture
RepoOps composes each tracked repository's ledger chain, redaction mode, coding-agent policy, and protected-path changes into one local view. Start with verification and coverage, then interpret a clean count or export an evidence bundle.
For: the repository operator checking local controls, and the team owner or admin reading the separate hosted budget and integrity rollup
What it does, and why it helps
Governance reads four local signals for every tracked repository. Ledger verifies the HMAC chain beside captured telemetry. Redaction reports the effective capture mode and any team-pinned floor. Policy counts configured coding-agent rules and journaled violations. File integrity compares watched paths in the working tree with the repository's canonical branch. A failed signal stays failed or unknown; it is not painted as an empty result.
The page also assembles per-change evidence packs, maps present signals to named control frameworks, shows a live What leaves my machine disclosure, and reports detector promotion evidence and nightly semantic-hold coverage. These views answer different questions. A verified chain speaks to the journal structure. A compliance row speaks to evidence present for one control. A zero incident count says little when zero turns were examined.
The pain. A clean count can mean the evidence passed, the evidence was absent, or the reader never ran. Those states need different decisions.
The point of view. Verify the chain and check coverage before reading the posture. Treat every missing fragment, unexamined turn, and unevidenced control as a named gap rather than an implied pass.
What gets easier. Review. One local page ties the chain result to redaction, policy, protected-path changes, live egress state, per-change fragments, and detector evidence.
When it helps. Use it before an audit handoff, after a suspected telemetry edit, before promoting a detector, or when a security reviewer asks what this installation sends.
Its limits. The local chain uses a key stored with the repository journal. It detects accidental or casual tampering and corruption. A determined developer with the key can recompute it. Server witness records provide the separate off-machine layer when configured.
Understand it in 30 seconds
Read the narration
- 0:00 A green posture can hide a ledger nobody verified or evidence never captured.
- 0:06 Start with coverage and chain integrity, then interpret policy, egress, and alerts.
- 0:13 RepoOps shows each repository's ledger, redaction and policy violations.
- 0:18 Then file changes, egress paths and semantic-hold turns.
- 0:23 Export local evidence only after every missing or unmeasured state has a name.
Synthetic example. Read the guide
Where to find it
Where to find it
- Desktop:
localhost:4000, then Local settings in the sidebar, then Governance under Workspace utilities. - Hosted:
repoops.ai/team/governance, from Team & settings in the sidebar, then Governance under Account and access. - Keyboard: ⌘ K, then type “Governance”.
When to use it
Check whether the local telemetry journal still verifies
Situation. An operator needs to distinguish an intact journal from a missing chain or a broken sequence across several tracked repositories.
What you do. Open Governance and select Verify entire ledger. Read each repository result rather than relying only on the cross-repository banner.
What you see. Each row reports Verified, Broken, or Not started, plus the verified position, break position, reason, and chain head where available.
What it establishes. You have a fresh local verification result. A verified result supports accidental-tamper and corruption detection within the stated key model; it is not proof against a developer who controls the journal and its key.
Prepare a local audit handoff
Situation. A reviewer needs repository posture or the record around one AI-authored change, including an honest account of missing evidence.
What you do. Use Export governance evidence (local) for cross-repository posture. For change evidence, choose the repository, select Assemble evidence packs, inspect every fragment and control row, then use Export evidence pack (local).
What you see. The posture bundle carries the overview, verification summary, policy snapshot, and chain-head watermark. A change pack lists ticket, PR, review, deploy, and attestation fragments, with missing items shown as gaps.
What it establishes. The running project folder receives a local JSON artifact. The watermark ties it to the chain head read at export time; it does not fill a fragment that the local stores lack.
Decide whether a detector may advance
Situation. A detector has fired enough times to review whether advisory behavior should move to warn or enforcing.
What you do. In Enforcement ramp, record False positive when the detector was wrong and Correct when it was right. Promote only when the row offers the action.
What you see. The row shows Detector, Mode, False-positive rate, Samples, Promotion, and Record an outcome. Promotion appears after at least 20 recorded outcomes with a rate at or under 5 percent.
What it establishes. The local policy bundle advances that detector by one rung. Promotion is manual, and a later synced policy bundle can set another mode.
Before you start
- Supported versions
- RepoOps desktop v0.3.1, the release this guide was read against.
- Where it runs
- Local: Local settings, Workspace utilities, Governance. Hosted: /team/governance is a separate owner/admin rollup for company scope, budget periods, developer activity, telemetry-integrity alerts, watched paths, and plan-gated control coverage.
- Permissions
- Local reads and exports require access to the running RepoOps installation and its tracked repositories. The hosted rollup requires a signed-in team owner or admin. Hosted company rollup and the control matrix require Enterprise entitlement.
- Connections
- No provider connection is needed for the local overview, verification, or exports. Hosted rows require activity previously streamed by bound devices. A local deploy fragment appears only when its adapter has recorded a production deploy event.
- Plan
- The local Governance surface has no plan gate. The hosted manager rollup is role-gated, and its company rollup and AI controls and compliance matrix are Enterprise capabilities.
Configure it
- Establish what has been measured.
Read every repository row and Nightly semantic-hold coverage. No tracked repositories, no chain yet, an unknown signal, and zero examined turns are evidence states, not clean findings.
- Verify the ledger now.
Verify entire ledger reads each active chain without caching the cryptographic verdict. A stale green result would be a false statement about current bytes.
- Read egress from live settings.
What leaves my machine groups never-leaves, opt-in and redacted, and default-on paths. Refresh disclosure before handing it to a reviewer, and inspect the post-redaction preview when present.
- Assemble before exporting.
Choose the repository and optional vertical, assemble the packs, then read every fragment, validation result, covered control, asserted control, and gap. Export records the state you saw; it does not repair it.
| Setting | Where | A sensible choice | Why it matters |
|---|---|---|---|
telemetry.capture_mode | Governance, Redaction; changed in Settings, Telemetry privacy | metadata (the default); content is available unless the team pins metadata | The overview reports the effective mode, while the egress disclosure reports what that mode makes eligible to leave. |
REPOOPS_LEDGER_ROTATE_MB | the process environment | 64 MB (the default); a positive number overrides it | Bounds the active chain file. Rotation writes compressed archive segments and a signed checkpoint rather than deleting the history. |
blockSecretExfil | config/agent-policy.json | true by default | Makes secret exfiltration one of the active policy rules counted in the overview. |
enforce.secret-exfil | config/agent-policy.json, base policy | On by default for the hard-tier rule; only the base policy can set it false | Controls whether a matching secret-exfil policy violation blocks rather than appearing only as preview. |
policy bundle detector mode | Governance, Enforcement ramp | advisory on a fresh installation; promote manually to warn, then enforcing | A detector needs 20 recorded outcomes and a false-positive rate at or under 5 percent before the page offers promotion. |
REPOOPS_ATTESTATION | the process environment | On unless set to 0 | Controls best-effort attestation emission. An empty store still yields an empty evidence-pack set rather than a fabricated record. |
REPOOPS_DEEP_CAPTURE | the process environment or Settings, prompt and response recording | Off unless set to 1 | Nightly semantic-hold analysis can examine tool-call sequences only when the required turn content was captured. |
REPOOPS_SEMGREP_CONFIG | the process environment; reported under What leaves my machine | auto when unset; set a local rule file or pinned ruleset to avoid the automatic registry lookup | The agent code scan runs locally, but the auto configuration fetches rules and sends Semgrep's own usage metrics when a scan runs. |
What you should see
Every tracked chain verifies
Configuration. Each tracked repository has a present chain whose signatures, sequence, event hashes, archives, and checkpoint pass the current verifier.
Expect. The banner says all tracked repository ledgers verified clean and shows a shortened chain head. Each Ledger cell reads Verified.
Verify. Run Verify entire ledger and retain the per-repository heads. Keep the local threat-model limit with the result; this is not a claim against a determined key holder.
A chain or signal cannot support a clean claim
Configuration. A journal is missing or broken, a signal read fails, or the nightly semantic pass examined zero turns.
Expect. The page renders Not started, Broken, unknown, a failed-read banner, or examined nothing. It does not turn those states into a clean result.
Verify. Read the reason and the coverage count. Repair the input or collect the required data before treating a later result as measured.
Hosted manager rollup has no streamed activity
Configuration. A team owner or admin opens /team/governance before any device has streamed telemetry.
Expect. Telemetry integrity alerts reads not evaluated yet, no telemetry streamed. Developer activity reads No developer activity this month.
Verify. Do not read the missing alert count as zero. Confirm a device binding and the relevant local publishing controls before expecting hosted data.
Data and cost
- What is captured
- The local view reads the per-repository telemetry chain and key under .claude/brain/claude-code-usage, the agent policy, journaled policy violations, redaction state, working-tree path changes, attestation and transparency-log records, detector outcome meters, and captured-turn coverage. It creates no new telemetry when opened.
- Who can see it
- Local overview rows, working-tree change findings, and exported JSON files stay on the machine. The hosted rollup reads team-scoped streamed activity and audit records. It counts sensitive-path patterns from policy, but working-tree breach details stay local because the tree is not uploaded.
- How long it is kept
- Not provided as a time window for the local governance journal or exported bundles. The active chain rotates at 64 MB by default into compressed archives with a checkpoint. The page provides no purge action for those files or hosted audit history.
- What leaves the machine
- The overview, verification, assembly, and local exports make no provider call. What leaves my machine derives the current network posture from the same resolvers used by each path. Export writes to the running project folder and does not upload the file.
- What it costs
- No model call and no provider charge for the local page, cryptographic verification, evidence assembly, or export. The work is local file reads, git reads, hashing, validation, and JSON writes.
When the result differs
| Symptom | Likely cause | Next action |
|---|---|---|
| The overview says Not started. | That repository has no ledger chain yet. No captured batch has created the first entry. | Confirm the repository is tracked and capture has produced telemetry. Then run Verify entire ledger again. |
| Verification reports a break. | A signature, sequence, event cross-check, archive, or checkpoint failed, or the current per-repository key does not match an older chain. | Preserve the files and inspect the returned break position and reason. Do not export the broken state as verified evidence. |
| An evidence pack shows a missing fragment. | The local merged-PR history, closing keyword, review mirror, deploy events, or attestation store has no matching record for that change. | Check the named source. Leave the gap visible if no source record exists; assembling again cannot infer it. |
| A detector has a low displayed rate but no Promote button. | It has fewer than 20 recorded outcomes, is already enforcing, or its measured false-positive rate is above 5 percent. | Record each real outcome as False positive or Correct. Wait for enough measured samples rather than editing the displayed rate. |
| Hosted integrity reads not evaluated yet. | The team has no streamed telemetry batches, so the hosted audit trail cannot support an integrity count. | Check the bound device and local publishing path. Keep the hosted state as unmeasured until data arrives. |
- Disable
- Not provided for the whole feature. Stop individual producers and egress paths at their named settings; the read surface itself has no disable control.
- Roll back
- Detector policy rollback is provided outside this page through the versioned policy workflow and its disarm rollback command. Not provided for a ledger verification result, evidence bundle, or exported change pack; those are snapshots of observed state.
- Revoke access
- Not provided. Local verification and exports use no feature credential. Revoke a team device or provider connection at the connection that created the hosted or external path.
- Delete
- Not provided. Governance has no purge route for the chain, archives, attestations, outcome meter, exported JSON, or hosted audit rows. A local export is an ordinary file in the running project folder and must be removed outside RepoOps.
Related tasks
Maintenance evidence
- Feature id
governance(spine leafgovernance)- Owner
- Local-first cryptographic governance, Governance rollup Phase 6, and Cloud-Native Accountability programs; Guide: LDG-0717
- Supported product version
- RepoOps v0.3.1
- Last verified
- 2026-09-15, read against origin/main at 52366bb6d; labels read from the served tab source; local cryptographic routes, compliance assembly, egress disclosure, and hosted manager rollup also checked
- Example fixtures
- lib/governance-overview.test.mjs; lib/ledger-chain.test.mjs; test/governance-overview-errors.test.mjs; lib/compliance/evidence-pack.test.mjs; lib/compliance/framework-map.test.mjs; lib/egress-disclosure.test.mjs; test/enforcement-ramp-promote-route.test.mjs; website/lib/governance.test.ts; website/app/team/(home)/governance/page.test.tsx
- Source references
lib/canonical-spine.json,lib/canonical-tabs.mjs,public/governance.html,lib/routes/governance.mjs,lib/governance-overview.mjs,lib/ledger-chain.mjs,lib/agent-policy.mjs,lib/file-integrity.mjs,lib/routes/compliance.mjs,lib/compliance/evidence-pack.mjs,lib/attestation/attestation.mjs,lib/routes/egress.mjs,lib/egress-disclosure.mjs,lib/enforcement-ramp.mjs,website/app/team/(home)/governance/page.tsx,website/lib/governance.ts- Documentation review
- Independent review requested on the slice pull request; not yet recorded.
- Video review
- Narrated story rendered and published 2026-09-26 (render f0c1e8c108a1, LDG-1018) with the breadcrumb Local settings, checked against main at 0f24215b5. One frame, the captions and the transcript were reviewed by the authoring agent, not an independent reviewer; the audio was not listened to by a person. Narration is the provisional Windows voice until LDG-0721.
Last updated