Merge Batch A: CI signal per commit (#44) and the main-checkout guard (#37)

Two guardrails on the path that deploys and verifies everything else, landed
first so later batches inherit them: each main commit now gets its own CI run,
and replicator.service refuses to start on any checkout but main.

Includes CR round 1 (#1-#8) and the AGENTS.md curation that took the policy file
from 6031 back to 5890 against its 6000 budget.

Closes #44
Closes #37

Author: gregoryfoster

.github/workflows/ci.yml

@@ -10,10 +10,17 @@ on:
 permissions:
   contents: read
 
-# Cancel superseded runs on the same PR; never cancel runs on main (keep
-# CI signal for every commit that lands on the protected branch).
+# Two mechanisms, one per event kind:
+#   - PR runs share a group per branch (`github.head_ref` is non-empty only on
+#     `pull_request`), and `cancel-in-progress` cancels the superseded one.
+#   - Everything else (`push`, `workflow_dispatch`) is keyed on `github.sha`,
+#     unique per commit, so each `main` run sits alone in its own group.
+# The second is not redundant with the first. A group holds at most one
+# *pending* run regardless of `cancel-in-progress`, so under one branch-keyed
+# group a third push evicts the second's queued run before it ever starts —
+# a commit lands on the protected branch with no CI signal at all (#44).
 concurrency:
-  group: ${{ github.workflow }}-${{ github.head_ref || github.ref }}
+  group: ${{ github.workflow }}-${{ github.head_ref || github.sha }}
   cancel-in-progress: ${{ github.event_name == 'pull_request' }}
 
 jobs:

.gitignore

@@ -42,8 +42,15 @@ coverage.xml
 *.swp
 *.swo
 
-# Git worktrees
+# Git worktrees. Two roots, because two things provision them: the
+# using-git-worktrees scripts resolve to <repo>/.worktrees/, and the Claude Code
+# Agent harness (isolation: "worktree") provisions into .claude/worktrees/.
+# Both are ignored so that `git status --porcelain` on the main checkout stays
+# empty while agents run — that emptiness is the orchestrator's tripwire for an
+# agent falling through into the deployment checkout, and a tripwire that fires
+# on every clean run is one nobody reads.
 .worktrees/
+.claude/worktrees/
 
 # Runtime (BUILD_ID stamp target — the systemd unit writes /run/replicator/build-id)
 /run/

.skills/context-loss-ok

@@ -0,0 +1,3 @@
+# 2026-08-17 curation (#47). Two lines rewritten because a command refuted them.
+disproven :: Auth is ADC: on the VM the SA key at `GOOGLE_APPLICATION_CREDENTIALS` (`/etc/replicator/co-pypi-reader.json`), in CI a keyless WIF token. Pin the current minor
+disproven :: enforces eight charter invariants in CI; change a

.skills/context-metrics.jsonl

@@ -2,3 +2,5 @@
 {"actions": ["split:content-fetch-issuer-contract", "relocate:Settled->docs/plans", "restructure:payload headings", "index:Where the rest lives", "reindex:context-artifacts"], "budget": 6000, "bytes": 14582, "delta_days": 0, "delta_tokens": 123, "docs_orphaned": 0, "docs_total": 10, "file": "AGENTS.md", "lines": 234, "links_dead": 0, "no_loss": "ok", "note": "#24 doc split: issuer contract 14772->9966, new reference 7349; every live doc under the 10k per-doc budget", "over_budget": false, "repo": "replicator", "skill_commit": "3fc7b71", "skill_version": "1.2", "tokens": 5896, "tokens_exact": true, "tokens_live": 54697, "top_section": "Code Exploration Policy", "top_section_share": 18, "ts": "2026-08-06"}
 {"actions": ["prune:Code Exploration Policy prefetch query (dup of SessionStart hook)", "add:content-replicate-issuer-contract"], "budget": 6000, "bytes": 14651, "delta_days": 5, "delta_tokens": -24, "docs_orphaned": 0, "docs_total": 11, "file": "AGENTS.md", "lines": 236, "links_dead": 0, "no_loss": "failed", "note": "prefetch select: string dropped from AGENTS.md — verbatim duplicate of the SessionStart hook in .claude/settings.json; issuer-reference was never over budget (guard estimate ran 9.4% high vs exact)", "over_budget": false, "repo": "replicator", "skill_commit": "3fc7b71", "skill_version": "1.2", "tokens": 5872, "tokens_exact": true, "tokens_live": 66108, "top_section": "Bus Conventions", "top_section_share": 19, "ts": "2026-08-11"}
 {"actions": ["split:ARCHITECTURE->CONVENTIONS", "split:Code Exploration Policy->SOCRATICODE (skills#115)", "relocate:Why the issuer renders->docs/plans", "demote:test-layout->TESTING", "demote:founding-design->ARCHITECTURE", "rescue:repo-authored notes outside marker pair", "tighten:Bus Conventions", "prune:dup env-load snippet", "index:CONVENTIONS.md+SOCRATICODE.md", "reindex:context-artifacts"], "budget": 6000, "bytes": 14489, "delta_days": 4, "delta_tokens": -26, "docs_orphaned": 0, "docs_total": 13, "file": "AGENTS.md", "lines": 248, "links_dead": 0, "no_loss": "failed", "note": "GH #35, CR rounds 1-2 (findings 1-12). Issue premise partly refuted: replicator-boundaries.md 9152 exact, 848 UNDER — the guard estimator runs +13.5% high on contract docs because the ratio is fitted to the policy file alone (skills#172). Genuinely over and unlisted in the issue: ARCHITECTURE.md 11075 and AGENTS.md itself 6349. Code Exploration Policy brought onto init-socraticode's post-#115 Variant A shape (935 -> 446 tok); vendored pin 3fc7b71 predates that split, so a re-run before #41 reverts the block — recorded in docs/SOCRATICODE.md's header. Manifest description de-coupled from positional doc lists to stop it rotting. All prove-no-loss lines warranted: template-owned block regenerated, duplications, or reflows.", "over_budget": false, "repo": "replicator-ctx35", "skill_commit": "3fc7b71", "skill_version": "1.2", "tokens": 5846, "tokens_exact": true, "tokens_live": 74795, "top_section": "Bus Conventions", "top_section_share": 24, "ts": "2026-08-15"}
+{"actions": ["baseline:pre-curation"], "budget": 6000, "bytes": 14853, "delta_days": 2, "delta_tokens": 185, "docs_orphaned": 0, "docs_total": 13, "file": "AGENTS.md", "lines": 252, "links_dead": 0, "links_dead_anchors": 0, "no_loss": null, "no_loss_warrants": null, "note": null, "over_budget": true, "repo": "replicator", "seams": null, "seams_acked": null, "skill_commit": "1bf970b", "skill_version": "1.9", "tokens": 6031, "tokens_exact": true, "tokens_live": 78605, "top_section": "Bus Conventions", "top_section_share": 24, "ts": "2026-08-17"}
+{"actions": ["demote:Bus Conventions/replicate-gcs->docs/CONVENTIONS.md", "fix:co-core-pin-disproven", "fix:charter-invariant-count-disproven"], "budget": 6000, "bytes": 14446, "delta_days": 0, "delta_tokens": -141, "docs_orphaned": 0, "docs_total": 13, "file": "AGENTS.md", "lines": 247, "links_dead": 0, "links_dead_anchors": 0, "no_loss": "ok", "no_loss_warrants": 2, "note": null, "over_budget": false, "repo": "replicator", "seams": 0, "seams_acked": 24, "skill_commit": "1bf970b", "skill_version": "1.9", "tokens": 5890, "tokens_exact": true, "tokens_live": 78803, "top_section": "Bus Conventions", "top_section_share": 22, "ts": "2026-08-17"}

.skills/context-seams-ok

@@ -0,0 +1,54 @@
+# Seams judged legitimate — check-seams.sh --ack-file default.
+#
+# A back-reference is wrong only if the content it points at moved. Judged
+# 2026-08-17 during the #47 curation, which moved exactly one block (the
+# replicate/gcs bullet, AGENTS.md -> docs/CONVENTIONS.md). Nothing below points
+# at that block: verified with a grep for AGENTS.md mentions co-occurring with
+# replicate/gcs/create-if-absent/alias, which returned only DEPLOYMENT.md's
+# incident narrative — prose about 2026-08-14, not a pointer.
+#
+# One entry per judged line.
+
+# --- back-references describing the AGENTS.md <-> docs relationship itself.
+# Each states the split that this skill maintains, so each is made MORE true by
+# a demotion, not less. They point at the arrangement, never at a given block.
+docs/ARCHITECTURE.md :: keeps the rules needed on nearly every task; the reasoning that makes
+docs/ARCHITECTURE.md :: Reference docs; the Detail Docs index in AGENTS.md is the roster
+docs/ARCHITECTURE.md :: Each rule `AGENTS.md` states in one line, with the reasoning that makes it non-negotiable.
+docs/CONVENTIONS.md :: touches, with the reasoning that makes each one non-negotiable.
+docs/DEPLOYMENT.md :: keeps the two-env-file boundary and the restart
+docs/STYLE.md :: Code style beyond the conventions `AGENTS.md` keeps inline. Today that is the
+
+# --- narrative, not a pointer: the 2026-08-14 branch-deploy incident that #37
+# closes. "AGENTS.md asserted" the main-is-deployed invariant, which it still
+# does, under ## Infrastructure.
+docs/DEPLOYMENT.md :: was an invariant AGENTS.md asserted and nothing enforced
+
+# --- docs/SKILLS.md rows: an inventory of tooling that ACTS on AGENTS.md.
+# These name the file as a target, so they stay true wherever its content sits.
+docs/SKILLS.md :: Curates `AGENTS.md` and its live reference docs against a token budget
+docs/SKILLS.md :: write guard: warns when an edit pushes `AGENTS.md` over
+docs/SKILLS.md :: and every doc here are registered artifacts; nothing re-embeds them
+docs/SKILLS.md :: Repo-specific *prose* needs no re-applying — it lives in `AGENTS.md` under
+
+# --- docs/SOCRATICODE.md: points at two AGENTS.md SECTION HEADINGS, both of
+# which this run left in place (## Code Exploration Policy, ## Code Exploration
+# Notes (repo-specific)). Re-checked against the current headings.
+docs/SOCRATICODE.md :: Detail doc for the `## Code Exploration Policy` block in `AGENTS.md`. That block
+docs/SOCRATICODE.md :: file wholesale. Repo-specific exploration notes belong in `AGENTS.md` under
+docs/SOCRATICODE.md :: `AGENTS.md` → `## Code Exploration Notes (repo-specific)`.
+docs/SOCRATICODE.md :: Two ways this check lies on this repo — both in `AGENTS.md` under
+
+# --- provenance headings: `(#NN)` in a heading makes the anchor slug carry an
+# issue number. An established convention here rather than drift — 8 of the 9
+# predate this branch, across four docs and three contracts. Renaming them is a
+# repo-wide decision with its own dead-anchor risk, not a curation side effect.
+docs/COMMANDS.md :: Politeness — `content.fetch-policy` (#19)
+docs/DEPLOYMENT.md :: The checkout guard — the service refuses to start off `main` (#37)
+docs/DEPLOYMENT.md :: The co-core 0.8.0 cutover is a two-repo deploy, streams flushed between (#28)
+docs/DEPLOYMENT.md :: The dedupe keys gain a stream segment (#29) — no action, but know why
+docs/contracts/content-fetch-issuer-contract.md :: Request options: what Replicator will send, and what it refuses (#11)
+docs/contracts/content-fetch-issuer-reference.md :: Request options: what Replicator will send, and what it refuses (#11)
+docs/contracts/content-replicate-issuer-contract.md :: T3a — the *source* is a path too, and it is the sharper half (#29)
+docs/contracts/replicator-boundaries.md :: The policy stream (shipped, #19)
+docs/contracts/replicator-boundaries.md :: The fallback default (was the interim, #12 → #19)

.skills/context-token-counts

@@ -3,15 +3,15 @@
 # The offline estimators prefer a file's own last exact measurement to the
 # repo-wide figure in .skills/context-token-ratio, falling back to it for a
 # file never counted exactly or since drifted far from the size recorded here.
-14483 5847 AGENTS.md
+14446 5890 AGENTS.md
 26209 9510 docs/ARCHITECTURE.md
-9668 3826 docs/COMMANDS.md
-4753 1864 docs/CONVENTIONS.md
-16910 6670 docs/DEPLOYMENT.md
-11333 4297 docs/SKILLS.md
-5204 2023 docs/SOCRATICODE.md
+9766 3857 docs/COMMANDS.md
+5653 2203 docs/CONVENTIONS.md
+20574 8003 docs/DEPLOYMENT.md
+15846 6006 docs/SKILLS.md
+4796 1847 docs/SOCRATICODE.md
 5686 2097 docs/STORAGE.md
-2907 1034 docs/STYLE.md
+3325 1206 docs/STYLE.md
 2952 1088 docs/TESTING.md
 24690 9338 docs/contracts/content-fetch-issuer-contract.md
 24893 9234 docs/contracts/content-fetch-issuer-reference.md

AGENTS.md

@@ -31,7 +31,7 @@ Python ≥3.12, uv, pytest, ruff. `ty` is available as a **non-gating** type che
 uv run --no-project --with 'google-cloud-storage>=2,<4' python scripts/sync_wheelhouse.py
 ```
 
-Auth is ADC: on the VM the SA key at `GOOGLE_APPLICATION_CREDENTIALS` (`/etc/replicator/co-pypi-reader.json`), in CI a keyless WIF token. Pin the current minor — `>=0.9.4,<0.10`. The **patch** floor is load-bearing, not tidiness: the change-bus payloads are `extra="ignore"`, so on an older wheel a model constructed with fields it does not have yet succeeds and silently discards them. Raise the floor with every co-core feature the code starts depending on, or a version skew publishes facts that look right and carry nothing (#10). Both floors since fail *loudly* instead — a ValidationError at construction (0.8.0 requires `info_source_id` on all three fetch payloads, #19/#28) or an ImportError at load, never reaching a running worker (0.9.4 cuts the replicate contracts, #29).
+Auth is ADC: on the VM the SA key at `GOOGLE_APPLICATION_CREDENTIALS` (`/etc/replicator/co-pypi-reader.json`), in CI a keyless WIF token. Pin the current minor — `>=0.10,<0.11`. The **patch** floor is load-bearing, not tidiness: the change-bus payloads are `extra="ignore"`, so on an older wheel a model constructed with fields it does not have yet succeeds and silently discards them. Raise the floor with every co-core feature the code starts depending on, or a version skew publishes facts that look right and carry nothing (#10). Both floors since fail *loudly* instead — a ValidationError at construction (0.8.0 requires `info_source_id` on all three fetch payloads, #19/#28) or an ImportError at load, never reaching a running worker (0.9.4 cuts the replicate contracts, #29).
 
 <!-- BEGIN socraticode-policy -->
 ## Code Exploration Policy
@@ -91,8 +91,10 @@ test a branch with `uv run python -m src.worker.main` under a distinct
 `REPLICATOR_CONSUMER_NAME`. **After editing `deploy/replicator.service`, `cp` it to
 `/etc/systemd/system/`** — the installed unit is a copy, not a symlink, so
 `daemon-reload` alone silently re-reads the old file and the mismatch has no
-symptom until a directive matters. Full lifecycle table and the dev-server
-invocation: [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md).
+symptom until a directive matters. **Refuses to start off `main`** (#37) —
+`scripts/check_main_checkout.sh`; `REPLICATOR_ALLOW_ANY_CHECKOUT=1` overrides.
+Full lifecycle table and the dev-server invocation:
+[docs/DEPLOYMENT.md](docs/DEPLOYMENT.md).
 
 ## Environment Variables
 
@@ -143,21 +145,16 @@ Replicator is a **consumer** first. Follow the conventions co-core and the archi
   `content.blobs` and `content.artifacts` each carry both outcomes of their
   command; `content.fetch-policy` is read **groupless** — no group, no ack, no
   DLQ.
-- **The replicate loop writes for `gcs` (#29).** T4's create-if-absent, so a
-  redelivery onto matching bytes re-emits the same `public_url` and differing bytes
-  are a terminal conflict. `blob_uri` is **never resolved as a path** — fingerprint
-  out, compared against `store.uri_for()`. Writers are keyed **by alias**, and every
-  refusal happens before any credential is touched. Provider failures classify by
-  HTTP status — 4xx closes the command, 5xx/408/429 and statusless errors leave it
-  pending — because a transient failure is exempt from the delivery ceiling and
-  publishes no fact at all, so misclassifying one strands the issuer forever
-  (#29 CR #26, #27).
+- **The replicate loop writes for `gcs` (#29)** — create-if-absent, `blob_uri`
+  never resolved as a path, writers keyed by alias, refusals before credentials,
+  provider failures classified by HTTP status. Read
+  [docs/CONVENTIONS.md](docs/CONVENTIONS.md) before touching that path.
 - **Nothing but the seed script writes to `content.fetch`.** `scripts/seed_fetch.py`
   requires `--production` for the one combination the live worker consumes — a
   frame there is fetched for real.
 - **Three normative contracts bound the wire and the roadmap** — four documents,
   all under `docs/contracts/`, linked from sibling repos and indexed below.
-  `tests/test_boundaries.py` enforces eight charter invariants in CI; change a
+  `tests/test_boundaries.py` enforces the charter in CI; change a
   charter and its tests together.
 
 Where the reasoning lives:
@@ -219,7 +216,7 @@ logger = get_logger(__name__)
 ```
 Entry points only: `configure_logging()` is called once inside the FastAPI `lifespan` or the worker's `run()`. Never in library modules.
 
-The logging stack — one formatter, two installers, and the two journald lines that
+The logging stack — one formatter, two installers, and the journald lines that
 are deliberately not JSON: [docs/STYLE.md](docs/STYLE.md).
 
 **Date & Time:**

deploy/replicator.service

@@ -28,6 +28,30 @@ StateDirectory=replicator
 # Create runtime dir (runs as root before User= takes effect with + prefix)
 ExecStartPre=+/bin/bash -c 'mkdir -p /run/replicator && chown exedev:exedev /run/replicator'
 
+# Hard guard: "Code committed to main is the deployed code" (AGENTS.md) was an
+# invariant nothing enforced until #37 — a restart while the checkout sat on a
+# feature branch deployed unmerged code. Refuses a non-main or detached HEAD;
+# warns only on a stale, unpushed, or dirty tree. Not '-' prefixed: a guard whose
+# refusal is logged and ignored is not a guard.
+#
+# Placed BEFORE the BUILD_ID stamp on purpose. /run/replicator/build-id outlives a
+# failed start, so stamping the branch SHA first would leave the journal
+# describing code that never ran — the same "looks correct, is not" failure the
+# guard exists to close.
+#
+# REPLICATOR_ALLOW_ANY_CHECKOUT=1 in /etc/replicator/.env bypasses it. That is not
+# the documented way to test a branch on this VM (run the worker directly under a
+# distinct REPLICATOR_CONSUMER_NAME) — it is for testing this unit itself. The
+# override still reaches this step even though the EnvironmentFile= lines appear
+# below it: EnvironmentFile= is a unit-level setting applied to every Exec*
+# process, not a sequential instruction, so its position in the file is not an
+# ordering.
+#
+# The checkout it inspects is WorkingDirectory= (systemd's cwd for every Exec*),
+# which is the same tree the stamp below reads and ExecStart runs from — so the
+# guard cannot end up verifying a different tree than the one that starts.
+ExecStartPre=/bin/bash /home/exedev/replicator/scripts/check_main_checkout.sh
+
 # Write current git SHA to a runtime env file before starting
 ExecStartPre=/bin/bash -c 'echo BUILD_ID=$(git rev-parse --short HEAD) > /run/replicator/build-id'
 

docs/COMMANDS.md

@@ -211,6 +211,8 @@ git submodule update --remote --merge         # pull upstream skill changes
 ## Deploy
 
 ```bash
+bash scripts/check_main_checkout.sh                     # what the unit asserts before it starts
+
 sudo cp deploy/replicator.service /etc/systemd/system/replicator.service
 sudo systemctl daemon-reload
 sudo systemctl enable --now replicator

docs/CONVENTIONS.md

@@ -20,3 +20,15 @@ states them in one line each; what a *particular* stream carries, and why, is in
 - **`occurred_at` is enforced tz-aware UTC on every payload** since co-core v0.7.2 (cannobserv#273). Naive is rejected fail-loud rather than assumed UTC; aware non-UTC is normalized. Load-bearing beyond tidiness — `isoformat()` is half `fetch_failed`'s envelope key, and a naive value would serialize without an offset. Issuer-visible: a naive `occurred_at` now fails `from_wire` and dead-letters as an anomaly.
 - **`from_wire`'s topic and message_id are keyword-only** — `from_wire(fields, topic=..., message_id=...)`. The founding plan's API table showed them positionally.
 - `sha256` lives at `co_core.pure.util.hashing`, not `co_core.pure.extract` (which carries `simhash`, `Chunk`, and the parsers). Import parsers from submodules — they are not re-exported from `__init__`.
+- **The replicate loop writes for `gcs` (#29).** T4's create-if-absent, so a
+  redelivery onto matching bytes re-emits the same `public_url` and differing bytes
+  are a terminal conflict. `blob_uri` is **never resolved as a path** — fingerprint
+  out, compared against `store.uri_for()`. Writers are keyed **by alias**, and every
+  refusal happens before any credential is touched. Provider failures classify by
+  HTTP status — 4xx closes the command, 5xx/408/429 and statusless errors leave it
+  pending — because a transient failure is exempt from the delivery ceiling and
+  publishes no fact at all, so misclassifying one strands the issuer forever
+  (#29 CR #26, #27).
+  The mechanism in full — the four outcomes, the guard order, why the writers are
+  keyed by alias — is [ARCHITECTURE.md](ARCHITECTURE.md); this bullet is the rule
+  an agent needs before touching the replicate path.