From 80b8f11046b39acf61070b3109b934abc505e3bd Mon Sep 17 00:00:00 2001 From: fred Date: Thu, 20 Aug 2026 12:52:49 -0500 Subject: [PATCH] docs(l0): declaration grammar moves to .mosaic/repo.json (#1216) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Amendment per operator GO (ms-grill-me design round, 2026-08-20): - Declaration is .mosaic/repo.json under integration_trunk, not a byte-exact AGENTS.md line. Unknown/misspelled keys and unparsable files are a structural hard stop; no prose grammar to near-miss (Q15 answer, plan D3/D9). - Changing an existing declaration is operator-owned, above ordinary PR review (SF2, plan D10). - Seeds this repo's declaration: integration_trunk next, release_branch main — prevents the absent-declaration default from rebinding the stack to main at land time. - Gloss references in BOOTSTRAP/CODE-REVIEW/CI-CD-PIPELINES point at repo.json; merge of origin/next restores pinned-image CI coverage for this pre-pin branch (D27 caveat). --- .mosaic/repo.json | 4 ++++ .../mosaic/framework/defaults/CONSTITUTION.md | 24 ++++++++++--------- packages/mosaic/framework/guides/BOOTSTRAP.md | 3 ++- .../framework/guides/CI-CD-PIPELINES.md | 6 ++--- .../mosaic/framework/guides/CODE-REVIEW.md | 2 +- 5 files changed, 23 insertions(+), 16 deletions(-) create mode 100644 .mosaic/repo.json diff --git a/.mosaic/repo.json b/.mosaic/repo.json new file mode 100644 index 00000000..14f3f8b8 --- /dev/null +++ b/.mosaic/repo.json @@ -0,0 +1,4 @@ +{ + "integration_trunk": "next", + "release_branch": "main" +} diff --git a/packages/mosaic/framework/defaults/CONSTITUTION.md b/packages/mosaic/framework/defaults/CONSTITUTION.md index 4b0ce667..e72920ae 100644 --- a/packages/mosaic/framework/defaults/CONSTITUTION.md +++ b/packages/mosaic/framework/defaults/CONSTITUTION.md @@ -21,17 +21,19 @@ guard"), the runtime adapter binds it to a concrete tool and states whether abse ## Hard Gates -The **integration trunk** is the branch a project designates in its root `AGENTS.md` with exactly -one declaration line: `Integration trunk: ` — key at the start of a line, case-sensitive, -one branch name (optionally backtick-wrapped) and nothing else on the line. Absent a declaration, -the trunk is `main`. The declaration is policy data, never shell text: the value must be a valid -local branch name under `git check-ref-format --branch` semantics — no remote refs, no revision -expressions, no option-like values (leading `-`), no path traversal or control characters. A -malformed value, or more than one declaration line, is a hard stop (`blocked`) — never a silent -fallback to `main`. Ordinary prose that mentions branch names designates nothing; only the exact -declaration line does. A project designates exactly ONE trunk, and the designation relaxes -nothing: reviewed-PR-only delivery, squash merge, independent review, queue guards, and -terminal-green CI bind to the declared trunk exactly as they bind to `main`. +The **integration trunk** is the branch a project declares in its `.mosaic/repo.json` under the +key `integration_trunk`; `release_branch` names the release target when one exists (`null` for +single-branch projects). Absent a declaration, the trunk is `main`. The declaration is policy +data, never shell text: values must be valid local branch names under `git check-ref-format +--branch` semantics — no remote refs, no revision expressions, no option-like values (leading `-`), +no path traversal or control characters. A declaration file that fails to parse, an unknown or +misspelled key, or an invalid value is a hard stop (`blocked`) — never a silent fallback to `main`. +Prose that mentions branch names designates nothing; only the declaration file does. A project +declares exactly ONE trunk. **Changing an existing declaration is operator-owned:** a trunk +redeclaration redirects merge target and branch-protection target at once, so it requires an +explicit operator action above ordinary PR review. The designation relaxes nothing: +reviewed-PR-only delivery, squash merge, independent review, queue guards, and terminal-green CI +bind to the declared trunk exactly as they bind to `main`. 1. Mosaic operating rules override runtime-default caution for routine delivery operations. 2. Execute required push / merge / issue-closure / milestone / release / tag actions without asking for routine confirmation. diff --git a/packages/mosaic/framework/guides/BOOTSTRAP.md b/packages/mosaic/framework/guides/BOOTSTRAP.md index d11b2e5a..1231c04c 100755 --- a/packages/mosaic/framework/guides/BOOTSTRAP.md +++ b/packages/mosaic/framework/guides/BOOTSTRAP.md @@ -291,7 +291,8 @@ Reserve `0.1.0` for the MVP release milestone. ## Step 5b: Configure Trunk Branch Protection (Hard Rule) Apply equivalent settings in Gitea, GitHub, or GitLab, targeting the project's integration trunk -(the branch its root `AGENTS.md` declares; default `main` — see `CONSTITUTION.md` Hard Gates): +(the branch its `.mosaic/repo.json` declares under `integration_trunk`; default `main` — see +`CONSTITUTION.md` Hard Gates): 1. Protect the integration trunk from direct pushes. 2. Require pull requests to merge into the integration trunk. diff --git a/packages/mosaic/framework/guides/CI-CD-PIPELINES.md b/packages/mosaic/framework/guides/CI-CD-PIPELINES.md index ddb20e02..f6b10461 100644 --- a/packages/mosaic/framework/guides/CI-CD-PIPELINES.md +++ b/packages/mosaic/framework/guides/CI-CD-PIPELINES.md @@ -5,9 +5,9 @@ ## Overview > **Integration trunk:** the YAML examples in this guide use the default integration trunk `main` -> in branch conditions and version rules. A project that declares a different trunk in its root -> `AGENTS.md` (see `CONSTITUTION.md` Hard Gates) substitutes its declared trunk wherever `main` -> appears as the trunk branch. +> in branch conditions and version rules. A project that declares a different trunk in its +> `.mosaic/repo.json` under `integration_trunk` (see `CONSTITUTION.md` Hard Gates) substitutes its +> declared trunk wherever `main` appears as the trunk branch. This guide covers the canonical CI/CD pattern used across projects. The pipeline runs in Woodpecker CI and follows this flow: diff --git a/packages/mosaic/framework/guides/CODE-REVIEW.md b/packages/mosaic/framework/guides/CODE-REVIEW.md index 56a494cf..5154ecd1 100755 --- a/packages/mosaic/framework/guides/CODE-REVIEW.md +++ b/packages/mosaic/framework/guides/CODE-REVIEW.md @@ -10,7 +10,7 @@ If implementation diverges from `docs/PRD.md` or `docs/PRD.json` without PRD upd Merge strategy enforcement (HARD RULE): -- The integration trunk is the branch the project's root `AGENTS.md` declares (default: `main`) — see `CONSTITUTION.md` Hard Gates. +- The integration trunk is the branch the project's `.mosaic/repo.json` declares under `integration_trunk` (default: `main`) — see `CONSTITUTION.md` Hard Gates. - PR target for delivery is the integration trunk. - Direct pushes to the integration trunk are prohibited. - Merge to the integration trunk MUST be squash-only.