Docs: data-boundary contract v1 in EGRESS.md, guarded, with the egress tests running in CI by vivekchand · Pull Request #5958 · vivekchand/clawmetry

vivekchand · 2026-09-13T23:48:58Z

Refs vivekchand/clawmetry-landing#744

Product record: https://factory.8090.ai/project/b415065f-ab2f-4f53-8864-0c009fd098cb/requirements/293c9122-ce60-4809-bb00-887acef0b414 (REQ-DBC-001, AC-DBC-005.3)

Why

The public site's storage and egress claims were wrong in ways a security reviewer would find on the wire: "cloud off: no network destination", "we never store the raw key", "the key never leaves your machine". docs/EGRESS.md is the inventory those pages summarise, and it carried one of the same errors itself ("the key never leaves your machine") while also saying the key is handed to the browser.

What

docs/EGRESS.md: data-boundary contract version 1. Cloud sync off (CLAWMETRY_NO_CLOUD=1, onboard --local) is not offline. DO_NOT_TRACK=1 stops the install ping and failure report but not the PyPI check; CLAWMETRY_OFFLINE=1 stops every discretionary request. Adds the hosted ingest push row (readable, not sealed). States that the cloud stores the account key alongside its hash and that it cannot decrypt. Replaces "Data that never leaves the machine" with "Data ClawMetry does not store" and lists where the encryption key actually travels: browser (URL fragment), paired desk device (sealed to its key), and the cloud during a web-dashboard key rotation (/api/account/secret-key relays the caller-supplied key through the node command queue).
tests/test_data_boundary_contract.py (7 tests): cloud sync off stops uploads, but the install ping, failure report and PyPI check are still reached; a telemetry opt-out stops the ping and failure report only; offline stops every discretionary request; content endpoints refuse without a key; EGRESS.md carries the contract and no longer says the key never leaves the machine.
.github/workflows/ci.yml: the new file plus tests/test_egress_suppression.py and tests/test_telemetry.py. Neither existing file was named in any job, so the offline and opt-out guards had never run in CI.

No product code changes. No new routes, so no cloud route-policy entry is needed.

Verified

pytest tests/test_data_boundary_contract.py tests/test_egress_suppression.py tests/test_telemetry.py: 81 passed (Python 3.11 venv, scratch HOME).
Regression guard proven: with main's docs/EGRESS.md restored, test_egress_doc_declares_the_contract fails (1 failed, 6 passed); with this change, 7 passed.
tests/test_workflow_yaml_valid.py and tests/test_ci_workflow_invocations_are_real.py: 595 passed.

Paired PR

Landing copy that consumes this contract, with its own claims guard: https://github.com/vivekchand/clawmetry-landing/pull/824

🤖 Generated with Claude Code

https://claude.ai/code/session_01Jm9d7s4fN55hN3YzQo75o9

8090-software-factory · 2026-09-13T23:50:10Z

✅ Drift Bot (ClawMetry): no drift detected

Drift Bot analyzed the changed files against this project's blueprints and requirements and found no drift.

8090-software-factory · 2026-09-14T00:41:37Z

✅ Drift Bot (ClawMetry): no drift detected

Drift Bot analyzed the changed files against this project's blueprints and requirements and found no drift.

8090-software-factory · 2026-09-14T06:21:11Z

✅ Drift Bot (ClawMetry): no drift detected

Drift Bot analyzed the changed files against this project's blueprints and requirements and found no drift.

8090-software-factory · 2026-09-14T07:03:22Z

✅ Drift Bot (ClawMetry): no drift detected

Drift Bot analyzed the changed files against this project's blueprints and requirements and found no drift.

8090-software-factory · 2026-09-14T12:25:01Z

✅ Drift Bot (ClawMetry): no drift detected

Drift Bot analyzed the changed files against this project's blueprints and requirements and found no drift.

vivekchand · 2026-09-14T12:37:52Z

Non-mergeable PR sweeper — run summary (2026-09-14)

vivekchand/clawmetry

Rebased (13 PRs):
#5958 (docs/egress-contract-744), #5957 (fix/cold-load-timeouts-5935), #5114 (feat/has-capacity-batch), #5953 (fix/otlp-spans-guard-redaction), #5950 (feat/fleet-install-vdi-5942), #5959 (feat/price-book-azure-aliases-5936), #5963 (feat/otlp-durable-ack), #5968 (feat/project-attribution-budgets-5941), #5970 (feat/selfhost-signed-image-5948), #5971 (feat/agent-supply-chain-inventory), #5962 (feat/guard-prompt-injection-detector), #5965 (feat/litellm-integration-5940), #5972 (feat/otel-langgraph-recipe-5939)

Skipped — not conflicted (mergeable_state ≠ dirty):
#5967, #5933, #5916, #5204, #5684, #5676, #2440

Skipped — bot/auto-generated:
#5960 (github-actions[bot])

Comment-only (aborted — non-trivial): none

vivekchand/clawmetry-landing

Rebased (1 PR):
#833 (blog/tool-calls-returned-200-broke-everything)

Skipped: none

vivekchand/clawmetry-cloud

No open conflicted PRs found.

Conflict resolution approach used throughout:

CHANGELOG.md: keep both sides (additive entries)
docs/acceptance_criteria.json: keep both sides; fix missing commas introduced at merge boundaries
docs/MODULE_MAP.md, docs/ac_coverage_baseline.json, docs/ci_test_coverage_baseline.json: keep HEAD (generated files — main's counts are authoritative)
clawmetry/framework_map.py, docs/FRAMEWORK_COVERAGE.md, tests/test_guard_framework_map.py: keep HEAD (main's reviewed and merged version; stale copies in PR branches discarded)
clawmetry/sync.py dict fields: keep both (independent additive fields)

Generated by Claude Code

8090-software-factory · 2026-09-14T13:14:10Z

✅ Drift Bot (ClawMetry): no drift detected

Drift Bot analyzed the changed files against this project's blueprints and requirements and found no drift.

8090-software-factory · 2026-09-14T18:09:10Z

✅ Drift Bot (ClawMetry): no drift detected

Drift Bot analyzed the changed files against this project's blueprints and requirements and found no drift.

vivekchand · 2026-09-14T18:17:38Z

Updated to current main via update_pull_request_branch (was behind by ~15 commits).

Generated by Claude Code

vivekchand · 2026-09-14T18:49:44Z

Test plan & review notes

Repo: vivekchand/clawmetry
What changed

docs/EGRESS.md: data-boundary contract v1 — corrects wrong claims ("cloud off = offline", "key never leaves the machine"), adds the CLAWMETRY_OFFLINE=1 vs DO_NOT_TRACK=1 distinction, documents where the encryption key actually travels (browser URL fragment, paired desk device, cloud during key rotation via /api/account/secret-key)
tests/test_data_boundary_contract.py (7 tests, new): machine-readable guard on the contract wording — regression test fails if EGRESS.md is reverted
.github/workflows/ci.yml: adds test_data_boundary_contract.py, test_egress_suppression.py, and test_telemetry.py to the CI matrix (the existing suppression and telemetry tests were never running in CI before this PR)

Smoke commands

# All three test files:
python -m pytest tests/test_data_boundary_contract.py tests/test_egress_suppression.py tests/test_telemetry.py -v

# Regression proof (confirm the guard works):
git stash        # temporarily restore main's EGRESS.md
python -m pytest tests/test_data_boundary_contract.py -v  # should fail on test_egress_doc_declares_the_contract
git stash pop

# CI workflow sanity (confirms the new job steps reference real test files):
python -m pytest tests/test_workflow_yaml_valid.py tests/test_ci_workflow_invocations_are_real.py -v

Things to check

CLAWMETRY_OFFLINE=1 vs CLAWMETRY_NO_CLOUD=1 vs DO_NOT_TRACK=1: the doc now distinguishes them — verify the contract matches clawmetry/sync.py and clawmetry/cli.py behaviour for each flag
The key-rotation relay via /api/account/secret-key is documented as a path where the key travels through cloud. Verify this matches the actual routes/meta.py or equivalent relay code.
Paired landing PR (clawmetry-landing#824) consumes these claims — worth checking both land together to avoid the public site reading ahead of or behind this contract.

Likely failure modes

test_egress_suppression.py and test_telemetry.py being added to CI for the first time means any pre-existing flakiness in those files now fails CI. Run them in isolation on main to confirm they're green before merge.
CLAWMETRY_OFFLINE=1 env var: test_data_boundary_contract.py likely sets this and checks that specific endpoints are not reached — if the env var name changed or is checked inconsistently, the test could give a false green.

Issue link
Refs REQ-DBC-001 / AC-DBC-005.3. The paired landing PR (clawmetry-landing#824) should merge together with this one.

Generated by Claude Code

vivekchand · 2026-09-15T03:09:50Z

✨ auto-fixed: merged main into branch (was BEHIND)

Generated by Claude Code

8090-software-factory · 2026-09-15T03:10:07Z

✅ Drift Bot (ClawMetry): no drift detected

Drift Bot analyzed the changed files against this project's blueprints and requirements and found no drift.

…ress tests in CI Cloud sync off is not offline: it stops uploads, while the install ping, the failure report and the PyPI check still run until CLAWMETRY_OFFLINE=1. EGRESS.md now says so as a versioned contract, states how the cloud stores the account key, and stops claiming the encryption key never leaves the machine: it reaches the browser, a paired device and, during a dashboard rotation, the cloud. tests/test_data_boundary_contract.py pins that behaviour. The existing test_egress_suppression.py and test_telemetry.py were named in no CI job; they now run in the MOAT verifier job alongside it. Refs vivekchand/clawmetry-landing#744 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Jm9d7s4fN55hN3YzQo75o9

vivekchand · 2026-09-15T03:46:29Z

PR sweeper: mergeable_state: blocked with all CI skipped by queue-priority and C6 Required-status-checks gate: success. The blocking is not a CI failure — it appears to be a required-review rule (human approval needed). This is an author-decision blocker; no code change is required to unblock it.

Generated by Claude Code

8090-software-factory · 2026-09-15T03:46:55Z

✅ Drift Bot (ClawMetry): no drift detected

Drift Bot analyzed the changed files against this project's blueprints and requirements and found no drift.

8090-software-factory · 2026-09-15T07:01:24Z

✅ Drift Bot (ClawMetry): no drift detected

Drift Bot analyzed the changed files against this project's blueprints and requirements and found no drift.

8090-software-factory · 2026-09-15T08:09:56Z

✅ Drift Bot (ClawMetry): no drift detected

Drift Bot analyzed the changed files against this project's blueprints and requirements and found no drift.

vivekchand force-pushed the docs/egress-contract-744 branch from b4872cb to e8b7b05 Compare September 14, 2026 06:20

vivekchand force-pushed the docs/egress-contract-744 branch from 6c1ed8d to abd8983 Compare September 14, 2026 12:23

vivekchand force-pushed the docs/egress-contract-744 branch from abd8983 to 8987304 Compare September 14, 2026 13:13

vivekchand force-pushed the docs/egress-contract-744 branch from 9b80e13 to cf80c9c Compare September 15, 2026 03:46

Merge remote-tracking branch 'origin/main' into docs/egress-contract-744

3da2b65

vivekchand merged commit a9451c8 into main Sep 15, 2026
41 checks passed

Conversation

vivekchand commented Sep 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Why

What

Verified

Paired PR

Uh oh!

8090-software-factory Bot commented Sep 13, 2026

✅ Drift Bot (ClawMetry): no drift detected

Uh oh!

8090-software-factory Bot commented Sep 14, 2026

✅ Drift Bot (ClawMetry): no drift detected

Uh oh!

8090-software-factory Bot commented Sep 14, 2026

✅ Drift Bot (ClawMetry): no drift detected

Uh oh!

8090-software-factory Bot commented Sep 14, 2026

✅ Drift Bot (ClawMetry): no drift detected

Uh oh!

8090-software-factory Bot commented Sep 14, 2026

✅ Drift Bot (ClawMetry): no drift detected

Uh oh!

vivekchand commented Sep 14, 2026

Non-mergeable PR sweeper — run summary (2026-09-14)

vivekchand/clawmetry

vivekchand/clawmetry-landing

vivekchand/clawmetry-cloud

Uh oh!

8090-software-factory Bot commented Sep 14, 2026

✅ Drift Bot (ClawMetry): no drift detected

Uh oh!

8090-software-factory Bot commented Sep 14, 2026

✅ Drift Bot (ClawMetry): no drift detected

Uh oh!

vivekchand commented Sep 14, 2026

Uh oh!

vivekchand commented Sep 14, 2026

Test plan & review notes

Uh oh!

vivekchand commented Sep 15, 2026

Uh oh!

8090-software-factory Bot commented Sep 15, 2026

✅ Drift Bot (ClawMetry): no drift detected

Uh oh!

vivekchand commented Sep 15, 2026

Uh oh!

8090-software-factory Bot commented Sep 15, 2026

✅ Drift Bot (ClawMetry): no drift detected

Uh oh!

8090-software-factory Bot commented Sep 15, 2026

✅ Drift Bot (ClawMetry): no drift detected

Uh oh!

8090-software-factory Bot commented Sep 15, 2026

✅ Drift Bot (ClawMetry): no drift detected

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

vivekchand commented Sep 13, 2026 •

edited

Loading