Document main-based feature workflow (#40)

## Summary
- replace the completed dev integration branch with focused feature
branches from main
- record the workflow as ADR 0052
- update contribution and Voice planning documents without changing
release authorization

## Verification
- full repository check passed before publication
- signed macOS app build verified and installed

This PR changes documentation only.

Author: MarcusJRLee

.github/workflows/codeql.yml

@@ -22,7 +22,7 @@ concurrency:
 
 jobs:
   analyze:
-    name: Analyze (swift)
+    name: CodeQL
     runs-on: macos-26
     timeout-minutes: 45
     steps:

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
 

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

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

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.

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
 

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.

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.

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.
 ```

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