# Organizational Modes (sequential vs parallel)

GMD ships two organizational modes as init-time choices. This reference doc
covers what each mode is, when each fits, cross-mode interaction (migration),
phase numbering, and commit message conventions.

Authoritative spec: `.planning/milestones/v1.5.9-SPEC.md` (§2 mode comparison,
§7 organizational principles, §11 numbering, §D6 asymmetric safety).

## Mode Comparison

| Dimension | Sequential | Parallel |
|-----------|------------|----------|
| Active milestones | 1 at a time | N at a time |
| `.planning/` root | Holds active milestone artifacts | Holds project-level + pointer artifacts |
| Per-milestone artifacts | At `.planning/` root | At `.planning/milestones/<slug>/` |
| Phase numbering | Global to project lifetime | Per-milestone (restart at `01` per milestone) |
| Cross-milestone refs | (rare; no syntax needed) | `<slug>:phase-<N>` syntax (Phase 66 NUMBER-03) |
| Default for new projects | YES (per SPEC L4 dogfood scope) | Opt-in via `config.organizational_mode = parallel` |
| MILESTONES.md shape | Retrospective log (authored at first `/gmd:complete-milestone`) | Forward-looking index (`In Progress` / `Planned` / `Shipped` tables) |
| Active-milestone resolution | Implicit (single milestone is THE milestone) | 4-tier resolver via `bin/lib/active-milestone.js` (current_milestone pointer → CLI flag → branch hint → prompt) |

### Sequential Mode Strength

**Focus.** Reduced WIP. Clean planning artifacts at `.planning/` root.
Suits single-initiative work — GMD itself runs sequential per L4 dogfood
scope, as do side projects and MVP-stage products. The ownership-concurrency
test from SPEC §2 says it directly: sequential's strength is focus.

### Parallel Mode Strength

**Multi-initiative team coordination.** Each milestone gets its own
self-contained planning subtree under `.planning/milestones/<slug>/`.
Suits teams running concurrent feature streams on the same codebase
(originating case: tradesrv3 with `24-5-compatibility` and
`interval-vwap-crossing` advancing in parallel).

## When Each Mode Fits

