docs(lanes): document ship-feature-lane skill + --qc flag (E1)
This commit is contained in:
@@ -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/<name>/` 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 <requirement>
|
||||
```
|
||||
|
||||
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.**
|
||||
|
||||
Reference in New Issue
Block a user