From 8ca45dd069d75dc12048aea41d893fa5160c2d12 Mon Sep 17 00:00:00 2001 From: MarcusJRLee <7527115+MarcusJRLee@users.noreply.github.com> Date: Thu, 27 Aug 2026 23:38:13 -0400 Subject: [PATCH 1/2] Document main-based feature workflow --- CONTRIBUTING.md | 7 ++- .../0029_local_voice_platform_expansion.md | 2 + ...0051_unreleased_voice_integration_build.md | 3 ++ .../0052_main_feature_branch_workflow.md | 48 +++++++++++++++++++ docs/game_plan.md | 9 ++-- docs/open_questions.md | 4 +- docs/voice_cujs.md | 2 +- docs/voice_implementation_goal_prompt.md | 24 +++++----- docs/voice_platform_design.md | 15 +++--- 9 files changed, 84 insertions(+), 30 deletions(-) create mode 100644 docs/decisions/0052_main_feature_branch_workflow.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fecdbad..5c1c5b7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -45,10 +45,9 @@ GitHub requests review from the repository owner. Automated verification must pass, review threads must be resolved, and accepted changes are squash-merged. The `Analyze (swift)` gate performs an extended CodeQL scan when Swift or its build inputs change and completes without compiling Swift for unrelated -changes. During the accepted Voice program, focused pull requests target -`dev`; `dev` returns to `main` only after the completed program receives final -user verification. See -[`0029_local_voice_platform_expansion.md`](docs/decisions/0029_local_voice_platform_expansion.md). +changes. Create each focused branch from current `main` and target its pull +request at `main`. See +[`0052_main_feature_branch_workflow.md`](docs/decisions/0052_main_feature_branch_workflow.md). ## Privacy and hardware evidence diff --git a/docs/decisions/0029_local_voice_platform_expansion.md b/docs/decisions/0029_local_voice_platform_expansion.md index 50cb5db..be84693 100644 --- a/docs/decisions/0029_local_voice_platform_expansion.md +++ b/docs/decisions/0029_local_voice_platform_expansion.md @@ -2,6 +2,8 @@ - **Status:** Accepted; macOS M1–M12 implemented - **Date:** 2026-08-25 +- **Branch workflow superseded by:** + [`0052_main_feature_branch_workflow.md`](0052_main_feature_branch_workflow.md) - **Amends:** [`0001_native_macos_stack.md`](0001_native_macos_stack.md), [`0005_app_owned_transcription.md`](0005_app_owned_transcription.md), and diff --git a/docs/decisions/0051_unreleased_voice_integration_build.md b/docs/decisions/0051_unreleased_voice_integration_build.md index 318076e..84ea7d1 100644 --- a/docs/decisions/0051_unreleased_voice_integration_build.md +++ b/docs/decisions/0051_unreleased_voice_integration_build.md @@ -2,6 +2,9 @@ **Status:** Accepted +**Branch workflow superseded by:** +[decision 0052](0052_main_feature_branch_workflow.md) + ## Context The accepted Voice program is integrated into `dev`, including the macOS Voice diff --git a/docs/decisions/0052_main_feature_branch_workflow.md b/docs/decisions/0052_main_feature_branch_workflow.md new file mode 100644 index 0000000..1915abd --- /dev/null +++ b/docs/decisions/0052_main_feature_branch_workflow.md @@ -0,0 +1,48 @@ +# Decision 0052: Integrate focused feature branches through main + +**Status:** Accepted + +**Date:** 2026-08-28 + +**Supersedes:** The `dev` integration-branch workflow in +[decision 0029](0029_local_voice_platform_expansion.md) and the execution +instructions derived from it. Release approval remains unchanged. + +## Context + +The accepted Voice program completed on `dev`. Keeping a permanent integration +branch after that program finished would duplicate the default branch, require +manual promotion, and let documentation or fixes drift between two long-lived +lines. The user directed future work to use individual feature branches from +`main` and to remove `dev` without losing its reviewed history. + +| Criterion | Focused branches into `main` | Permanent `dev` integration branch | +| --- | ---: | ---: | +| One current integration line | 5 | 2 | +| Required-check visibility | 5 | 5 | +| Risk of branch drift | 5 | 2 | +| Focused review and rollback | 5 | 5 | +| Extra promotion ceremony | 5 | 1 | +| **Total** | **25** | **15** | + +## Decision + +- Preserve the completed `dev` history through pull request 39 into `main`, + verify the merge, then delete the local and remote `dev` branches. +- Create each subsequent `codex/*` feature branch from the latest integrated + `main` and target its focused pull request at `main`. +- Merge only after required checks pass. Keep dependent work stacked when a + repository rule prevents an immediate merge; do not bypass protections. +- Keep behavior, tests, migrations, and documentation together when they form + one vertical change. Split unrelated responsibilities into separate PRs. +- Treat integration into `main` as source control only. It does not approve a + tag, release version, DMG, GitHub Release, notarization, App Store submission, + or public binary. + +## Consequences + +- `main` is the only long-lived integration branch. +- Completed program history remains reachable through the preservation merge + and its original pull requests. +- Current documentation no longer describes a pending `dev` promotion gate. +- Release metadata and distribution remain separately and explicitly gated. diff --git a/docs/game_plan.md b/docs/game_plan.md index 45e1f5b..b7ed6d4 100644 --- a/docs/game_plan.md +++ b/docs/game_plan.md @@ -47,7 +47,7 @@ evidence is retained in [`release_validation.md`](release_validation.md). ## Approved next program -The local Voice expansion is accepted and integrated into `dev`: macOS M1–M15, +The local Voice expansion is accepted and integrated into `main`: macOS M1–M15, iOS Gate K0, I1 local onboarding and Model admission, I2 local formatting and History, Style-qualified keyboard delivery, target-safe field handling, I7 lifecycle recovery, I8 stale-service recovery, I9 bounded insertion recovery, @@ -63,9 +63,10 @@ The acceptance and execution authorities are: | [`voice_platform_design.md`](voice_platform_design.md) | Model, runtime, iOS keyboard, storage, performance, and milestone design. | | [`voice_implementation_goal_prompt.md`](voice_implementation_goal_prompt.md) | Autonomous worktree/PR execution contract and definition of done. | -Focused vertical PRs are integrated into `dev`. `main`, tags, distribution -artifacts, and store submission remain unchanged until the user verifies the -finished `dev` state and separately approves promotion. +New work uses focused feature branches from `main` and pull requests back into +`main`. Tags, distribution artifacts, and store submission remain separately +gated. See +[`decisions/0052_main_feature_branch_workflow.md`](decisions/0052_main_feature_branch_workflow.md). ## Quality gates diff --git a/docs/open_questions.md b/docs/open_questions.md index 410a1f7..c71e299 100644 --- a/docs/open_questions.md +++ b/docs/open_questions.md @@ -53,7 +53,7 @@ Current behavior remains unchanged until the accepted roadmap ships. | --- | --- | | Product boundary | Add Voice to the existing Hardware Controller macOS app; create no second macOS product. | | Repository | Use one repository with incremental `apps/`, Rust crate, Apple support, schema, and CUJ boundaries. | -| Delivery | Start with M1 and proceed CUJ-by-CUJ through focused worktree PRs into `dev`; keep `main` gated on final user verification. | +| Delivery | Use focused feature branches from current `main` and pull requests back into `main`; keep release promotion separately gated. | | History | Retain transcripts until deletion; cap successful audio by accepted age, byte, and artifact-count defaults; retain recoverable partials for 24 hours; import bounded local recordings into one app-owned CAF without changing the source. | | Local-only | Permit explicit verified Model-package downloads containing no Voice data; exclude Voice data from app sync/backup where supported; add no accounts, telemetry, cloud inference, or remote storage. | | Models | Use separate ASR and optional formatting stages with deterministic edits, validation, and Raw/Edited fallback; delegate provider/package choice to measured evidence. | @@ -63,4 +63,4 @@ Current behavior remains unchanged until the accepted roadmap ships. No unresolved user choice blocks the implementation goal. K0 signed-device, model, performance, and App Review checks are evidence gates that must not stop -independent work. Release promotion and `dev` → `main` remain separately gated. +independent work. Release promotion remains separately gated. diff --git a/docs/voice_cujs.md b/docs/voice_cujs.md index 8c7fe2d..f019bd0 100644 --- a/docs/voice_cujs.md +++ b/docs/voice_cujs.md @@ -595,6 +595,6 @@ The user accepted on 2026-08-25: 5. Gate K0 and an honest cold-start/app-switch experience; and 6. benchmark-selected deployment floors and Model packages. -These choices do not approve release promotion or `dev` → `main`. Model, +These choices do not approve release promotion. Model, signed-device, and App Review findings are implementation evidence, not new preference questions. diff --git a/docs/voice_implementation_goal_prompt.md b/docs/voice_implementation_goal_prompt.md index d8992be..62d2b6a 100644 --- a/docs/voice_implementation_goal_prompt.md +++ b/docs/voice_implementation_goal_prompt.md @@ -9,7 +9,7 @@ Create and pursue a goal with no token budget to implement the accepted local Voice platform roadmap to polished completion. Incur no monetary cost: do not purchase services, models, subscriptions, hardware, certificates, or paid build capacity. Continue autonomously until every safe, in-scope macOS and iOS -requirement is implemented, verified, documented, and integrated into the dev +requirement is implemented, verified, documented, and integrated into the main branch. Do not stop merely because the work is large, slow, spans many pull requests, or encounters an evidence gap. @@ -47,20 +47,20 @@ Operating mode: or prototype web/mobile web in this program. Git and pull-request workflow: -- Use dev as the integration branch. If it does not exist, create it from the - current main without modifying main. -- Implement every logical slice on a new codex/voice_* branch in its own Git - worktree. Base it on the latest integrated dev state. +- Use main as the integration branch. +- Implement every logical slice on a new codex/voice_* branch from the latest + integrated main state. Use a separate Git worktree when slices run in + parallel. - Each PR must be focused and vertically useful: acceptance/docs, behavioral test, implementation, migration, and verification for one coherent slice. Avoid giant PRs, layer-only batches, unrelated cleanup, and artificial one-file PRs. -- Target every program PR at dev. Merge it after required checks pass when +- Target every program PR at main. Merge it after required checks pass when repository policy permits. If policy requires unavailable human review, keep dependent work in explicit stacked PRs and continue without bypassing it. - Keep PR descriptions concise: CUJs covered, architecture decision, tests and measurements, migrations, risks, and rollback/recovery behavior. -- Never push directly to main or merge dev into main. Do not change release +- Never push directly to main. Do not change release versions/build numbers, create tags, DMGs, GitHub Releases, App Store submissions, or release records without separate explicit approval. @@ -108,7 +108,7 @@ Testing strategy—strong but adaptable: complete quality/performance matrix before final handoff. Program sequence: -1. Integrate the approved planning/decision/CUJ baseline and establish dev/CI. +1. Integrate the approved planning/decision/CUJ baseline and establish CI. 2. Deliver the macOS M1 tracer inside the existing Hardware Controller app. 3. Complete macOS capture gestures, Styles, Dictionary, spoken edits, safe delivery, History, retention, recovery, imported audio, local enforcement, @@ -136,7 +136,7 @@ Definition of done: latency, memory, energy, migrations, and failure paths meet the documented gates or have an evidence-backed documented adjustment preserving the product promise. -- All required checks pass on dev. Every focused PR is merged to dev or, only +- All required checks pass on main. Every focused PR is merged to main or, only where repository policy makes that impossible, is ready and explicitly ordered with no missing engineering work. - The canonical signed macOS development app is installed, verified, and @@ -145,10 +145,10 @@ Definition of done: hardware. - README, product brief, architecture, game plan, CUJs, decisions, user guide, contributor guidance, troubleshooting, privacy, and release/install runbooks - describe the finished dev state without stale proposal language. + describe the finished main state without stale proposal language. - Final handoff is concise and includes: outcome, PR list, remaining external- owner evidence only, exact verification results, known limitations, and quick macOS/iOS installation and first-use instructions. -- main remains untouched. Stop after dev is ready for my final verification and - wait for explicit approval before proposing or performing dev → main. +- Source integration into main does not approve release promotion. Wait for + explicit approval before changing release metadata or publishing artifacts. ``` diff --git a/docs/voice_platform_design.md b/docs/voice_platform_design.md index 0f1e063..8ac8586 100644 --- a/docs/voice_platform_design.md +++ b/docs/voice_platform_design.md @@ -533,17 +533,18 @@ peak memory, installed size, and energy per audio minute. ## Program delivery and test balance -Use `dev` as the integration branch. Each coherent vertical slice uses a fresh -`codex/voice_*` branch in a separate Git worktree and a focused pull request into -`dev`. A slice includes its acceptance/documentation change, behavior test, +Use `main` as the integration branch. Each coherent vertical slice uses a fresh +`codex/voice_*` branch from current `main` and a focused pull request into +`main`. A slice includes its acceptance/documentation change, behavior test, implementation, migration, and verification where those responsibilities change together. Do not use layer-only batches or unrelated cleanup to manufacture PR boundaries. -Merge a PR to `dev` after required checks pass when repository policy permits. +Merge a PR to `main` after required checks pass when repository policy permits. If policy requires unavailable human review, keep later work in explicit stacked -PRs without bypassing protections. `main` remains unchanged until the complete -`dev` state receives user verification and separate merge approval. +PRs without bypassing protections. Source integration does not approve release +metadata, tags, packages, notarization, or store submission. See +[`decisions/0052_main_feature_branch_workflow.md`](decisions/0052_main_feature_branch_workflow.md). Testing uses four complementary levels: @@ -569,7 +570,7 @@ test first or batch the entire implementation behind mocked internals. - Reconcile the accepted decision, canonical language, CUJ observations, retention defaults, and current source without reopening approved choices. -- Establish `dev`, the per-PR worktree workflow, and required CI checks. +- Establish focused branches from `main` and required CI checks. - Create the repository directory skeleton only as needed by the first test. - Add one failing, deterministic Mac CUJ M1 tracer test using a short sanitized audio fixture, fake capture clock, temporary repository, and fake delivery From 87db1b89eeb694988406dd2d2c8b80ad014a3434 Mon Sep 17 00:00:00 2001 From: MarcusJRLee <7527115+MarcusJRLee@users.noreply.github.com> Date: Fri, 28 Aug 2026 00:46:55 -0400 Subject: [PATCH 2/2] Align CodeQL check with main protection --- .github/workflows/codeql.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml index 71f94f0..a1adc43 100644 --- a/.github/workflows/codeql.yml +++ b/.github/workflows/codeql.yml @@ -22,7 +22,7 @@ concurrency: jobs: analyze: - name: Analyze (swift) + name: CodeQL runs-on: macos-26 timeout-minutes: 45 steps: