@lumenflow/cli 4.10.0 → 4.12.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.
Files changed (70) hide show
  1. package/README.md +1 -0
  2. package/dist/doctor.js +186 -0
  3. package/dist/doctor.js.map +1 -1
  4. package/dist/gates-runners.js +26 -9
  5. package/dist/gates-runners.js.map +1 -1
  6. package/dist/init-package-config.js +24 -0
  7. package/dist/init-package-config.js.map +1 -1
  8. package/dist/init.js +124 -3
  9. package/dist/init.js.map +1 -1
  10. package/dist/lane-create.js +9 -2
  11. package/dist/lane-create.js.map +1 -1
  12. package/dist/lane-edit.js +21 -4
  13. package/dist/lane-edit.js.map +1 -1
  14. package/dist/lane-remove.js +214 -0
  15. package/dist/lane-remove.js.map +1 -0
  16. package/dist/public-manifest.js +14 -0
  17. package/dist/public-manifest.js.map +1 -1
  18. package/dist/state-doctor.js +14 -7
  19. package/dist/state-doctor.js.map +1 -1
  20. package/dist/wu-claim-branch.js +8 -15
  21. package/dist/wu-claim-branch.js.map +1 -1
  22. package/dist/wu-claim-output.js +22 -0
  23. package/dist/wu-claim-output.js.map +1 -1
  24. package/dist/wu-claim-state.js +5 -1
  25. package/dist/wu-claim-state.js.map +1 -1
  26. package/dist/wu-claim-worktree.js +7 -16
  27. package/dist/wu-claim-worktree.js.map +1 -1
  28. package/dist/wu-code-path-coverage.js +42 -3
  29. package/dist/wu-code-path-coverage.js.map +1 -1
  30. package/dist/wu-create.js +57 -6
  31. package/dist/wu-create.js.map +1 -1
  32. package/dist/wu-done-git-ops.js +5 -1
  33. package/dist/wu-done-git-ops.js.map +1 -1
  34. package/dist/wu-done-policies.js +4 -10
  35. package/dist/wu-done-policies.js.map +1 -1
  36. package/dist/wu-done.js +7 -10
  37. package/dist/wu-done.js.map +1 -1
  38. package/dist/wu-edit-operations.js +80 -32
  39. package/dist/wu-edit-operations.js.map +1 -1
  40. package/dist/wu-edit-validators.js +48 -0
  41. package/dist/wu-edit-validators.js.map +1 -1
  42. package/dist/wu-edit.js +72 -0
  43. package/dist/wu-edit.js.map +1 -1
  44. package/dist/wu-prep.js +31 -5
  45. package/dist/wu-prep.js.map +1 -1
  46. package/dist/wu-recover.js +50 -0
  47. package/dist/wu-recover.js.map +1 -1
  48. package/dist/wu-rename.js +238 -0
  49. package/dist/wu-rename.js.map +1 -0
  50. package/dist/wu-spawn-prompt-builders.js +157 -27
  51. package/dist/wu-spawn-prompt-builders.js.map +1 -1
  52. package/dist/wu-spawn-strategy-resolver.js +9 -1
  53. package/dist/wu-spawn-strategy-resolver.js.map +1 -1
  54. package/dist/wu-state-mutation-ownership.js +22 -4
  55. package/dist/wu-state-mutation-ownership.js.map +1 -1
  56. package/package.json +9 -8
  57. package/packs/agent-runtime/.turbo/turbo-build.log +1 -1
  58. package/packs/agent-runtime/package.json +1 -1
  59. package/packs/sidekick/.turbo/turbo-build.log +1 -1
  60. package/packs/sidekick/package.json +1 -1
  61. package/packs/software-delivery/.turbo/turbo-build.log +1 -1
  62. package/packs/software-delivery/package.json +1 -1
  63. package/templates/core/.lumenflow/constraints.md.template +2 -0
  64. package/templates/core/AGENTS.md.template +14 -0
  65. package/templates/core/LUMENFLOW.md.template +16 -0
  66. package/templates/core/ai/onboarding/docs-generation.md.template +23 -0
  67. package/templates/core/ai/onboarding/quick-ref-commands.md.template +52 -21
  68. package/templates/core/ai/onboarding/release-process.md.template +43 -23
  69. package/templates/core/ai/onboarding/starting-prompt.md.template +15 -5
  70. package/templates/core/ai/onboarding/troubleshooting-wu-done.md.template +6 -2
