diff --git a/docs/LANES.md b/docs/LANES.md index 9416586..e2684bb 100644 --- a/docs/LANES.md +++ b/docs/LANES.md @@ -964,6 +964,78 @@ The lane card shows a lock badge when the lane **holds** a named lock (its `lane - **Never delete the lock directory by hand.** A lock that outlives its holder (e.g. after a hard reboot) is cleaned up automatically — the next `acquire` on that name finds it stale (older than `LOCK_MAX_HOLD`) and breaks it. Deleting `LANES_ROOT/.locks//` yourself only races whoever else's `acquire` is about to do the same check safely. - **Never shrink `LOCK_MAX_HOLD` to force through a wait.** The 300-second floor exists specifically to stop this mistake. If the true holder is gone, the 300-second minimum wait is the price of safety. If the true holder is still running (e.g., a build with a network stall), shortening the timeout from 2700 to 300 does not help — it converts a slow success into a premature timeout, leaving the lock held and every other lane blocked forever. +## The ship-feature-lane skill (E1) + +The **ship-feature-lane** skill is the ported Shipyard driving skill for autonomous end-to-end feature pipelines in a single CCAM lane. It coordinates the entire development flow: implementation (TDD) → pre-push CI gates + dev preflight → e2e testing → code review → local QC → senior gate authorization → PR push and publication → CI watch → final report. + +### Invoking the skill + +```bash +# Inside a lane's working directory: +/ship-feature-lane +``` + +The skill frontloads all clarifying questions once, then runs unattended. The only interactive touchpoints are **Stage 0 (Q&A intake)** and **merging the PR on GitHub**; everything else runs to completion or escalates with a `blocked` status visible on the dashboard. Progress is declared via `ccam stage` commands at every step. + +### Current status: stages 0–8, 10–12, 14 work; stages 9, 13 deferred; stages 6–7 agent-gated + +**Stages implemented now:** +- **0-8**: Intake & frontloaded Q&A → plan → implementation → gates+preflight → e2e on feature branch → code review → QC plan → publish PR +- **10-12**: CI watch on the PR → report → watch PR until merge (gated fix-loop re-entries on review feedback) +- **14**: Done + +**Stages currently hardcoded skipped** (pending F's integrations): +- **9 (Ticket)**: Ticket-filing integration not yet built — this stage is skipped entirely. +- **13 (Post-merge verification)**: Dev-CI-wait and dev-QC integrations are off — the stage transitions immediately to `done` with a note explaining the gap. + +**Stages agent-gated** (will block until the agents-port task lands): +- **6 (Browser QC)**: Requires the `qc-local` agent to drive local Playwright QC against the booted lane stack. +- **7 (Senior gate)**: Requires the `senior-gate-reviewer` agent to authorize feature merge. + +Until these agents are ported, a lane reaching Stage 6 or 7 will be marked `blocked` with a note. See [the skill text](../.claude/skills/ship-feature-lane/SKILL.md) for the full pipeline definition. + +### QC boot flag and profile integration + +When the lane stack needs to run under QC conditions (deterministic, mocked externals), use the `--qc` flag: + +```bash +ccam lanes up --qc +``` + +This flag activates the lane's `QC_BOOT_ENV` profile declaration. Define it in the profile's `profile.env` file as space-separated `KEY=value` pairs (the same format as the `PORTS` declaration): + +```bash +# .ccam/profile/profile.env +PORTS="app" +PORT_BASE_app=3000 +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. + +### Pipeline template: ship-feature (16 node stages) + +The skill uses the `ship-feature` pipeline template, which defines the following 16 stages (node IDs): + +1. **intake** — frontloaded Q&A and feature activation +2. **plan** — investigation and plan debate +3. **implementing** — TDD implementation +4. **gates** — CI gates + preflight check +5. **e2e-feature** — run e2e on feature branch +6. **e2e-feature-passed** — e2e result gate +7. **review** — code review +8. **qc-plan** — bound QC scope +9. **qc** — browser QC (agent-gated until qc-local lands) +10. **gate** — senior GO/NO-GO gate (agent-gated until senior-gate-reviewer lands) +11. **publishing** — push branch + open/update PR +12. **pr-open** — PR open and published +13. **reported** — report posted +14. **watching-pr** — watch for comments, conflicts, merge +15. **merged** — PR merged, post-verify transition +16. **done** — pipeline complete + +The Workspace page (`/run`) displays this template with nodes rendered in five states: `failed` (rejected), `current` (now), `done` (with evidence), `passed-no-evidence` (claimed or skipped), and `pending` (not reached). + ## Orchestration: what CCAM does NOT do **CCAM does not chain, queue, retry, or evaluate gates.** diff --git a/docs/superpowers/plans/2026-08-03-shipyard-parity-lanes.md b/docs/superpowers/plans/2026-08-03-shipyard-parity-lanes.md index 530e1c9..77ac583 100644 --- a/docs/superpowers/plans/2026-08-03-shipyard-parity-lanes.md +++ b/docs/superpowers/plans/2026-08-03-shipyard-parity-lanes.md @@ -279,6 +279,8 @@ 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. + **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 records.