**Sequential is the default for a reason.** SPEC §2 ("sequential's strength
is focus") fits most workflows. Pick parallel ONLY when ALL of the following
hold:

1. You have ≥2 simultaneously-active feature streams.
2. Each stream needs independent prioritization (different stakeholders, different
   release cadences, or different review owners).
3. Cross-stream coordination overhead exceeds the cost of artifact isolation.

If you're not sure, **start sequential**. `/gmd:migrate-to-parallel <slug>`
is always-safe (per SPEC D6 asymmetric safety) — you can convert later
without rewriting history.

## Cross-Milestone Reference Syntax

Parallel mode introduces per-milestone phase numbering — each milestone restarts
its phase counter at `01`. To reference a phase in a different milestone, use
the `<slug>:phase-<N>` syntax (codified by Phase 66 NUMBER-03):

```
v1.5.8:phase-64                # Phase 64 in milestone v1.5.8
24-5-compatibility:phase-03    # Phase 03 in milestone 24-5-compatibility
interval-vwap-crossing:phase-05  # Phase 05 in milestone interval-vwap-crossing
```

Sequential mode does NOT use this syntax — phase numbers are globally unique
across the project lifetime (Phase 64, 65, 66… ascend monotonically), so a
bare `phase-64` reference is unambiguous.

## Migration Safety

GMD provides two migration commands with **asymmetric safety contracts**.
Sequential→parallel is always safe; parallel→sequential refuses unless
exactly one milestone is In Progress (SPEC D6).

### `/gmd:migrate-to-parallel <first-milestone-slug>`

**Always safe** (modulo dirty-tree refusal). Moves root `.planning/` artifacts
into `milestones/<slug>/`, rewrites PROJECT.md to remove the embedded
`## Current Milestone` section and add an `## Active Milestones` pointer,
authors MILESTONES.md in LAYOUT-03 forward-looking-index shape, flips
`config.organizational_mode` to `parallel`. Single atomic commit.

Refuses if:
- Dirty git tree (uncommitted changes): `refusing migration: working tree not clean. Commit or stash changes before running /gmd:migrate-to-parallel.`
- Source state already parallel: `refusing migration: organizational_mode already 'parallel'. /gmd:migrate-to-parallel is sequential→parallel only.`
- Multiple milestones In Progress (sequential anomaly): `refusing migration: <N> milestones In Progress (...); sequential mode expects ≤1. Resolve manually before migrating.`
- `--yes` flag with research files needing disposition: `refusing --yes migration: <N> research files require explicit disposition. Use --all-milestone, --all-project, or run interactively.`
- `--all-milestone` and `--all-project` flags both passed: `refusing migration: --all-milestone and --all-project are mutually exclusive`

### `/gmd:migrate-to-sequential`

**Asymmetric — refuses unless exactly 1 milestone In Progress.** This is by
design (SPEC D6): sequential mode holds 1 active milestone; converting from
parallel requires choosing which one survives at the `.planning/` root.

Refuses if:
- Multiple milestones In Progress (locked refusal vocabulary): `[migrate-to-sequential] REFUSED: <N> milestones In Progress — sequential mode requires exactly 1 active milestone. Complete or pause others before migration.`
- Dirty git tree: `[migrate-to-sequential] REFUSED: dirty git tree — commit or stash uncommitted changes before migration.`
- `--yes` flag without prior `--dry-run` review: `[migrate-to-sequential] REFUSED: --yes requires prior --dry-run preview. Re-run with --dry-run first to inspect operations.`

### Phase 68 `_archive/` semantics

`/gmd:migrate-to-sequential` relocates **shipped milestone folders** from
`milestones/<slug>/` → `milestones/_archive/<slug>/` at migration time (SPEC
§7 O3; shipped Phase 68 Plan 68-02). This frees the top-level `milestones/`
directory for sequential mode's single-active-milestone layout while
preserving shipped-milestone history.

**`/gmd:complete-milestone` semantics are UNCHANGED.** Shipped folders stay
at top-level (`milestones/<slug>/`) for `/gmd:list-milestones` consumption
UNTIL migration to sequential happens. Archive relocation is a migration-time
concern only — completing a milestone in parallel mode does NOT move folders
to `_archive/`.

The round-trip audit (`tests/audit-migration-round-trip.sh`, Phase 69-01
AUDIT-02) filters `milestones/_archive/*` from the comparison walk as a
documented D9 allowed-differ extension specific to round-trip — the archive
file produced during `migrate-to-sequential` lingers across the round trip,
which is intentional source-of-truth preservation, not a round-trip bug.

### Asymmetric Safety Hard-Contract Vocabulary

The refusal messages above are **byte-asserted** in the migration libraries
(`bin/lib/migrate-to-parallel.js` + `bin/lib/migrate-to-sequential.js`) and
in their sibling test files. Workflows that surface these messages MUST emit
them verbatim — they never paraphrase. Users see consistent UX vocabulary
across the migration command pair. The locked vocabulary is the
hard-contract surface; future refinements may add detail, but the assertion
prefix (`refusing migration:` for parallel direction; `[migrate-to-sequential] REFUSED:`
for sequential direction) is stable.

## Commit Message Suggestion (DOC-05; not enforced)

Parallel mode introduces multiple concurrent milestones, which means commits
may touch multiple milestones' planning subtrees within a short window. The
recommended commit message format is:

```
<slug>: phase-N: <subject>
```

Examples:

```
v1.5.9: phase-69: ship closure substrate
24-5-compatibility: phase-03: add session-replay state machine
interval-vwap-crossing: phase-05: implement crossing detector
```

This format is **suggested, not enforced.** TD-07 hook (`bin/lib/mirror-check.js`)
enforces mirror-byte-identity for source/mirror pairs; it does NOT lint commit
messages. Conflating mirror-byte-identity (structural correctness) with
commit-message linting (stylistic preference) is explicitly rejected per
SPEC §7 O2 lean.

Sequential-mode commits keep the conventional-commit format unchanged:

```
<type>(<scope>): <subject>

feat(69-02): wire 3 workflows to consume get-template-root.js helper
docs(69-02): author references/organizational-modes.md
```

The scope is the phase-plan identifier (`69-02`) since a sequential project
has exactly one active milestone — the milestone is implicit context.

## Related Commands and Files

- `/gmd:new-project` — Step 3.6 prompts for mode (default sequential per L4).
- `/gmd:new-milestone <slug>` — Sequential branch keeps current behavior; parallel branch (1P.3) scaffolds `milestones/<slug>/` via `bin/lib/scaffold-parallel.js`.
- `/gmd:migrate-to-parallel <slug>` — Workflow + library + slash-command shim shipped Phase 68-01.
- `/gmd:migrate-to-sequential` — Workflow + library + slash-command shim shipped Phase 68-02.
- `/gmd:switch-milestone` — Parallel-mode only; changes `current_milestone:` pointer atomically.
- `/gmd:list-milestones` — Parallel-mode only; reads MILESTONES.md In Progress / Planned / Shipped tables.
- `bin/lib/get-template-root.js` — Shared helper resolving `templates/` directory (dev-repo OR npm-global install layout). Consumed by `workflows/new-project.md` Step 3.6 + `workflows/new-milestone.md` parallel branch.

## References

- `.planning/milestones/v1.5.9-SPEC.md` — Authoritative spec (§2 mode comparison; §7 organizational principles; §11.E4 commit-msg format; D6 asymmetric safety; O2 hook-scope lean; O3 archive-preservation).
- `.planning/phases/68-migration-tools/68-02-SUMMARY.md` — `/gmd:migrate-to-sequential` ship summary; locked refusal-message contract; `_archive/` relocation semantics.
- `.planning/phases/66-core-commands/66-04-SUMMARY.md` — Phase 66 NUMBER-03 (`<slug>:phase-<N>` cross-milestone syntax codification).
- `.planning/phases/65-foundation/` — Phase 65 LAYOUT-01..04 (parallel-mode scaffolding shapes).

---

*Reference doc shipped Phase 69-02 (v1.5.9 FINAL milestone). DOC-02 + DOC-05 satisfied. DEFER-66-02 helper consumer-edits in companion workflows landed same plan.*