@@ -1 +1 @@
1
- {"version":3,"file":"wu-state-mutation-ownership.js","sourceRoot":"","sources":["../src/wu-state-mutation-ownership.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"wu-state-mutation-ownership.js","sourceRoot":"","sources":["../src/wu-state-mutation-ownership.ts"],"names":[],"mappings":"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"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@lumenflow/cli",
3
- "version": "4.10.0",
3
+ "version": "4.12.0",
4
4
  "description": "Command-line interface for LumenFlow workflow framework",
5
5
  "keywords": [
6
6
  "lumenflow",
@@ -69,6 +69,7 @@
69
69
  "lane-edit": "./dist/lane-edit.js",
70
70
  "lane-health": "./dist/lane-health.js",
71
71
  "lane-lock": "./dist/lane-lock.js",
72
+ "lane-remove": "./dist/lane-remove.js",
72
73
  "lane-setup": "./dist/lane-setup.js",
73
74
  "lane-status": "./dist/lane-status.js",
74
75
  "lane-suggest": "./dist/lane-suggest.js",
@@ -186,13 +187,13 @@
186
187
  "xstate": "^5.28.0",
187
188
  "yaml": "^2.8.2",
188
189
  "zod": "^4.3.6",
189
- "@lumenflow/agent": "4.10.0",
190
- "@lumenflow/control-plane-sdk": "4.10.0",
191
- "@lumenflow/core": "4.10.0",
192
- "@lumenflow/initiatives": "4.10.0",
193
- "@lumenflow/kernel": "4.10.0",
194
- "@lumenflow/memory": "4.10.0",
195
- "@lumenflow/metrics": "4.10.0"
190
+ "@lumenflow/agent": "4.12.0",
191
+ "@lumenflow/core": "4.12.0",
192
+ "@lumenflow/initiatives": "4.12.0",
193
+ "@lumenflow/kernel": "4.12.0",
194
+ "@lumenflow/memory": "4.12.0",
195
+ "@lumenflow/metrics": "4.12.0",
196
+ "@lumenflow/control-plane-sdk": "4.12.0"
196
197
  },
197
198
  "devDependencies": {
198
199
  "@vitest/coverage-v8": "^4.0.18",
@@ -1,4 +1,4 @@
1
1
 
2
- > @lumenflow/packs-agent-runtime@4.10.0 build /home/runner/work/lumenflow-dev/lumenflow-dev/packages/@lumenflow/packs/agent-runtime
2
+ > @lumenflow/packs-agent-runtime@4.12.0 build /home/runner/work/lumenflow-dev/lumenflow-dev/packages/@lumenflow/packs/agent-runtime
3
3
  > tsc
4
4
 
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@lumenflow/packs-agent-runtime",
3
- "version": "4.10.0",
3
+ "version": "4.12.0",
4
4
  "description": "Agent runtime pack scaffold for LumenFlow — governed model-turn execution, pack config, and provider capability baselines",
5
5
  "keywords": [
6
6
  "lumenflow",
@@ -1,4 +1,4 @@
1
1
 
2
- > @lumenflow/packs-sidekick@4.10.0 build /home/runner/work/lumenflow-dev/lumenflow-dev/packages/@lumenflow/packs/sidekick
2
+ > @lumenflow/packs-sidekick@4.12.0 build /home/runner/work/lumenflow-dev/lumenflow-dev/packages/@lumenflow/packs/sidekick
3
3
  > tsc
4
4
 
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@lumenflow/packs-sidekick",
3
- "version": "4.10.0",
3
+ "version": "4.12.0",
4
4
  "description": "Sidekick personal assistant pack for LumenFlow — 16 tools for task management, typed memory, channels, routines, and audit",
5
5
  "keywords": [
6
6
  "lumenflow",
@@ -1,4 +1,4 @@
1
1
 
2
- > @lumenflow/packs-software-delivery@4.10.0 build /home/runner/work/lumenflow-dev/lumenflow-dev/packages/@lumenflow/packs/software-delivery
2
+ > @lumenflow/packs-software-delivery@4.12.0 build /home/runner/work/lumenflow-dev/lumenflow-dev/packages/@lumenflow/packs/software-delivery
3
3
  > tsc
4
4
 
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@lumenflow/packs-software-delivery",
3
- "version": "4.10.0",
3
+ "version": "4.12.0",
4
4
  "description": "Software delivery pack for LumenFlow — work units, gates, lanes, initiatives, and agent coordination",
5
5
  "keywords": [
6
6
  "lumenflow",
@@ -59,6 +59,8 @@ If you see something broken on main (failing gates, format issues, typos, lint e
59
59
 
60
60
  **If you're on main and want to change something: STOP. Create a WU first.**
61
61
 
62
+ **If main is already dirty from an unexpected command side effect:** Use `git restore` and `git clean -n` (dry run) to recover — never hand-edit files to "undo" a generator. See [.lumenflow/rules/git-safety.md](rules/git-safety.md) section "Main Went Dirty Unexpectedly" for the full recovery procedure.
63
+
62
64
  ---
63
65
 
64
66
  ### 2. WUs Are Specs, Not Code
@@ -111,6 +111,7 @@ For detailed troubleshooting, see [troubleshooting-wu-done.md]({{DOCS_ONBOARDING
111
111
  3. **Gates Before Done**: Run `pnpm gates` before `wu:done`
112
112
  4. **Never Bypass Hooks**: No `--no-verify`
113
113
  5. **Vendor-Agnostic Dirty-Main Guard**: `wu:prep` and `wu:done` hard-block when main has non-allowlisted dirty files during worktree WUs (including MCP/tool-originated writes). `branch-pr` mode is exempt.
114
+ 6. **Docs Parity For Behavior Changes**: If you change LumenFlow behavior or workflow guidance, update internal docs, Starlight docs, or both as appropriate. Generated reference docs do not cover narrative behavior changes by themselves.
114
115
 
115
116
  For the complete set of non-negotiable constraints (git safety, forbidden commands, skip-gates policy, and more), see [.lumenflow/constraints.md](.lumenflow/constraints.md).
116
117
 
@@ -172,6 +173,19 @@ This file provides universal guidance for all AI agents. Additional vendor-speci
172
173
  - `apps/docs/src/data/language-support.yaml`
173
174
  - `apps/docs/src/data/example-repos.yaml`
174
175
 
176
+ ## Documentation Obligations
177
+
178
+ When LumenFlow behavior changes, decide documentation impact explicitly instead of assuming
179
+ `docs:generate` is sufficient.
180
+
181
+ - Update **internal docs** when the change affects agent workflow, maintainer workflow, onboarding,
182
+ or repo-specific operating rules.
183
+ - Update **Starlight docs** when the change affects public CLI behavior, pack behavior, language
184
+ guidance, or user-facing workflow expectations.
185
+ - Update **both** when the same behavior change affects agents internally and users externally.
186
+ - State the outcome in your completion notes or report: `Internal docs`, `Starlight docs`, `Both`,
187
+ or `None`.
188
+
175
189
  ---
176
190
 
177
191
  ## Further Reading
@@ -200,6 +200,22 @@ For cloud agents (Codex/Claude web/CI) operating on feature branches:
200
200
  - **apps/docs/src/data/language-support.yaml** - Language guide support metadata
201
201
  - **apps/docs/src/data/example-repos.yaml** - Companion example-repo mapping
202
202
 
203
+ ### Documentation Obligations
204
+
205
+ `pnpm docs:generate` only keeps generated reference pages in sync. It does **not** update narrative
206
+ workflow guidance for you.
207
+
208
+ When behavior changes:
209
+
210
+ - Update **internal docs** (`AGENTS.md`, `LUMENFLOW.md`, onboarding docs) when the change affects
211
+ agent workflow, maintainer workflow, onboarding, or repo-specific operating rules.
212
+ - Update **Starlight docs** (`apps/docs/src/content/docs/**`) when the change affects public CLI
213
+ behavior, pack behavior, language guides, or user-facing workflow expectations.
214
+ - Update **both** when the same behavior change affects agents internally and users externally.
215
+
216
+ Do not mark a behavior-change WU complete until you have explicitly decided: `Internal docs`,
217
+ `Starlight docs`, `Both`, or `None`.
218
+
203
219
  ### Client/Vendor Overlays
204
220
 
205
221
  - **CLAUDE.md** - Claude Code overlay (single file at root)
@@ -16,6 +16,29 @@ LumenFlow automatically generates CLI and configuration reference documentation
16
16
  | Config Reference | `packages/@lumenflow/core/src/lumenflow-config-schema.ts` | `apps/docs/src/content/docs/reference/config.mdx` |
17
17
  | MCP Reference | `packages/@lumenflow/mcp/src/tools.ts` | `apps/docs/src/content/docs/reference/mcp.mdx` |
18
18
 
19
+ ## What This Does Not Cover
20
+
21
+ Generated reference docs are only one part of docs parity.
22
+
23
+ `pnpm docs:generate` does **not** update narrative behavior docs such as:
24
+
25
+ - `AGENTS.md`
26
+ - `LUMENFLOW.md`
27
+ - `{{DOCS_ONBOARDING_PATH}}/**`
28
+ - `apps/docs/src/content/docs/packs/**`
29
+ - `apps/docs/src/content/docs/kernel/**`
30
+ - `apps/docs/src/content/docs/packs/software-delivery/languages/**`
31
+
32
+ When behavior changes, make an explicit docs decision:
33
+
34
+ - **Internal docs** when the change affects agent workflow, maintainer workflow, onboarding, or
35
+ repo-specific operating rules
36
+ - **Starlight docs** when the change affects public CLI behavior, pack behavior, language guides,
37
+ or user-facing workflow expectations
38
+ - **Both** when the same behavior change affects internal agents and external users
39
+
40
+ If you changed behavior and only ran `pnpm docs:generate`, your docs work is probably incomplete.
41
+
19
42
  ## Example Tagging Conventions
20
43
 
21
44
  Docs example parity now distinguishes between copy-paste workflow examples and illustrative
@@ -130,27 +130,42 @@ you want to refresh docs without upgrading packages (e.g., after manually editin
130
130
 
131
131
  ## WU Lifecycle
132
132
 
133
- | Command | Description |
134
- | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
135
- | `pnpm wu:create --lane <Lane> --title "..." ..` | Create new WU spec (ID auto-generated; see fields below) |
136
- | `pnpm wu:claim --id WU-XXX --lane <Lane>` | Claim WU and create worktree (default) |
137
- | `pnpm wu:claim --id WU-XXX --lane <L> --cloud` | Claim WU in cloud/branch-pr mode (no worktree) |
138
- | `pnpm wu:prep --id WU-XXX [--full-tests]` | Run gates, prep for wu:done (`tests.unit` scoped by default) |
139
- | `pnpm wu:done --id WU-XXX` | Complete WU (merge or PR, stamp, cleanup) |
140
- | `pnpm wu:edit --id WU-XXX --description "..."` | Edit WU spec fields (run --help for all flags) |
141
- | `pnpm wu:escalate --id WU-XXX` | Show escalation status for a WU |
142
- | `pnpm wu:escalate --resolve --id WU-XXX` | Resolve escalation (sets resolved_by/resolved_at) |
143
- | `pnpm approval:request --type <type> --subject <json>` | Request control-plane approval for an action |
144
- | `pnpm approval:review --id <approvalId> --decision <decision>` | Resolve an approval decision (`approved`/`rejected`/`expired`) |
145
- | `pnpm approval:list [--status <status>]` | List approvals with optional status/type filters |
146
- | `pnpm wu:block --id WU-XXX --reason "..."` | Block WU with reason (ownership-guarded, v3.19.0) |
147
- | `pnpm wu:unblock --id WU-XXX` | Unblock WU (ownership-guarded, v3.19.0) |
148
- | `pnpm wu:release --id WU-XXX --reason "..."` | Release orphaned WU (ownership-guarded, v3.19.0) |
149
- | `pnpm wu:status --id WU-XXX` | Show WU status, location, valid commands |
150
- | `pnpm wu:brief --id WU-XXX --client <client>` | **MANDATORY after wu:claim.** Generate handoff prompt + record evidence. wu:done blocks without this (WU-2379) |
151
- | `pnpm wu:brief --id WU-XXX --no-context` | Generate prompt without memory context injection |
152
- | `pnpm wu:delegate --id WU-XXX --parent-wu <P>` | Generate prompt, record lineage, and store brief hash attestation |
153
- | `pnpm wu:sandbox --id WU-XXX -- <cmd>` | Run command through hardened WU sandbox backend |
133
+ | Command | Description |
134
+ | -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
135
+ | `pnpm wu:create --lane <Lane> --title "..." ..` | Create new WU spec (ID auto-generated; see fields below) |
136
+ | `pnpm wu:claim --id WU-XXX --lane <Lane>` | Claim WU and create worktree (default) |
137
+ | `pnpm wu:claim --id WU-XXX --lane <L> --cloud` | Claim WU in cloud/branch-pr mode (no worktree) |
138
+ | `pnpm wu:prep --id WU-XXX [--full-tests]` | Run gates, prep for wu:done (`tests.unit` is scoped only when the active preset supports path-scoped execution) |
139
+ | `pnpm wu:done --id WU-XXX` | Complete WU (merge or PR, stamp, cleanup) |
140
+ | `pnpm wu:edit --id WU-XXX --description "..."` | Edit WU spec fields (run --help for all flags) |
141
+ | `pnpm wu:escalate --id WU-XXX` | Show escalation status for a WU |
142
+ | `pnpm wu:escalate --resolve --id WU-XXX` | Resolve escalation (sets resolved_by/resolved_at) |
143
+ | `pnpm approval:request --type <type> --subject <json>` | Request control-plane approval for an action |
144
+ | `pnpm approval:review --id <approvalId> --decision <decision>` | Resolve an approval decision (`approved`/`rejected`/`expired`) |
145
+ | `pnpm approval:list [--status <status>]` | List approvals with optional status/type filters |
146
+ | `pnpm wu:block --id WU-XXX --reason "..."` | Block WU with reason (ownership-guarded, v3.19.0) |
147
+ | `pnpm wu:unblock --id WU-XXX` | Unblock WU (ownership-guarded, v3.19.0) |
148
+ | `pnpm wu:release --id WU-XXX --reason "..."` | Release orphaned WU (ownership-guarded, v3.19.0) |
149
+ | `pnpm wu:status --id WU-XXX` | Show WU status, location, valid commands |
150
+ | `pnpm wu:brief --id WU-XXX --client <client>` | **MANDATORY after wu:claim.** Generate handoff prompt + record evidence. wu:done blocks without this (WU-2379) |
151
+ | `pnpm wu:brief --id WU-XXX --no-context` | Generate prompt without memory context injection |
152
+ | `pnpm wu:delegate --id WU-XXX --parent-wu <P>` | Generate prompt, record lineage, and store brief hash attestation |
153
+ | `pnpm wu:sandbox --id WU-XXX -- <cmd>` | Run command through hardened WU sandbox backend |
154
+
155
+ Common surgical `wu:edit` patterns:
156
+
157
+ ```bash
158
+ # Rename one code_path entry without rewriting the full array
159
+ pnpm wu:edit --id WU-123 \
160
+ --rename-code-paths "docs/08_concepts.md=docs/08_crosscutting_concepts.md"
161
+
162
+ # Remove one stale code_path entry
163
+ pnpm wu:edit --id WU-123 --remove-code-paths "docs/old-path.md"
164
+
165
+ # Rename one scoped unit test path without replacing all test paths
166
+ pnpm wu:edit --id WU-123 \
167
+ --rename-test-paths-unit "tests/old-name.test.ts=tests/new-name.test.ts"
168
+ ```
154
169
 
155
170
  ### WU Maintenance
156
171
 
@@ -465,6 +480,22 @@ For the complete orchestration workflow (delegation, memory coordination, failur
465
480
  | `pnpm docs:generate` | Generate CLI documentation |
466
481
  | `pnpm docs:validate` | Validate CLI documentation |
467
482
 
483
+ ### Documentation Decision Rule
484
+
485
+ For behavior changes, make an explicit docs decision instead of assuming generated reference docs
486
+ cover everything:
487
+
488
+ - **Internal docs**: agent workflow, maintainer workflow, onboarding, or repo-specific operating
489
+ rules changed.
490
+ - **Starlight docs**: public CLI behavior, pack behavior, language guidance, or user-facing
491
+ workflow changed.
492
+ - **Both**: the same behavior change affects agents internally and users externally.
493
+ - **None**: no user-facing or agent-facing guidance changed.
494
+
495
+ `pnpm docs:generate` only covers generated reference pages. Narrative workflow docs in
496
+ `AGENTS.md`, `LUMENFLOW.md`, onboarding docs, and `apps/docs/src/content/docs/**` still need
497
+ manual updates when behavior changes.
498
+
468
499
  ---
469
500
 
470
501
  ## Release
@@ -240,34 +240,48 @@ The workflow:
240
240
  1. Installs D2 (`astro-d2` prerequisite)
241
241
  2. Builds docs with `pnpm --filter @lumenflow/docs build`
242
242
  3. Uploads `apps/docs/dist` as a workflow artifact
243
- 4. Deploys to Vercel when `VERCEL_TOKEN`, `VERCEL_ORG_ID`, and `VERCEL_PROJECT_ID` secrets are configured
243
+ 4. Deploys to Vercel when `VERCEL_TOKEN`, `VERCEL_ORG_ID`, and `VERCEL_PROJECT_ID` Actions secrets are configured and valid
244
+ 5. Skips deploy cleanly when those secrets are absent, while still preserving the build artifact for inspection
244
245
 
245
246
  ### Deployment
246
247
 
247
- Production deploy is still manual via Vercel CLI:
248
+ Production deploy normally happens through `.github/workflows/docs.yml` on a release tag push. When the workflow reaches the Vercel step successfully, it runs these commands against `apps/docs/`:
248
249
 
249
250
  ```bash
250
- cd apps/docs
251
- pnpm build
252
- vercel --prod
251
+ pnpm dlx vercel pull --yes --environment=production --cwd apps/docs --token "$VERCEL_TOKEN"
252
+ pnpm dlx vercel build --prod --cwd apps/docs --token "$VERCEL_TOKEN"
253
+ pnpm dlx vercel deploy --prebuilt --prod --cwd apps/docs --token "$VERCEL_TOKEN"
254
+ ```
255
+
256
+ Use a manual Vercel CLI deploy only as a recovery path when the GitHub Actions run needs to be replayed outside a tag push or `workflow_dispatch`. In that case, export the same values used by Actions:
257
+
258
+ ```bash
259
+ export VERCEL_TOKEN=<token>
260
+ export VERCEL_ORG_ID=<team-id>
261
+ export VERCEL_PROJECT_ID=<project-id>
253
262
  ```
254
263
 
255
264
  ### When to Deploy
256
265
 
266
+ - Release tags (`v*`) automatically trigger the docs workflow
267
+ - Use `workflow_dispatch` when you need to rebuild or redeploy docs without cutting a new release tag
257
268
  - After any changes to `apps/docs/src/content/docs/**`
258
269
  - After version bumps (to update any version references)
259
270
  - After adding new features documented in Starlight
260
271
 
261
- ### Vercel Project
272
+ ### Required Secrets
273
+
274
+ - **`VERCEL_TOKEN`**: deploy token used by the workflow's Vercel CLI steps
275
+ - **`VERCEL_ORG_ID`**: Vercel team/org that owns the production docs project
276
+ - **`VERCEL_PROJECT_ID`**: Vercel project that serves `lumenflow.dev`
262
277
 
263
- - **Project**: `lumenflow-docs` (ID: `prj_myK4BzfHKctGhxfvALJaMOXVLx4g`)
264
- - **Domain**: lumenflow.dev
265
- - **Team**: lumenflow
278
+ Treat those GitHub Actions secrets as the source of truth for automated docs deploys. Do not rely on the repo-root `.vercel/project.json` for docs releases; it may be linked to a different Vercel project such as the monorepo preview app.
266
279
 
267
280
  ### Important Notes
268
281
 
269
282
  - **No private repo links**: Starlight docs are public; never link to `github.com/hellmai/lumenflow`
270
283
  - **Link to npm**: Use <https://www.npmjs.com/org/lumenflow> for package links
284
+ - **Secret failures are explicit**: if `VERCEL_TOKEN` is invalid, the workflow will fail at `vercel pull`; rotating the Actions secret and rerunning `docs.yml` is the correct fix
271
285
 
272
286
  ---
273
287
 
@@ -394,7 +408,7 @@ pnpm release --release-version 1.3.0 --skip-publish --dry-run
394
408
  pnpm release --release-version 1.3.0 --skip-publish
395
409
  ```
396
410
 
397
- This handles version bump and tag locally; GitHub Actions handles npm publish, docs build, and GitHub release creation.
411
+ This handles version bump and tag locally; GitHub Actions handles npm publish, GitHub release creation, and the docs build/deploy path when the Vercel secrets are configured correctly.
398
412
 
399
413
  ### Release Steps (Manual)
400
414
 
@@ -423,16 +437,21 @@ If you need more control:
423
437
  gh release view v1.3.0
424
438
  ```
425
439
 
426
- 4. **Verify docs workflow** (if docs changed)
440
+ 4. **Verify docs workflow** (if docs changed or the release should refresh public docs)
427
441
 
428
442
  ```bash
429
443
  gh run list --workflow=docs.yml --limit 1
430
444
  ```
431
445
 
432
- 5. **Deploy Starlight docs** (if content changed and you are deploying manually)
446
+ 5. **Manual Starlight recovery deploy** (only if you need to replay deploy outside the normal workflow)
433
447
 
434
448
  ```bash
435
- cd apps/docs && pnpm build && vercel --prod
449
+ export VERCEL_TOKEN=<token>
450
+ export VERCEL_ORG_ID=<team-id>
451
+ export VERCEL_PROJECT_ID=<project-id>
452
+ pnpm dlx vercel pull --yes --environment=production --cwd apps/docs --token "$VERCEL_TOKEN"
453
+ pnpm dlx vercel build --prod --cwd apps/docs --token "$VERCEL_TOKEN"
454
+ pnpm dlx vercel deploy --prebuilt --prod --cwd apps/docs --token "$VERCEL_TOKEN"
436
455
  ```
437
456
 
438
457
  ### After Release
@@ -445,13 +464,13 @@ If you need more control:
445
464
 
446
465
  ## Keeping Components in Sync
447
466
 
448
- | Change Type | npm | Docs | Packs |
449
- | ---------------- | ------------- | ----------------------- | ------- |
450
- | Bug fix in CLI | Tag + publish | Auto\* | No |
451
- | New CLI command | Tag + publish | Auto\* | No |
452
- | Pack changes | Tag + publish | No | Publish |
453
- | Docs-only update | No | Build workflow + deploy | No |
454
- | Full release | Tag + publish | Build workflow + deploy | Publish |
467
+ | Change Type | npm | Docs | Packs |
468
+ | ---------------- | ------------- | ------------------------------- | ------- |
469
+ | Bug fix in CLI | Tag + publish | Auto\* | No |
470
+ | New CLI command | Tag + publish | Auto\* | No |
471
+ | Pack changes | Tag + publish | No | Publish |
472
+ | Docs-only update | No | `workflow_dispatch` + deploy | No |
473
+ | Full release | Tag + publish | Tag-triggered workflow + deploy | Publish |
455
474
 
456
475
  \* CLI/config reference docs regenerate automatically during `wu:done` when trigger files change. See [Automatic Docs Generation](./docs-generation.md).
457
476
 
@@ -467,9 +486,10 @@ If you need more control:
467
486
 
468
487
  ### Vercel deploy fails
469
488
 
470
- 1. Check build locally: `cd apps/docs && pnpm build`
471
- 2. Check Vercel CLI auth: `vercel whoami`
472
- 3. Check project link: `vercel link`
489
+ 1. Check build locally: `pnpm --filter @lumenflow/docs build`
490
+ 2. Check the `VERCEL_TOKEN` GitHub Actions secret is valid; an invalid token fails at `vercel pull`
491
+ 3. Check `VERCEL_ORG_ID` and `VERCEL_PROJECT_ID` still target the production docs project for `lumenflow.dev`
492
+ 4. If you must replay deploy locally, export the same `VERCEL_*` values and run the same `vercel pull/build/deploy` sequence used in `docs.yml`
473
493
 
474
494
  ---
475
495
 
@@ -197,13 +197,14 @@ 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 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.
200
+ 2. **When wu:done reports branch drift, a non-fast-forward error, or patch-equivalent local-main catch-up, rerun it from main first.** It auto-rebases the lane branch when it can and now reconciles patch-equivalent local-main divergence after atomic push. 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.
204
- 6. **wu:edit requires a clean worktree.** Commit `wu-events.jsonl` and other changes before running `wu:edit`.
204
+ 6. **Structural `wu:edit` changes require a clean worktree.** Metadata-only edits such as `--notes`, `--acceptance`, and scoped test-path updates can run on a dirty worktree, but scope-changing edits like `--code-paths`, `--remove-code-paths`, `--rename-code-paths`, `--lane`, or `--plan` still require a clean state.
205
205
  7. **Don't edit on main then stash to a worktree.** If a hook blocks you on main, that means you need a WU. Create one and work in the worktree from the start.
206
206
  8. **Don't modify another agent's WU to free a lane.** `wu:block`, `wu:unblock`, `wu:release`, and `wu:recover` enforce ownership guards (v3.19.0). If you hit a `SESSION OWNERSHIP VIOLATION`, wait for the owning WU to complete or block itself — never use `--override-owner` without explicit human instruction.
207
+ 9. **Behavior changes need a docs decision.** Update internal docs, Starlight docs, or both when behavior changes. Generated reference docs alone do not cover narrative workflow changes.
207
208
 
208
209
  ---
209
210
 
@@ -461,18 +462,26 @@ Do not use `git stash`, switch local main, or otherwise mutate main just to prov
461
462
 
462
463
  ### Scenario 6: wu:done reports branch drift or a non-fast-forward error
463
464
 
464
- **Cause:** Another agent or process pushed to main between your fetch and push (race condition).
465
+ **Cause:** Another agent or process pushed to main between your fetch and push (race condition), or
466
+ your local `main` needs to catch up after the atomic push path.
465
467
 
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`.
468
+ **Fix:** Rerun `wu:done` from main first. It has built-in lane auto-rebase for branch drift and
469
+ automatic local-main reconciliation for patch-equivalent divergence after a successful atomic push.
470
+ If the rerun still fails with a real conflict, resolve the conflict in the worktree, rerun
471
+ `wu:prep` if needed, then return to main and rerun `wu:done`.
467
472
 
468
473
  ```bash
469
474
  # WRONG - never manually rebase main
470
475
  git rebase origin/main # DON'T DO THIS
471
476
 
472
- # RIGHT - just rerun the command
477
+ # RIGHT - just rerun the command from main first
473
478
  pnpm wu:done --id WU-XXX
474
479
  ```
475
480
 
481
+ If the rerun still reports a true local-main mismatch after a completed atomic push, treat that as
482
+ an abnormal recovery case and use the surfaced recovery guidance or `pnpm wu:recover --id WU-XXX`
483
+ instead of rebasing `main` manually.
484
+
476
485
  ---
477
486
 
478
487
  ## Delegating Sub-Agents with wu:brief / wu:delegate
@@ -597,6 +606,7 @@ Before reporting a WU complete, verify:
597
606
  - [ ] `pnpm wu:done --id WU-XXX` ran successfully
598
607
  - [ ] Output shows "Marked done, pushed, and cleaned up"
599
608
  - [ ] Worktree was removed (check `ls worktrees/`)
609
+ - [ ] Required docs updates were made, or you can explicitly justify `Internal docs`, `Starlight docs`, `Both`, or `None`
600
610
 
601
611
  ---
602
612
 
@@ -66,7 +66,8 @@ cd /path/to/main && pnpm wu:done --id WU-XXX
66
66
  ```
67
67
 
68
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`.
69
+ main. It auto-rebases the lane branch when possible and also catches up patch-equivalent local-main
70
+ divergence after atomic push. Do not manually rebase `main`.
70
71
 
71
72
  ---
72
73
 
@@ -131,7 +132,7 @@ Feature WUs **must** include `spec_refs` (use `pnpm wu:create --plan` if the pla
131
132
  ### "non-fast-forward" or "branch is behind main"
132
133
 
133
134
  If `wu:done` reports branch drift or a non-fast-forward push, another completion landed while your
134
- WU was in progress.
135
+ WU was in progress or your local `main` needs to catch up after the atomic push path.
135
136
 
136
137
  ```bash
137
138
  # Retry from main first
@@ -142,6 +143,9 @@ pnpm wu:done --id WU-XXX
142
143
  - If the rerun succeeds, you are done.
143
144
  - If the rerun reports an auto-rebase conflict, return to the worktree, resolve the conflict there,
144
145
  rerun `pnpm wu:prep --id WU-XXX` if needed, then retry `wu:done` from main.
146
+ - If the rerun still reports a true local-main mismatch after a completed atomic push, stop and use
147
+ the surfaced recovery guidance or `pnpm wu:recover --id WU-XXX` rather than manually rebasing
148
+ `main`.
145
149
  - Do **not** manually `git rebase` the main checkout.
146
150
 
147
151
  ---