Document gate branch contribution workflow

Author: geraldarthurdavis

AGENTS.md

@@ -4,6 +4,9 @@
 - Never explicitly version source code without direct instruction. Source code is always implicitly versioned to the active Bitcode canon and current gate; routes, file names, CSS files, constants, classes, API paths, tests, and implementation identifiers must be written in-place as the single current Bitcode system. Do not introduce names such as `api/v1`, `v27-*`, `first-gate-*`, `wip-*`, or similar version/gate/work-in-progress source constructs unless explicitly directed for a bounded compatibility artifact.
 - Do not consider any legacy code. All legacy code is located under `_legacy/`.
 - Highest caliber software engineering crafstmanship (maintainibility, abstractions, architectures, naming, patterns, comments, documentation, structures, algorithmic and data flow designs, UI/UX, etc.), correctness (specification and implementation precision, reliability, completeness, boundaried, scoped, encapsulated, etc.), and auditable (totalistic proofs systems from static code, build time, runtime, etc. etc. as is Bitcode, tests from unit, integration, E2E, linting and building, etc.).
+- Do not push work directly to `main`. Create a version base branch for each draft target, such as `version/v28`, then create scoped gate branches from that version branch. Gate branches must be prefixed with the gate number, such as `v28/gate-3-read-fit-workflow` or `v28/gate-8-promotion-proof`. Pull-request each closed gate back into the version branch. Pull-request the version branch into `main` only when all gates are closed and the version is formally promoted as canon. The default branch is protected by the `Bitcode Core Contributions` ruleset and requires pull requests plus verified signatures.
+- Once implementation starts on a gate branch, do not stop at partial progress unless blocked by missing external input or explicit user pause. A gate branch is ready to stop only when the gate's acceptance criteria are implemented, specified, tested, documented, committed, pushed, and pull-requested for closure into the version branch.
+- Write quality commit messages that describe the grouped work, proof, or documentation change. Avoid generic messages such as `wip v28` unless the user explicitly asks for that exact temporary commit shape.
 
 ## The Bezalel Protocol: Sacred Craft for Coding Agents
 

BITCODE_SPEC_V28.md

@@ -149,6 +149,10 @@ V28 requires:
 - compatibility storage carriers are hidden behind Bitcode vocabulary and registry-derived read models;
 - no new versioned UAPI route family is introduced;
 - implementation source remains implicitly versioned to the active canon and current gate: routes, file names, CSS, constants, tests, and identifiers must not introduce explicit version/gate/work-in-progress names without a bounded compatibility instruction;
+- repository contribution flow uses a V28 version branch as the draft integration
+  branch, with scoped gate-number-prefixed branches opened from it and
+  pull-requested back into it only when their gate acceptance criteria are
+  implemented, specified, tested, documented, and ready for closure review;
 - value-bearing mainnet remains gated by explicit operational approval;
 - V29 Terminal depth, V30 Protocol/BTD hardening, V31 Auxillaries depth, V32 provation/testing depth, V33 interface depth beyond the V28 MVP, V34 deployment depth, V35 telemetry/documenting depth, and V36+ Exchange/Conversations depth remain staged unless V28 requires a narrow Protocol/Terminal/MCP/ChatGPT hook.
 
@@ -950,7 +954,7 @@ Minimum V28 validation includes spec-family checks, canon-posture drift checks,
 
 ## promotion canon
 
-Promotion requires V28 PROVEN, synchronized SPEC/DELTA/NOTES/PARITY, closed gates, route scan, test/build proof, and explicit update of `BITCODE_SPEC.txt` from `V27` to `V28`.
+Promotion requires V28 PROVEN, synchronized SPEC/DELTA/NOTES/PARITY, closed gates, route scan, test/build proof, pull-requested integration from gate-number-prefixed branches into the V28 version branch, and explicit update of `BITCODE_SPEC.txt` from `V27` to `V28` when the version branch is pull-requested back into `main`.
 
 ## appendices and canonical supporting material
 

README.md

@@ -30,6 +30,27 @@ App.
 - Update source in-place to match the active canon and current draft target.
 - Keep specification notes, QA ledgers, tests, and implementation synchronized.
 
+## Contributor Workflow
+
+The default branch is protected by the active `Bitcode Core Contributions`
+ruleset. Direct pushes to `main` are not part of the normal workflow; expect
+them to be rejected because changes must arrive through pull requests and
+verified signatures.
+
+Use a version branch and gate-numbered branches:
+
+1. Create one base branch per draft target, such as `version/v28`.
+2. Create scoped gate branches from the version branch. Prefix every gate branch
+   with the gate number, for example `v28/gate-3-read-fit-workflow` or
+   `v28/gate-8-promotion-proof`.
+3. Group related work into clear commits with descriptive commit messages.
+4. Continue on the gate branch until that gate's acceptance criteria are
+   implemented, specified, tested, documented, committed, pushed, and ready for
+   closure review.
+5. Open pull requests from gate branches into the version branch as gates close.
+6. Open the version branch back into `main` only after all gates close and the
+   version is formally promoted as canon.
+
 ## Key Surfaces
 
 - [BITCODE_SPEC.txt](BITCODE_SPEC.txt) is the canonical version pointer.