feat(standards): org-wide engineering standards — canon + sync guard (backend#1602)

[LukasWodka]

Summary

Item 1 of tracebloc/backend#1602 (content approved by Lukas 2026-08-06): one canonical org-standards.md — the org's ~50-line working rules — plus the guard that keeps every active repo's CLAUDE.md carrying it verbatim, so every Claude Code session in every repo loads the same rules.

• org-standards.md — the canon: branches & PRs (develop-only, small single-purpose PRs, no stacked PRs, sync before starting, reviewer requested at open), quality bar (run affected tests before push / never push red, read the full diff, evidence not assertion, same-day Bugbot triage, recurring findings become BUGBOT.md/house-rules entries), kanban (team-coordinated pickup — the old "never from Backlog" rule is retired), releases (the train owns staging/main and every registry), filing rules, AI-session guardrails. Drafted from the train's actual behaviour, RFC-1405, epic #1405's adopted process rules, and external research (Google eng-practices, DORA, trunk-based development, Anthropic/Cursor guidance). Header meta-rule: the moment a rule becomes mechanically enforced, its sentence gets deleted here — prose is only for what tooling can't judge.
• scripts/standards-sync.py — caller-drift's design rules applied to CLAUDE.md blocks: develop-first reads; never all-clear from a failed read (one unreadable repo → exit 2); absence never implicit (every repo-inventory.yml repo is a target or a written exemption — sole exemption today: devex-bootstrap, backend#1597 item 3); malformed/duplicated markers are reported and never auto-spliced.
• scripts/tests/standards-sync-selftest.py — offline, no network, no token: 19 checks over the splice logic (repo-owned prose preserved byte-for-byte around the block, idempotence, MALFORMED never spliced) and every fail-closed path.
• .github/workflows/standards-sync.yml — selftest on PRs touching these four files; audit on schedule (Mondays 07:00 UTC, after caller-drift) and workflow_dispatch. Report-only by default; dispatching with create-prs: true opens/refreshes one docs/1602-org-standards-sync PR per drifted repo against its develop. Drift reports comment on backend#1602; never an all-clear comment.

The audit deliberately does not run on PRs: the canon is read from the checkout, so a PR editing it would see the whole fleet as legitimately behind and go red by construction (the same checkout-vs-API awkwardness caller-drift documents; here it is resolved by scoping the trigger instead).

Type

Feature (process/CI).

Test plan

• Offline selftest: 19/19 locally; runs in CI as the selftest job on this PR
• python -m py_compile on both scripts
• actionlint locally on the new workflow (SC2016 markdown-in-printf silenced with the same disable comment caller-drift.yml uses)
• Live read-only report run against the org (local, report mode): all 19 targets read, 0 unreadable, exit 1 as expected — 14× MISSING_BLOCK (CLAUDE.md exists, no managed block yet), 5× NO_FILE (.github, cli, e2e-test-agent, release-train, rfcs), and the develop-first fallback correctly read main for the two repos without a develop branch
• After merge: dispatch report-only from develop; confirm the drift comment lands on backend#1602
• Before Wave 1: confirm PROJECTS_KANBAN_TOKEN carries Contents:RW + Pull requests:RW on the targets (else mint a fine-grained STANDARDS_SYNC_TOKEN); then dispatch create-prs: true and review the ~19 sync PRs

Rollout

Wave 1 stamps the block fleet-wide (create-prs dispatch, one reviewable PR per repo). Wave 2 — separate per-repo PRs with named individual owners — fills repo-specific CLAUDE.md content and retires the two live contradictions (client's stale assignee rule, model-zoo's master line). Tracking: tracebloc/backend#1602.

🤖 Generated with Claude Code

---

Note

Medium Risk
New automation can push branches and open PRs across many repos when dispatched with write-capable tokens; logic is fail-closed and offline-tested, but mistaken remediation or token scope still has org-wide blast radius.

Overview
Introduces org-standards.md as the single source of org engineering rules (branches/PRs, quality bar, kanban, releases, filing, AI session limits) meant to live inside each repo's CLAUDE.md between <!-- org-standards:begin/end --> markers.

Adds scripts/standards-sync.py and standards-sync-selftest.py: develop-first reads from repo-inventory.yml, classify drift without treating failed reads as “no file,” refuse to auto-splice malformed markers, and optionally open docs/1602-org-standards-sync PRs per repo. standards-sync.yml runs the offline selftest on PR/push to the four touched files; the live audit runs on schedule and workflow_dispatch only (not on PRs, so canon edits do not fail the whole fleet by design), posts drift to backend#1602 when not clean, and can remediate via create-prs: true.

^{Reviewed by Cursor Bugbot for commit a1d6f4c. Bugbot is set up for automated code reviews on this repo. Configure here.}

[LukasWodka]

Drive-by diagnosis on the selftest red, since I hit the identical trap on the cron-watchdog three days ago.

Root cause: PyYAML isn't importable in the runner.

##[error]PyYAML is not importable; there is no trustworthy degraded mode
##[error]Refusing to report on standards drift from an incomplete read.

The job runs python scripts/tests/standards-sync-selftest.py with no actions/setup-python and no dependency install, so the script's own fail-closed guard fires — correctly — and takes the step to exit 2.

Precedent + fix: backend#1531's cron-watchdog.yml failed exactly this way. Bugbot's objection there was that a bare pip install pyyaml is a supply-chain gamble in a workflow, so the landed shape is actions/setup-python (SHA-pinned) plus a version-pinned pyyaml. Copying that job's two steps verbatim should turn this green.

The more interesting finding — three of your assertions are currently vacuous. These pass:

PASS canon: empty file fails closed exited 2 (want 2)
PASS canon: marker inside canon fails closed exited 2 (want 2)
PASS canon: unreadable path fails closed exited 2 (want 2)

…but read the interleaved stderr: in this environment the script is exiting 2 because PyYAML is missing, not because the canon was empty / had a nested marker / was unreadable. The assertion is exit == 2, and 2 is also the code for "I couldn't even start", so the tests report green while testing nothing. They'd keep reporting green if the canon guards were deleted outright.

That's the same class as the quality / gitleaks zero-files-scanned rule ("a guard that cannot verify must refuse to claim it did") applied one level up, to the test rather than the gate. Worth distinguishing the exit codes — e.g. reserve 2 for a genuine fail-closed refusal and use a different code for environment/precondition failure, then assert on the specific one. FR-assist ended up doing exactly that with exit 2 vs 3 for its validation fixtures, for this reason.

Not my PR and I haven't touched it — flagging only because the false-green would survive the dependency fix and then look permanently healthy.

[LukasWodka]

Note for review: the red pii-gate / pii-check is not from this diff — the gate fails closed because the org PII_DENYLIST secret is unset (backend#1409, parked red-inert per epic #1405). Same failure on any PR in this repo until #1409 is picked up.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 647f43e. Configure here.}