docs(lanes): document ccam lanes sync-base (E2)

2026-08-05 10:59:02 +07:00
parent 5a127df709
commit ed884c6961
3 changed files with 27 additions and 6 deletions
@@ -1013,6 +1013,28 @@ QC_BOOT_ENV="MOCK_PAYMENTS=1 STUB_EMAIL=1"

 These environment variables are passed to the profile's `boot` hook during `ccam lanes up --qc`, ensuring QC test runs are deterministic.

+### Dev preflight and merge safety: sync-base
+
+`ccam lanes sync-base` is the ONE sanctioned merge in the pipeline — `origin/development` into a feature branch — used at Stages 2, 8, and 12. Three modes:
+
+```bash
+ccam lanes sync-base --check feat/<slug>      # read-only preflight: fetch + collision check + DEV_DELTA/DEV_OVERLAP
+ccam lanes sync-base feat/<slug>               # merge origin/development into the feature branch
+ccam lanes sync-base --continue feat/<slug>    # finish after a manually resolved conflict
+```
+
+Exit codes: `0` clean, `4` merge conflict (left in place — resolve, commit, then `--continue`), `5` migration-number collision (nothing merged — rename the printed file, re-run).
+
+Two profile declarations control it, both empty (off) by default:
+
+```bash
+# .ccam/profile/profile.env
+MIGRATIONS_DIR="db/migrations"
+GENERATED_MERGE_PATHS="api/openapi.json api/client.ts"
+```
+
+`MIGRATIONS_DIR` enables the collision preflight against a numbered-migrations directory. `GENERATED_MERGE_PATHS` gives the listed files a keep-ours merge driver (never hand-merged) and folds the profile's `regen` hook output into the sync commit — the single most common cross-lane conflict, for a repo that generates an API contract/client.
+
 ### Pipeline template: ship-feature (16 node stages)

 The skill uses the `ship-feature` pipeline template, which defines the following 16 stages (node IDs):
@@ -279,7 +279,7 @@ with `LOCK_MAX_HOLD=1`; release from a non-holder is refused and leaves the lock

 **Goal:** port Shipyard's driving skill and its five agents. Needs A2·B·C·D.

-**Progress:** pipeline template + skill text (E1) done 2026-08-04 — see `docs/superpowers/specs/2026-08-04-ship-feature-skill-design.md`. Agents, `sync-base`, and F's integrations remain.
+**Progress:** pipeline template + skill text (E1) done 2026-08-04 — see `docs/superpowers/specs/2026-08-04-ship-feature-skill-design.md`. `sync-base` (E2) done 2026-08-05 — see `docs/superpowers/specs/2026-08-05-sync-base-design.md`. Agents and F's integrations remain.

 **This is where "CCAM does not orchestrate" is preserved by construction:** the
 skill runs in the session and calls `ccam` commands; the dashboard still only