@exaudeus/workrail 3.67.0 → 3.68.0

package/docs/design/workflow-trigger-lifecycle-audit.md

@@ -0,0 +1,175 @@
+# WorkflowTrigger and Session Lifecycle Audit
+
+**Date:** 2026-04-19
+**Scope:** `WorkflowTrigger` interface field categorization; session lifecycle ownership map
+**Status:** Findings only -- no implementation plan attached
+
+---
+
+## Part 1: WorkflowTrigger Field-by-Field Analysis
+
+`WorkflowTrigger` is defined in `src/daemon/workflow-runner.ts` at line 288.
+It currently has 14 top-level fields (plus 6 nested under `agentConfig`).
+
+### Field inventory with category labels
+
+| Field | Category | Notes |
+|---|---|---|
+| `workflowId` | Trigger config | Sourced from TriggerDefinition; known before session start |
+| `goal` | Trigger config | May be dynamically interpolated from goalTemplate but is resolved before WorkflowTrigger is constructed |
+| `workspacePath` | Trigger config | Doubles as the session working directory; passed to tool factories |
+| `context` | Trigger config | Workflow context variables from contextMapping |
+| `referenceUrls` | Trigger config | Pass-through from TriggerDefinition so workflow-runner stays decoupled |
+| `soulFile` | Trigger config | Resolved path, cascade from trigger -> workspace -> global |
+| `branchStrategy` | Trigger config | 'worktree' or 'none'; sourced from TriggerDefinition |
+| `baseBranch` | Trigger config | Only meaningful when branchStrategy === 'worktree' |
+| `branchPrefix` | Trigger config | Only meaningful when branchStrategy === 'worktree' |
+| `botIdentity` | Trigger config / Delivery config | Set by polling-scheduler at trigger time; read by delivery-action.ts at commit time |
+| `agentConfig.model` | Trigger config | Per-trigger model override |
+| `agentConfig.maxSessionMinutes` | Trigger config | Session execution policy |
+| `agentConfig.maxTurns` | Trigger config | Session execution policy |
+| `agentConfig.maxSubagentDepth` | Trigger config | Session execution policy |
+| `agentConfig.stuckAbortPolicy` | Session execution policy | Controls runtime behavior inside the agent loop |
+| `agentConfig.noProgressAbortEnabled` | Session execution policy | Controls runtime behavior inside the agent loop |
+| `_preAllocatedStartResponse` | Session runtime state | Set by dispatch HTTP handler or spawnSession; skips duplicate executeStartWorkflow() |
+| `parentSessionId` | Session runtime state | Set by makeSpawnAgentTool; documented as 'not read by runWorkflow() directly' |
+| `spawnDepth` | Session runtime state | Set by parent factory at child construction time; enforces maxSubagentDepth |
+
+### Category summary
+
+- **Trigger config (10 fields):** Known before session start, sourced from TriggerDefinition or resolved at dispatch time. These are the "input parameters" the operator writes in triggers.yml.
+- **Session execution policy (2 fields in agentConfig):** Technically sourced from TriggerDefinition but they control runtime behavior inside the agent loop, not the trigger firing condition.
+- **Session runtime state (3 fields):** Set during or after session creation. `_preAllocatedStartResponse` and `parentSessionId` carry infrastructure handshake data; `spawnDepth` carries tree-position state from the parent session factory.
+
+### The mixing problem
+
+Three categories of fields live in one flat struct with no structural boundary. The consequences:
+
+1. **`_preAllocatedStartResponse` is an internal handshake field on a public-facing type.** The underscore prefix is the only signal. `trigger-listener.ts:467` constructs `WorkflowTrigger` with this field from outside the infrastructure layer, proving the underscore convention does not act as an access barrier.
+
+2. **`parentSessionId` is documented as "not read by runWorkflow() directly"** (workflow-runner.ts line 382). It exists for documentation and potential future use. A field that is not read by the function it is passed to is a dead field on the input type.
+
+3. **`botIdentity` is double-threaded.** It appears on `WorkflowTrigger` (input) and is explicitly re-surfaced on `WorkflowRunSuccess` (output, lines 506-521) so `trigger-router.ts maybeRunDelivery()` can pass it to `delivery-action.ts`. The threading comment says "follows the sessionId/sessionWorkspacePath threading pattern" -- meaning this pattern is now established and will repeat for any future delivery-config field added to the trigger.
+
+4. **`branchStrategy`, `baseBranch`, and `branchPrefix` are pass-through forwarding fields** that exist solely because `workflow-runner.ts` must remain decoupled from `TriggerDefinition`. This is the right goal, but the mechanism (copy each field individually onto the flat struct) does not scale as the worktree feature grows.
+
+### Proposed decomposition sketch
+
+A future refactor could split the interface into three composed types:
+
+```typescript
+// Fields the trigger operator configures in triggers.yml
+interface TriggerConfig {
+  readonly workflowId: string;
+  readonly goal: string;
+  readonly workspacePath: string;
+  readonly context?: Readonly<Record<string, unknown>>;
+  readonly referenceUrls?: readonly string[];
+  readonly soulFile?: string;
+  readonly agentConfig?: AgentConfig;
+  readonly worktreeConfig?: WorktreeConfig; // branchStrategy, baseBranch, branchPrefix
+}
+
+// Fields set by delivery systems; read at git-commit time
+interface DeliveryConfig {
+  readonly botIdentity?: { readonly name: string; readonly email: string };
+}
+
+// Fields set by session infrastructure at creation time
+interface SessionContext {
+  readonly _preAllocatedStartResponse?: ...; // or move to a separate creation parameter
+  readonly parentSessionId?: string;
+  readonly spawnDepth?: number;
+}
+
+// WorkflowTrigger becomes a composition
+type WorkflowTrigger = TriggerConfig & DeliveryConfig & SessionContext;
+```
+
+The immediate safe win -- without a full refactor -- would be to pull `_preAllocatedStartResponse`, `parentSessionId`, and `spawnDepth` into a separate `SessionContext` parameter to `runWorkflow()` rather than embedding them in the trigger input. This makes the contract explicit: `runWorkflow(config: TriggerConfig, ctx: V2ToolContext, sessionCtx?: SessionContext, ...)`.
+
+---
+
+## Part 2: Session Lifecycle Ownership Map
+
+### Who does what
+
+| Responsibility | Owner | Location |
+|---|---|---|
+| Session sidecar creation (initial) | `runWorkflow()` | `workflow-runner.ts:3279` -- `persistTokens(sessionId, token, checkpoint)` |
+| Session sidecar update (add worktreePath) | `runWorkflow()` | `workflow-runner.ts:3333` -- second `persistTokens()` call after worktree creation |
+| Session sidecar deletion (normal end) | `runWorkflow()` | `workflow-runner.ts:3376` -- `fs.unlink(DAEMON_SESSIONS_DIR/sessionId.json)` |
+| Worktree creation | `runWorkflow()` | `workflow-runner.ts:3299-3354` -- `git worktree add` |
+| Worktree removal (normal path, after delivery) | `trigger-router.ts maybeRunDelivery()` | `trigger-router.ts:382-394` -- `git worktree remove --force` |
+| Orphan sidecar cleanup (restart recovery) | `runStartupRecovery()` | `workflow-runner.ts:917-928` -- `fs.unlink` per orphaned sidecar |
+| Orphan worktree cleanup (restart recovery, after 24h) | `runStartupRecovery()` | `workflow-runner.ts:893-915` -- `git worktree remove --force` |
+| Session spawn for adaptive pipeline | `coordinatorDeps.spawnSession` | `trigger-listener.ts:411-476` -- `executeStartWorkflow` + `router.dispatch()` |
+| In-process liveness registration | `runWorkflow()` | `workflow-runner.ts:3258` -- `daemonRegistry.register()` |
+| In-process liveness heartbeat | `runWorkflow()` -- `onAdvance` callback | `workflow-runner.ts:3162` -- `daemonRegistry.heartbeat()` |
+| In-process liveness deregistration | `runWorkflow()` | Multiple early-exit paths and normal completion |
+
+### Who is responsible for worktree creation/cleanup?
+
+Worktree creation is owned by `runWorkflow()`. Worktree cleanup is **split**:
+
+- **Normal path:** `trigger-router.ts maybeRunDelivery()` removes the worktree after delivery completes (success or error). The comment explains why it cannot be in `runWorkflow()`: delivery must run inside the worktree, so `runWorkflow()` must not remove it before returning.
+- **Crash/orphan path:** `runStartupRecovery()` in `workflow-runner.ts` removes worktrees older than 24 hours.
+
+This split is architecturally deliberate (the worktree comment at trigger-router.ts:370-381 explains the constraint) but it means no single location owns the full worktree lifecycle. The constraint that forces the split is real: delivery happens outside `runWorkflow()`. The design pressure to resolve it would be to either push delivery into `runWorkflow()`, or introduce a `SessionOwner` abstraction that holds the worktree handle and is responsible for cleanup regardless of which path ends the session.
+
+### Is DaemonRegistry the authoritative source of truth for "what's running"?
+
+No. `DaemonRegistry` is explicitly documented as "ephemeral in-process liveness tracking -- cleared on process restart -- this is intentional" (`src/v2/infra/in-memory/daemon-registry/index.ts:8`). It answers the question "is this session being heartbeated by the currently running process?" It cannot answer:
+
+- Was this session running before the process restarted?
+- Is this sidecar file for a live or crashed session?
+- Did delivery complete before the process died?
+
+Session sidecar files (`DAEMON_SESSIONS_DIR/*.json`) are the only durable record. `runStartupRecovery()` reads them directly (not through DaemonRegistry) because the registry is empty after a restart.
+
+The result is two mechanisms answering the same question, with no overlap and no single API surface that gives a correct answer in all states:
+
+| State | DaemonRegistry | Sidecar file |
+|---|---|---|
+| Session running, same process | Present, heartbeating | Present |
+| Session completed normally | Absent (unregistered) | Absent (deleted) |
+| Process crashed mid-session | Absent (process died) | Present (not cleaned up) |
+| After restart, before recovery | Absent | Present (orphan) |
+
+### Gaps and ambiguities
+
+**Gap 1: No single owner for the session liveness question.**
+There is no function, class, or module that can correctly answer "is session X currently running?" across all process states. `DaemonRegistry` answers it for the in-process case; sidecar files answer it for the post-crash case; but there is no unified interface. `ConsoleService` has to handle both separately.
+
+**Gap 2: Worktree cleanup has two owners with different trigger conditions.**
+The 24-hour threshold in `runStartupRecovery()` and the post-delivery immediate cleanup in `maybeRunDelivery()` are not coordinated. If a session's sidecar is orphaned but its worktree is less than 24 hours old, `runStartupRecovery()` will delete the sidecar but leave the worktree. The worktree becomes a resource leak that is only cleaned on the next startup after 24 hours have elapsed.
+
+Confirmed path to this state:
+1. `runWorkflow()` creates worktree and sidecar.
+2. Session completes, `runWorkflow()` deletes the sidecar.
+3. `maybeRunDelivery()` tries to remove the worktree but fails (disk full, git lock, etc.) -- error is logged and swallowed.
+4. Worktree is now orphaned with no sidecar pointing to it. `runStartupRecovery()` can never find it because it searches sidecars, not the worktrees directory.
+
+This is a real orphan leak path that the current recovery mechanism cannot reach.
+
+**Gap 3: `_preAllocatedStartResponse` leaks infrastructure state into the public trigger type.**
+`spawnSession` in `trigger-listener.ts` constructs `WorkflowTrigger` directly with this field. Any future caller that constructs `WorkflowTrigger` without understanding the `_preAllocatedStartResponse` invariant can accidentally call `executeStartWorkflow()` twice for the same session (the MUST NOT invariant documented at line 356).
+
+**Gap 4: `parentSessionId` is a documented dead field.**
+The comments on lines 379-383 say "This field is not read by runWorkflow() directly" and "exists for documentation purposes and potential future use." A field on an input type that is not read by the function it is passed to is not providing value and creates confusion about which fields are operative.
+
+**Gap 5: `spawnDepth` has no compile-time enforcement.**
+`spawnDepth` is an optional numeric field. Callers that construct `WorkflowTrigger` (e.g. `spawnSession` in `trigger-listener.ts:467`) must correctly set `spawnDepth` or the `maxSubagentDepth` enforcement in `runWorkflow()` will silently default to depth 0 for all sessions, allowing unlimited recursion depth regardless of the configured limit.
+
+---
+
+## Summary of findings
+
+| Finding | Severity | Concrete risk |
+|---|---|---|
+| WorkflowTrigger mixes three concern categories in one flat struct | Medium | Type leaks, confusion about which fields are operative, MUST NOT invariant on `_preAllocatedStartResponse` easily violated |
+| Worktree cleanup has two owners; the sidecar-less orphan case is unreachable by recovery | Medium | Disk space leak when delivery cleanup fails; orphaned worktrees accumulate indefinitely |
+| DaemonRegistry is not authoritative; two mechanisms answer "is session alive?" | Low-Medium | No concrete bug today, but any code that reads DaemonRegistry as a complete truth (e.g. a future health check) will be wrong after a crash |
+| `_preAllocatedStartResponse` is an internal field on a public type, constructed by the composition root | Medium | Double-session-creation risk if the invariant is violated by a new caller |
+| `parentSessionId` is a dead field on the input type | Low | Confusion only; no operational risk |
+| `spawnDepth` has no compile-time enforcement at construction sites | Low-Medium | Silent depth=0 default for coordinator-spawned sessions if the field is omitted |

package/docs/design/worktrain-task-queue-candidates.md

@@ -78,9 +78,9 @@ Nearby contracts that must stay consistent:
 
 **Routing table (exhaustive):**
 ```
-maturity=idea | rough    =>  wr.discovery -> wr.shaping -> coding-task-workflow-agentic
-maturity=specced         =>  wr.discovery -> coding-task-workflow-agentic
-maturity=ready           =>  coding-task-workflow-agentic (Phase 0.5 searches for upstream spec at runtime)
+maturity=idea | rough    =>  wr.discovery -> wr.shaping -> wr.coding-task
+maturity=specced         =>  wr.discovery -> wr.coding-task
+maturity=ready           =>  wr.coding-task (Phase 0.5 searches for upstream spec at runtime)
 ```
 
 Type refines within the coding workflow (bug => skip hypothesis, chore => skip design phases) but does not change pipeline selection.
@@ -121,7 +121,7 @@ upstream_spec: https://docs.example.com/pitch-feature-x
 affected_files: src/foo.ts src/bar.ts
 ```
 
-**Routing mechanism:** Identical to A -- coordinator uses labels only. Body section is not read at routing time. Downstream workflows (coding-task-workflow-agentic Phase 0.5, wr.shaping) call GitHub API to fetch body and parse the `## WorkTrain` section when they need enrichment.
+**Routing mechanism:** Identical to A -- coordinator uses labels only. Body section is not read at routing time. Downstream workflows (wr.coding-task Phase 0.5, wr.shaping) call GitHub API to fetch body and parse the `## WorkTrain` section when they need enrichment.
 
 **Tensions resolved:** T1, T2, T3 (two-layer schema: labels for routing, body for enrichment), T4
 **Tensions accepted:** None materially -- the body section is optional and gracefully absent
@@ -192,7 +192,7 @@ affected_files:
 **Summary:** Instead of a coordinator that routes, create three triggers with different `labelFilter` values -- one per pipeline path. Routing is implicit in which trigger fires.
 
 **Proposed triggers:**
-- `worktrain-coding` trigger: labelFilter=`worktrain:maturity:ready` => `coding-task-workflow-agentic`
+- `worktrain-coding` trigger: labelFilter=`worktrain:maturity:ready` => `wr.coding-task`
 - `worktrain-discovery` trigger: labelFilter=`worktrain:maturity:specced` => `wr.discovery`
 - `worktrain-full` trigger: labelFilter=`worktrain:maturity:idea` => `wr.discovery` (with full-pipeline flag)
 

package/docs/design/worktrain-task-queue.md

@@ -54,7 +54,7 @@ The Three-Workflow Pipeline and taskMaturity spectrum are already partially defi
 **Routing signals defined in backlog (not yet implemented):**
 - `taskMaturity`: idea / rough / specced / ready / code-complete (backlog Apr 15)
 - `existingArtifacts`: brd / designs / arch-decision / acceptance-criteria / ticket / implementation
-- Three-Workflow Pipeline: `wr.discovery` (optional) -> `wr.shaping` (optional) -> `coding-task-workflow-agentic` (Apr 18)
+- Three-Workflow Pipeline: `wr.discovery` (optional) -> `wr.shaping` (optional) -> `wr.coding-task` (Apr 18)
 
 **TriggerDefinition routing fields:** `workflowId` is static per trigger. To dispatch different workflows from the same trigger, the routing must happen either in a coordinator script (reads issue, decides workflowId) or via multiple triggers with different `labelFilter` values.
 
