Document branch-based contribution workflow

Author: geraldarthurdavis

AGENTS.md

@@ -4,6 +4,8 @@
 - 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/work branches from that version branch. 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.
+- 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,9 @@ 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 work branches opened from it and pull-requested back into
+  it as individual gates close;
 - 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 +953,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 scoped gate 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,24 @@ 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 branches:
+
+1. Create one base branch per draft target, such as `version/v28`.
+2. Create scoped work branches from the version branch, for example
+   `v28/<gate-or-work-slice>`.
+3. Group related work into clear commits with descriptive commit messages.
+4. Open pull requests from scoped branches into the version branch as gates
+   close.
+5. 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.