docs(l0): declaration grammar moves to .mosaic/repo.json (#1216)
ci/woodpecker/pr/ci Pipeline was successful
ci/woodpecker/pr/ci Pipeline was successful
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).
This commit is contained in:
@@ -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: <branch>` — 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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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:
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user