forge: step 1 — bootstrap wrapper workflow

.forge/steps/step-1-plan.md

@@ -0,0 +1,56 @@
+# Step 1 Execution Plan: Bootstrap wrapper repository, upstream submodule, and patch workflow
+
+## Goal
+Create a reproducible Colorado Mesh firmware wrapper that pins upstream MeshCore and can apply/export Colorado bot patches without relying on untracked submodule edits.
+
+## Current Code Observations
+- Local MeshCore exists at `/Users/cjvana/Documents/GitHub/MeshCore` commit `6b52fb32301c273fc78d96183501eb23ad33c5bb`, but research recommends pinning the wrapper submodule independently.
+- MeshCore builds from its repo root with `build.sh build-firmware <env>` and expects `FIRMWARE_VERSION` in the environment before building.
+- MeshCore `platformio.ini` includes all variant configs via `variants/*/platformio.ini` and currently enables `ENABLE_PRIVATE_KEY_IMPORT=1` / `ENABLE_PRIVATE_KEY_EXPORT=1`; key hardening is a later step.
+- Representative environments exist in the local checkout: `Heltec_v3_companion_radio_usb`, `Heltec_v3_companion_radio_ble`, `RAK_4631_companion_radio_usb`, and `RAK_4631_companion_radio_ble`.
+- PlatformIO is not installed locally right now, so Step 1 verification must be limited to git/submodule/script behavior and shell syntax.
+
+## Files to Change
+- `.gitmodules` — created by `git submodule add`.
+- `vendor/MeshCore` — submodule pointer to upstream MeshCore.
+- `scripts/meshcore-env.sh` — shared wrapper environment variables and helper functions.
+- `scripts/apply-patches.sh` — verify submodule state and apply sorted patch queue.
+- `scripts/export-patches.sh` — regenerate patch queue from a named submodule branch/range.
+- `patches/meshcore/.gitkeep` — keep empty patch queue directory tracked.
+- `colorado/README.md` — short notes for Colorado overlay intent.
+- `README.md` — wrapper workflow instructions for future contributors.
+
+## Ordered Implementation Checklist
+1. Add `vendor/MeshCore` as a git submodule from `https://github.com/meshcore-dev/MeshCore.git` and leave it pinned at the resolved commit.
+2. Create `scripts/`, `patches/meshcore/`, and `colorado/` directories.
+3. Implement `scripts/meshcore-env.sh` with repo-root detection, `MESHCORE_DIR`, `PATCH_DIR`, representative env list, and `meshcore_commit()` helper.
+4. Implement `scripts/apply-patches.sh` with strict shell settings, submodule existence check, dirty submodule check, empty-patch success path, sorted patch application, and clear status output.
+5. Implement `scripts/export-patches.sh` with strict shell settings, dirty submodule guidance, configurable base ref defaulting to `origin/main`, deterministic patch regeneration, and refusal to export when there are no commits beyond the base.
+6. Add minimal README/development notes describing submodule init, patch apply, patch export, and representative env names.
+7. Run shell syntax checks and `scripts/apply-patches.sh` with the empty patch queue.
+8. Stage only Step 1 files for review.
+
+## Interfaces and Data Contracts
+- `scripts/meshcore-env.sh` can be sourced by other scripts and must not execute builds itself.
+- `scripts/apply-patches.sh` exits 0 with an empty patch queue and exits non-zero if the submodule is missing, dirty, or patch application fails.
+- `scripts/export-patches.sh [base-ref]` regenerates `patches/meshcore/*.patch` from commits after `base-ref`; it does not export uncommitted submodule edits.
+- Representative env names are exposed as the shell array `REPRESENTATIVE_ENVS`.
+
+## Verification Plan
+- Automated:
+  - `git submodule status`
+  - `bash -n scripts/meshcore-env.sh scripts/apply-patches.sh scripts/export-patches.sh`
+  - `bash scripts/apply-patches.sh`
+  - `git status --short`
+- Manual:
+  - Confirm `vendor/MeshCore` points to a real upstream commit.
+  - Confirm an empty patch queue leaves the submodule unchanged.
+- Regression:
+  - No firmware source files should be modified in Step 1.
+  - `.forge/` artifacts are not staged as product source except required Forge documents remain available for review.
+
+## Stop Conditions
+- Stop and ask if `git submodule add` fails due to network/auth issues.
+- Stop and ask if `vendor/MeshCore` already exists with unexpected contents.
+- Stop and ask before deleting or overwriting any existing non-Forge files.
+- Stop if the submodule checkout has unexpected dirty changes immediately after adding it.