RCP-CWK-038 Monorepo Pre-Push Gate

Mandatory verification gate that must be executed before any push to shared repositories

Performs an 8-point validation covering repository state, branch verification, remote synchronization, scope validation, force-push detection, structure integrity, changelog awareness, and pre-push backup. Returns an explicit GO, CONDITIONAL GO, or NO-GO verdict. Push proceeds only on GO.

Monorepo Pre-Push Gate

Cowork | Safety | Difficulty: Intermediate | Time: 3–5 min
Tags: Introduced in Beta, Safety, Git, Pre-Push, Verification Gate, Monorepo, Legacy, Cowork

TL;DR

What It Does
Mandatory verification gate that must be executed before any push to shared repositories. Performs an 8-point validation covering repository state, branch verification, remote synchronization, scope validation, force-push detection, structure integrity, changelog awareness, and pre-push backup. Returns an explicit GO, CONDITIONAL GO, or NO-GO verdict. Push proceeds only on GO.
How It Works
Eight sequential checks. (1) Repository verification — confirms path exists and is a valid git repository. (2) Branch state — must be on main, not detached HEAD. (3) Pull-before-push — fetches origin and merges if behind, blocks on merge conflicts. (4) Scope validation — all changed files must be within the MASTER project’s folder or authorized shared root files. (5) Force-push detection — blocks any –force or –force-with-lease flags. (6) Monorepo structure integrity — verifies projects/ and specs/ directories exist with expected contents. (7) Changelog read confirmation — displays recent changelog entries for conflict awareness. (8) Pre-push snapshot — calls CWK-037 to create a git bundle backup before pushing. Any FAIL check produces a NO-GO verdict.
What To Expect
A structured results table showing PASS, WARN, or FAIL for each of the 8 checks. A verdict of GO (all checks passed), CONDITIONAL GO (warnings present, requires human confirmation), or NO-GO (any check failed, push blocked). Post-gate reminder to update the changelog after pushing.
Best Results When You
Ensure the repository is on the main branch with all changes committed before running the gate. Have a valid PAT for fetch/merge operations. Use the default push command unless you have a specific reason to customize it.
Typical Time
3–5 minutes. Most time is spent on the CWK-037 snapshot (Check 8). The skip_snapshot flag saves 1–2 minutes if a snapshot was just taken.
Difficulty
Intermediate — the recipe handles all verification internally. User provides the repository path, project ID, and session ID. Understanding of monorepo conventions helps interpret any FAIL results.

How To Start

This recipe is the mandatory pre-push verification gate for monorepo-layout projects. Note: for projects using the two-repo architecture, use CWK-046 (Push Orchestrator) instead — CWK-046 supersedes CWK-038 for two-repo model pushes. CWK-038 remains valid only for projects using the legacy monorepo layout with a projects/ folder structure.

STEP 1Provide Push Context

Specify the repository path, MASTER project ID, and session ID.
Available parameters
  • monorepo_path · string · required
    Path to the cloned monorepo root.
  • project_id · string · required
    Must match MONOREPO_ROLE=MASTER. Non-MASTER projects should not execute this recipe.
  • session_id · string · required
    Current session ID for snapshot tagging.
  • project_folder_prefix · string · optional · default: projects/CFT-PROJ-{project_id}
    Expected folder prefix for scope validation.
  • push_command · string · optional · default: git push origin main
    The intended push command (inspected for force flags).
  • skip_snapshot · boolean · optional · default: false
    Skip CWK-037 snapshot (only valid if snapshot was just taken).
Invocations
Standard pre-push gate
#H->AI::Directive: (Execute CWK-038 with monorepo_path="/tmp/p060-clone", project_id="CP-060", session_id="H074")
Gate with snapshot skip
#H->AI::Directive: (Execute CWK-038 with monorepo_path="/tmp/p060-clone", project_id="CP-060", session_id="H074", skip_snapshot=true)

Usage Examples

EXAMPLE 1Clean pre-push gate pass

User
Run the pre-push gate before we push.
Cat
Pre-Push Gate — 8 checks. Check 1 PASS (valid repo). Check 2 PASS (on main). Check 3 PASS (up-to-date with origin). Check 4 PASS (12 files, all in scope). Check 5 PASS (no force flags). Check 6 PASS (6 projects, 4 specs). Check 7 PASS (changelog reviewed). Check 8 PASS (snapshot created). Verdict: GO. All 8 checks passed. Push is authorized.

EXAMPLE 2Gate with scope violation

User
Run the pre-push gate.
Cat
Pre-Push Gate — 8 checks. Checks 1–3 PASS. Check 4 FAIL: out-of-scope changes detected — specs/CFT-SPEC-003.txt is not in the MASTER project’s folder. For Global file changes, use CWK-045. Checks 5–8 PASS. Verdict: NO-GO. 1 check failed. Resolve scope violation before retrying.

EXAMPLE 3Conditional pass with warnings

