@lumenflow/cli 3.20.0 → 3.21.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/init-templates.js +30 -22
- package/dist/init-templates.js.map +1 -1
- package/package.json +8 -8
- package/packs/agent-runtime/.turbo/turbo-build.log +1 -1
- package/packs/agent-runtime/package.json +1 -1
- package/packs/sidekick/.turbo/turbo-build.log +1 -1
- package/packs/sidekick/package.json +1 -1
- package/packs/software-delivery/.turbo/turbo-build.log +1 -1
- package/packs/software-delivery/package.json +1 -1
- package/templates/core/.lumenflow/constraints.md.template +68 -3
- package/templates/core/LUMENFLOW.md.template +26 -26
- package/templates/core/_frameworks/lumenflow/wu-sizing-guide.md.template +1 -3
- package/templates/core/ai/onboarding/agent-safety-card.md.template +14 -4
- package/templates/core/ai/onboarding/first-wu-mistakes.md.template +96 -0
- package/templates/core/ai/onboarding/quick-ref-commands.md.template +23 -22
- package/templates/core/ai/onboarding/rapid-prototyping.md +2 -1
- package/templates/core/ai/onboarding/starting-prompt.md.template +3 -3
- package/templates/core/ai/onboarding/troubleshooting-wu-done.md.template +69 -1
package/dist/init-templates.js
CHANGED
|
@@ -74,10 +74,10 @@ pnpm lane:lock
|
|
|
74
74
|
pnpm wu:claim --id WU-XXXX --lane <Lane>
|
|
75
75
|
cd worktrees/<lane>-wu-xxxx
|
|
76
76
|
|
|
77
|
-
# 2. Work in worktree,
|
|
78
|
-
pnpm
|
|
77
|
+
# 2. Work in worktree, then prep for completion
|
|
78
|
+
pnpm wu:prep --id WU-XXXX
|
|
79
79
|
|
|
80
|
-
# 3. Complete
|
|
80
|
+
# 3. Complete from main using the command printed by wu:prep
|
|
81
81
|
cd <project-root>
|
|
82
82
|
pnpm wu:done --id WU-XXXX
|
|
83
83
|
\`\`\`
|
|
@@ -86,9 +86,10 @@ pnpm wu:done --id WU-XXXX
|
|
|
86
86
|
|
|
87
87
|
---
|
|
88
88
|
|
|
89
|
-
## Critical:
|
|
89
|
+
## Critical: Use wu:prep Then wu:done
|
|
90
90
|
|
|
91
|
-
After completing work,
|
|
91
|
+
After completing work in the worktree, run \`pnpm wu:prep --id WU-XXXX\`, then run
|
|
92
|
+
\`pnpm wu:done --id WU-XXXX\` from the main checkout.
|
|
92
93
|
|
|
93
94
|
This is the single most forgotten step. See [LUMENFLOW.md](LUMENFLOW.md) for details.
|
|
94
95
|
|
|
@@ -98,7 +99,7 @@ This is the single most forgotten step. See [LUMENFLOW.md](LUMENFLOW.md) for det
|
|
|
98
99
|
|
|
99
100
|
1. **Fit-For-Surface Verification**: Choose the least brittle verification that gives strong confidence. Prefer TDD for runtime logic when policy requires it; avoid brittle UI implementation-detail tests.
|
|
100
101
|
2. **Worktree Discipline**: After \`wu:claim\`, work ONLY in the worktree
|
|
101
|
-
3. **Gates Before Done**: Run \`pnpm
|
|
102
|
+
3. **Gates Before Done**: Run \`pnpm wu:prep\` before \`wu:done\`
|
|
102
103
|
4. **Never Bypass Hooks**: No \`--no-verify\`
|
|
103
104
|
|
|
104
105
|
---
|
|
@@ -123,7 +124,7 @@ This file provides universal guidance for all AI agents. Additional vendor-speci
|
|
|
123
124
|
// Template for LUMENFLOW.md (main entry point)
|
|
124
125
|
// WU-1309: Use <project-root> placeholder for portability
|
|
125
126
|
// WU-1364: Added initiative workflow section
|
|
126
|
-
export const LUMENFLOW_MD_TEMPLATE = `# LumenFlow Workflow Guide\n\n**Last updated:** {{DATE}}\n\nLumenFlow is a vendor-agnostic workflow framework for AI-native software development.\n\n---\n\n## Critical Rule:
|
|
127
|
+
export const LUMENFLOW_MD_TEMPLATE = `# LumenFlow Workflow Guide\n\n**Last updated:** {{DATE}}\n\nLumenFlow is a vendor-agnostic workflow framework for AI-native software development.\n\n---\n\n## Critical Rule: Use wu:prep Then wu:done\n\nCompletion is a two-step process: run \`pnpm wu:prep --id WU-XXXX\` from the worktree, then run \`pnpm wu:done --id WU-XXXX\` from the main checkout.\n\nDo NOT:\n- Write "To Complete: pnpm wu:done" and stop\n- Ask if you should run wu:done\n- Forget to run wu:done after wu:prep\n- Run wu:done from the worktree\n\n**DO**: finish the full \`wu:prep -> wu:done\` flow every time.\n\n---\n\n## When to Use Initiatives\n\nUse **Initiatives** for multi-phase work spanning multiple WUs:\n\n- **Product visions**: "Build a task management app"\n- **Larger features**: Work requiring multiple WUs across lanes\n- **Complex projects**: Anything that needs phased delivery\n\n\`\`\`bash\n# Create an initiative for multi-phase work\npnpm initiative:create --id INIT-001 --title "Feature Name" \\\\\n --description "..." --phase "Phase 1: MVP" --phase "Phase 2: Polish"\n\n# Add WUs to the initiative\npnpm initiative:add-wu --initiative INIT-001 --wu WU-XXX --phase 1\n\n# Track progress\npnpm initiative:status --id INIT-001\n\`\`\`\n\n**Skip initiatives** for: single-file bug fixes, small docs updates, isolated refactoring.\n\n---\n\n## Quick Start\n\n\`\`\`bash\n# 1. Configure lanes (once per project)\npnpm lane:setup\npnpm lane:validate\npnpm lane:lock\n\n# 2. Create a WU\npnpm wu:create --id WU-XXXX --lane <Lane> --title "Title"\n\n# 3. Edit WU spec with acceptance criteria, then claim:\npnpm wu:claim --id WU-XXXX --lane <Lane>\ncd worktrees/<lane>-wu-xxxx\n\n# 4. Implement in worktree\n\n# 5. Prep for completion\npnpm wu:prep --id WU-XXXX\n# This runs the right gates in the worktree\n\n# 6. Complete (from main checkout)\ncd <project-root>\npnpm wu:done --id WU-XXXX\n\`\`\`\n\n---\n\n## Core Principles\n\n1. **Fit-For-Surface Verification**: Choose the least brittle verification that gives strong confidence. Prefer TDD for runtime logic when repository policy requires it; prefer behavior-focused integration, smoke, visual, or manual verification for UI, content, and presentation work.\n2. **Library-First**: Search existing libraries before custom code\n3. **DRY/SOLID/KISS/YAGNI**: No magic numbers, no hardcoded strings\n4. **Worktree Discipline**: After \`wu:claim\`, work ONLY in the worktree\n5. **Gates Before Done**: All gates must pass before \`wu:done\`\n6. **Do Not Bypass Hooks**: No \`--no-verify\`, fix issues properly\n7. **Finish the two-step flow**: Complete every WU with \`pnpm wu:prep\` and then \`pnpm wu:done\`\n\n---\n\n## Documentation Structure\n\n### Core (Vendor-Agnostic)\n\n- **LUMENFLOW.md** - This file, main entry point\n- **.lumenflow/constraints.md** - Non-negotiable workflow constraints\n- **.lumenflow/agents/** - Agent instructions (vendor-agnostic)\n- **workspace.yaml** - Kernel workspace configuration (software_delivery block)\n\n### Optional Overlays\n\n- **CLAUDE.md + .claude/agents/** - Claude Code overlay (auto if Claude Code detected)\n- **{{DOCS_TASKS_PATH}}** - Task boards and WU storage (\`lumenflow init --full\`)\n- **{{DOCS_ONBOARDING_PATH}}** - Agent onboarding docs\n- **.lumenflow.framework.yaml** - Framework hint file (created with \`--framework\`)\n\n---\n\n## Worktree Discipline (IMMUTABLE LAW)\n\nAfter claiming a WU, you MUST work in its worktree:\n\n\`\`\`bash\n# 1. Claim creates worktree\npnpm wu:claim --id WU-XXX --lane <lane>\n\n# 2. IMMEDIATELY cd to worktree\ncd worktrees/<lane>-wu-xxx\n\n# 3. ALL work happens here\n\n# 4. Return to main ONLY after wu:prep prints the completion command\ncd <project-root>\npnpm wu:done --id WU-XXX\n\`\`\`\n\n---\n\n## Definition of Done\n\n- Acceptance criteria satisfied\n- Gates green (\`pnpm gates\` or \`pnpm gates:docs\`; \`pnpm gates --docs-only\` is the equivalent flag form)\n- WU YAML status = \`done\`\n- \`wu:done\` has been run\n\n---\n\n## Commands Reference\n\n| Command | Description |\n| ----------------- | ----------------------------------- |\n| \`pnpm lane:status\` | Show lane lifecycle status |\n| \`pnpm lane:setup\` | Create/update draft lane artifacts |\n| \`pnpm lane:lock\` | Lock lane lifecycle for WU creation |\n| \`pnpm wu:create\` | Create new WU spec |\n| \`pnpm wu:claim\` | Claim WU and create worktree |\n| \`pnpm wu:prep\` | Run gates in worktree, prep for completion |\n| \`pnpm wu:done\` | Complete WU (merge, stamp, cleanup) |\n| \`pnpm gates\` | Run quality gates |\n| \`pnpm gates:docs\`| Preferred docs-only gate alias |\n| \`pnpm initiative:create\` | Create multi-phase initiative |\n| \`pnpm initiative:status\` | View initiative progress |\n\n---\n\n## Constraints\n\nSee [.lumenflow/constraints.md](.lumenflow/constraints.md) for the 6 non-negotiable rules.\n\n---\n\n## Agent Onboarding\n\n- Start with **CLAUDE.md** if present (Claude Code overlay).\n- Add vendor-agnostic guidance in **.lumenflow/agents/**.\n- Check the onboarding docs in **{{DOCS_ONBOARDING_PATH}}** for detailed guidance.\n`;
|
|
127
128
|
// Template for .lumenflow/constraints.md
|
|
128
129
|
export const CONSTRAINTS_MD_TEMPLATE = `# LumenFlow Constraints Capsule\n\n**Version:** 1.0\n**Last updated:** {{DATE}}\n\n## The 6 Non-Negotiable Constraints\n\n### 1. Worktree Discipline and Git Safety\nWork only in worktrees, treat main as read-only, never run destructive git commands on main.\n\n### 2. WUs Are Specs, Not Code\nRespect code_paths boundaries, no feature creep, no code blocks in WU YAML files.\n\n### 3. Docs-Only vs Code WUs\nDocumentation WUs use \`--docs-only\` gates, code WUs run full gates.\n\n### 4. LLM-First, Zero-Fallback Inference\nUse LLMs for semantic tasks, fall back to safe defaults (never regex/keywords).\n\n### 5. Gates and Skip-Gates\nComplete via \`pnpm wu:done\`; skip-gates only for pre-existing failures with \`--reason\` and \`--fix-wu\`.\n\n### 6. Safety and Governance\nRespect privacy rules, approved sources, security policies; when uncertain, choose safer path.\n\n---\n\n## Mini Audit Checklist\n\nBefore running \`wu:done\`, verify:\n\n- [ ] Working in worktree (not main)\n- [ ] Only modified files in \`code_paths\`\n- [ ] Gates pass\n- [ ] No forbidden git commands used\n- [ ] Acceptance criteria satisfied\n\n---\n\n## Escalation Triggers\n\nStop and ask a human when:\n- Same error repeats 3 times\n- Auth or permissions changes required\n- PII/safety issues discovered\n- Cloud spend or secrets involved\n`;
|
|
129
130
|
// Template for root CLAUDE.md
|
|
@@ -335,8 +336,9 @@ pnpm wu:create \\
|
|
|
335
336
|
|
|
336
337
|
| Command | Description |
|
|
337
338
|
| ------------------------ | -------------------------- |
|
|
338
|
-
| \`pnpm gates\` | Run all quality gates
|
|
339
|
-
| \`pnpm gates
|
|
339
|
+
| \`pnpm gates\` | Run all quality gates |
|
|
340
|
+
| \`pnpm gates:docs\` | Preferred docs-only alias |
|
|
341
|
+
| \`pnpm gates --docs-only\` | Equivalent docs-only flag form |
|
|
340
342
|
| \`pnpm format\` | Format all files |
|
|
341
343
|
| \`pnpm lint\` | Run linter |
|
|
342
344
|
| \`pnpm typecheck\` | Run TypeScript check |
|
|
@@ -565,11 +567,15 @@ Agents complete their work, write "To Complete: pnpm wu:done --id WU-XXX" in the
|
|
|
565
567
|
|
|
566
568
|
## The Fix
|
|
567
569
|
|
|
568
|
-
### Rule:
|
|
570
|
+
### Rule: Use wu:prep Then wu:done
|
|
569
571
|
|
|
570
|
-
After
|
|
572
|
+
After implementation is complete, you MUST run:
|
|
571
573
|
|
|
572
574
|
\`\`\`bash
|
|
575
|
+
# 1. From the worktree, run wu:prep
|
|
576
|
+
pnpm wu:prep --id WU-XXX
|
|
577
|
+
|
|
578
|
+
# 2. Then complete from main
|
|
573
579
|
cd <project-root>
|
|
574
580
|
pnpm wu:done --id WU-XXX
|
|
575
581
|
\`\`\`
|
|
@@ -586,10 +592,10 @@ Do NOT:
|
|
|
586
592
|
## Correct Completion Flow
|
|
587
593
|
|
|
588
594
|
\`\`\`bash
|
|
589
|
-
# 1. In worktree, run
|
|
590
|
-
pnpm
|
|
595
|
+
# 1. In worktree, run wu:prep
|
|
596
|
+
pnpm wu:prep --id WU-XXX
|
|
591
597
|
|
|
592
|
-
# 2. If
|
|
598
|
+
# 2. If wu:prep passes, return to main
|
|
593
599
|
cd <project-root>
|
|
594
600
|
|
|
595
601
|
# 3. IMMEDIATELY run wu:done
|
|
@@ -729,8 +735,8 @@ pnpm wu:claim --id WU-XXX --lane <Lane>
|
|
|
729
735
|
cd worktrees/<lane>-wu-xxx
|
|
730
736
|
|
|
731
737
|
# Run gates
|
|
732
|
-
pnpm gates
|
|
733
|
-
pnpm gates
|
|
738
|
+
pnpm gates # Code changes
|
|
739
|
+
pnpm gates:docs # Docs changes (equivalent: pnpm gates --docs-only)
|
|
734
740
|
|
|
735
741
|
# Complete WU
|
|
736
742
|
cd <project-root>
|
|
@@ -826,7 +832,7 @@ LumenFlow uses Work Units (WUs) to track all changes:
|
|
|
826
832
|
|
|
827
833
|
1. **Claim a WU**: \`pnpm wu:claim --id WU-XXX --lane <Lane>\`
|
|
828
834
|
2. **Work in worktree**: \`cd worktrees/<lane>-wu-xxx\`
|
|
829
|
-
3. **
|
|
835
|
+
3. **Prep for completion**: \`pnpm wu:prep --id WU-XXX\`
|
|
830
836
|
4. **Complete WU**: \`pnpm wu:done --id WU-XXX\` (from main checkout)
|
|
831
837
|
|
|
832
838
|
---
|
|
@@ -836,7 +842,7 @@ LumenFlow uses Work Units (WUs) to track all changes:
|
|
|
836
842
|
1. **Worktree Discipline**: Never work in main after claiming a WU
|
|
837
843
|
2. **Fit-For-Surface Verification**: Choose the least brittle verification that gives strong confidence. Prefer TDD for runtime logic when policy requires it; avoid brittle UI implementation-detail tests.
|
|
838
844
|
3. **Gates**: Must pass before \`wu:done\`
|
|
839
|
-
4. **Always
|
|
845
|
+
4. **Always finish the flow**: Never skip \`wu:prep\` or \`wu:done\`
|
|
840
846
|
|
|
841
847
|
---
|
|
842
848
|
|
|
@@ -845,7 +851,8 @@ LumenFlow uses Work Units (WUs) to track all changes:
|
|
|
845
851
|
| Command | Description |
|
|
846
852
|
| ------- | ----------- |
|
|
847
853
|
| \`pnpm wu:claim --id WU-XXX --lane <Lane>\` | Claim a WU |
|
|
848
|
-
| \`pnpm
|
|
854
|
+
| \`pnpm wu:prep --id WU-XXX\` | Run worktree gates and prep for completion |
|
|
855
|
+
| \`pnpm gates:docs\` | Preferred docs-only gate alias |
|
|
849
856
|
| \`pnpm wu:done --id WU-XXX\` | Complete WU |
|
|
850
857
|
| \`pnpm wu:status --id WU-XXX\` | Check WU status |
|
|
851
858
|
| \`pnpm initiative:create ...\` | Create a new initiative |
|
|
@@ -1058,8 +1065,8 @@ pnpm gates
|
|
|
1058
1065
|
|
|
1059
1066
|
- **Stay in the worktree** after claiming
|
|
1060
1067
|
- **Fit-For-Surface Verification**: Prefer stable, least-brittle verification; reserve test-first discipline for runtime logic when policy requires it
|
|
1061
|
-
- **Gates before done**: Always run \`pnpm
|
|
1062
|
-
- **Always
|
|
1068
|
+
- **Gates before done**: Always run \`pnpm wu:prep\`
|
|
1069
|
+
- **Always finish the flow**: Never forget \`wu:prep\` and \`wu:done\`
|
|
1063
1070
|
|
|
1064
1071
|
---
|
|
1065
1072
|
|
|
@@ -1183,7 +1190,8 @@ ready -> in_progress -> waiting/blocked -> done
|
|
|
1183
1190
|
pnpm wu:claim --id WU-XXX --lane <lane>
|
|
1184
1191
|
cd worktrees/<lane>-wu-xxx # IMMEDIATELY
|
|
1185
1192
|
|
|
1186
|
-
#
|
|
1193
|
+
# Prep in worktree, then complete from main
|
|
1194
|
+
pnpm wu:prep --id WU-XXX
|
|
1187
1195
|
cd ../..
|
|
1188
1196
|
pnpm wu:done --id WU-XXX
|
|
1189
1197
|
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"init-templates.js","sourceRoot":"","sources":["../src/init-templates.ts"],"names":[],"mappings":"AAAA,iCAAiC;AACjC,yCAAyC;AAEzC;;;;;;GAMG;AAEH,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAE5E,MAAM,qBAAqB,GAAG,WAAW,CAAC,SAAS,CAAC;AACpD,MAAM,yBAAyB,GAAG,qBAAqB,CAAC,QAAQ,CAAC,GAAG,CAAC;IACnE,CAAC,CAAC,qBAAqB,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACpC,CAAC,CAAC,qBAAqB,CAAC;AAC1B,MAAM,wBAAwB,GAAG,eAAe,CAAC,SAAS,CAAC,QAAQ,CAAC,GAAG,CAAC;IACtE,CAAC,CAAC,eAAe,CAAC,SAAS;IAC3B,CAAC,CAAC,GAAG,eAAe,CAAC,SAAS,GAAG,CAAC;AAEpC,mEAAmE;AACnE,sEAAsE;AACtE,MAAM,CAAC,MAAM,wBAAwB,GAAG;IACtC;QACE,IAAI,EAAE,iBAAiB;QACvB,SAAS,EAAE,CAAC;QACZ,UAAU,EAAE,CAAC,qBAAqB,EAAE,aAAa,EAAE,QAAQ,CAAC;KAC7D;IACD;QACE,IAAI,EAAE,gBAAgB;QACtB,SAAS,EAAE,CAAC;QACZ,UAAU,EAAE,CAAC,oBAAoB,EAAE,YAAY,EAAE,QAAQ,CAAC;KAC3D;IACD;QACE,IAAI,EAAE,gBAAgB;QACtB,SAAS,EAAE,CAAC;QACZ,UAAU,EAAE,CAAC,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,mBAAmB,EAAE,cAAc,CAAC;KACpF;IACD;QACE,IAAI,EAAE,4BAA4B;QAClC,SAAS,EAAE,CAAC;QACZ,UAAU,EAAE,CAAC,mBAAmB,EAAE,WAAW,CAAC;KAC/C;IACD;QACE,IAAI,EAAE,mBAAmB;QACzB,SAAS,EAAE,CAAC;QACZ,UAAU,EAAE,CAAC,sBAAsB,EAAE,oBAAoB,EAAE,cAAc,CAAC;KAC3E;IACD;QACE,IAAI,EAAE,wBAAwB;QAC9B,SAAS,EAAE,CAAC;QACZ,UAAU,EAAE,CAAC,SAAS,EAAE,MAAM,CAAC;KAChC;CACF,CAAC;AAEF,0DAA0D;AAC1D,kDAAkD;AAClD,iFAAiF;AACjF,MAAM,CAAC,MAAM,kBAAkB,GAAG
|
|
1
|
+
{"version":3,"file":"init-templates.js","sourceRoot":"","sources":["../src/init-templates.ts"],"names":[],"mappings":"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"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@lumenflow/cli",
|
|
3
|
-
"version": "3.
|
|
3
|
+
"version": "3.21.0",
|
|
4
4
|
"description": "Command-line interface for LumenFlow workflow framework",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"lumenflow",
|
|
@@ -186,13 +186,13 @@
|
|
|
186
186
|
"xstate": "^5.28.0",
|
|
187
187
|
"yaml": "^2.8.2",
|
|
188
188
|
"zod": "^4.3.6",
|
|
189
|
-
"@lumenflow/
|
|
190
|
-
"@lumenflow/
|
|
191
|
-
"@lumenflow/
|
|
192
|
-
"@lumenflow/
|
|
193
|
-
"@lumenflow/
|
|
194
|
-
"@lumenflow/
|
|
195
|
-
"@lumenflow/
|
|
189
|
+
"@lumenflow/control-plane-sdk": "3.21.0",
|
|
190
|
+
"@lumenflow/core": "3.21.0",
|
|
191
|
+
"@lumenflow/initiatives": "3.21.0",
|
|
192
|
+
"@lumenflow/kernel": "3.21.0",
|
|
193
|
+
"@lumenflow/memory": "3.21.0",
|
|
194
|
+
"@lumenflow/metrics": "3.21.0",
|
|
195
|
+
"@lumenflow/agent": "3.21.0"
|
|
196
196
|
},
|
|
197
197
|
"devDependencies": {
|
|
198
198
|
"@vitest/coverage-v8": "^4.0.18",
|
|
@@ -1,4 +1,4 @@
|
|
|
1
1
|
|
|
2
|
-
> @lumenflow/packs-agent-runtime@3.
|
|
2
|
+
> @lumenflow/packs-agent-runtime@3.21.0 build /home/runner/work/lumenflow-dev/lumenflow-dev/packages/@lumenflow/packs/agent-runtime
|
|
3
3
|
> tsc
|
|
4
4
|
|
|
@@ -1,4 +1,4 @@
|
|
|
1
1
|
|
|
2
|
-
> @lumenflow/packs-software-delivery@3.
|
|
2
|
+
> @lumenflow/packs-software-delivery@3.21.0 build /home/runner/work/lumenflow-dev/lumenflow-dev/packages/@lumenflow/packs/software-delivery
|
|
3
3
|
> tsc
|
|
4
4
|
|
|
@@ -3,11 +3,11 @@
|
|
|
3
3
|
**Version:** 1.3
|
|
4
4
|
**Last updated:** {{DATE}}
|
|
5
5
|
|
|
6
|
-
This document contains the
|
|
6
|
+
This document contains the 11 non-negotiable constraints that every agent must keep "in working memory" from first plan through `wu:done`.
|
|
7
7
|
|
|
8
8
|
---
|
|
9
9
|
|
|
10
|
-
## The
|
|
10
|
+
## The 11 Non-Negotiable Constraints
|
|
11
11
|
|
|
12
12
|
### 1. Worktree Discipline and Git Safety
|
|
13
13
|
|
|
@@ -175,6 +175,16 @@ If you see something broken on main (failing gates, format issues, typos, lint e
|
|
|
175
175
|
|
|
176
176
|
**Why:** Lane boundaries define ownership, WIP limits, and parallel execution safety. Misassigned WUs undermine these guarantees and create coordination confusion.
|
|
177
177
|
|
|
178
|
+
**Occupied-lane workaround:**
|
|
179
|
+
|
|
180
|
+
If the ideal lane is occupied by another WU (WIP limit reached), do NOT wait, force the lock, or try to modify the other WU. Instead:
|
|
181
|
+
|
|
182
|
+
1. Use a nearby lane whose `code_paths` overlap with the files you need to change
|
|
183
|
+
2. Or ask the user which lane to use
|
|
184
|
+
3. Or wait for the lane to free up if the user prefers
|
|
185
|
+
|
|
186
|
+
Never touch, release, or complete another agent's WU to free a lane.
|
|
187
|
+
|
|
178
188
|
---
|
|
179
189
|
|
|
180
190
|
### 9. YAML Files Must Be Modified via CLI Tooling Only (WU-1907)
|
|
@@ -205,6 +215,61 @@ If you see something broken on main (failing gates, format issues, typos, lint e
|
|
|
205
215
|
|
|
206
216
|
---
|
|
207
217
|
|
|
218
|
+
### 10. Stop and Escalate After 3 Failures
|
|
219
|
+
|
|
220
|
+
**Rule:** If the same operation fails 3 times, STOP. Do not retry. Escalate to the user with a summary of what failed and why.
|
|
221
|
+
|
|
222
|
+
**Applies to:**
|
|
223
|
+
|
|
224
|
+
- CLI commands (`wu:create`, `wu:claim`, `wu:done`, `gates`, etc.)
|
|
225
|
+
- Git operations (push, merge, rebase)
|
|
226
|
+
- Build/install operations
|
|
227
|
+
- Any repeated error, including validation failures
|
|
228
|
+
|
|
229
|
+
**What "same operation" means:**
|
|
230
|
+
|
|
231
|
+
Retrying `wu:create` with slightly different flags after each validation error counts as the same operation. Six attempts with six different missing-field errors is still one operation failing six times. The fix is to run `--help` and read the requirements, not to guess-and-retry.
|
|
232
|
+
|
|
233
|
+
**Escalation format:**
|
|
234
|
+
|
|
235
|
+
```
|
|
236
|
+
I've attempted [operation] 3 times and it's still failing.
|
|
237
|
+
|
|
238
|
+
Attempts:
|
|
239
|
+
1. [what I tried] → [error]
|
|
240
|
+
2. [what I tried] → [error]
|
|
241
|
+
3. [what I tried] → [error]
|
|
242
|
+
|
|
243
|
+
Root cause: [my best diagnosis]
|
|
244
|
+
Options: [what I think the fix is, or "I don't know"]
|
|
245
|
+
```
|
|
246
|
+
|
|
247
|
+
**Why:** Retry loops waste user time and context window. Three failures usually means the agent has a wrong mental model of the problem. Escalating early lets the user correct course before the agent creates additional mess (orphaned commits, diverged branches, locked lanes) that requires manual cleanup.
|
|
248
|
+
|
|
249
|
+
---
|
|
250
|
+
|
|
251
|
+
### 11. Client-Facing Content Accuracy
|
|
252
|
+
|
|
253
|
+
**Rule:** When writing or updating content shown to external stakeholders (client portals, proposals, meeting materials), do not treat internal docs as ground truth for factual claims. Flag specific claims to the user for verification.
|
|
254
|
+
|
|
255
|
+
**Claims that require user verification:**
|
|
256
|
+
|
|
257
|
+
- Headcount, team size, or organisational structure
|
|
258
|
+
- Revenue, AUM, or financial figures
|
|
259
|
+
- Product status (shipped vs planned vs architectural)
|
|
260
|
+
- Customer-specific details (tech stack, timelines, contract terms)
|
|
261
|
+
- Competitive claims ("no other platform can...")
|
|
262
|
+
|
|
263
|
+
**Enforcement:**
|
|
264
|
+
|
|
265
|
+
- Before committing client-facing copy with specific factual claims, present a summary of claims to the user: "I'm about to commit these facts — please confirm they're current"
|
|
266
|
+
- If internal docs contradict each other, flag the contradiction rather than picking one
|
|
267
|
+
- Never cite a public URL or external source to "verify" an internal claim without telling the user you did so — the external source may also be stale
|
|
268
|
+
|
|
269
|
+
**Why:** Internal docs go stale. An agent confidently writing "four-person engineering team" into a client portal when the team is actually 12+ undermines trust in both the portal and the agent. The user always knows what's current; the docs often don't.
|
|
270
|
+
|
|
271
|
+
---
|
|
272
|
+
|
|
208
273
|
## Mini Audit Checklist
|
|
209
274
|
|
|
210
275
|
Before running `wu:done`, verify:
|
|
@@ -296,7 +361,7 @@ Context compaction causes agents to lose critical rules. See [wu-sizing-guide.md
|
|
|
296
361
|
|
|
297
362
|
Stop and ask a human when:
|
|
298
363
|
|
|
299
|
-
- Same error repeats 3 times
|
|
364
|
+
- Same error repeats 3 times (see Constraint 10 — this is non-negotiable, not advisory)
|
|
300
365
|
- Auth or permissions changes required
|
|
301
366
|
- PII/safety issues discovered
|
|
302
367
|
- Cloud spend or secrets involved
|
|
@@ -258,7 +258,7 @@ For the full worktree lifecycle (parallel execution, bootstrap, isolation guaran
|
|
|
258
258
|
## Definition of Done
|
|
259
259
|
|
|
260
260
|
- Acceptance criteria satisfied
|
|
261
|
-
- Gates green (`pnpm gates` or `pnpm gates --docs-only`)
|
|
261
|
+
- Gates green (`pnpm gates` or `pnpm gates:docs`; `pnpm gates --docs-only` is the equivalent flag form)
|
|
262
262
|
- WU YAML status = `done`
|
|
263
263
|
- `.lumenflow/stamps/WU-<id>.done` exists
|
|
264
264
|
- **wu:done has been run** (not just documented as "to do")
|
|
@@ -269,31 +269,31 @@ For the full worktree lifecycle (parallel execution, bootstrap, isolation guaran
|
|
|
269
269
|
|
|
270
270
|
> **Complete CLI reference (100+ commands):** See [quick-ref-commands.md]({{QUICK_REF_LINK}}). Always run `<command> --help` for the authoritative option list.
|
|
271
271
|
|
|
272
|
-
| Command | Description
|
|
273
|
-
| ------------------------- |
|
|
274
|
-
| `pnpm wu:create` | Create new WU spec
|
|
275
|
-
| `pnpm wu:claim` | Claim WU, update canonical state, create worktree
|
|
276
|
-
| `pnpm wu:prep` | Run gates in worktree, prep for wu:done
|
|
277
|
-
| `pnpm wu:done` | Complete WU (merge, stamp, cleanup)
|
|
278
|
-
| `pnpm wu:status` | Show WU status, location, and valid commands
|
|
279
|
-
| `pnpm wu:recover` | Analyze and fix WU state inconsistencies
|
|
280
|
-
| `pnpm wu:block` | Block WU (transitions to blocked, frees lane)
|
|
281
|
-
| `pnpm wu:unblock` | Unblock WU (transitions to in_progress)
|
|
282
|
-
| `pnpm wu:release` | Release orphaned WU (in_progress to ready for reclaim)
|
|
283
|
-
| `pnpm wu:brief` | **MANDATORY after wu:claim.** Generate handoff prompt + record evidence
|
|
284
|
-
| `pnpm wu:delegate` | Generate prompt + record lineage + brief hash attestation
|
|
285
|
-
| `pnpm wu:escalate` | Show or resolve WU escalation status
|
|
286
|
-
| `pnpm wu:verify` | Verify WU completion (stamp, commit, clean tree)
|
|
287
|
-
| `pnpm wu:delete` | Delete WU spec and cleanup
|
|
288
|
-
| `pnpm gates` | Run quality gates (
|
|
289
|
-
| `pnpm lumenflow:commands` | List all public commands (primary + alias + legacy)
|
|
290
|
-
| `pnpm docs:generate` | Regenerate CLI/config reference docs from source
|
|
291
|
-
| `pnpm docs:validate` | Verify generated docs are up-to-date
|
|
292
|
-
| `pnpm lane:status` | Show lane lifecycle status + next step
|
|
293
|
-
| `pnpm lane:setup` | Create/update draft lane artifacts
|
|
294
|
-
| `pnpm lane:validate` | Validate lane artifacts before lock
|
|
295
|
-
| `pnpm lane:lock` | Lock lane lifecycle for delivery WUs
|
|
296
|
-
| `pnpm mem:checkpoint` | Save memory checkpoint
|
|
272
|
+
| Command | Description |
|
|
273
|
+
| ------------------------- | ------------------------------------------------------------------------------- |
|
|
274
|
+
| `pnpm wu:create` | Create new WU spec |
|
|
275
|
+
| `pnpm wu:claim` | Claim WU, update canonical state, create worktree |
|
|
276
|
+
| `pnpm wu:prep` | Run gates in worktree, prep for wu:done |
|
|
277
|
+
| `pnpm wu:done` | Complete WU (merge, stamp, cleanup) |
|
|
278
|
+
| `pnpm wu:status` | Show WU status, location, and valid commands |
|
|
279
|
+
| `pnpm wu:recover` | Analyze and fix WU state inconsistencies |
|
|
280
|
+
| `pnpm wu:block` | Block WU (transitions to blocked, frees lane) |
|
|
281
|
+
| `pnpm wu:unblock` | Unblock WU (transitions to in_progress) |
|
|
282
|
+
| `pnpm wu:release` | Release orphaned WU (in_progress to ready for reclaim) |
|
|
283
|
+
| `pnpm wu:brief` | **MANDATORY after wu:claim.** Generate handoff prompt + record evidence |
|
|
284
|
+
| `pnpm wu:delegate` | Generate prompt + record lineage + brief hash attestation |
|
|
285
|
+
| `pnpm wu:escalate` | Show or resolve WU escalation status |
|
|
286
|
+
| `pnpm wu:verify` | Verify WU completion (stamp, commit, clean tree) |
|
|
287
|
+
| `pnpm wu:delete` | Delete WU spec and cleanup |
|
|
288
|
+
| `pnpm gates` | Run quality gates (`pnpm gates:docs` for docs WUs; `--docs-only` is equivalent) |
|
|
289
|
+
| `pnpm lumenflow:commands` | List all public commands (primary + alias + legacy) |
|
|
290
|
+
| `pnpm docs:generate` | Regenerate CLI/config reference docs from source |
|
|
291
|
+
| `pnpm docs:validate` | Verify generated docs are up-to-date |
|
|
292
|
+
| `pnpm lane:status` | Show lane lifecycle status + next step |
|
|
293
|
+
| `pnpm lane:setup` | Create/update draft lane artifacts |
|
|
294
|
+
| `pnpm lane:validate` | Validate lane artifacts before lock |
|
|
295
|
+
| `pnpm lane:lock` | Lock lane lifecycle for delivery WUs |
|
|
296
|
+
| `pnpm mem:checkpoint` | Save memory checkpoint |
|
|
297
297
|
|
|
298
298
|
Commands include **context-aware validation** that checks location, WU status, and git state. When validation fails, commands provide copy-paste ready fix commands. Configure in `workspace.yaml` under `software_delivery.experimental.context_validation`.
|
|
299
299
|
The Starlight CLI reference page is intentionally curated to primary commands; use `pnpm lumenflow:commands` for complete discovery.
|
|
@@ -491,7 +491,7 @@ Only use these patterns after you have confirmed the work is no longer one coher
|
|
|
491
491
|
|
|
492
492
|
**Heading:** Default Triggers (Deviations require written justification in WU notes)
|
|
493
493
|
|
|
494
|
-
If you hit ANY of these triggers during a session, you MUST perform a Standard Session Handoff
|
|
494
|
+
If you hit ANY of these triggers during a session, you MUST perform a Standard Session Handoff:
|
|
495
495
|
|
|
496
496
|
- **Token Limit:** Context usage hits **50% (Warning)** or **80% (Critical)**.
|
|
497
497
|
- **Tool Volume:** **50+ tool calls** in current session.
|
|
@@ -619,9 +619,7 @@ This is a case study in genuinely non-atomic work. Do not generalize it into "mu
|
|
|
619
619
|
|
|
620
620
|
## 8. Related Documentation
|
|
621
621
|
|
|
622
|
-
- [session-handoff.md](./agent/onboarding/session-handoff.md) — Mid-WU checkpoint protocol
|
|
623
622
|
- [agent-safety-card.md](./agent/onboarding/agent-safety-card.md) — Quick reference safety thresholds
|
|
624
|
-
- [parallel-session-optimization.md](./agent/onboarding/parallel-session-optimization.md) — Running 4-6 WUs concurrently
|
|
625
623
|
- [agent-invocation-guide.md](./agent/onboarding/agent-invocation-guide.md) — Orchestrator-worker patterns
|
|
626
624
|
- [LumenFlow Agent Capsule](./lumenflow-agent-capsule.md) — Full LumenFlow framework
|
|
627
625
|
- [Canonical Lifecycle Map](./lumenflow-agent-capsule.md) — Command-mode matrix and handoff points
|
|
@@ -35,6 +35,8 @@ Quick reference for AI agents working in LumenFlow projects.
|
|
|
35
35
|
|
|
36
36
|
| Action | Why |
|
|
37
37
|
| ------------------------------------ | --------------------------------- |
|
|
38
|
+
| Run `--help` before first use | Prevents retry cascades |
|
|
39
|
+
| Check lanes before `wu:create` | Lane names are project-specific |
|
|
38
40
|
| Read WU spec first | Understand scope |
|
|
39
41
|
| cd to worktree after claim | Isolation |
|
|
40
42
|
| Write tests before code | TDD |
|
|
@@ -75,13 +77,21 @@ Audit logs:
|
|
|
75
77
|
|
|
76
78
|
## Error Handling
|
|
77
79
|
|
|
78
|
-
### Max 3 Attempts
|
|
80
|
+
### Max 3 Attempts (Constraint 10 — Non-Negotiable)
|
|
79
81
|
|
|
80
|
-
If same
|
|
82
|
+
If the same operation fails 3 times: **STOP. Do not retry.**
|
|
83
|
+
|
|
84
|
+
Retry loops create cascading mess (orphaned commits, diverged branches, locked lanes)
|
|
85
|
+
that the user must clean up manually.
|
|
81
86
|
|
|
82
87
|
1. Stop trying
|
|
83
|
-
2.
|
|
84
|
-
3.
|
|
88
|
+
2. Summarise all 3 attempts and their errors
|
|
89
|
+
3. Present your diagnosis and options to the user
|
|
90
|
+
4. Wait for direction
|
|
91
|
+
|
|
92
|
+
**What counts as "same operation":** Retrying `wu:create` with slightly different flags
|
|
93
|
+
after each validation error is one operation failing multiple times. The fix is `--help`,
|
|
94
|
+
not guess-and-retry.
|
|
85
95
|
|
|
86
96
|
### Gate Failures
|
|
87
97
|
|
|
@@ -344,6 +344,102 @@ See the [WU Sizing Guide](../../wu-sizing-guide.md) section 1.5 for the full con
|
|
|
344
344
|
|
|
345
345
|
---
|
|
346
346
|
|
|
347
|
+
## Mistake 14: Not Running --help Before First Use
|
|
348
|
+
|
|
349
|
+
### Wrong
|
|
350
|
+
|
|
351
|
+
```bash
|
|
352
|
+
# Agent guesses wu:create flags, misses required ones
|
|
353
|
+
pnpm wu:create --lane "Portal: UI" --title "Add feature" --description "..."
|
|
354
|
+
# Error: Unknown parent lane "Portal"
|
|
355
|
+
|
|
356
|
+
pnpm wu:create --lane "Experience: Auth" --title "Add feature" --description "..."
|
|
357
|
+
# Error: --test-paths-manual is required
|
|
358
|
+
|
|
359
|
+
pnpm wu:create --lane "Experience: Auth" --title "Add feature" --description "..." --test-paths-manual "..."
|
|
360
|
+
# Error: --spec-refs is required for type: feature
|
|
361
|
+
|
|
362
|
+
pnpm wu:create --lane "Experience: Auth" --title "Add feature" --description "..." --test-paths-manual "..." --spec-refs "..."
|
|
363
|
+
# Error: plan already exists
|
|
364
|
+
|
|
365
|
+
# Six attempts later, agent has burned context and user patience
|
|
366
|
+
```
|
|
367
|
+
|
|
368
|
+
### Right
|
|
369
|
+
|
|
370
|
+
```bash
|
|
371
|
+
# Run --help ONCE before first use
|
|
372
|
+
pnpm wu:create --help
|
|
373
|
+
# Now you know every required flag, valid lane format, and option
|
|
374
|
+
|
|
375
|
+
# First attempt succeeds
|
|
376
|
+
pnpm wu:create --lane "Experience: Auth" --title "Add feature" \
|
|
377
|
+
--description "..." --acceptance "..." \
|
|
378
|
+
--code-paths "src/..." --test-paths-unit "src/..." \
|
|
379
|
+
--test-paths-manual "..." --spec-refs "..." --exposure ui
|
|
380
|
+
```
|
|
381
|
+
|
|
382
|
+
**Rule:** `--help` before first use is mandatory (see AGENTS.md rule #2). One `--help` call prevents an entire retry cascade. If you still fail after reading `--help`, that's a real problem worth escalating — not a reason to guess again.
|
|
383
|
+
|
|
384
|
+
---
|
|
385
|
+
|
|
386
|
+
## Mistake 15: Guessing Lane Names
|
|
387
|
+
|
|
388
|
+
### Wrong
|
|
389
|
+
|
|
390
|
+
```bash
|
|
391
|
+
# Agent invents a lane name that doesn't exist
|
|
392
|
+
pnpm wu:create --lane "Portal: UI" --title "..."
|
|
393
|
+
# Error: Unknown parent lane: "Portal"
|
|
394
|
+
```
|
|
395
|
+
|
|
396
|
+
### Right
|
|
397
|
+
|
|
398
|
+
```bash
|
|
399
|
+
# Check what lanes exist first
|
|
400
|
+
pnpm lane:status
|
|
401
|
+
|
|
402
|
+
# Or infer the right lane from file paths
|
|
403
|
+
pnpm wu:infer-lane --paths "src/app/clients/[slug]/client-portal.tsx" \
|
|
404
|
+
--desc "Add light mode to client portal"
|
|
405
|
+
|
|
406
|
+
# Then use the suggested lane
|
|
407
|
+
pnpm wu:create --lane "Experience: Auth" --title "..."
|
|
408
|
+
```
|
|
409
|
+
|
|
410
|
+
**Rule:** Lane names are project-specific and defined in `workspace.yaml`. Never guess them. Run `pnpm lane:status` or `pnpm wu:infer-lane` to discover valid lanes before creating a WU.
|
|
411
|
+
|
|
412
|
+
---
|
|
413
|
+
|
|
414
|
+
## Mistake 16: Retry Loops Instead of Escalating
|
|
415
|
+
|
|
416
|
+
### Wrong
|
|
417
|
+
|
|
418
|
+
```
|
|
419
|
+
Attempt 1: wu:create fails (wrong lane) → try different lane
|
|
420
|
+
Attempt 2: wu:create fails (missing field) → add field
|
|
421
|
+
Attempt 3: wu:create fails (missing another field) → add field
|
|
422
|
+
Attempt 4: wu:create fails (stale plan) → delete plan, retry
|
|
423
|
+
Attempt 5: wu:create fails (inode exhaustion) → try to diagnose
|
|
424
|
+
Attempt 6: wu:create fails (inode exhaustion) → ask user to clean up
|
|
425
|
+
# Agent has burned 20 minutes on what should have been a 30-second operation
|
|
426
|
+
```
|
|
427
|
+
|
|
428
|
+
### Right
|
|
429
|
+
|
|
430
|
+
```
|
|
431
|
+
Attempt 1: wu:create fails → read the error carefully
|
|
432
|
+
Attempt 2: wu:create fails → try the fix the error suggested
|
|
433
|
+
Attempt 3: wu:create fails → STOP. Escalate to user:
|
|
434
|
+
|
|
435
|
+
"wu:create has failed 3 times. Errors were: [X], [Y], [Z].
|
|
436
|
+
Root cause appears to be [diagnosis]. Would you like me to [option]?"
|
|
437
|
+
```
|
|
438
|
+
|
|
439
|
+
**Rule:** See [Constraint 10](../../../../../.lumenflow/constraints.md) — stop and escalate after 3 failures. Retry loops create cascading mess (orphaned commits, diverged branches, locked lanes) that the user then has to clean up manually.
|
|
440
|
+
|
|
441
|
+
---
|
|
442
|
+
|
|
347
443
|
## Quick Checklist
|
|
348
444
|
|
|
349
445
|
Before starting any WU:
|
|
@@ -36,7 +36,7 @@ Run `--help` first, then run the real command with explicit flags.
|
|
|
36
36
|
| Tooling Operations | `pnpm lumenflow:upgrade --help` | `pnpm lumenflow:upgrade --latest` |
|
|
37
37
|
| WU Lifecycle | `pnpm wu:claim --help` | `pnpm wu:claim --id WU-1561 --lane "Operations: Tooling"` |
|
|
38
38
|
| WU Maintenance | `pnpm wu:recover --help` | `pnpm wu:recover --id WU-1561` |
|
|
39
|
-
| Gates & Quality | `pnpm gates --help` | `pnpm gates
|
|
39
|
+
| Gates & Quality | `pnpm gates --help` | `pnpm gates:docs` |
|
|
40
40
|
| Memory & Sessions | `pnpm mem:checkpoint --help` | `pnpm mem:checkpoint --wu WU-1561` |
|
|
41
41
|
| State Management | `pnpm state:doctor --help` | `pnpm state:doctor --json` |
|
|
42
42
|
| Repo-Only Scripts | `pnpm docs:validate --help` | `pnpm docs:validate` |
|
|
@@ -178,27 +178,28 @@ without explicit human instruction.**
|
|
|
178
178
|
|
|
179
179
|
## Gates & Quality
|
|
180
180
|
|
|
181
|
-
| Command | Description
|
|
182
|
-
| ------------------------------------------------------------------ |
|
|
183
|
-
| `pnpm gates` | Run all quality gates
|
|
184
|
-
| `pnpm gates
|
|
185
|
-
| `pnpm
|
|
186
|
-
| `pnpm format
|
|
187
|
-
| `pnpm
|
|
188
|
-
| `pnpm
|
|
189
|
-
| `pnpm
|
|
190
|
-
| `pnpm
|
|
191
|
-
| `pnpm
|
|
192
|
-
| `pnpm lane:
|
|
193
|
-
| `pnpm lane:
|
|
194
|
-
| `pnpm lane:
|
|
195
|
-
| `pnpm lane:
|
|
196
|
-
| `pnpm lane:
|
|
197
|
-
| `pnpm lane:
|
|
198
|
-
| `pnpm
|
|
199
|
-
| `pnpm gate:co-change --
|
|
200
|
-
| `pnpm gate:co-change --
|
|
201
|
-
| `pnpm gate:co-change --
|
|
181
|
+
| Command | Description |
|
|
182
|
+
| ------------------------------------------------------------------ | ---------------------------------------------------- |
|
|
183
|
+
| `pnpm gates` | Run all quality gates |
|
|
184
|
+
| `pnpm gates:docs` | Preferred docs-only alias (`pnpm gates --docs-only`) |
|
|
185
|
+
| `pnpm gates --docs-only` | Equivalent flag form for docs-only gates |
|
|
186
|
+
| `pnpm format` | Format all files (Prettier) |
|
|
187
|
+
| `pnpm format:check` | Check formatting without changes |
|
|
188
|
+
| `pnpm lint` | Run ESLint |
|
|
189
|
+
| `pnpm typecheck` | Run TypeScript type checking |
|
|
190
|
+
| `pnpm test` | Run all tests (Vitest) |
|
|
191
|
+
| `pnpm spec:linter` | Validate WU specs (all) ¹ |
|
|
192
|
+
| `pnpm lane:health` | Check lane config health |
|
|
193
|
+
| `pnpm lane:suggest --output workspace.lanes.yaml` | Generate a workspace lane-definition snippet |
|
|
194
|
+
| `pnpm lane:status` | Show lane lifecycle status |
|
|
195
|
+
| `pnpm lane:setup` | Create/update draft lane config |
|
|
196
|
+
| `pnpm lane:validate` | Validate lane draft artifacts |
|
|
197
|
+
| `pnpm lane:lock` | Lock lane lifecycle for WU create |
|
|
198
|
+
| `pnpm lane:edit --name <L>` | Edit lane definition (rename, wip-limit, paths) |
|
|
199
|
+
| `pnpm gate:co-change --add --name <N> --trigger <G> --require <G>` | Add co-change gate rule |
|
|
200
|
+
| `pnpm gate:co-change --remove --name <N>` | Remove co-change gate rule |
|
|
201
|
+
| `pnpm gate:co-change --edit --name <N> --severity <S>` | Edit co-change gate rule |
|
|
202
|
+
| `pnpm gate:co-change --list` | List all co-change rules (built-in + custom) |
|
|
202
203
|
|
|
203
204
|
¹ **Script aliases:** `spec:linter` and `tasks:validate` are pnpm script aliases
|
|
204
205
|
for `wu:validate --all`. They are not standalone CLI commands.
|
|
@@ -197,7 +197,7 @@ LUMENFLOW_CLOUD=1 pnpm wu:claim --id WU-XXXX --lane "Lane Name"
|
|
|
197
197
|
These are the mistakes agents make most often. Memorize these before reading anything else:
|
|
198
198
|
|
|
199
199
|
1. **wu:done deletes the worktree.** After it completes, your shell CWD is invalid. Immediately `cd` back to the project root.
|
|
200
|
-
2. **When wu:done
|
|
200
|
+
2. **When wu:done reports branch drift or a non-fast-forward error, rerun it from main.** It auto-rebases by default when it can. Never manually `git rebase` on main.
|
|
201
201
|
3. **Always run `--help` before first use of any command.** Don't guess flags — 30 seconds reading help saves 5 minutes of failed attempts.
|
|
202
202
|
4. **Never `pnpm update @lumenflow/*` directly.** Use `pnpm lumenflow:upgrade --latest` (uses micro-worktree isolation).
|
|
203
203
|
5. **State files are auto-generated.** Never manually edit `wu-events.jsonl`, `backlog.md`, or `status.md` — lifecycle commands manage them.
|
|
@@ -459,11 +459,11 @@ cd <project-root> && pnpm wu:done --id WU-XXX --skip-gates \
|
|
|
459
459
|
|
|
460
460
|
Do not use `git stash`, switch local main, or otherwise mutate main just to prove a pre-existing failure.
|
|
461
461
|
|
|
462
|
-
### Scenario 6: wu:done
|
|
462
|
+
### Scenario 6: wu:done reports branch drift or a non-fast-forward error
|
|
463
463
|
|
|
464
464
|
**Cause:** Another agent or process pushed to main between your fetch and push (race condition).
|
|
465
465
|
|
|
466
|
-
**Fix:**
|
|
466
|
+
**Fix:** Rerun `wu:done` from main. It has built-in auto-rebase for this case. If the rerun still fails with a real conflict, resolve the conflict in the worktree, rerun `wu:prep` if needed, then return to main and rerun `wu:done`.
|
|
467
467
|
|
|
468
468
|
```bash
|
|
469
469
|
# WRONG - never manually rebase main
|
|
@@ -65,6 +65,9 @@ cd /path/to/main && pnpm wu:done --id WU-XXX
|
|
|
65
65
|
# 3. Report success with the wu:done output
|
|
66
66
|
```
|
|
67
67
|
|
|
68
|
+
If `wu:done` reports branch drift, parallel completions, or a non-fast-forward push, rerun it from
|
|
69
|
+
main. It auto-rebases by default when possible. Do not manually rebase `main`.
|
|
70
|
+
|
|
68
71
|
---
|
|
69
72
|
|
|
70
73
|
## What wu:prep Does (WU-1223)
|
|
@@ -80,7 +83,7 @@ When you run `pnpm wu:prep --id WU-XXX` from a worktree:
|
|
|
80
83
|
When you run `pnpm wu:done --id WU-XXX` from main:
|
|
81
84
|
|
|
82
85
|
1. Validates you're in main checkout (errors if in worktree)
|
|
83
|
-
2.
|
|
86
|
+
2. Merges the lane branch to main and may auto-rebase first if parallel work landed
|
|
84
87
|
3. Creates the done stamp
|
|
85
88
|
4. Updates status and backlog docs
|
|
86
89
|
5. Removes the worktree
|
|
@@ -125,6 +128,71 @@ Feature WUs **must** include `spec_refs` (use `pnpm wu:create --plan` if the pla
|
|
|
125
128
|
|
|
126
129
|
---
|
|
127
130
|
|
|
131
|
+
### "non-fast-forward" or "branch is behind main"
|
|
132
|
+
|
|
133
|
+
If `wu:done` reports branch drift or a non-fast-forward push, another completion landed while your
|
|
134
|
+
WU was in progress.
|
|
135
|
+
|
|
136
|
+
```bash
|
|
137
|
+
# Retry from main first
|
|
138
|
+
cd /path/to/main
|
|
139
|
+
pnpm wu:done --id WU-XXX
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
- If the rerun succeeds, you are done.
|
|
143
|
+
- If the rerun reports an auto-rebase conflict, return to the worktree, resolve the conflict there,
|
|
144
|
+
rerun `pnpm wu:prep --id WU-XXX` if needed, then retry `wu:done` from main.
|
|
145
|
+
- Do **not** manually `git rebase` the main checkout.
|
|
146
|
+
|
|
147
|
+
---
|
|
148
|
+
|
|
149
|
+
## wu:create Failure Recovery
|
|
150
|
+
|
|
151
|
+
`wu:create` uses a micro-worktree to commit the spec atomically. If it fails mid-transaction
|
|
152
|
+
(rebase conflict, disk full, inode exhaustion, network error), it can leave main in an
|
|
153
|
+
inconsistent state.
|
|
154
|
+
|
|
155
|
+
### Symptoms
|
|
156
|
+
|
|
157
|
+
- `git log` shows main is ahead of `origin/main` by 1 commit (the orphaned spec commit)
|
|
158
|
+
- `wu:delete` fails because main can't fast-forward
|
|
159
|
+
- Subsequent `wu:create` or `wu:claim` operations fail
|
|
160
|
+
|
|
161
|
+
### Recovery
|
|
162
|
+
|
|
163
|
+
**Step 1: Check the divergence**
|
|
164
|
+
|
|
165
|
+
```bash
|
|
166
|
+
git log --oneline origin/main..main
|
|
167
|
+
# If you see a single spec commit like "docs: create wu-XXX for ...", that's the orphan
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
**Step 2: Ask the user to discard the orphaned commit**
|
|
171
|
+
|
|
172
|
+
Agents cannot run `git reset --hard` (forbidden command). Present this to the user:
|
|
173
|
+
|
|
174
|
+
```
|
|
175
|
+
wu:create failed mid-transaction and left an orphaned spec commit on main.
|
|
176
|
+
Main is now 1 ahead of origin/main. The safe fix is:
|
|
177
|
+
|
|
178
|
+
git fetch origin && git reset --hard origin/main
|
|
179
|
+
|
|
180
|
+
This discards only the failed spec commit. No other work is lost.
|
|
181
|
+
Shall I proceed after you run this?
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
**Step 3: After user resets main, retry wu:create**
|
|
185
|
+
|
|
186
|
+
Do NOT attempt to recover by rebasing, cherry-picking, or manually editing state files.
|
|
187
|
+
The clean path is: discard the orphan, retry the command.
|
|
188
|
+
|
|
189
|
+
### Prevention
|
|
190
|
+
|
|
191
|
+
- Run `wu:create --help` before first use to avoid validation failures that trigger retries
|
|
192
|
+
- If `wu:create` fails, check `git log --oneline -3` before retrying — if the spec commit
|
|
193
|
+
landed locally but wasn't pushed, you already have an orphan
|
|
194
|
+
- After 3 failed attempts, stop and escalate (Constraint 10)
|
|
195
|
+
|
|
128
196
|
---
|
|
129
197
|
|
|
130
198
|
## Cloud / Branch-PR Mode
|