docs(l0): parameterize hard gates on the project's integration trunk (#1216, Option A) #1217

2026-08-13T18:46:26Z

mos-dt-0 commented

2026-08-13 18:46:26 +00:00

Executes Jason's Option (a) ruling on #1216 (comment 22359): the constitution supplies the general framework; the project declares its own flow; no branch naming convention is forced by L0.

What changes

CONSTITUTION.md — defines the integration trunk once, ahead of the Hard Gates: declared by exactly one Integration trunk: <branch> line in the project's root AGENTS.md; default main; value bound by git check-ref-format --branch semantics (no remote refs, revisions, option-like values, traversal/control characters); malformed or multiple declarations are a hard stop (blocked), never a silent fallback; prose mentioning branch names designates nothing; exactly ONE trunk; designation relaxes no gate (reviewed-PR-only, squash, independent review, queue guards, terminal-green CI all bind to the declared trunk). Gates 5 and 15 now bind to the term.
defaults/AGENTS.md — session-closure evidence binds to the integration trunk.
guides/CODE-REVIEW.md — HARD RULE block, review diff command, and after-review merge step parameterized.
guides/E2E-DELIVERY.md — step 10 (PR integration) and post-PR hard-gate item 13 parameterized.
guides/ORCHESTRATOR.md / ORCHESTRATOR-PROTOCOL.md — trunk-workflow enforcement lines, worker branch/PR/merge policy, wrapper command templates, remediation checkout template, Merge-to-Trunk candidate protocol, milestone checklist.
guides/BOOTSTRAP.md — day-one consistency claims and Step 5b branch-protection provisioning target the declared trunk.
guides/CI-CD-PIPELINES.md — worked YAML examples stay on the default trunk main; a substitution note at the top classifies them; normative sentences (non-trunk-branch testing, merge step, PR-build audit) parameterized.

Consumer classification (reviewer anchors, scrappy 20260813T184158Z)