User
Pre-push gate please.
Cat
Pre-Push Gate — 8 checks. Check 1 PASS. Check 2 PASS. Check 3 WARN (fetch failed — Cowork sandbox network). Check 4 PASS. Check 5 PASS. Check 6 PASS. Check 7 PASS. Check 8 WARN (snapshot creation failed). Verdict: CONDITIONAL GO — 2 warnings. Review warnings above. Proceed with push? [User confirms] Push authorized.

How AI Reads This Recipe

When this recipe is triggered, the AI executes a mandatory pre-push verification gate. The AI should:
  1. Check 1: Repository Verification. Verify monorepo_path exists and is a valid git repository (.git directory present). Fail immediately if not.
  2. Check 2: Branch State. Verify current branch is main. Fail on detached HEAD or any non-main branch.
  3. Check 3: Pull-Before-Push. Run git fetch origin. If behind origin/main, merge. Fail on merge conflicts. Warn (do not fail) if fetch fails due to sandbox network issues.
  4. Check 4: Scope Validation. Compare changed files (git diff –name-only origin/main…HEAD) against allowed prefixes. All changes must be within the MASTER project’s folder or authorized shared root files (changelog, recipe index). Fail on any out-of-scope files.
  5. Check 5: Force-Push Detection. Inspect push_command for –force, -f, or –force-with-lease flags. Fail if any force flag is detected.
  6. Check 6: Structure Integrity. Verify projects/ and specs/ directories exist. Count project folders and spec files. Fail if either directory is missing.
  7. Check 7: Changelog Read. Display recent changelog entries for awareness. Warn if changelog file is missing.
  8. Check 8: Pre-Push Snapshot. Call CWK-037 to create a git bundle backup. Warn (do not fail) if snapshot creation fails. Skip if skip_snapshot flag is set.
  9. Verdict. Count PASS, WARN, FAIL results. Any FAIL → NO-GO. All PASS → GO. Warnings only → CONDITIONAL GO (requires human confirmation). Post-gate: remind to update changelog after pushing.

When To Use This Recipe

Use this recipe when you are about to push from a monorepo-layout project to the shared repository, are the MASTER project (MONOREPO_ROLE=MASTER) and need to validate push scope and safety, or want systematic pre-push verification covering branch, scope, structure, and backup.
Do Not Use When
You are using the two-repo architecture — use CWK-046 (Push Orchestrator) instead, which supersedes this recipe for two-repo model projects. For Global file pushes to craft-framework-master-dev, use CWK-045 directly. For routine commit checkpoints without pushing, use CWK-005.

Recipe FAQ

Why is this recipe marked LEGACY?
CWK-038 was designed for the original monorepo layout where all projects shared one repository with a projects/ folder structure. The framework has since transitioned to a two-repo architecture where each project has its own repository. CWK-046 (Push Orchestrator) supersedes CWK-038 for two-repo model projects. CWK-038 remains valid only for projects still on the legacy monorepo layout.
What is the difference between GO, CONDITIONAL GO, and NO-GO?
GO means all 8 checks passed — push is authorized. CONDITIONAL GO means all checks passed but warnings exist (like a failed network fetch or snapshot issue) — push requires explicit human confirmation. NO-GO means at least one check failed — push is blocked until the failure is resolved.
Can I skip individual checks?
Only Check 8 (snapshot) can be skipped via the skip_snapshot flag — use this only if a snapshot was just taken in the current session. All other checks are mandatory and cannot be skipped.
What happens if Check 4 (scope) fails?
It means you have changes outside your project’s folder. This typically means you modified shared framework files. For Global file pushes, use CWK-045 which handles the /tmp clone pattern required for cross-project file distribution.
Does this recipe actually execute the push?
No — it only validates that a push is safe. After receiving a GO verdict, you execute the push separately. The recipe reminds you to update the changelog after pushing.

Version History

v1.00a — 2026-03-05
Initial creation. Eight-point pre-push verification gate with GO/CONDITIONAL GO/NO-GO verdicts. Unanimously endorsed by all 6 active projects during DR consensus (Phase 0, H073). Integrates CWK-037 for pre-push snapshots. Legacy status added when two-repo architecture superseded the monorepo layout.

Get this recipe with CRAFT for Claude Cowork

Cowork recipes ship bundled with CRAFT for Claude Cowork — there’s no separate download. Clone the framework once, and your AI runs every recipe automatically when invoked.

Pull anytime to stay on the latest version — free to clone, no login or email required.

Then start your session

Once CRAFT is in your project folder, open a new Cowork session and ask Claude to initialize. For example:

You

Please initialize my CRAFT session.

Claude

CRAFT session ready. Your project is loaded, your persona is active, and your recipes are available. What would you like to work on?

What is CRAFT for Claude Cowork?

Not familiar with Git? Download as a ZIP

No command line needed. Just download, move, and unzip:

  1. Open the CRAFT framework repo on GitHub.
  2. Click the green Code button, then choose Download ZIP.
  3. Move the downloaded ZIP into your Claude Cowork project folder.
  4. Unzip it: double-click on Mac, or right-click → Extract All on Windows.

Similar Posts