@@ -395,9 +395,9 @@ The `## WorkTrain` section header is frozen after v1. `upstream_spec` must be a
 
 | Maturity label | Pipeline |
 |----------------|----------|
-| `worktrain:idea` | `wr.discovery` -> `wr.shaping` -> `coding-task-workflow-agentic` |
-| `worktrain:specced` | `wr.shaping` -> `coding-task-workflow-agentic` |
-| `worktrain:ready` | `coding-task-workflow-agentic` (Phase 0.5 searches for upstream spec at runtime) |
+| `worktrain:idea` | `wr.discovery` -> `wr.shaping` -> `wr.coding-task` |
+| `worktrain:specced` | `wr.shaping` -> `wr.coding-task` |
+| `worktrain:ready` | `wr.coding-task` (Phase 0.5 searches for upstream spec at runtime) |
 | (no maturity label) | Add `worktrain:needs-labels`, skip dispatch, emit structured log entry |
 
 **Multi-label conflict rule:** if multiple maturity labels are present (e.g. both `worktrain:idea` and `worktrain:ready`), the lowest maturity wins (idea > specced > ready). Coordinator logs a warning.

package/docs/discovery/coordinator-script-design.md

@@ -159,4 +159,4 @@ The scope is correct: 3 new files, clear boundaries, no speculative abstractions
 
 3. Should the coordinator write a full report file (`coordinator-pr-review-YYYY-MM-DD.md`)? Yes, per UX spec. This is a simple file write via CoordinatorDeps.
 
-4. Is `coding-task-workflow-agentic` the correct fix-agent workflow? Yes -- it handles "implement/fix" tasks. The goal string `Fix review findings in PR #N: [finding summaries]` is the goal format.
+4. Is `wr.coding-task` the correct fix-agent workflow? Yes -- it handles "implement/fix" tasks. The goal string `Fix review findings in PR #N: [finding summaries]` is the goal format.

package/docs/discovery/coordinator-ux-discovery.md

@@ -59,7 +59,7 @@ Rationale: The goal was a solution-statement. The risk is designing the wrong in
 **What spawn/await enable today:**
 `worktrain spawn` prints a session handle to stdout. `worktrain await` blocks until sessions complete and prints structured JSON results. These two commands are the building blocks for a coordinator script.
 
-**The MR review workflow (mr-review-workflow-agentic):**
+**The MR review workflow (wr.mr-review):**
 - 8+ phases: locate/bound/classify, hypothesis, freeze fact packet, reviewer family bundle (parallel), contradiction resolution, adversarial validation, final recommendation, handoff
 - Produces: severity-graded findings (Critical/Major/Minor/Nit), recommendation (approve/request changes/needs discussion), confidence band, coverage ledger, ready-to-post MR comments
 - Output lives in `notesMarkdown` and context variables -- no automatic post to GitHub
@@ -154,7 +154,7 @@ Not every PR review ends cleanly. The coordinator must surface decision points w
 ```
 $ worktrain review 47
 Reviewing PR #47: "feat(engine): add OAuth refresh token rotation"
-Session started: sess_4cd0b579 (mr-review-workflow-agentic)
+Session started: sess_4cd0b579 (wr.mr-review)
 Run 'worktrain logs --follow --session sess_4cd0b579' to watch progress.
 Run 'worktrain inbox' when done.
 ^  Takes ~20-30 min. You can do other things.
@@ -411,7 +411,7 @@ worktrain run pr-review 47
 ```
 PR #47: feat(engine): add OAuth refresh token rotation  (3 files, +142/-18)
 Base: main  merge-base: abc1234
-Session: sess_4cd0b579  (mr-review-workflow-agentic)
+Session: sess_4cd0b579  (wr.mr-review)
 
 Watch raw events: worktrain logs --follow --session sess_4cd0b579
 

package/docs/discovery/simulation-report.md

