@lumenflow/cli 2.2.1 → 2.3.1

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

@@ -0,0 +1,186 @@
+# Quick Reference: LumenFlow Commands
+
+**Last updated:** {{DATE}}
+
+---
+
+## Project Setup
+
+| Command                                       | Description                                        |
+| --------------------------------------------- | -------------------------------------------------- |
+| `pnpm exec lumenflow init`                    | Scaffold minimal LumenFlow core                    |
+| `pnpm exec lumenflow init --full`             | Add docs + agent onboarding + task scaffolding     |
+| `pnpm exec lumenflow init --framework <name>` | Add framework hint + overlay docs                  |
+| `pnpm exec lumenflow init --force`            | Overwrite existing files                           |
+| `pnpm exec lumenflow docs:sync`               | Sync agent docs to existing project (for upgrades) |
+| `pnpm exec lumenflow docs:sync --force`       | Overwrite existing agent docs                      |
+| `pnpm exec lumenflow doctor`                  | Diagnose LumenFlow configuration issues            |
+
+---
+
+## WU Management
+
+| Command                                                                                                                                                                                                               | Description                                          |
+| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
+| `pnpm wu:create --id WU-XXX --lane <Lane> --title "Title" --description "..." --acceptance "..." --code-paths "path" --test-paths-unit "path" --exposure backend-only --spec-refs "lumenflow://plans/WU-XXX-plan.md"` | Create new WU (default: spec branch mode)            |
+| `pnpm wu:create ... --direct`                                                                                                                                                                                         | Create WU directly on main (legacy/emergency)        |
+| `pnpm wu:create ... --plan`                                                                                                                                                                                           | Also create plan template in $LUMENFLOW_HOME/plans/  |
+| `pnpm wu:claim --id WU-XXX --lane <Lane>`                                                                                                                                                                             | Claim WU (auto-merges spec branch if needed)         |
+| `pnpm wu:spawn --id WU-XXX --client <client>`                                                                                                                                                                         | Spawn sub-agent prompt with client guidance          |
+| `pnpm wu:edit --id WU-1039 --exposure backend-only`                                                                                                                                                                   | Edit WU spec (supports exposure updates on done WUs) |
+| `pnpm wu:done --id WU-XXX`                                                                                                                                                                                            | Complete WU (merge, stamp, cleanup) - primary method |
+| `pnpm wu:block --id WU-XXX --reason "Reason"`                                                                                                                                                                         | Block a WU                                           |
+| `pnpm wu:unblock --id WU-XXX`                                                                                                                                                                                         | Unblock a WU                                         |
+| `pnpm wu:cleanup --id WU-XXX`                                                                                                                                                                                         | PR-only: cleanup after PR merge (see note below)     |
+| `pnpm wu:cleanup --artifacts`                                                                                                                                                                                         | Remove build artifacts in current worktree           |
+| `pnpm wu:delete --id WU-XXX`                                                                                                                                                                                          | Delete WU spec and cleanup                           |
+| `pnpm wu:unlock-lane --lane <Lane>`                                                                                                                                                                                   | Unlock stuck lane                                    |
+
+### wu:done vs wu:cleanup
+
+**IMPORTANT:** Use `wu:done` for completing WUs. `wu:cleanup` is NOT a replacement for `wu:done`.
+
+| Command      | Purpose                                    | When to Use                    |
+| ------------ | ------------------------------------------ | ------------------------------ |
+| `wu:done`    | Complete WU: run gates, merge, stamp, push | Always use this to finish a WU |
+| `wu:cleanup` | Remove worktree/branch after PR merge      | PR-based workflows only (rare) |
+
+**wu:cleanup is PR-only:** When `gh` CLI is available, `wu:cleanup` requires the PR to be merged before it will run. It checks the PR merge status via GitHub API and blocks if the PR is not merged. This prevents accidental cleanup of work-in-progress WUs.
+
+**Common mistake:** Agents sometimes try to run `wu:cleanup` after `wu:done` fails. This is incorrect. If `wu:done` fails:
+
+1. Fix the underlying issue (gate failures, merge conflicts, etc.)
+2. Re-run `wu:done --id WU-XXX`
+
+Do NOT use `wu:cleanup` to work around `wu:done` failures.
+
+### wu:edit Write Modes
+
+`wu:edit` has two distinct modes depending on WU status:
+
+| WU Status     | Write Mode     | Target Location                   |
+| ------------- | -------------- | --------------------------------- |
+| `ready`       | MICRO_WORKTREE | main (via temp branch + ff-merge) |
+| `in_progress` | WORKTREE       | Active worktree directly          |
+
+**Key behavior:**
+
+- **Ready WUs**: Edits go to main via a micro-worktree transaction (same as `wu:create`)
+- **In-progress WUs**: Edits write directly to the active worktree's WU YAML file
+
+This means `wu:edit` on an `in_progress` WU automatically propagates to the worktree - no manual sync needed. When `wu:done` runs, it uses `readWUPreferWorktree()` which reads from the worktree first, ensuring your edits are preserved.
+
+**Common confusion:** Agents sometimes think they need to manually sync edits to the worktree. This is unnecessary - `wu:edit` handles it automatically based on WU status.
+
+---
+
+## Gates
+
+| Command                  | Description                |
+| ------------------------ | -------------------------- |
+| `pnpm gates`             | Run all quality gates      |
+| `pnpm gates --docs-only` | Run gates for docs changes |
+| `pnpm format`            | Format all files           |
+| `pnpm lint`              | Run linter                 |
+| `pnpm typecheck`         | Run TypeScript check       |
+| `pnpm test`              | Run tests                  |
+| `pnpm lane:health`       | Check lane config health   |
+| `pnpm lane:suggest`      | Suggest lane for code paths|
+
+---
+
+## Memory (Session Context)
+
+| Command                           | Description                |
+| --------------------------------- | -------------------------- |
+| `pnpm mem:init --wu WU-XXX`       | Initialize memory for WU   |
+| `pnpm mem:checkpoint --wu WU-XXX` | Save progress checkpoint   |
+| `pnpm mem:ready --wu WU-XXX`      | Check pending nodes        |
+| `pnpm mem:inbox --wu WU-XXX`      | Check coordination signals |
+
+---
+
+## Git (Safe Operations)
+
+| Command                              | Description               |
+| ------------------------------------ | ------------------------- |
+| `git status`                         | Check working tree status |
+| `git add .`                          | Stage all changes         |
+| `git commit -m "type: message"`      | Commit with message       |
+| `git push origin lane/<lane>/wu-xxx` | Push to remote            |
+| `git fetch origin`                   | Fetch remote changes      |
+| `git rebase origin/main`             | Update from main          |
+
+---
+
+## Navigation
+
+```bash
+# After claiming, go to worktree
+cd worktrees/<lane>-wu-xxx
+
+# Return to main for wu:done
+cd /path/to/main
+```
+
+---
+
+## Workflow Sequence
+
+```bash
+# 1. Create (default: spec branch mode, never writes to main)
+pnpm wu:create --id WU-001 --lane "Framework: Core" --title "Add feature" \
+  --description "Context: ...\nProblem: ...\nSolution: ..." \
+  --acceptance "Criterion 1" --acceptance "Criterion 2" \
+  --code-paths "packages/@lumenflow/core/src/example.ts" \
+  --test-paths-unit "packages/@lumenflow/core/__tests__/example.test.ts" \
+  --exposure backend-only \
+  --spec-refs "lumenflow://plans/WU-001-plan.md"
+
+# 2. Claim (auto-merges spec/wu-001 to main, creates worktree)
+pnpm wu:claim --id WU-001 --lane "Framework: Core"
+cd worktrees/framework-core-wu-001
+
+# 3. Work (TDD)
+# ... write tests first, then code ...
+
+# 4. Commit
+git add .
+git commit -m "feat: add feature"
+git push origin lane/framework-core/wu-001
+
+# 5. Gates
+pnpm gates
+
+# 6. Complete
+cd /path/to/main
+pnpm wu:done --id WU-001
+```
+
+---
+
+## Commit Message Format
+
+```
+type(scope): description
+
+Types: feat, fix, docs, style, refactor, test, chore
+```
+
+Examples:
+
+- `feat(api): add user endpoint`
+- `fix(auth): resolve token expiry`
+- `docs: update README`
+- `test: add unit tests for calculator`
+
+---
+
+## File Paths
+
+| Path                                      | Description          |
+| ----------------------------------------- | -------------------- |
+| `docs/04-operations/tasks/wu/WU-XXX.yaml` | WU specification     |
+| `docs/04-operations/tasks/status.md`      | Current status board |
+| `.lumenflow/stamps/WU-XXX.done`           | Completion stamp     |
+| `worktrees/<lane>-wu-xxx/`                | Worktree directory   |

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

