@lumenflow/cli 4.24.0 → 5.0.1

package/templates/core/AGENTS.md.template

@@ -46,9 +46,9 @@ cd worktrees/<lane>-wu-xxxx
 # 2. Record handoff evidence (MANDATORY — wu:done blocks without this)
 pnpm wu:brief --id WU-XXXX --client <client>
 
-# 3. Pull shared memory BEFORE coding (discoveries from other agents / vendors)
-pnpm mem:context --wu WU-XXXX
-pnpm mem:inbox --since 1h
+# 3. Engage disciplines (see below)
+#    Shared memory is auto-loaded into wu:brief output above (WU-2607).
+#    For ad-hoc lookups mid-WU: pnpm mem:context --wu WU-XXXX, pnpm mem:inbox
 
 # 4. Work in worktree — capture discoveries as you go:
 #    pnpm mem:create --type discovery --wu WU-XXXX --tags <csv> --title '<single-quoted>'
@@ -65,7 +65,37 @@ pnpm wu:prep --id WU-XXXX
 cd <project-root> && pnpm wu:done --id WU-XXXX
 ```
 
-**Always single-quote** `mem:create --title` values — bash expands `$var`, `$0`, and backticks in double-quoted strings, silently corrupting prose with prices (`$49`), positional refs, or `!`. See [LUMENFLOW.md Memory section](LUMENFLOW.md#memory-shared-vs-vendor-personal).
+### Before You Code (mandatory)
+
+Step 2 above is not optional:
+
+- `wu:brief` records checkpoint evidence; `wu:done` **blocks** without it for feature/bug WUs.
+- `wu:brief` also auto-loads shared memory and coordination signals into the generated prompt (WU-1240, WU-2607) — read the `## Memory Context` section in the brief output before coding. Manual `mem:context`/`mem:inbox` calls are still available as ad-hoc lookups mid-WU.
+- Load relevant skills (`design-first`, `tdd-workflow`, `frontend-design`, `worktree-discipline`, `lumenflow-gates`) via your vendor's skill primitive. Claude Code, Codex, Cursor, and Windsurf all support `SKILL.md`-based skills (with minor invocation differences); Aider uses `CONVENTIONS.md`; Cline uses `.clinerules`. See [LUMENFLOW.md "Skills & Agents"](LUMENFLOW.md#skills--agents) for the invocation table, and your per-vendor rules file for specifics.
+
+### During the WU
+
+Capture findings in shared memory so other agents (and other vendors) can see them:
+
+```bash
+pnpm mem:create --type discovery --wu WU-XXXX --tags <csv> --priority P? --title '<prose>'
+pnpm mem:signal '<short status>' --wu WU-XXXX
+pnpm mem:checkpoint --wu WU-XXXX --note '<progress>' --next-steps '<what is next>'
+```
+
+**Classification rule:** if the fact would help _another_ agent vendor working this repo, it belongs in shared memory (`mem:create`), not your vendor's personal memory folder. Examples of shared: bug discoveries, architecture decisions, CI/gates gotchas, initiative direction, cross-WU scope flags. Examples of vendor-personal: behavioural feedback, user preferences, tool-invocation mechanics.
+
+**Shell-quoting footgun:** always **single-quote** the `--title` value. Bash expands `$var`, `$0`, backticks, and `!hist` inside double-quoted strings, silently corrupting prose containing prices (`$49`), positional refs, or exclamation marks. See [Memory section in LUMENFLOW.md](LUMENFLOW.md#memory-shared-vs-vendor-personal) for the full mem:\* contract.
+
+### Before wu:done
+
+```bash
+pnpm mem:triage --wu WU-XXXX --list
+pnpm mem:triage --promote mem-XXXX --lane '<Parent: Sublane>'   # turn a discovery into a new WU
+pnpm mem:triage --archive mem-XXXX --reason '<why>'             # drop non-actionable
+```
+
+`wu:done` does not auto-triage. Unreviewed discoveries rot — always check the list before completing.
 
 ## Quick Start (Cloud / Branch-PR)
 
@@ -129,32 +159,61 @@ For detailed troubleshooting, see [troubleshooting-wu-done.md]({{DOCS_ONBOARDING
 
 For the complete set of non-negotiable constraints (git safety, forbidden commands, skip-gates policy, and more), see [.lumenflow/constraints.md](.lumenflow/constraints.md).
 
----
+## WU Types And Automated Test Diff Policy
 
-## Safety: Forbidden Commands and Safe Alternatives
+Canonical WU types are defined by the shared CLI/core taxonomy and advertised by
+`pnpm wu:create --help`:
 
-LumenFlow enforces safety at the repository level via git wrappers and hooks. For the full list of forbidden commands and their safe `wu:` alternatives, see [.lumenflow/constraints.md](.lumenflow/constraints.md).
+- `feature` — net-new user or system capability
+- `bug` — broken or regressed behavior fix
+- `documentation` — documentation-only change
+- `process` — workflow or operating-process maintenance
+- `tooling` — tooling, automation, or developer-experience change
+- `chore` — repository upkeep or housekeeping change
+- `refactor` — behavior-preserving code restructure
 
-**Key rule:** Always use `wu:` commands for worktree and branch management -- never raw `git worktree` or `git branch -D` commands. Use `wu:recover` for state inconsistencies, `wu:release` for abandoned WUs, and `wu:prune` for stale worktrees.
+Use `feature` when the WU introduces new capability; it must carry `spec_refs`
+(or use `--plan` so `wu:create` generates the reference for you).
+
+`wu:prep` automated test diff evidence is policy-driven, not a hardcoded
+"TDD-only" rule:
+
+- `software_delivery.gates.tdd_diff_evidence.mode: block` enforces the check
+- default mode follows `software_delivery.methodology.testing`:
+  - `tdd` => `block`
+  - `test-after` => `off`
+  - `none` => `off`
+- default `applies_to_types` are `feature` and `bug`
+- default `exempt_paths` is an empty list
+
+If a covered WU is intentionally exempt and the workspace policy does not
+already exclude it, document the reason in WU notes with
+`tdd-exception: <reason>`.
 
 ---
 
-## Skills and Shared Memory
+## Safety: Forbidden Commands and Safe Alternatives
 
-LumenFlow skills live in `.lumenflow/skills/` as `SKILL.md` files and are projected to each vendor via `pnpm lumenflow:integrate --client <x>`. Claude Code, OpenAI Codex, Cursor, and Windsurf all support `SKILL.md`-based skills (with minor invocation differences); Aider uses `CONVENTIONS.md`; Cline uses `.clinerules`. See [LUMENFLOW.md "Skills & Agents"](LUMENFLOW.md#skills--agents) for the canonical list and per-vendor invocation.
+LumenFlow enforces safety at the repository level via git wrappers and hooks. For the full list of forbidden commands and their safe `wu:` alternatives, see [.lumenflow/constraints.md](.lumenflow/constraints.md).
 
-Classification rule for memory: if a fact would help *another* agent vendor working this repo, it belongs in shared memory (`mem:create`). Only vendor-specific behavioural calibrations stay in vendor-personal memory. See [LUMENFLOW.md Memory section](LUMENFLOW.md#memory-shared-vs-vendor-personal).
+**Key rule:** Always use `wu:` commands for worktree and branch management -- never raw `git worktree` or `git branch -D` commands. Use `wu:recover` for state inconsistencies, `wu:release` for abandoned WUs, and `wu:prune` for stale worktrees.
 
 ---
 
 ## Vendor-Specific Overlays
 
-This file provides universal guidance for all AI agents. Additional vendor-specific configuration:
+This file provides universal guidance for all AI agents. LumenFlow skills live in `.lumenflow/skills/` as `SKILL.md` files and are projected to each vendor via `pnpm lumenflow:integrate --client <x>`.
+
+| Vendor       | Skill / rules surface                   | Invocation                                               |
+| ------------ | --------------------------------------- | -------------------------------------------------------- |
+| Claude Code  | `.claude/skills/` + `.claude/CLAUDE.md` | `Skill` tool call, or `/skill <name>` in interactive CLI |
+| OpenAI Codex | `.codex/skills/` or repo `skills/`      | `/skills`, `$<name>` mention, or implicit                |
+| Cursor       | `.cursor/rules/` + agent skills         | `/skills` or auto-discovery                              |
+| Windsurf     | `.windsurf/rules/` + Cascade skills     | Auto-discovery; workflows via `/<workflow-name>`         |
+| Aider        | `CONVENTIONS.md`                        | `/read CONVENTIONS.md` or `aider --read CONVENTIONS.md`  |
+| Cline        | `.clinerules`                           | Auto-loaded                                              |
 
-- **Claude Code**: See `CLAUDE.md` (if present)
-- **Cursor**: See `.cursor/rules/lumenflow.md` (if present)
-- **Windsurf**: See `.windsurf/rules/lumenflow.md` (if present)
-- **Cline**: See `.clinerules` (if present)
+A skill named in prose does nothing — load it through the vendor's invocation before the work it covers. See [LUMENFLOW.md "Skills & Agents"](LUMENFLOW.md#skills--agents) for the canonical skill list.
 
 ---
 
@@ -210,7 +269,7 @@ When LumenFlow behavior changes, decide documentation impact explicitly instead
 
 ---
 
-## Disable / Uninstall
+## Disable / Uninstall (WU-2590)
 
 LumenFlow supports reversible opt-out and full uninstall:
 

package/templates/core/LUMENFLOW.md.template

@@ -75,7 +75,7 @@ Use **Initiatives** for multi-phase work spanning multiple WUs:
 
 ```bash
 # Create an initiative for multi-phase work
-pnpm initiative:create --id INIT-001 --title "Feature Name" \
+pnpm initiative:create --title "Feature Name" \
   --description "..." --phase "Phase 1: MVP" --phase "Phase 2: Polish"
 
 # Add WUs to the initiative
@@ -85,6 +85,11 @@ pnpm initiative:add-wu --initiative INIT-001 --wu WU-XXX --phase 1
 pnpm initiative:status --id INIT-001
 ```
 
+`initiative:create` now auto-generates canonical padded IDs by default (`INIT-001`, `INIT-002`, ...).
+If you supply an unpadded numeric ID such as `--id INIT-4`, it is canonicalized to `INIT-004`
+before the YAML is written. Initiative ID formatting is configurable via
+`software_delivery.initiative_id.{width,strict,prefix}` in `workspace.yaml`.
+
 **Skip initiatives whenever the work is still one coherent WU**, even if it spans several files or needs checkpoint-resume.
 
 Typical no-initiative cases:
@@ -137,9 +142,69 @@ When `requireRemote: true` (default):
 
 ---
 
+## WU Types And Automated Test Diff Policy
+
+`pnpm wu:create --help` is the authoritative help surface for supported WU
+types. The canonical taxonomy is:
+
+| WU type         | Meaning                                             |
+| --------------- | --------------------------------------------------- |
+| `feature`       | Net-new user or system capability                   |
+| `bug`           | Broken or regressed behavior fix                    |
+| `documentation` | Documentation-only change                           |
+| `process`       | Workflow or operating-process maintenance           |
+| `tooling`       | Tooling, automation, or developer-experience change |
+| `chore`         | Repository upkeep or housekeeping change            |
+| `refactor`      | Behavior-preserving code restructure                |
+
+Practical rules:
+
+- `feature` WUs must include `spec_refs`. Using `pnpm wu:create --plan` is the
+  easiest way to satisfy that requirement.
+- `documentation` and `process` WUs are the only types that can omit
+  implementation paths and manual test paths at create time when the work is
+  truly non-code.
+- Other types should describe the code they touch explicitly and choose the
+  verification surface that fits the change.
+
+`wu:prep` automated test diff evidence is also configurable now. It no longer
+assumes every repo or every bug/feature change is governed by the same TDD
+rule.
+
+Default policy resolution:
+
+- `software_delivery.methodology.testing: tdd` => `software_delivery.gates.tdd_diff_evidence.mode: block`
+- `software_delivery.methodology.testing: test-after` => `software_delivery.gates.tdd_diff_evidence.mode: off`
+- `software_delivery.methodology.testing: none` => `software_delivery.gates.tdd_diff_evidence.mode: off`
+- default `software_delivery.gates.tdd_diff_evidence.applies_to_types` =>
+  `feature`, `bug`
+- default `software_delivery.gates.tdd_diff_evidence.exempt_paths` => `[]`
+
+Example:
+
+```yaml
+software_delivery:
+  methodology:
+    testing: tdd
+  gates:
+    tdd_diff_evidence:
+      mode: block
+      applies_to_types:
+        - feature
+        - bug
+      exempt_paths:
+        - .github/workflows/**
+        - workspace.yaml
+```
+
+Use `tdd-exception: <reason>` in WU notes only when a covered WU is
+intentionally exempt and the workspace policy does not already exclude it.
+
+---
+
 ## Core Principles
 
-1. **Design-First** (feature/refactor WUs): Load the `design-first` skill before implementation. Question requirements, delete unnecessary, simplify before optimizing. Invocation varies by vendor — see [Skills & Agents](#skills--agents).
+1. **Design-First** (feature/refactor WUs): Load the `design-first` skill before implementation. Question requirements, delete unnecessary, simplify before optimizing. Invocation varies by vendor — see [Skills & Agents](#skills--agents) below.
 2. **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. Never assert inline styles, CSS values, exact copy, or DOM shape in E2E/integration tests.
 3. **Library-First**: Search existing libraries before custom code
 4. **DRY/SOLID/KISS/YAGNI**: No magic numbers, no hardcoded strings
@@ -155,38 +220,85 @@ When `requireRemote: true` (default):
 
 ## Memory: Shared vs Vendor-Personal
 
-LumenFlow ships a shared memory layer at `.lumenflow/memory/memory.jsonl` that every agent (Claude, Codex, Cursor, Windsurf, Aider) reads and writes via `mem:*` CLIs. This is distinct from any vendor's private memory folder.
+LumenFlow ships a **shared memory layer** at `.lumenflow/memory/memory.jsonl` that every agent (Claude, Codex, Cursor, Windsurf, Aider) reads and writes via the `mem:*` CLIs. This is distinct from any vendor's private memory folder.
 
 ### Classification rule
 
-**"Would a different agent vendor working this repo need to know this?"**
+Ask one question: **"Would a different agent vendor working this repo need to know this?"**
+
+| Goes in shared memory (`mem:create`)                        | Stays in vendor-personal memory                        |
+| ----------------------------------------------------------- | ------------------------------------------------------ |
+| Bug discoveries, known issues, CI/gates gotchas             | Behavioural feedback (tone, verbosity, style)          |
+| Architecture decisions, pricing truth, initiative direction | User profile (role, background, preferences)           |
+| Cross-WU scope-creep flags                                  | Vendor tool-invocation mechanics                       |
+| Infrastructure debt future agents will hit                  | Session-continuity pointers                            |
+| Project facts not derivable from code/git history           | Corrections specific to one vendor's default behaviour |
 
-| Goes in shared memory (`mem:create`) | Stays in vendor-personal memory |
-| --- | --- |
-| Bug discoveries, known issues, CI/gates gotchas | Behavioural feedback (tone, verbosity, style) |
-| Architecture decisions, pricing truth, initiative direction | User profile (role, background, preferences) |
-| Cross-WU scope-creep flags | Vendor tool-invocation mechanics |
-| Infrastructure debt future agents will hit | Session-continuity pointers |
+If a fact would help a different vendor working the same repo, it belongs in shared memory. Period.
 
-### Required cadence
+### Before you code (auto-loaded by wu:brief)
+
+`wu:brief` auto-loads the read-side of the memory contract into the generated prompt under a `## Memory Context` section (WU-1240, WU-2607). It includes WU-scoped discoveries, summaries, project profile, and coordination signals from peer agents since `wu:claim`. Read that section before writing code — skipping it means working blind to what peer agents already found.
+
+For ad-hoc lookups mid-WU (rarely needed; the brief is normally sufficient):
 
 ```bash
-# BEFORE coding (after wu:claim + wu:brief)
-pnpm mem:context --wu WU-XXXX    # discoveries, known-issues for this WU
-pnpm mem:inbox --since 1h        # parallel-agent signals
+pnpm mem:context --wu WU-XXXX    # discoveries, signals, known-issues for this WU
+pnpm mem:inbox                    # coordination signals (defaults to unread)
+```
 
-# DURING the WU — always SINGLE-QUOTE --title (bash expands $var/$0/backticks in double-quoted strings)
-pnpm mem:create --type discovery --wu WU-XXXX --tags <csv> --priority P? --title '<prose>'
-pnpm mem:signal '<status>' --wu WU-XXXX
-pnpm mem:checkpoint --wu WU-XXXX --note '<progress>'
+### Agent addressing
 
-# BEFORE wu:done (triage is NOT automatic)
-pnpm mem:triage --wu WU-XXXX --list
+The memory layer also supports live-session addressing for active agents:
+
+```bash
+pnpm mem:roster                             # list active session_id/display_name/role rows
+pnpm mem:signal 'please review' --wu WU-XXXX --to Planck
+pnpm mem:inbox --for Planck                 # targeted + broadcast signals for that session
+pnpm mem:context --wu WU-XXXX --no-roster   # opt out when a test needs stable output
 ```
 
-### Storage note
+`display_name` is an ephemeral live-session handle, not a stable role alias. It
+is assigned from `.lumenflow/agents/display-name-pool.yaml` when a session
+starts and released when the session ends. `mem:signal --to` / `mem:inbox --for`
+resolve either a `session_id` or a current `display_name` against the live
+roster before reading or writing `target_agent`.
+
+### During the WU (capture, don't hoard)
 
-`.lumenflow/memory/memory.jsonl` is gitignored by default: shared across all vendors **on the same machine/worktree**, not cross-machine. For team-wide visibility, commit the jsonl or sync via your control plane.
+When you find something out-of-scope or non-obvious:
+
+```bash
+pnpm mem:create --type discovery --wu WU-XXXX --tags <csv> --priority P? --title '<content>'
+pnpm mem:signal '<short status>' --wu WU-XXXX    # broadcast AC completion, blockers, milestones
+pnpm mem:checkpoint --wu WU-XXXX --note '<progress>' --next-steps '<what is next>'
+```
+
+**Shell-quoting warning:** `--title` takes prose through a shell arg. Always **single-quote** the title (`'...'`) — never double-quote. Bash expands `$var`, `$0`, backticks, and `!hist` inside double-quoted strings, which silently corrupts prose containing prices (`$49`), positional references, or exclamation marks. If the content must include single quotes, use `--title-file <path>` or pipe via stdin.
+
+### Before `wu:done` (triage)
+
+```bash
+pnpm mem:triage --wu WU-XXXX --list              # review discoveries captured mid-WU
+pnpm mem:triage --promote mem-XXXX --lane '<Parent: Sublane>'   # promote to a new WU
+pnpm mem:triage --archive mem-XXXX --reason '<why>'             # archive non-actionable
+```
+
+`wu:done` does **not** auto-triage. Unreviewed discoveries rot.
+
+### Storage and sync note
+
+`.lumenflow/memory/memory.jsonl` is **local by default** — gitignored in every LumenFlow repo. The distribution contract is:
+
+- Shared across **all agent vendors on the same machine / worktree** ✓
+- **Not** shared cross-machine or cross-contributor out of the box ✗
+
+Cross-machine teams can opt into commit mode (trading locality for durability) once `software_delivery.memory.distribution: commit` ships; sync-based distribution is deferred to a future ADR. Until then, treat shared memory as "all agents running this worktree see it; humans and other machines don't." The authoritative model is [ADR-009](docs/09-architecture-decisions/ADR-009-shared-memory-jsonl-distribution.md).
+
+### Tooling bugs worth knowing
+
+- `mem:delete` supports `--tag` / `--older-than` but not per-id. Local-only jsonl can be patched with care; prefer fixing via new nodes when possible.
+- `mem:create --discovered-from` may silently drop invalid provenance ids. Verify with `tail -1 .lumenflow/memory/memory.jsonl` after creation.
 
 ---
 
@@ -196,6 +308,71 @@ LumenFlow enforces safety at the repository level via git wrappers, Husky hooks,
 
 ---
 
+## Canonical WU IDs (WU-2552)
+
+Every WU has a **canonical id** derived from a configurable prefix plus a
+zero-padded integer. The defaults preserve backward compatibility for every
+existing LumenFlow repo:
+
+| Setting                          | Default | Description                                                                                                                                      |
+| :------------------------------- | :------ | :----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `software_delivery.wu_id.width`  | `4`     | Zero-padding width (1-6). `width=4` produces `WU-0001`. Overflow is preserved — `WU-10000` is still canonical.                                   |
+| `software_delivery.wu_id.strict` | `true`  | When true, `wu:create` canonicalizes `--id` input and `wu:doctor` flags legacy unpadded ids. Set to `false` for a migration ramp (warning-only). |
+| `software_delivery.wu_id.prefix` | `'WU-'` | Canonical prefix (including trailing dash). Must match `/^[A-Z][A-Z0-9]{1,9}-$/`. OSS adopters can pick `TASK-`, `STORY-`, `TICKET-`, etc.       |
+
+### Creation rules
+
+- `pnpm wu:create` (no `--id`) always emits a zero-padded id at the configured
+  width: `WU-0001`, `WU-0014`, …
+- `pnpm wu:create --id WU-14` **canonicalizes** to `WU-0014` before any file is
+  written. The normalization is silent; it is not an error.
+- Integer-level collision detection is enforced: `WU-14` and `WU-0014` cannot
+  coexist. If the same integer is already on disk under any string form,
+  `wu:create` hard-errors with a copy-pasteable `wu:rename` remediation hint.
+- When the next auto-generated id reaches 90% of `10^width` (e.g. `WU-9000` at
+  `width=4`), `wu:create` prints a non-blocking width-exhaustion warning
+  recommending a `config:set --key software_delivery.wu_id.width` bump.
+
+### Legacy drift and repair
+
+- `pnpm wu:doctor` flags any WU YAML whose id is valid but not canonical for the
+  configured width (e.g. `WU-5.yaml` with `width=4`). The offender list ships
+  with copy-pasteable `wu:rename` commands. Strict mode treats drift as exit
+  code 1 (warning); `strict=false` treats it as warning-only so legacy repos
+  can migrate incrementally.
+- `pnpm wu:rename --from WU-5 --to WU-0005` is the repair path: moves the YAML,
+  rewrites the `id:` field, moves the `.done` stamp, appends a `wu_renamed`
+  event to `wu-events.jsonl`, and regenerates `backlog.md` and `status.md`.
+- `pnpm wu:rename --from WU-5 --to WU-0005 --replay-only` is the
+  event-log-only form. Use it when the YAML and stamp have already been
+  normalized out-of-band and you only need the event history + generated
+  views to catch up. No filesystem changes, no history rewrite — the rename
+  event is simply appended and the backlog/status regenerators honor it.
+
+### Vendor-neutral prefix example
+
+```bash
+# Switch a fresh project to a TASK- prefix (one-time, before any WU is created):
+pnpm config:set --key software_delivery.wu_id.prefix --value TASK-
+pnpm wu:create --title '...' --description '...' ...
+# ↳ generates TASK-0001.yaml with id: TASK-0001
+
+# --id input is canonicalized to the configured prefix and width:
+pnpm wu:create --id TASK-14 --title '...'
+# ↳ writes TASK-0014.yaml
+```
+
+### Event sourcing discipline (append-only)
+
+`wu_renamed` events never rewrite history. Historical events before the rename
+keep their original `wuId` field — the audit trail for _who did what under the
+old id_ stays intact. The current-state view is reconstructed by the
+`wu-rename-projection` helper that collapses rename chains at replay time.
+`state:bootstrap --dry-run` honors the rename projection and will not propose
+reverting a canonical id back to the legacy form from a disk scan alone.
+
+---
+
 ## Global State
 
 Canonical global state is defined by:
@@ -353,7 +530,7 @@ For the full worktree lifecycle (parallel execution, bootstrap, isolation guaran
 | --------------------- | ---------------------------------------------------------------- |
 | `pnpm wu:preflight`   | Pre-flight checks before wu:done                                 |
 | `pnpm wu:repair`      | Repair WU state issues (claim, admin, state, duplicate-ids mode) |
-| `pnpm wu:prune`       | Clean stale worktrees                                            |
+| `pnpm wu:prune`       | Clean stale worktrees and orphan directories                     |
 | `pnpm wu:cleanup`     | Cleanup after PR merge (branch-pr mode)                          |
 | `pnpm wu:deps`        | Show WU dependencies                                             |
 | `pnpm wu:infer-lane`  | Infer lane from code paths/description                           |
@@ -362,18 +539,18 @@ For the full worktree lifecycle (parallel execution, bootstrap, isolation guaran
 
 ### Gates & Quality
 
-| Command                           | Description                                           |
-| --------------------------------- | ----------------------------------------------------- |
-| `pnpm gates`                      | Run all quality gates (`--docs-only` for docs WUs)    |
-| `pnpm gates:docs`                 | Run docs-only quality gates (alias)                   |
-| `pnpm validate`                   | Run validation checks                                 |
-| `pnpm lumenflow:pre-commit-check` | Run enforcement checks used by pre-commit and CI      |
-| `pnpm gate:co-change`             | Manage co-change gate rules (add, remove, edit, list) |
+| Command                           | Description                                                |
+| --------------------------------- | ---------------------------------------------------------- |
+| `pnpm gates`                      | Run all quality gates (`--docs-only` for docs WUs)         |
+| `pnpm gates:docs`                 | Run docs-only quality gates (alias)                        |
+| `pnpm validate`                   | Run validation checks                                      |
+| `pnpm lumenflow:pre-commit-check` | Run enforcement checks used by pre-commit and CI           |
+| `pnpm gate:co-change`             | Manage co-change gate rules (add, remove, edit, list)      |
 | `pnpm gate:conditional`           | Manage conditional_commands entries (add/remove/edit/list) |
-| `pnpm format`                     | Format all files (Prettier)                           |
-| `pnpm lint`                       | Run ESLint                                            |
-| `pnpm typecheck`                  | Run TypeScript type checking                          |
-| `pnpm test`                       | Run all tests (Vitest)                                |
+| `pnpm format`                     | Format all files (Prettier)                                |
+| `pnpm lint`                       | Run ESLint                                                 |
+| `pnpm typecheck`                  | Run TypeScript type checking                               |
+| `pnpm test`                       | Run all tests (Vitest)                                     |
 
 ### Lane Management
 
@@ -397,11 +574,12 @@ For the full worktree lifecycle (parallel execution, bootstrap, isolation guaran
 | `pnpm mem:start`      | Start a memory session                     |
 | `pnpm mem:ready`      | Check pending memory nodes                 |
 | `pnpm mem:export`     | Export memory as markdown                  |
-| `pnpm mem:signal`     | Broadcast coordination signal              |
+| `pnpm mem:signal`     | Broadcast or address coordination signals  |
 | `pnpm mem:cleanup`    | Clean up stale memory data                 |
 | `pnpm mem:context`    | Get context for current lane/WU            |
 | `pnpm mem:create`     | Create memory node (bug discovery)         |
 | `pnpm mem:inbox`      | Check coordination signals                 |
+| `pnpm mem:roster`     | List active sessions and display names     |
 | `pnpm mem:summarize`  | Summarize memory context                   |
 | `pnpm mem:triage`     | Triage discovered bugs                     |
 | `pnpm mem:delete`     | Delete/archive a memory node               |
@@ -410,16 +588,18 @@ For the full worktree lifecycle (parallel execution, bootstrap, isolation guaran
 
 ### Initiatives
 
-| Command                       | Description                               |
-| ----------------------------- | ----------------------------------------- |
-| `pnpm initiative:create`      | Create new initiative                     |
-| `pnpm initiative:edit`        | Edit initiative fields and phase metadata |
-| `pnpm initiative:list`        | List all initiatives                      |
-| `pnpm initiative:status`      | Show initiative status                    |
-| `pnpm initiative:add-wu`      | Add WU to initiative                      |
-| `pnpm initiative:remove-wu`   | Remove WU from initiative                 |
-| `pnpm initiative:plan`        | Link plan to initiative                   |
-| `pnpm initiative:bulk-assign` | Bulk assign WUs to initiative             |
+| Command                       | Description                                 |
+| ----------------------------- | ------------------------------------------- |
+| `pnpm initiative:create`      | Create new initiative                       |
+| `pnpm initiative:edit`        | Edit initiative fields and phase metadata   |
+| `pnpm initiative:list`        | List all initiatives                        |
+| `pnpm initiative:status`      | Show initiative status                      |
+| `pnpm initiative:add-wu`      | Add WU to initiative                        |
+| `pnpm initiative:remove-wu`   | Remove WU from initiative                   |
+| `pnpm initiative:rename`      | Rename initiative ID and rewrite links      |
+| `pnpm initiative:delete`      | Delete initiative with linked-WU safeguards |
+| `pnpm initiative:plan`        | Link plan to initiative                     |
+| `pnpm initiative:bulk-assign` | Bulk assign WUs to initiative               |
 
 ### Plans
 
@@ -545,32 +725,39 @@ If you're an AI agent, read the onboarding docs:
 
 ## Skills & Agents
 
-Skills are reusable knowledge bundles that agents load on demand. The `SKILL.md` format pioneered by Claude Code has converged into a de-facto standard: OpenAI Codex (Dec 2025), Cursor (v2.4+), and Windsurf Cascade (Jan 2026) all support it. LumenFlow stores vendor-neutral skill sources in `.lumenflow/skills/` and projects them to each vendor surface via `pnpm lumenflow:integrate --client <x>`.
+Skills are reusable workflow/knowledge bundles that agents load on demand. The `SKILL.md` format pioneered by Claude Code has converged into a de-facto standard adopted by OpenAI Codex (Dec 2025), Cursor (v2.4), and Windsurf Cascade (Jan 2026). LumenFlow stores vendor-neutral skill sources in `.lumenflow/skills/` and projects them to each vendor surface via `pnpm lumenflow:integrate --client <x>`.
 
-### Core skills
+### Core skills (vendor-neutral)
 
-| Skill                 | Load before...                              |
-| --------------------- | ------------------------------------------- |
-| `design-first`        | Any feature or refactor WU                  |
-| `tdd-workflow`        | Writing tests or runtime-logic code         |
-| `frontend-design`     | Any UI / component / page work              |
-| `wu-lifecycle`        | Claim / block / unblock / done decisions    |
-| `worktree-discipline` | First Read/Edit/Write in a claimed worktree |
-| `lumenflow-gates`     | When gates fail                             |
-| `bug-classification`  | Mid-WU bug discovery (P0-P3 triage)         |
+| Skill                 | Load before...                               |
+| --------------------- | -------------------------------------------- |
+| `design-first`        | Any feature or refactor WU                   |
+| `tdd-workflow`        | Writing tests or runtime-logic code          |
+| `frontend-design`     | Any UI / component / page work               |
+| `wu-lifecycle`        | Claim / block / unblock / done decisions     |
+| `worktree-discipline` | First Read/Edit/Write in a claimed worktree  |
+| `lumenflow-gates`     | When gates fail (format/lint/typecheck/test) |
+| `bug-classification`  | Mid-WU bug discovery (P0-P3 triage)          |
 
-### Vendor invocation
+### Vendor activation
 
-| Vendor        | Skill primitive                | Invocation                                              |
-| ------------- | ------------------------------ | ------------------------------------------------------- |
-| Claude Code   | Skills (native)                | `Skill` tool call, or `/skill <name>` in interactive CLI |
-| OpenAI Codex  | Skills (Dec 2025)              | `/skills` list, `$<name>` mention, or implicit          |
-| Cursor        | Agent Skills (v2.4+)           | `/skills` or auto-discovery by agent                    |
-| Windsurf      | Cascade Skills (Jan 2026)      | Auto-discovery; workflows via `/<workflow-name>`        |
-| Aider         | `CONVENTIONS.md`               | `/read CONVENTIONS.md` or `aider --read CONVENTIONS.md` |
-| Cline         | `.clinerules`                  | Auto-loaded                                             |
+A skill name written in prose does nothing — it must be **loaded** through the vendor's invocation primitive before the work it covers.
 
-A skill named in prose does nothing — load it through the vendor's invocation before the work it covers.
+| Vendor       | Skill primitive           | Invocation                                               |
+| ------------ | ------------------------- | -------------------------------------------------------- |
+| Claude Code  | Skills (native)           | `Skill` tool call, or `/skill <name>` in interactive CLI |
+| OpenAI Codex | Skills (Dec 2025)         | `/skills` list, `$<name>` mention, or implicit selection |
+| Cursor       | Agent Skills (v2.4+)      | `/skills` or auto-discovery by agent                     |
+| Windsurf     | Cascade Skills (Jan 2026) | Auto-discovery; workflows via `/<workflow-name>`         |
+| Aider        | `CONVENTIONS.md`          | `/read CONVENTIONS.md` or `aider --read CONVENTIONS.md`  |
+| Cline        | `.clinerules`             | Auto-loaded                                              |
+
+For vendor-specific setup details and per-vendor quirks, see:
+
+- Claude Code: [.claude/CLAUDE.md](.claude/CLAUDE.md)
+- Cursor: [.cursor/rules/lumenflow.md](.cursor/rules/lumenflow.md)
+- Windsurf: [.windsurf/rules/lumenflow.md](.windsurf/rules/lumenflow.md)
+- Codex / Aider / Cline: [AGENTS.md](AGENTS.md)
 
 ### Agents
 
@@ -589,6 +776,17 @@ Record explicit delegation lineage when needed: `pnpm wu:delegate --id WU-XXX --
 
 Supported clients: `claude-code`, `codex-cli`, `cursor`, `gemini-cli`, `windsurf`
 
+### Typed agent-role contract (ADR-014)
+
+Agent aliases above (`general-purpose`, `lumenflow-pm`, etc.) are human-readable handles. The canonical orchestration identity is the typed role contract defined in [ADR-014](docs/09-architecture-decisions/ADR-014-typed-agent-role-contract.md) (public mirror: [lumenflow.dev / architecture / adr-014-typed-agent-role-contract](https://lumenflow.dev/architecture/adr-014-typed-agent-role-contract/)). Future delegation, session, launch-receipt, and `mem:signal` surfaces will carry:
+
+- `lifecycle_role` — `orchestrator` | `implementer` | `reviewer` | `finisher` | `recovery`
+- `specialty_profile` — `general` | `delivery` | `docs` | `test` | `triage` | `compliance`
+- `capabilities` — opaque descriptor list (transport-level, not a substitute for role)
+- `ownership_scope` — `initiative_id`, `wu_ids`, `lane`, `responsibility_kinds`
+
+Durable artifacts carry `requested_role` (from the orchestrator) and `actual_role` (from the live worker) separately, so role mismatches surface as visible diagnostics rather than being flattened. Aliases remain supported via `role_alias`; the split fields are authoritative. See ADR-014 for the full alias-to-descriptor table and rollout order (delegation → session → memory).
+
 ---
 
 ## References
@@ -598,5 +796,6 @@ Supported clients: `claude-code`, `codex-cli`, `cursor`, `gemini-cli`, `windsurf
 - [Troubleshooting wu:done]({{DOCS_ONBOARDING_PATH}}/troubleshooting-wu-done.md) -- Most common completion mistakes
 - [.lumenflow/constraints.md](.lumenflow/constraints.md) -- Non-negotiable rules and forbidden commands
 - [WU Sizing Guide]({{DOCS_OPERATIONS_PATH}}/_frameworks/lumenflow/wu-sizing-guide.md) -- Scoping work without needless fragmentation
+- [ADR-014: Typed Agent-Role Contract](docs/09-architecture-decisions/ADR-014-typed-agent-role-contract.md) — Canonical orchestration role vocabulary
 - [Skills Index](.claude/skills/INDEX.md)
 - [Agents README](.claude/agents/README.md)