Controlling prose — all amended atomically in this PR (list above).
Executable wrapper — framework/tools/git/pr-merge.sh:133 hardcodes a {main, next} base allowlist. Fail-closed: it can refuse a legally-declared exotic trunk but cannot misroute a merge. Parameterizing it to consume the declaration (policy data, never shell text; validated per the constitution grammar) is a code change with its own red-first test surface — tracked as follow-up on #1216, not smuggled into a docs PR.
Non-controlling — codex-code-review.sh (--base flag, defaulted), init-project.sh (--cicd-branches flag), test-pr-metadata-gitea.sh (test fixtures), mosaic-release-upgrade* (main there is the stack repo's own bootstrap ref, not a project trunk), defaults/README.md (install URLs/lanes), CI-CD YAML examples (covered by the note).

Behavioral controls (prose contract)

Absent declaration → main (every existing project unchanged).
Explicit Integration trunk: next → next through branch/PR/completion wording end-to-end.
Malformed/multiple declarations → hard stop, loud, no fallback.
Ordinary AGENTS prose containing branch words cannot select a trunk (exact line-start grammar).
Tightening boundary stated: one trunk only; no relaxation of review/queue/CI gates.

Notes

Pre-existing prettier --check warnings on CI-CD-PIPELINES.md / ORCHESTRATOR-PROTOCOL.md are on the base (VAULT-SECRETS.md, untouched, warns identically) — not introduced here.
L0 change — operator-owned. No merge before Jason's explicit GO. Independent gate: scrappy (fresh exact-head diff, source-to-installed parity, composition, terminal CI).
After this lands on next: #1215 comes off HOLD as a now-legal tightening and gets its fresh-head re-gate.

No self-merge.

🤖 Generated with Claude Code

https://claude.ai/code/session_01WYgWocp36goy8hj2ui6ps1

Executes Jason's **Option (a)** ruling on #1216 (comment 22359): the constitution supplies the general framework; the project declares its own flow; no branch naming convention is forced by L0. ## What changes - **CONSTITUTION.md** — defines the **integration trunk** once, ahead of the Hard Gates: declared by exactly one `Integration trunk: <branch>` line in the project's root `AGENTS.md`; default `main`; value bound by `git check-ref-format --branch` semantics (no remote refs, revisions, option-like values, traversal/control characters); malformed or multiple declarations are a hard stop (`blocked`), never a silent fallback; prose mentioning branch names designates nothing; exactly ONE trunk; designation relaxes no gate (reviewed-PR-only, squash, independent review, queue guards, terminal-green CI all bind to the declared trunk). Gates 5 and 15 now bind to the term. - **defaults/AGENTS.md** — session-closure evidence binds to the integration trunk. - **guides/CODE-REVIEW.md** — HARD RULE block, review diff command, and after-review merge step parameterized. - **guides/E2E-DELIVERY.md** — step 10 (PR integration) and post-PR hard-gate item 13 parameterized. - **guides/ORCHESTRATOR.md / ORCHESTRATOR-PROTOCOL.md** — trunk-workflow enforcement lines, worker branch/PR/merge policy, wrapper command templates, remediation checkout template, Merge-to-Trunk candidate protocol, milestone checklist. - **guides/BOOTSTRAP.md** — day-one consistency claims and Step 5b branch-protection provisioning target the declared trunk. - **guides/CI-CD-PIPELINES.md** — worked YAML examples stay on the default trunk `main`; a substitution note at the top classifies them; normative sentences (non-trunk-branch testing, merge step, PR-build audit) parameterized. ## Consumer classification (reviewer anchors, scrappy 20260813T184158Z) - **Controlling prose** — all amended atomically in this PR (list above). - **Executable wrapper** — `framework/tools/git/pr-merge.sh:133` hardcodes a `{main, next}` base allowlist. **Fail-closed**: it can refuse a legally-declared exotic trunk but cannot misroute a merge. Parameterizing it to consume the declaration (policy data, never shell text; validated per the constitution grammar) is a code change with its own red-first test surface — tracked as follow-up on #1216, not smuggled into a docs PR. - **Non-controlling** — `codex-code-review.sh` (`--base` flag, defaulted), `init-project.sh` (`--cicd-branches` flag), `test-pr-metadata-gitea.sh` (test fixtures), `mosaic-release-upgrade*` (`main` there is the stack repo's own bootstrap ref, not a project trunk), `defaults/README.md` (install URLs/lanes), CI-CD YAML examples (covered by the note). ## Behavioral controls (prose contract) - Absent declaration → `main` (every existing project unchanged). - Explicit `Integration trunk: next` → next through branch/PR/completion wording end-to-end. - Malformed/multiple declarations → hard stop, loud, no fallback. - Ordinary AGENTS prose containing branch words cannot select a trunk (exact line-start grammar). - Tightening boundary stated: one trunk only; no relaxation of review/queue/CI gates. ## Notes - Pre-existing `prettier --check` warnings on CI-CD-PIPELINES.md / ORCHESTRATOR-PROTOCOL.md are on the base (VAULT-SECRETS.md, untouched, warns identically) — not introduced here. - **L0 change — operator-owned. No merge before Jason's explicit GO.** Independent gate: scrappy (fresh exact-head diff, source-to-installed parity, composition, terminal CI). - After this lands on `next`: #1215 comes off HOLD as a now-legal tightening and gets its fresh-head re-gate. No self-merge. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01WYgWocp36goy8hj2ui6ps1

mos-dt-0 added 1 commit 2026-08-13 18:46:26 +00:00

docs(l0): parameterize hard gates on the project's integration trunk

ci/woodpecker/pr/ci Pipeline was successful

Details

18f960d3e1

Per Jason's Option-A ruling on #1216: the constitution supplies the general
framework; the project declares its own flow. Defines the integration trunk
once in CONSTITUTION.md Hard Gates — declared by exactly one
'Integration trunk: <branch>' line in the project's root AGENTS.md, default
'main', value bound by git check-ref-format --branch semantics, malformed or
multiple declarations are a hard stop, one trunk only, no gate relaxation —
and binds gates 5/15, E2E-DELIVERY, CODE-REVIEW, ORCHESTRATOR(-PROTOCOL),
BOOTSTRAP provisioning, and the defaults AGENTS session closure to that term.
CI-CD-PIPELINES YAML examples stay on the default trunk with a substitution
note.

Known mechanized consumer left as tracked follow-up on #1216: pr-merge.sh:133
hardcodes a {main,next} base allowlist — fail-closed (refuses exotic trunks,
cannot misroute), to be parameterized with red-first tests separately.

Refs #1216

Co-Authored-By: Claude Fable 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01WYgWocp36goy8hj2ui6ps1