@@ -0,0 +1,362 @@
+# LumenFlow Release Process
+
+**Last updated:** {{DATE}}
+
+This document covers the complete release process for LumenFlow, including versioning, npm publishing, documentation updates, and the GitHub App.
+
+---
+
+## Overview
+
+LumenFlow has several components that need to stay in sync:
+
+| Component      | Location                | Deployment                          |
+| -------------- | ----------------------- | ----------------------------------- |
+| npm packages   | `packages/@lumenflow/*` | Auto via GitHub Actions on tag push |
+| Starlight docs | `apps/docs/`            | Manual via Vercel CLI               |
+| GitHub App     | `apps/github-app/`      | Auto via Vercel Git integration     |
+
+---
+
+## Release Command
+
+The `pnpm release` command automates the entire release process:
+
+```bash
+pnpm release --release-version 1.3.0
+```
+
+### What It Does
+
+1. Validates semver version format
+2. Ensures clean working directory on main branch
+3. Bumps all `@lumenflow/*` package versions using micro-worktree isolation
+4. Builds all packages
+5. Creates and pushes git tag `vX.Y.Z`
+6. Publishes to npm
+
+### Options
+
+| Flag                        | Description                             |
+| --------------------------- | --------------------------------------- |
+| `--release-version <X.Y.Z>` | **Required.** Semver version to release |
+| `--dry-run`                 | Preview changes without making them     |
+| `--skip-publish`            | Bump and tag only (no npm publish)      |
+| `--skip-build`              | Skip build step (use existing dist)     |
+| `--version`, `-V`           | Show CLI version                        |
+| `--help`, `-h`              | Show help                               |
+
+### Examples
+
+```bash
+# Full release
+pnpm release --release-version 1.3.0
+
+# Preview what would happen
+pnpm release --release-version 1.3.0 --dry-run
+
+# Version bump and tag only (CI will publish)
+pnpm release --release-version 1.3.0 --skip-publish
+```
+
+### Authentication
+
+For npm publish, set one of these environment variables:
+
+```bash
+export NPM_TOKEN=<your-npm-token>
+# or
+export NODE_AUTH_TOKEN=<your-npm-token>
+```
+
+Get a token at: https://www.npmjs.com/settings/tokens
+
+---
+
+## Version Bumping (Manual)
+
+If you need to bump versions manually without the release command:
+
+All `@lumenflow/*` packages share the same version number for simplicity.
+
+### Packages to Update
+
+```text
+packages/@lumenflow/core/package.json
+packages/@lumenflow/cli/package.json
+packages/@lumenflow/memory/package.json
+packages/@lumenflow/agent/package.json
+packages/@lumenflow/metrics/package.json
+packages/@lumenflow/initiatives/package.json
+packages/@lumenflow/shims/package.json
+```
+
+### Manual Version Bump
+
+```bash
+# Update all package.json files
+# Change "version": "1.2.0" to "1.3.0" in each file
+
+# Verify versions match
+grep '"version"' packages/@lumenflow/*/package.json
+```
+
+### Semantic Versioning
+
+- **Patch** (1.2.x): Bug fixes, docs updates
+- **Minor** (1.x.0): New features, non-breaking changes
+- **Major** (x.0.0): Breaking changes (rare)
+
+---
+
+## npm Publishing
+
+### Trigger
+
+Publishing is triggered by pushing a git tag matching `v*`:
+
+```bash
+git tag -a v1.3.0 -m "v1.3.0 - Description of changes"
+git push origin v1.3.0
+```
+
+### Workflow
+
+The `.github/workflows/publish.yml` workflow:
+
+1. Checks out the tagged commit
+2. Installs dependencies
+3. Builds all packages
+4. Publishes to npm with `pnpm -r publish --access public`
+
+### Required Secrets
+
+- **`NPM_TOKEN`**: npm automation token with publish access to `@lumenflow` scope
+  - Generate at: <https://www.npmjs.com/settings/tokens>
+  - Type: Automation token (bypasses 2FA)
+  - Store in: GitHub repo settings → Secrets → Actions
+
+### Troubleshooting npm Publish
+
+#### Token Issues
+
+If you see "Access token expired or revoked":
+
+- Regenerate npm token and update `NPM_TOKEN` secret
+
+#### Package Not Found (404)
+
+If you see "404 Not Found" for a package:
+
+- Check if package has `"private": true` (should NOT be published)
+- Apps (`apps/*`) should have `"private": true`
+- Only `packages/@lumenflow/*` should be published
+
+#### Re-running Failed Workflow
+
+```bash
+gh run list --workflow=publish.yml --limit 5
+gh run rerun <run-id>
+```
+
+### Verifying Publication
+
+```bash
+npm view @lumenflow/cli versions --json | tail -5
+```
+
+---
+
+## Starlight Documentation
+
+The public docs at <https://lumenflow.dev> are built from `apps/docs/`.
+
+### Deployment
+
+Starlight docs are deployed **manually** via Vercel CLI:
+
+```bash
+cd apps/docs
+pnpm build
+vercel --prod
+```
+
+### When to Deploy
+
+- 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
+
+- **Project**: `lumenflow-docs` (ID: `prj_myK4BzfHKctGhxfvALJaMOXVLx4g`)
+- **Domain**: lumenflow.dev
+- **Team**: hellm-ai
+
+### Important Notes
+
+- **No private repo links**: Starlight docs are public; never link to `github.com/hellmai/os`
+- **Link to GitHub App**: Use <https://github.com/apps/lumenflow-by-hellmai> for GitHub links
+- **Link to npm**: Use <https://www.npmjs.com/org/lumenflow> for package links
+
+---
+
+## GitHub App
+
+The LumenFlow GitHub App provides workflow enforcement for teams.
+
+### Components
+
+- **App manifest**: `apps/github-app/app.yml`
+- **Webhook handler**: `apps/github-app/api/webhook.ts`
+- **Validation endpoints**: `apps/github-app/api/validate-token.ts`
+
+### Deployment
+
+The GitHub App is deployed **automatically** via Vercel Git integration when changes are pushed to `main`.
+
+- **Project**: `lumenflow-app` (ID: `prj_JKfcHVb4QjzAxdjCIJwaUf5PWusG`)
+- **URL**: <https://lumenflow-app.vercel.app>
+
+### Package Configuration
+
+The `apps/github-app/package.json` must have `"private": true` to prevent npm publish attempts.
+
+### Environment Variables (Vercel)
+
+| Variable                | Description                  |
+| ----------------------- | ---------------------------- |
+| `GITHUB_APP_ID`         | GitHub App ID                |
+| `GITHUB_PRIVATE_KEY`    | PEM private key for app auth |
+| `GITHUB_WEBHOOK_SECRET` | Webhook signature secret     |
+
+---
+
+## Release Checklist
+
+### Before Release
+
+- [ ] All acceptance criteria met
+- [ ] Gates pass (`pnpm gates`)
+- [ ] CHANGELOG updated (if maintained)
+
+### Release Steps (Automated)
+
+Use the release command for the standard workflow:
+
+```bash
+# Preview first
+pnpm release --release-version 1.3.0 --dry-run
+
+# Execute release
+pnpm release --release-version 1.3.0
+```
+
+This handles version bump, build, tag, and npm publish automatically.
+
+### Release Steps (Manual)
+
+If you need more control:
+
+1. **Complete WU** (includes version bump commit)
+
+   ```bash
+   pnpm wu:done --id WU-XXXX
+   ```
+
+2. **Create and push tag**
+
+   ```bash
+   git tag -a v1.3.0 -m "v1.3.0 - Summary of changes"
+   git push origin v1.3.0
+   ```
+
+3. **Verify npm publish**
+
+   ```bash
+   gh run list --workflow=publish.yml --limit 1
+   # Wait for completion, then verify
+   npm view @lumenflow/cli version
+   ```
+
+4. **Create GitHub release**
+
+   ```bash
+   gh release create v1.3.0 --title "v1.3.0 - Title" --notes "Release notes..."
+   ```
+
+5. **Deploy Starlight docs** (if content changed)
+
+   ```bash
+   cd apps/docs && pnpm build && vercel --prod
+   ```
+
+### After Release
+
+- [ ] Verify npm packages accessible: `npm view @lumenflow/cli`
+- [ ] Verify docs updated: <https://lumenflow.dev>
+- [ ] Verify GitHub App functional (if changed)
+
+---
+
+## Keeping Components in Sync
+
+| Change Type      | npm           | Docs   | GitHub App   |
+| ---------------- | ------------- | ------ | ------------ |
+| Bug fix in CLI   | Tag + publish | No     | No           |
+| New CLI command  | Tag + publish | Update | No           |
+| Docs-only update | No            | Deploy | No           |
+| GitHub App fix   | No            | No     | Auto on push |
+| Full release     | Tag + publish | Deploy | Auto         |
+
+---
+
+## Troubleshooting Deployments
+
+### npm publish fails
+
+1. Check `NPM_TOKEN` secret is valid
+2. Check all `apps/*/package.json` have `"private": true`
+3. Re-run: `gh run rerun <run-id>`
+
+### 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`
+
+### GitHub App webhook failures
+
+1. Check Vercel deployment logs
+2. Verify environment variables set
+3. Check webhook secret matches GitHub App settings
+
+---
+
+## Known Warnings
+
+These warnings appear during `pnpm install` and are expected:
+
+### Cyclic workspace dependencies
+
+```
+WARN  There are cyclic workspace dependencies: @lumenflow/core, @lumenflow/memory
+```
+
+**Why:** `@lumenflow/core` has `@lumenflow/memory` as an **optional peer dependency** for advanced features, while `@lumenflow/memory` depends on `@lumenflow/core` for base utilities. This is intentional architecture.
+
+### Deprecated subdependencies
+
+```
+WARN  5 deprecated subdependencies found: glob@7.2.3, inflight@1.0.6, path-match@1.2.4, ...
+```
+
+**Why:** These come from transitive dependencies of packages like `vercel`. They cannot be fixed without upstream updates.
+
+### Ignored build scripts
+
+```
+Ignored build scripts: esbuild@..., sharp@...
+```
+
+**Why:** pnpm ignores build scripts by default for security. These packages work correctly without their postinstall scripts in our use case.

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