@@ -51,7 +51,7 @@ Pass 3: passCount=2 -> review: 'minor' -> passCount becomes 3 -> CHECK: 3 >= 3 -
 **Trace:**
 ```
 discoverPort() -> no lock files -> falls back to 3456
-spawnSession('mr-review-workflow-agentic', 'Review PR #419...', '/workspace')
+spawnSession('wr.mr-review', 'Review PR #419...', '/workspace')
   POST http://127.0.0.1:3456/api/v2/auto/dispatch
   -> fetch throws Error: ECONNREFUSED 127.0.0.1:3456
   -> spawnSession catches -> returns err('Could not connect to WorkTrain daemon on port 3456')

package/docs/discovery/workflow-modernization-discovery.md

@@ -0,0 +1,326 @@
+# Discovery: Workflow Modernization Backlog Audit
+
+*Session artifact -- human-readable summary. Durable truth lives in session notes and context.*
+
+**Artifact strategy:** This document is for human readers only. It does not need to be complete or current for the session to function correctly. If a chat rewind occurs, the session's `notesMarkdown` and context variables are the authoritative record -- this file may be stale or absent. Do not treat this doc as a checkpoint or source of truth for workflow execution.
+
+**Capability summary:**
+- Web browsing: AVAILABLE (curl probe confirmed reachable) -- but NOT needed; all required information is local
+- Delegation (spawn_agent): AVAILABLE (tool present in session, spawn depth < 3) -- deferred to candidate-generation phase where parallel cognitive lenses add value; not useful for local file reading
+- GitHub CLI: AVAILABLE (`gh` confirmed working)
+- Local session store: AVAILABLE and queried (`~/.workrail/data/sessions` yielded real usage counts)
+
+---
+
+## Context / Ask
+
+**Stated goal (original):** Modernize `workflows/exploration-workflow.json` to current v2/lean authoring patterns. This is the highest-priority candidate among the unmodernized workflows.
+
+**Statedgoal classification:** `solution_statement` -- names a specific file and solution, not an outcome.
+
+**Reframed problem:** Some bundled workflows still in use provide lower-quality agent guidance than the current authoring standard allows, and the planning documents tracking this work reference files that no longer exist -- making it impossible to execute the stated backlog without first auditing what actually exists and what is worth keeping.
+
+---
+
+## Critical Finding: Planning Docs Are Stale
+
+**`exploration-workflow.json` does not exist.** It was:
+1. Modernized in PR #158 (March 27, 2026, commit `edbc3161`)
+2. Deleted and consolidated into `workflows/wr.discovery.json` (commit `a582e1a1`)
+
+All 10 filenames in the primary modernization list are missing from the repo. The planning documents (`now-next-later.md`, `open-work-inventory.md`, `tickets/next-up.md`) all reference stale filenames.
+
+**The stated backlog cannot be executed as written.** A real audit of existing files against actual usage is the prerequisite.
+
+---
+
+## Path Recommendation
+
+**Path: `landscape_first`**
+
+The dominant need is understanding the current state -- what workflows exist, which are actively used, what modernization gaps each actually has. The goal was stated as a solution (file + technique), but the underlying problem is best served by first establishing a correct, usage-ranked picture of the real modernization backlog.
+
+**Why not `design_first`?** The modernization technique itself is not in question -- the authoring guide is clear, the spec is versioned, the target state is known. The risk is not solving the wrong problem; it is executing against a stale and incorrect task list.
+
+**Why not `full_spectrum`?** This is not an ambiguous problem requiring deep reframing. It is an operational audit problem: match current reality to the planning system, then execute in priority order.
+
+---
+
+## Constraints / Anti-goals
+
+**Constraints:**
+- Do not modify protected files (`src/daemon/`, `src/trigger/`, `src/v2/`, `triggers.yml`)
+- All changes must pass `npx vitest run`
+- Never modernize in a way that breaks existing session behavior (no step ID renames on active workflows)
+
+**Anti-goals:**
+- Do not mechanically rename files to `.v2` or `.lean` -- that is cargo-cult modernization
+- Do not add `metaGuidance` fields just to clear a checklist item if the content is empty or generic
+- Do not modernize workflows that are effectively retired (near-zero usage and no unique value)
+- Do not update planning docs to be accurate only to immediately make them stale again -- the audit output should drive concrete, executable ticket updates
+
+---
+
+## Landscape Packet
+
+### Usage-ranked workflow inventory (actual, as of this session)
+
+| Usage | Workflow ID | File | Spec Stamp | Gaps |
+|------:|-------------|------|-----------|------|
+| 910 | wr.coding-task | coding-task-workflow-agentic.json | unstamped | features, stamp |
+| 606 | wr.mr-review | mr-review-workflow.agentic.v2.json | unstamped | stamp only |
+| 461 | wr.discovery | wr.discovery.json | v3 (current) | MODERN |
+| 125 | wr.production-readiness-audit | production-readiness-audit.json | unstamped | stamp only |
+| 74 | wr.bug-investigation | bug-investigation.agentic.v2.json | unstamped | features, stamp |
+| 64 | wr.architecture-scalability-audit | architecture-scalability-audit.json | unstamped | stamp only |
+| 51 | wr.ui-ux-design | ui-ux-design-workflow.json | v3 (current) | MODERN |
+| 39 | wr.diagnose-environment | workflow-diagnose-environment.json | unstamped | meta, recs, features, stamp |
+| 39 | wr.shaping | wr.shaping.json | unstamped | features, stamp |
+| 33 | wr.workflow-for-workflows | workflow-for-workflows.json | v3 (current) | MODERN |
+| 7 | wr.documentation-update | documentation-update-workflow.json | unstamped | recs, features, stamp |
+| 5 | wr.document-creation | document-creation-workflow.json | unstamped | recs, features, stamp |
+| 4 | wr.scoped-documentation | scoped-documentation-workflow.json | unstamped | recs, features, stamp |
+| 4 | wr.cross-platform-code-conversion | cross-platform-code-conversion.v2.json | unstamped | features, stamp |
+| 3 | wr.adaptive-ticket-creation | adaptive-ticket-creation.json | unstamped | recs, features, stamp |
+| 2 | wr.relocation-us | relocation-workflow-us.json | unstamped | features, stamp |
+| 0 | wr.intelligent-test-case-generation | intelligent-test-case-generation.json | unstamped | recs, features, stamp |
+| 0 | wr.personal-learning-course-design | learner-centered-course-workflow.json | unstamped | recs, features, stamp |
+| 0 | wr.personal-learning-materials | personal-learning-materials-creation-branched.json | unstamped | recs, features, stamp |
+| 0 | wr.presentation-creation | presentation-creation.json | unstamped | recs, features, stamp |
+| 0 | wr.classify-task | classify-task-workflow.json | v3 (current) | MODERN (but 0 usage) |
+
+### Modernization depth classification
+
+| Level | Description | Count | Workflows |
+|-------|-------------|-------|-----------|
+| L0 | MODERN -- no action needed | 4 | wr.discovery, wr.ui-ux-design, wr.workflow-for-workflows, wr.classify-task |
+| L1 | Stamp only | 2 | wr.production-readiness-audit, wr.architecture-scalability-audit |
+| L2 | Stamp + features declaration | 0 | (none -- all that need features also need raw->promptBlocks migration) |
+| L3 | Raw prompt -> promptBlocks migration + features | 6 | wr.coding-task(910), wr.mr-review(606), wr.bug-investigation(74), wr.shaping(39), wr.cross-platform-code-conversion(4), wr.relocation-us(2) |
+| L4 | Missing basics (no recs, raw prompts, no features) | 9 | wr.documentation-update(7), wr.document-creation(5), wr.scoped-documentation(4), wr.adaptive-ticket-creation(3), wr.intelligent-test-case-generation(0), wr.personal-learning-course-design(0), wr.personal-learning-materials(0), wr.presentation-creation(0), wr.diagnose-environment(39) |
+
+### Critical architectural finding: features only work with promptBlocks
+
+**Features injection (`wr.features.capabilities`, `wr.features.subagent_guidance`) only applies to steps using `promptBlocks`.** Raw `prompt` field steps are explicitly skipped by the compiler (`src/application/services/compiler/resolve-features.ts`, line 62: `if (!step.promptBlocks || features.length === 0) return step;`).
+
+This means:
+- `wr.coding-task` (910 uses, ALL 9 steps are raw prompt) -- declaring `features` in the header has **zero runtime effect** until steps are migrated to `promptBlocks`
+- `wr.bug-investigation` (74 uses, ALL 8 steps are raw prompt) -- same
+- `wr.shaping` (39 uses, ALL 8 steps are raw prompt) -- same
+- `wr.mr-review` (606 uses, 3 of 6 steps are raw prompt) -- features only inject into the 3 promptBlocks steps
+
+**Raw prompt → promptBlocks migration is a prerequisite for features to matter.** This is a deeper migration than just adding a features declaration.
+
+### Modern workflows (no modernization needed)
+- `wr.discovery` (v3.2.0, stamped, full features, all promptBlocks)
+- `wr.ui-ux-design` (v3 stamped, features declared, all promptBlocks)
+- `wr.workflow-for-workflows` (v3 stamped, references, features, all promptBlocks)
+- `wr.classify-task` (v3 stamped -- but 0 usage, may need visibility review)
+
+### Contradictions in prior understanding
+
+**[C1] HIGH -- Planning docs name 10 files, all missing**
+All 10 filenames in the primary modernization list (`now-next-later.md`, `open-work-inventory.md`, `tickets/next-up.md`) do not exist on disk. They were renamed, merged, or deleted in March 2026 during a workflow consolidation sprint.
+
+**[C2] HIGH -- Adding `wr.features` to `wr.coding-task` would have zero runtime effect**
+`wr.coding-task` has 9 raw `prompt` steps and 0 `promptBlocks` steps. The compiler explicitly skips feature injection for raw prompt steps. The "missing features" gap reported for this workflow is not a simple header field addition -- it requires a full step structure migration first.
+
+**[C3] MEDIUM -- `wr.mr-review` has a deeper gap than "stamp only"**
+Earlier assessment said stamp was the only gap. Actually, 3 of 6 steps use raw prompt and would not receive feature injections. The stamp gap is real, but the structural gap is also real.
+
+**[C4] MEDIUM -- `wr.coding-task` already has substantive delegation/parallelism guidance in metaGuidance**
+`wr.coding-task` has 11 `metaGuidance` items including explicit ownership, delegation, and parallelism rules. The `wr.features.subagent_guidance` would inject similar content via promptBlocks, potentially duplicating what already exists in metaGuidance prose. This needs de-duplication thinking, not blind injection.
+
+### Evidence gaps
+
+- Usage telemetry uses all-time counts including old deleted workflow IDs (`exploration-workflow: 19`, `design-thinking-workflow: 42`). Recent counts would be more actionable.
+- No before/after session quality comparison for any modernization -- whether promptBlocks migration produces measurably better sessions is assumed but unvalidated.
+- Unknown: why `wr.coding-task` and `wr.bug-investigation` use raw prompts (intentional choice? legacy carryover? waiting for migration tooling?).
+- Unknown: whether any zero-usage workflows are referenced in external team configs that would make them important to keep despite 0 local sessions.
+
+### What "unstamped" actually means
+17 of 21 workflows lack `validatedAgainstSpecVersion`. This is advisory-only (no CI failure), but signals they haven't been reviewed against spec v3. The `stamp-workflow` script resolves this after running `workflow-for-workflows` on them.
+
+### Key gap: `wr.features` adoption
+Most workflows do not declare `wr.features.capabilities` or `wr.features.subagent_guidance`. These inject concrete constraints and procedure items into every step at compile time -- they are not cosmetic. High-usage workflows missing them: `wr.coding-task` (910 uses), `wr.bug-investigation` (74), `wr.shaping` (39).
+
+### What the planning docs say vs. reality
+The planning docs reference all of:
+- `exploration-workflow.json` -- DELETED, replaced by wr.discovery
+- `wr.adaptive-ticket-creation.json` -- exists but as `adaptive-ticket-creation.json`
+- `mr-review-workflow.json` -- DELETED, v2 is `mr-review-workflow.agentic.v2.json`
+- `mr-review-workflow.agentic.json` -- DELETED
+- `bug-investigation.json` -- DELETED, v2 is `bug-investigation.agentic.v2.json`
+- `bug-investigation.agentic.json` -- DELETED
+- `design-thinking-workflow.json` -- DELETED, merged into wr.discovery
+- `design-thinking-workflow-autonomous.agentic.json` -- DELETED
+- `wr.documentation-update.json` -- exists as `documentation-update-workflow.json`
+- `wr.document-creation.json` -- exists as `document-creation-workflow.json`
+
+---
+
+## Problem Frame Packet
+
+### Users / Stakeholders
+
+1. **Daemon sessions as consumers** (primary): autonomous agents running inside `wr.coding-task`, `wr.mr-review`, `wr.bug-investigation` etc. receive the workflow step prompts. These are the actual beneficiaries of better guidance -- 910 runs of wr.coding-task alone.
+2. **Workflow authors** (secondary): developers writing and maintaining workflow JSON. They need planning docs that reflect reality, and a modernization approach that doesn't require heroic manual effort.
+3. **Project owner** (decision authority): decides what merges, what gets prioritized, and what gets retired. Needs a clear prioritized plan, not an open-ended backlog.
+
+### Jobs, Goals, Outcomes
+
+- Agents should receive step prompts that reinforce behavioral constraints (durability, delegation, synthesis ownership) without relying on the agent to have read and retained `metaGuidance` at inspection time.
+- Workflow authors should be able to trust that planning docs reflect actual file paths and current priorities.
+- The CI staleness advisory should shrink -- it currently fires for 17/21 workflows, creating noise.
+
+### Pains / Tensions
+
+- **Pain 1 (high):** `metaGuidance` is inspection-time-only -- it shows when an agent calls `inspect_workflow` but does NOT inject into per-step prompts. For high-usage workflows like `wr.coding-task`, behavioral constraints only appear at inspection time, not at each step where they are most needed. Feature injection via `promptBlocks` is the per-step mechanism, but it requires step migration first.
+- **Pain 2 (high):** Planning docs are stale -- all 10 filenames in the primary modernization list don't exist. Backlog cannot be executed as written.
+- **Pain 3 (medium):** The modernization approach (add features field) has zero runtime effect on workflows still using raw `prompt` steps. The real fix (raw→promptBlocks migration) is 10x the effort of adding a header field.
+- **Tension 1:** Modernizing `wr.coding-task` (910 uses, 14 steps, all raw prompt) is the highest-impact action, but also the riskiest -- changing the step structure of a heavily used workflow could break in-flight sessions or degrade guidance quality if done carelessly.
+- **Tension 2:** Stamp-only passes are fast and reduce advisory noise, but they falsely signal "reviewed against spec v3" when the content has not actually changed.
+
+### Constraints That Matter in Lived Use
+
+- `wr.features` injection is compile-time -- changing a workflow file is immediately effective for NEW sessions; in-flight sessions use the pinned version
+- Step IDs must not be renamed on widely-used workflows (session continuity depends on stable step IDs in active sessions)
+- Any change must pass `npx vitest run` -- the bundled workflow smoke test covers all workflows automatically
+
+### Success Criteria (observable and falsifiable)
+
+1. `now-next-later.md`, `open-work-inventory.md`, `tickets/next-up.md` reference only filenames that exist in `workflows/` (checkable with `ls`)
+2. `wr.production-readiness-audit` and `wr.architecture-scalability-audit` have `validatedAgainstSpecVersion: 3` after stamp
+3. At least one high-usage L3 workflow (e.g. `wr.shaping`, 39 uses, 8 raw steps) has been fully migrated to `promptBlocks` and declares `wr.features.capabilities` -- can be verified by checking the JSON and running the compiler
+4. `npx vitest run` passes after all changes
+5. The staleness advisory list shrinks by at least 2 entries (the L1 stamps)
+
+### Assumptions Still Active
+
+- **A1:** Migrating `wr.coding-task` raw prompts to `promptBlocks` is safe without breaking the existing step logic. (Unvalidated -- needs careful review of each step's prompt content vs. promptBlocks rendering)
+- **A2:** `metaGuidance` at inspection time is insufficient for behavioral reinforcement in long sessions. (Structurally supported but empirically unvalidated)
+- **A3:** Zero-usage workflows (presentation-creation, personal-learning-materials etc.) are safe to deprioritize indefinitely. (May be used by external teams not captured in local session store)
+
+### What Would Make This Framing Wrong
+
+- If agents reliably call `inspect_workflow` before each session and retain `metaGuidance` throughout, the per-step injection via promptBlocks may be redundant overhead. (Unlikely given how daemon sessions work -- they receive step prompts directly without prior inspection)
+- If wr.coding-task raw prompts were authored this way intentionally (as a v1-style "trust the agent" design), migrating them would work against the author's intent. (Git history shows no explicit reasoning for the choice -- likely legacy carryover from before promptBlocks existed)
+
+### HMW Reframes
+
+1. **HMW ensure behavioral constraints reach agents at the moment they need them (per step), not just at inspection time?** -- This reframe surfaces promptBlocks migration as the core action, not just field additions.
+2. **HMW reduce the gap between what planning docs say and what the repo actually contains?** -- This reframe surfaces that planning doc accuracy is itself a product quality issue, separate from workflow file quality.
+
+### Framing Risk
+
+The biggest framing risk: treating this as "modernization work" (cosmetic checklist) when the real problem is "per-step behavioral guidance is not reaching agents reliably." A stamp pass or features header addition would satisfy the planning doc metric while doing nothing for the agents that run these workflows 910 times.
+
+---
+
+## Opportunity Synthesis
+
+Two problems to solve in sequence:
+
+**Problem 1 (prerequisite): Planning system is stale.** All 10 named files in the modernization backlog are deleted. No execution can proceed against the current plan.
+
+**Problem 2 (the real work): High-usage workflows lack per-step behavioral guidance.** `metaGuidance` is inspection-time-only and not surfaced to daemon sessions. `wr.features` injection (the per-step path) requires `promptBlocks` steps, but `wr.coding-task` (910 runs), `wr.bug-investigation` (74 runs), and `wr.shaping` (39 runs) are entirely raw-prompt. Declaring features without migrating steps has zero runtime effect.
+
+**Self-challenge results (5 challenges conducted):**
+- Challenge 1: metaGuidance inspection-time claim confirmed by source code -- absent from start_workflow, continue_workflow, and daemon workflow-runner
+- Challenge 2: features-requires-promptBlocks confirmed by `resolve-features.ts` line 62 -- intentional design decision
+- Challenge 3: **FRAMING CORRECTION** -- wr.coding-task should NOT be the first L3 migration target. wr.shaping (39 uses, 8 steps) is the risk-appropriate starting point. Validate the migration pattern there before attempting the 910-run workflow.
+- Challenge 4: planning doc staleness is a genuine prerequisite, not a side issue
+- Challenge 5: stamp-only is honest for L1 workflows (already modern); dishonest for L4 without prior review
+
+**Riskiest assumption:** That migrating wr.coding-task's 9 raw prompt steps to promptBlocks will preserve the semantic quality of the existing prompts without fragmenting or diluting the guidance. Mitigation: validate on wr.shaping first.
+
+## Decision Criteria
+
+A valid direction must satisfy all of the following:
+1. Step IDs not renamed on active high-usage workflows (session continuity)
+2. `npx vitest run` passes after each change
+3. Planning docs reference only existing filenames after update
+4. Modernization order follows usage-ranked priority, not arbitrary list order
+5. Stamp follows genuine review (not precedes it) -- at minimum for L1 workflows
+
+## Candidate Directions
+
+**Direction A (Recommended): Fix planning docs + stamp L1 + migrate wr.shaping as first L3 target**
+- Update planning docs to correct filenames and usage-ranked priority
+- Review + stamp `wr.production-readiness-audit` and `wr.architecture-scalability-audit` (L1 -- already modern)
+- Migrate `wr.shaping` (39 uses, 8 raw steps) to full promptBlocks + features as the risk-appropriate first L3 migration
+- Defer wr.coding-task until wr.shaping validates the migration pattern
+- Ship as one PR (planning doc changes + stamp + first L3 migration)
+
+**Direction B: Fix planning docs only, output a usage-ranked ticket**
+- Update the three planning docs to reflect real filenames and real usage order
+- Create a GitHub issue with the correct prioritized modernization backlog
+- No workflow file changes in this PR -- separate concerns, minimize blast radius
+- Pro: cleanest separation; Con: defers the actual guidance quality fix
+
+**Direction C: Stamp-only pass on L1 + planning doc fixes, defer all L3 migration**
+- Fix planning docs
+- Review + stamp wr.production-readiness-audit and wr.architecture-scalability-audit
+- Explicitly defer all raw→promptBlocks migration to a future PR
+- Pro: very low risk; Con: doesn't address the per-step guidance gap at all
+
+**Direction D: Fix planning docs + full L3 migration of wr.shaping + wr.coding-task in one PR**
+- Aggressive scope: modernize two L3 workflows in a single PR
+- High impact but also high review burden; wr.coding-task is 14 steps
+- Pro: maximum value delivered; Con: risky, large diff, hard to review carefully
+
+---
+
+## Candidate Generation Requirements (landscape_first path)
+
+The following expectations apply to the next candidate generation pass. They are recorded here so the synthesis step can judge whether the candidates met the bar.
+
+### What the candidate set must reflect (landscape_first constraints)
+
+1. **Grounded in actual usage data.** Candidates must reflect the usage-ranked inventory (wr.coding-task: 910, wr.mr-review: 606, etc.) -- not an alphabetical or arbitrary ordering. Any direction that does not prioritize by usage fails this criterion.
+
+2. **Must account for the architectural constraint.** Candidates cannot treat "declare wr.features in the header" as meaningful for workflows that are entirely raw-prompt. The only valid modernization path for L3 workflows is raw→promptBlocks migration. Directions that skip this constraint are disqualified.
+
+3. **Must address both problems (planning docs AND workflow quality).** A direction that only fixes planning docs without any workflow quality improvement is incomplete. A direction that modernizes workflows without fixing planning docs first is unorderable (can't find the files). Both problems must appear in every viable direction.
+
+4. **Must not invent a third problem.** The scope is: fix planning system accuracy AND improve per-step guidance delivery for high-usage workflows. Candidates that reframe toward "build a migration tooling layer" or "redesign the features system" are out of scope -- those are good ideas but belong in the backlog, not in this decision.
+
+5. **Must include at least one direction that explicitly scopes OUT wr.coding-task.** The riskiest assumption is that wr.coding-task can be migrated without quality degradation. At least one candidate must treat wr.shaping as the only L3 migration target in the first PR, deferring wr.coding-task to a follow-on.
+
+6. **Must include at least one direction that includes wr.coding-task.** The counterpoint must also exist -- the highest-usage workflow deserves a candidate that argues for tackling it now.
+
+### What would disqualify a candidate
+
+- Proposes "stamp first, review later" for L4 workflows
+- Ignores the raw→promptBlocks prerequisite
+- Treats planning doc fixes as optional
+- Proposes step ID renames on active workflows
+- Requires changes to protected files (src/daemon/, src/trigger/, src/v2/)
+
+---
+
+## Decision Log
+
+- **2026-04-28**: Discovered `exploration-workflow.json` does not exist -- it was deleted in March 2026. Planning docs are stale. Path selection shifted to `landscape_first`.
+- **Capability check**: No web access needed -- all data is local (repo files, session store). Web browsing available but not used.
+- **Delegation**: Not used for file reading/analysis. Delegation deferred to candidate generation; decision at phase 3b was to use self-generation given STANDARD rigor and well-evidenced context.
+- **Self-challenge (Phase 2)**: 5 challenges conducted. Key correction: wr.shaping (not wr.coding-task) is the risk-appropriate first L3 migration target. Stamp is honest for L1, dishonest for L4 without prior review.
+
+---
+
+## Challenge Notes
+
+*(to be populated after direction challenge in phase 3d)*
+
+---
+
+## Resolution Notes
+
+*(to be populated at phase 5)*
+
+---
+
+## Final Summary
+
+*(to be populated at handoff)*
+