@lumenflow/cli 4.11.0 → 4.12.0

package/templates/core/ai/onboarding/quick-ref-commands.md.template

@@ -130,27 +130,42 @@ you want to refresh docs without upgrading packages (e.g., after manually editin
 
 ## WU Lifecycle
 
-| Command                                                        | Description                                                                                                    |
-| -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
-| `pnpm wu:create --lane <Lane> --title "..." ..`                | Create new WU spec (ID auto-generated; see fields below)                                                       |
-| `pnpm wu:claim --id WU-XXX --lane <Lane>`                      | Claim WU and create worktree (default)                                                                         |
-| `pnpm wu:claim --id WU-XXX --lane <L> --cloud`                 | Claim WU in cloud/branch-pr mode (no worktree)                                                                 |
-| `pnpm wu:prep --id WU-XXX [--full-tests]`                      | Run gates, prep for wu:done (`tests.unit` scoped by default)                                                   |
-| `pnpm wu:done --id WU-XXX`                                     | Complete WU (merge or PR, stamp, cleanup)                                                                      |
-| `pnpm wu:edit --id WU-XXX --description "..."`                 | Edit WU spec fields (run --help for all flags)                                                                 |
-| `pnpm wu:escalate --id WU-XXX`                                 | Show escalation status for a WU                                                                                |
-| `pnpm wu:escalate --resolve --id WU-XXX`                       | Resolve escalation (sets resolved_by/resolved_at)                                                              |
-| `pnpm approval:request --type <type> --subject <json>`         | Request control-plane approval for an action                                                                   |
-| `pnpm approval:review --id <approvalId> --decision <decision>` | Resolve an approval decision (`approved`/`rejected`/`expired`)                                                 |
-| `pnpm approval:list [--status <status>]`                       | List approvals with optional status/type filters                                                               |
-| `pnpm wu:block --id WU-XXX --reason "..."`                     | Block WU with reason (ownership-guarded, v3.19.0)                                                              |
-| `pnpm wu:unblock --id WU-XXX`                                  | Unblock WU (ownership-guarded, v3.19.0)                                                                        |
-| `pnpm wu:release --id WU-XXX --reason "..."`                   | Release orphaned WU (ownership-guarded, v3.19.0)                                                               |
-| `pnpm wu:status --id WU-XXX`                                   | Show WU status, location, valid commands                                                                       |
-| `pnpm wu:brief --id WU-XXX --client <client>`                  | **MANDATORY after wu:claim.** Generate handoff prompt + record evidence. wu:done blocks without this (WU-2379) |
-| `pnpm wu:brief --id WU-XXX --no-context`                       | Generate prompt without memory context injection                                                               |
-| `pnpm wu:delegate --id WU-XXX --parent-wu <P>`                 | Generate prompt, record lineage, and store brief hash attestation                                              |
-| `pnpm wu:sandbox --id WU-XXX -- <cmd>`                         | Run command through hardened WU sandbox backend                                                                |
+| Command                                                        | Description                                                                                                     |
+| -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| `pnpm wu:create --lane <Lane> --title "..." ..`                | Create new WU spec (ID auto-generated; see fields below)                                                        |
+| `pnpm wu:claim --id WU-XXX --lane <Lane>`                      | Claim WU and create worktree (default)                                                                          |
+| `pnpm wu:claim --id WU-XXX --lane <L> --cloud`                 | Claim WU in cloud/branch-pr mode (no worktree)                                                                  |
+| `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) |
+| `pnpm wu:done --id WU-XXX`                                     | Complete WU (merge or PR, stamp, cleanup)                                                                       |
+| `pnpm wu:edit --id WU-XXX --description "..."`                 | Edit WU spec fields (run --help for all flags)                                                                  |
+| `pnpm wu:escalate --id WU-XXX`                                 | Show escalation status for a WU                                                                                 |
+| `pnpm wu:escalate --resolve --id WU-XXX`                       | Resolve escalation (sets resolved_by/resolved_at)                                                               |
+| `pnpm approval:request --type <type> --subject <json>`         | Request control-plane approval for an action                                                                    |
+| `pnpm approval:review --id <approvalId> --decision <decision>` | Resolve an approval decision (`approved`/`rejected`/`expired`)                                                  |
+| `pnpm approval:list [--status <status>]`                       | List approvals with optional status/type filters                                                                |
+| `pnpm wu:block --id WU-XXX --reason "..."`                     | Block WU with reason (ownership-guarded, v3.19.0)                                                               |
+| `pnpm wu:unblock --id WU-XXX`                                  | Unblock WU (ownership-guarded, v3.19.0)                                                                         |
+| `pnpm wu:release --id WU-XXX --reason "..."`                   | Release orphaned WU (ownership-guarded, v3.19.0)                                                                |
+| `pnpm wu:status --id WU-XXX`                                   | Show WU status, location, valid commands                                                                        |
+| `pnpm wu:brief --id WU-XXX --client <client>`                  | **MANDATORY after wu:claim.** Generate handoff prompt + record evidence. wu:done blocks without this (WU-2379)  |
+| `pnpm wu:brief --id WU-XXX --no-context`                       | Generate prompt without memory context injection                                                                |
+| `pnpm wu:delegate --id WU-XXX --parent-wu <P>`                 | Generate prompt, record lineage, and store brief hash attestation                                               |
+| `pnpm wu:sandbox --id WU-XXX -- <cmd>`                         | Run command through hardened WU sandbox backend                                                                 |
+
+Common surgical `wu:edit` patterns:
+
+```bash
+# Rename one code_path entry without rewriting the full array
+pnpm wu:edit --id WU-123 \
+  --rename-code-paths "docs/08_concepts.md=docs/08_crosscutting_concepts.md"
+
+# Remove one stale code_path entry
+pnpm wu:edit --id WU-123 --remove-code-paths "docs/old-path.md"
+
+# Rename one scoped unit test path without replacing all test paths
+pnpm wu:edit --id WU-123 \
+  --rename-test-paths-unit "tests/old-name.test.ts=tests/new-name.test.ts"
+```
 
 ### WU Maintenance
 
@@ -210,11 +225,9 @@ only run when matching files change. Supports `error` (blocks), `warn` (logs), a
 severity levels. See workspace-spec.mdx for schema.
 
 **Formatting: always scope to changed files only.**
-Use `{{format_fix_command}}` — never unscoped `pnpm format`.
+Use `pnpm prettier --write <changed-files...>` — never unscoped `pnpm format`.
 Running `pnpm format` reformats every file in the repo, creating hundreds of
 dirty YAML/initiative changes that pollute the worktree and block `wu:done`.
-The command above is resolved at init time from your gate preset (WU-2547), so
-`.NET` repos get `dotnet format`, Python repos get `ruff format`, etc.
 
 ---
 
@@ -467,6 +480,22 @@ For the complete orchestration workflow (delegation, memory coordination, failur
 | `pnpm docs:generate` | Generate CLI documentation |
 | `pnpm docs:validate` | Validate CLI documentation |
 
+### Documentation Decision Rule
+
+For behavior changes, make an explicit docs decision instead of assuming generated reference docs
+cover everything:
+
+- **Internal docs**: agent workflow, maintainer workflow, onboarding, or repo-specific operating
+  rules changed.
+- **Starlight docs**: public CLI behavior, pack behavior, language guidance, or user-facing
+  workflow changed.
+- **Both**: the same behavior change affects agents internally and users externally.
+- **None**: no user-facing or agent-facing guidance changed.
+
+`pnpm docs:generate` only covers generated reference pages. Narrative workflow docs in
+`AGENTS.md`, `LUMENFLOW.md`, onboarding docs, and `apps/docs/src/content/docs/**` still need
+manual updates when behavior changes.
+
 ---
 
 ## Release

package/templates/core/ai/onboarding/release-process.md.template

@@ -240,34 +240,48 @@ The workflow:
 1. Installs D2 (`astro-d2` prerequisite)
 2. Builds docs with `pnpm --filter @lumenflow/docs build`
 3. Uploads `apps/docs/dist` as a workflow artifact
-4. Deploys to Vercel when `VERCEL_TOKEN`, `VERCEL_ORG_ID`, and `VERCEL_PROJECT_ID` secrets are configured
+4. Deploys to Vercel when `VERCEL_TOKEN`, `VERCEL_ORG_ID`, and `VERCEL_PROJECT_ID` Actions secrets are configured and valid
+5. Skips deploy cleanly when those secrets are absent, while still preserving the build artifact for inspection
 
 ### Deployment
 
-Production deploy is still manual via Vercel CLI:
+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/`:
 
 ```bash
-cd apps/docs
-pnpm build
-vercel --prod
+pnpm dlx vercel pull --yes --environment=production --cwd apps/docs --token "$VERCEL_TOKEN"
+pnpm dlx vercel build --prod --cwd apps/docs --token "$VERCEL_TOKEN"
+pnpm dlx vercel deploy --prebuilt --prod --cwd apps/docs --token "$VERCEL_TOKEN"
+```
+
+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:
+
+```bash
+export VERCEL_TOKEN=<token>
+export VERCEL_ORG_ID=<team-id>
+export VERCEL_PROJECT_ID=<project-id>
 ```
 
 ### When to Deploy
 
+- Release tags (`v*`) automatically trigger the docs workflow
+- Use `workflow_dispatch` when you need to rebuild or redeploy docs without cutting a new release tag
 - After any changes to `apps/docs/src/content/docs/**`
 - After version bumps (to update any version references)
 - After adding new features documented in Starlight
 
-### Vercel Project
+### Required Secrets
+
+- **`VERCEL_TOKEN`**: deploy token used by the workflow's Vercel CLI steps
+- **`VERCEL_ORG_ID`**: Vercel team/org that owns the production docs project
+- **`VERCEL_PROJECT_ID`**: Vercel project that serves `lumenflow.dev`
 
-- **Project**: `lumenflow-docs` (ID: `prj_myK4BzfHKctGhxfvALJaMOXVLx4g`)
-- **Domain**: lumenflow.dev
-- **Team**: lumenflow
+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.
 
 ### Important Notes
 
 - **No private repo links**: Starlight docs are public; never link to `github.com/hellmai/lumenflow`
 - **Link to npm**: Use <https://www.npmjs.com/org/lumenflow> for package links
+- **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
 
 ---
 
@@ -394,7 +408,7 @@ pnpm release --release-version 1.3.0 --skip-publish --dry-run
 pnpm release --release-version 1.3.0 --skip-publish
 ```
 
-This handles version bump and tag locally; GitHub Actions handles npm publish, docs build, and GitHub release creation.
+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.
 
 ### Release Steps (Manual)
 
@@ -423,16 +437,21 @@ If you need more control:
    gh release view v1.3.0
    ```
 
-4. **Verify docs workflow** (if docs changed)
+4. **Verify docs workflow** (if docs changed or the release should refresh public docs)
 
    ```bash
    gh run list --workflow=docs.yml --limit 1
    ```
 
-5. **Deploy Starlight docs** (if content changed and you are deploying manually)
+5. **Manual Starlight recovery deploy** (only if you need to replay deploy outside the normal workflow)
 
    ```bash
-   cd apps/docs && pnpm build && vercel --prod
+   export VERCEL_TOKEN=<token>
+   export VERCEL_ORG_ID=<team-id>
+   export VERCEL_PROJECT_ID=<project-id>
+   pnpm dlx vercel pull --yes --environment=production --cwd apps/docs --token "$VERCEL_TOKEN"
+   pnpm dlx vercel build --prod --cwd apps/docs --token "$VERCEL_TOKEN"
+   pnpm dlx vercel deploy --prebuilt --prod --cwd apps/docs --token "$VERCEL_TOKEN"
    ```
 
 ### After Release
@@ -445,13 +464,13 @@ If you need more control:
 
 ## Keeping Components in Sync
 
-| Change Type      | npm           | Docs                    | Packs   |
-| ---------------- | ------------- | ----------------------- | ------- |
-| Bug fix in CLI   | Tag + publish | Auto\*                  | No      |
-| New CLI command  | Tag + publish | Auto\*                  | No      |
-| Pack changes     | Tag + publish | No                      | Publish |
-| Docs-only update | No            | Build workflow + deploy | No      |
-| Full release     | Tag + publish | Build workflow + deploy | Publish |
+| Change Type      | npm           | Docs                            | Packs   |
+| ---------------- | ------------- | ------------------------------- | ------- |
+| Bug fix in CLI   | Tag + publish | Auto\*                          | No      |
+| New CLI command  | Tag + publish | Auto\*                          | No      |
+| Pack changes     | Tag + publish | No                              | Publish |
+| Docs-only update | No            | `workflow_dispatch` + deploy    | No      |
+| Full release     | Tag + publish | Tag-triggered workflow + deploy | Publish |
 
 \* CLI/config reference docs regenerate automatically during `wu:done` when trigger files change. See [Automatic Docs Generation](./docs-generation.md).
 
@@ -467,9 +486,10 @@ If you need more control:
 
 ### Vercel deploy fails
 
-1. Check build locally: `cd apps/docs && pnpm build`
-2. Check Vercel CLI auth: `vercel whoami`
-3. Check project link: `vercel link`
+1. Check build locally: `pnpm --filter @lumenflow/docs build`
+2. Check the `VERCEL_TOKEN` GitHub Actions secret is valid; an invalid token fails at `vercel pull`
+3. Check `VERCEL_ORG_ID` and `VERCEL_PROJECT_ID` still target the production docs project for `lumenflow.dev`
+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`
 
 ---
 

package/templates/core/ai/onboarding/starting-prompt.md.template

@@ -197,13 +197,14 @@ LUMENFLOW_CLOUD=1 pnpm wu:claim --id WU-XXXX --lane "Lane Name"
 These are the mistakes agents make most often. Memorize these before reading anything else:
 
 1. **wu:done deletes the worktree.** After it completes, your shell CWD is invalid. Immediately `cd` back to the project root.
-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.
+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.
 3. **Always run `--help` before first use of any command.** Don't guess flags — 30 seconds reading help saves 5 minutes of failed attempts.
 4. **Never `pnpm update @lumenflow/*` directly.** Use `pnpm lumenflow:upgrade --latest` (uses micro-worktree isolation).
 5. **State files are auto-generated.** Never manually edit `wu-events.jsonl`, `backlog.md`, or `status.md` — lifecycle commands manage them.
-6. **wu:edit requires a clean worktree.** Commit `wu-events.jsonl` and other changes before running `wu:edit`.
+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.
 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.
 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.
+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.
 
 ---
 
@@ -289,7 +290,7 @@ When gates fail, read the error and fix it. Common failures and fixes:
 
 | Failure        | Cause                   | Fix                                    |
 | -------------- | ----------------------- | -------------------------------------- |
-| `format:check` | Formatter check failed  | `{{format_fix_command}}`               |
+| `format:check` | Prettier formatting     | `pnpm prettier --write <file>`         |
 | `backlog-sync` | WU missing from backlog | Regenerate backlog or add WU reference |
 | `typecheck`    | TypeScript errors       | Fix the type errors                    |
 | `lint`         | ESLint violations       | `pnpm lint --fix` or manual fix        |
@@ -461,18 +462,26 @@ Do not use `git stash`, switch local main, or otherwise mutate main just to prov
 
 ### Scenario 6: wu:done reports branch drift or a non-fast-forward error
 
-**Cause:** Another agent or process pushed to main between your fetch and push (race condition).
+**Cause:** Another agent or process pushed to main between your fetch and push (race condition), or
+your local `main` needs to catch up after the atomic push path.
 
-**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`.
+**Fix:** Rerun `wu:done` from main first. It has built-in lane auto-rebase for branch drift and
+automatic local-main reconciliation for patch-equivalent divergence after a successful atomic push.
+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`.
 
 ```bash
 # WRONG - never manually rebase main
 git rebase origin/main  # DON'T DO THIS
 
-# RIGHT - just rerun the command
+# RIGHT - just rerun the command from main first
 pnpm wu:done --id WU-XXX
 ```
 
+If the rerun still reports a true local-main mismatch after a completed atomic push, treat that as
+an abnormal recovery case and use the surfaced recovery guidance or `pnpm wu:recover --id WU-XXX`
+instead of rebasing `main` manually.
+
 ---
 
 ## Delegating Sub-Agents with wu:brief / wu:delegate
@@ -597,6 +606,7 @@ Before reporting a WU complete, verify:
 - [ ] `pnpm wu:done --id WU-XXX` ran successfully
 - [ ] Output shows "Marked done, pushed, and cleaned up"
 - [ ] Worktree was removed (check `ls worktrees/`)
+- [ ] Required docs updates were made, or you can explicitly justify `Internal docs`, `Starlight docs`, `Both`, or `None`
 
 ---
 

package/templates/core/ai/onboarding/troubleshooting-wu-done.md.template

@@ -66,7 +66,8 @@ cd /path/to/main && pnpm wu:done --id WU-XXX
 ```
 
 If `wu:done` reports branch drift, parallel completions, or a non-fast-forward push, rerun it from
-main. It auto-rebases by default when possible. Do not manually rebase `main`.
+main. It auto-rebases the lane branch when possible and also catches up patch-equivalent local-main
+divergence after atomic push. Do not manually rebase `main`.
 
 ---
 
@@ -131,7 +132,7 @@ Feature WUs **must** include `spec_refs` (use `pnpm wu:create --plan` if the pla
 ### "non-fast-forward" or "branch is behind main"
 
 If `wu:done` reports branch drift or a non-fast-forward push, another completion landed while your
-WU was in progress.
+WU was in progress or your local `main` needs to catch up after the atomic push path.
 
 ```bash
 # Retry from main first
@@ -142,6 +143,9 @@ pnpm wu:done --id WU-XXX
 - If the rerun succeeds, you are done.
 - If the rerun reports an auto-rebase conflict, return to the worktree, resolve the conflict there,
   rerun `pnpm wu:prep --id WU-XXX` if needed, then retry `wu:done` from main.
+- If the rerun still reports a true local-main mismatch after a completed atomic push, stop and use
+  the surfaced recovery guidance or `pnpm wu:recover --id WU-XXX` rather than manually rebasing
+  `main`.
 - Do **not** manually `git rebase` the main checkout.
 
 ---