@@ -0,0 +1,159 @@
+# Troubleshooting: wu:done Not Run
+
+**Last updated:** {{DATE}}
+
+This is the most common mistake agents make. This document explains why it happens and how to fix it.
+
+---
+
+## The Problem
+
+Agents complete their work, write "To Complete: pnpm wu:done --id WU-XXX" in their response, and then **stop without actually running the command**.
+
+### Why This Happens
+
+1. **Confusion about scope**: Agent thinks completion is a "next step" for the human
+2. **Fear of overstepping**: Agent hesitates to take "final" actions
+3. **Missing context**: Agent doesn't realize wu:done is expected to be run immediately
+4. **Token limits**: Agent runs out of context and summarizes remaining steps
+
+---
+
+## The Fix
+
+### Rule: ALWAYS Run wu:done
+
+After gates pass, you MUST run:
+
+```bash
+cd /path/to/main
+pnpm wu:done --id WU-XXX
+```
+
+Do NOT:
+
+- Ask "Should I run wu:done?"
+- Write "To Complete: pnpm wu:done"
+- Wait for permission
+- Treat it as a "future step"
+
+---
+
+## Correct Completion Flow
+
+```bash
+# 1. In worktree, run gates
+pnpm gates
+
+# 2. If gates pass, return to main
+cd /path/to/main
+
+# 3. IMMEDIATELY run wu:done
+pnpm wu:done --id WU-XXX
+
+# 4. Report success with the wu:done output
+```
+
+---
+
+## What wu:done Does
+
+When you run `pnpm wu:done --id WU-XXX`:
+
+1. Validates the worktree exists and has commits
+2. Runs gates in the worktree (not main)
+3. Fast-forward merges to main
+4. Creates the done stamp
+5. Updates status and backlog docs
+6. Removes the worktree
+7. Pushes to origin
+
+**This is the ONLY way to complete a WU.** Manual steps will leave things in an inconsistent state.
+
+---
+
+## Exposure Auto-Fill (WU-1041)
+
+If a WU is missing `exposure`, `wu:done` auto-sets a safe default:
+
+- **Content lanes** → `documentation`
+- **Framework/Operations lanes** → `backend-only`
+
+Existing exposure values are preserved.
+
+---
+
+## Symptoms of Incomplete WU
+
+If wu:done wasn't run, you'll see:
+
+- Worktree still exists: `ls worktrees/`
+- No stamp: `ls .lumenflow/stamps/WU-XXX.done` returns nothing
+- Status unchanged: WU still shows as `in_progress`
+- Branch not merged: Changes only on lane branch
+
+---
+
+## Recovery
+
+If a previous agent forgot to run wu:done:
+
+```bash
+# 1. Check worktree exists
+ls worktrees/
+
+# 2. If it does, run wu:done
+pnpm wu:done --id WU-XXX
+
+# 3. If worktree was deleted but branch exists
+# This is a bad state - may need manual recovery
+```
+
+---
+
+## Why This Matters
+
+An incomplete WU causes problems:
+
+1. **Lane blocked**: WIP=1 means no other work can start
+2. **Work lost**: Changes might not reach main
+3. **Context lost**: Next agent doesn't know work is done
+4. **Process broken**: The whole workflow depends on wu:done
+
+---
+
+## Checklist Before Ending Session
+
+- [ ] Did I run `pnpm gates` in the worktree?
+- [ ] Did gates pass?
+- [ ] Did I `cd` back to main?
+- [ ] Did I run `pnpm wu:done --id WU-XXX`?
+- [ ] Did wu:done complete successfully?
+
+If any answer is "no", you're not done yet.
+
+---
+
+## Anti-Patterns
+
+### WRONG:
+
+```
+I've completed all the work. To finish:
+1. Run `pnpm wu:done --id WU-123`
+```
+
+### RIGHT:
+
+```bash
+# Actually run it
+cd /home/project/main
+pnpm wu:done --id WU-123
+# Output: WU-123 completed successfully
+```
+
+Then report:
+
+```
+WU-123 completed successfully. Changes merged to main, stamp created.
+```